APP · 33.1 %
Applications et intégration
Ce domaine couvre l'intégration de la Messages API dans une application : format des échanges, lecture de stop_reason, erreurs, limites de débit et traitements en lot. Il teste aussi les choix d'exploitation : identifiants de modèle, plateformes tierces et discipline de changement.
Une API sans état
La Messages API ne garde rien entre deux appels : l'application renvoie tout l'historique à chaque tour, d'où un coût d'entrée qui croît avec la conversation. Elle n'ajoute aucun system prompt, contrairement à claude.ai ou à Claude Code : le comportement dépend uniquement de ce qui est envoyé. Dans l'Agent SDK, sans option systemPrompt, seul un prompt minimal s'applique, et le preset claude_code redonne le comportement du CLI.
Renvoyer les résultats d'outils
Tous les tool_result d'un tour partent dans un seul message user, juste après le message de l'assistant et avant tout texte. Il n'existe pas de rôle tool : tout passe par user et assistant. Ajouter du texte après chaque résultat apprend à Claude à clore son tour, ce qui produit des réponses vides avec end_turn.
Lire `stop_reason` avant le contenu
max_tokens signale une sortie tronquée : un tool_use incomplet se relance avec un plafond plus haut. pause_turn signale qu'un server tool a atteint sa limite d'itérations : on renvoie la réponse telle quelle pour que Claude reprenne. refusal arrive en HTTP 200, donc seul stop_reason le distingue d'un succès.
Streaming : où arrivent les signaux
En streaming, stop_reason vaut null dans message_start et n'arrive que dans message_delta. Une erreur survenue après le 200 arrive comme un événement error dans le flux, puisque le statut HTTP est déjà parti. Le streaming améliore la latence perçue et protège les longues requêtes des coupures de connexion inactive, sans réduire le coût.
Erreurs, retries et idempotence
Le SDK relance déjà deux fois les erreurs transitoires (connexion, 408, 409, 429, 5xx) : une boucle maison par-dessus multiplie les appels. Le code se branche sur le statut et error.type, jamais sur le texte du message, car de nouveaux types peuvent apparaître sans nouvelle version d'API ; le request-id se journalise pour le support. Un retry n'est sûr que sur une opération idempotente : une clé d'idempotence évite qu'un outil à effet de bord s'exécute deux fois.
Limites de débit et concurrence
Les limites suivent un token bucket : la capacité se recharge en continu, et une rafale peut déclencher un 429 sous le quota par minute. Les lectures de cache ne comptent pas dans l'ITPM, et max_tokens n'entre pas dans l'OTPM. Pour un gros volume avec échéance, un pool de concurrence borné qui respecte retry-after donne un débit régulier, et un handler async utilise AsyncAnthropic pour ne pas bloquer la boucle d'événements.
Message Batches API
Le batch coûte 50 % du prix standard en échange d'un délai non garanti : la plupart des batches finissent en moins d'une heure, mais seule l'expiration à 24 heures fait foi. Les résultats arrivent dans un ordre quelconque et se rapprochent par custom_id. La validation de params est asynchrone : une requête invalide revient errored, non facturée, sans bloquer les autres.
Ce que refusent les modèles récents
Depuis Claude 4.6, un prefill du dernier tour assistant renvoie une 400 : on passe par les structured outputs ou le system prompt. Les blocs thinking et redacted_thinking se renvoient exactement tels que reçus, car l'API vérifie leur intégrité. Plusieurs modèles récents (Opus 5.5, Sonnet 5.5, Fable 5.2) refusent tool_choice any ou tool : on utilise auto avec le strict tool use, et la boucle de l'application impose l'ordre des étapes.
Identifiants de modèle et cycle de vie
Depuis la génération 4.6, l'ID sans date (claude-sonnet-4-6) est un snapshot figé ; avant, l'alias court suivait le dernier snapshot daté. Épingler fixe les poids, pas la disponibilité : chaque ID a sa date de retrait, annoncée au moins 60 jours avant pour les modèles publics, après quoi les requêtes échouent. On migre donc tôt, evals à l'appui, et l'export d'usage de la Console montre les clés qui appellent encore l'ancien modèle.
Plateformes tierces et contraintes fermes
Sur Google Cloud (Google managed) ou Bedrock, la forme des messages reste la même, mais l'authentification, les endpoints, les ID de modèle et les fonctionnalités changent : pas de Files API ni de sources URL sur Google managed, par exemple. Les exigences de résidence éliminent des options avant toute comparaison de coût. Sur l'API Claude, inference_geo accepte global ou us, alors que Google Cloud (Google managed) propose un endpoint multi-région eu.
Documents PDF
Chaque page d'un PDF est convertie en image et son texte est extrait : les deux sont facturés, soit environ 1 500 à 3 000 tokens de texte plus au plus 1 568 tokens d'image par page. Le coût dépend donc du nombre de pages, pas du poids du fichier. Placer le PDF avant la question améliore les résultats.
Versionner prompts et changements
Prompts, ID de modèle, schémas et jeux d'evals vivent dans le contrôle de version, passent en revue et se promeuvent sur un score d'eval : un incident peut alors nommer la version fautive et revenir en arrière. La doc pose les critères de succès et les tests empiriques comme préalables à tout travail de prompt. Un changement de structure et un changement de comportement se livrent séparément, avec des tests qui fixent d'abord le comportement à préserver.
AGT · 14.7 %
Agents et workflows
Anthropic distingue les workflows, où le code décide de l'étape suivante, des agents, où le modèle en décide. La plupart des questions vérifient que l'architecture choisie est la plus simple qui fonctionne, et que les points de contrôle reposent sur du code ou des données structurées.
Workflow ou agent
Le critère est unique : qui choisit l'étape suivante. Si le code fixe le chemin, c'est un workflow, quel que soit le nombre d'appels ou d'outils ; si le modèle décide à partir des résultats obtenus, c'est un agent. Un workflow apporte prévisibilité et coût maîtrisé, un agent échange latence et coût contre de la flexibilité, et ce compromis doit se justifier.
Commencer par la solution la plus simple
Anthropic recommande de n'ajouter de la complexité que si elle améliore un résultat mesuré. Souvent, un appel unique bien construit, avec récupération ou exemples dans le prompt, suffit. Une base de connaissances de moins de 200 000 tokens (environ 500 pages) peut aller entière dans le prompt, et le prompt caching rend cette approche rapide et peu coûteuse.
Les patrons de workflow
Prompt chaining : des étapes fixes, avec une vérification programmatique (une porte) entre elles. Routing : classer l'entrée puis l'envoyer vers un traitement spécialisé. Parallélisation : des sous-tâches définies d'avance dans le code (sectioning) ou la même tâche répétée (voting). Orchestrator-workers : un LLM décompose la tâche selon l'entrée, utile quand les sous-tâches sont imprévisibles, comme le nombre de fichiers à modifier.
Frameworks : comprendre ce qu'ils génèrent
Les frameworks accélèrent le démarrage mais ajoutent des couches qui masquent les prompts et les réponses réels, ce qui complique le débogage. Anthropic conseille de commencer par l'API directe, puisque la plupart des patrons tiennent en quelques lignes. Avec un framework, il faut comprendre le code sous-jacent : les hypothèses fausses sur son fonctionnement sont une source d'erreur fréquente.
Une boucle pilotée par `stop_reason`
Une boucle d'agent écrite à la main lit stop_reason à chaque réponse : tool_use, exécuter les outils et renvoyer tous les résultats dans un seul message user ; pause_turn, renvoyer le contenu tel quel pour continuer ; end_turn, s'arrêter. Les tool_use d'un même tour ne sont pas ordonnés, et chacun attend son tool_result. Un plafond d'itérations et un budget servent de filet de sécurité, et la présence de texte ne signale jamais la fin.
Les règles absolues vont dans un hook
Une instruction, dans le prompt ou dans CLAUDE.md, reste soumise au jugement du modèle : Claude la lit comme du contexte, et rien ne garantit qu'il la suive. Un hook exécute du code à un point fixe du cycle de vie, à chaque fois : PostToolUse pour formater chaque fichier modifié, PreToolUse pour bloquer un appel. Quand une question dit « toujours », « jamais » ou « sans exception », chercher le mécanisme déterministe.
Sous-agents : un contexte isolé
Un sous-agent démarre avec son propre contexte : il ne voit ni l'historique de la conversation principale ni les fichiers déjà lus, et ne reçoit que le prompt de délégation. Ses appels d'outils restent chez lui, seul son message final remonte. Cet isolement protège le contexte principal (lire 40 fichiers, ne rapporter que la synthèse), à condition que le prompt de délégation contienne toutes les contraintes utiles. Seule exception : un fork, qui copie la conversation en cours.
Des relais structurés entre agents
Un agent ne peut exploiter que ce qu'il reçoit. Exiger de chaque sous-agent des enregistrements structurés (chemin, symbole, lignes, extrait), un rapport d'échec explicite (section, type d'erreur, résultats partiels, relance possible) et la provenance de chaque affirmation (client, outil, inférence, statut de vérification). Une dépendance entre étapes se contrôle dans le code, sur un champ structuré, jamais sur un mot comme « done ». Un résultat vide marqué comme réussi rend l'erreur invisible en aval.
Agent SDK : réglages chargés et fin de boucle
L'option settingSources décide de ce que le SDK charge depuis le disque : "project" pour le CLAUDE.md, les skills, les hooks et les permissions du projet, "user" pour ~/.claude. Omise, elle vaut ["user", "project", "local"] ; fixée explicitement, elle doit lister chaque source nécessaire. En fin de boucle, le ResultMessage porte un subtype : le texte result n'existe que sur success, alors que coût, usage et session_id sont présents sur tous les sous-types. max_turns et max_budget_usd bornent une exécution qui, sinon, tourne jusqu'à ce que Claude s'arrête.
Managed Agents ou Agent SDK
Avec Managed Agents, Anthropic héberge la boucle, le sandbox et l'exécution des outils ; les sessions sont stateful et stockées côté serveur, ce qui convient aux tâches longues et asynchrones. Ce stockage a un prix : pas d'éligibilité HIPAA, et le ZDR seulement en variante auto-hébergée. L'Agent SDK tourne dans le processus de l'application, qui lance un sous-processus claude par session et gère hébergement, persistance et montée en charge. Une exigence de rétention peut trancher avant tout autre critère.