Production-Grade Prompting, Agents & Tool Use

Screen 1: What you will be able to do by the end

MODULE 2 ORIENTATION · 2 MIN Ce que vous serez capable de faire à la fin

Écrire du code qui utilise Claude est différent d'utiliser Claude pour écrire du code.

Vous avez probablement utilisé Claude de manière interactive en tapant une invite, en lisant la réponse et en l'ajustant selon les besoins. Ce module aborde tous les aspects suivants de l'utilisation de Claude au-delà de ce niveau de base, y compris les schémas d'outils, la gestion du contexte et les boucles d'agents. Ce module s'appuie sur votre capacité à façonner les résultats de Claude. En tant qu'ingénieur, vous êtes responsable de l'intégration programmatique de Claude, de la gestion fiable des résultats et du déploiement réussi d'une solution robuste en production.

Chaque sujet de ce module aborde un mode de défaillance spécifique qui est fréquemment négligé pendant le développement mais qui nécessite un temps et des efforts importants pour être identifié et résolu une fois le développement en cours. Lorsque vous apprenez à identifier et à éviter ces modes de défaillance, vous serez en position d'intégrer efficacement et efficacement Claude dans vos processus de développement.

À la fin de ce module, vous serez capable de : 1 Écrire des invites prêtes pour la production en utilisant des invites système, des balises XML, des exemples few-shot et des contraintes de résultat, et diagnostiquer pourquoi une invite sous-performe lorsque les résultats de première passe ne sont pas à la hauteur. 2 Décider quand activer la réflexion étendue, calibrer son paramètre d'effort et gérer correctement les blocs de réflexion dans les tours d'utilisation d'outils. 3 Définir et implémenter un schéma d'outil que Claude sélectionne correctement, construire la boucle d'utilisation d'outils, gérer les blocs de messages multi-tours et distinguer quand utiliser un seul appel d'outil par rapport à plusieurs appels parallèles. 4 Consommer une réponse en streaming, assembler les événements en streaming dans des blocs de contenu complets et récupérer proprement lorsqu'un streaming est interrompu à mi-chemin. 5 Appliquer des techniques d'ingénierie du contexte, y compris la gestion de la fenêtre de contexte, la compaction, l'effacement de l'historique entre les tâches et les transferts de sous-agents, pour maintenir les sessions d'agents multi-tours dans le budget sans perdre la continuité des tâches. 6 Construire un agent de production en choisissant entre les modèles de flux de travail et d'agent, en câblant les outils et le contexte dans une boucle de travail, en sélectionnant un chemin de câblage qui correspond à vos contraintes de déploiement et en ajoutant des points de contrôle Human-in-the-loop (HITL) où les actions sont irréversibles. 7 Gérer la mémoire de l'agent entre les sessions en utilisant des modèles de stockage persistant et en choisissant la bonne portée de mémoire afin que l'état de l'agent survive entre les tours sans gonfler le coût du contexte. 8 Envoyer des images et des PDF à Claude en utilisant la structure correcte du bloc de message, appliquer l'API Files pour les actifs réutilisables et soumettre des charges de travail à haut volume en utilisant l'API Message Batches afin qu'elles se terminent de manière asynchrone.

Ce module s'adresse au Developer qui est prêt à utiliser Claude pour transformer un prototype en un système de production complet qui tient bon lors d'une utilisation réelle. Vous êtes pratique, orienté code et orienté modèles. Ce module suppose que vous êtes déjà à l'aise pour écrire du code ; il n'enseigne pas les fondamentaux de la programmation et ne concerne pas l'utilisation de Claude de manière décontractée dans une fenêtre de chat. Il enseigne les décisions d'ingénierie autour du modèle : comment structurer les invites, définir les outils, gérer le streaming en toute sécurité, gérer le contexte et la mémoire, et construire des boucles d'agents qui restent fiables, abordables et contrôlables une fois déployées.

"THE BUILD" IN THIS MODULE

Tout dans ce module est construit autour d'un problème d'ingénierie récurrent : une intégration Claude qui fonctionnait bien pendant le développement mais qui doit maintenant tenir bon en production. En développement, l'invite semblait solide, l'appel d'outil fonctionnait, la session restait courte et les entrées de test étaient gérables. Cependant, en production, ce même système doit survivre à des sessions plus longues, à des résultats d'outils plus volumineux, à des streams interrompus, à des contraintes de coût et de latence plus strictes, à la mémoire entre les tours et à des actions qui peuvent être irréversibles. Ce module vous enseigne quelle décision d'implémentation prévient quelle défaillance en production : comment structurer les invites, définir les outils, gérer le streaming, gérer le contexte, choisir la portée de la mémoire et câbler les agents en toute sécurité avant que ces défaillances ne se produisent.

DISCLAIMER / NOTICE FOR EDUCATIONAL CONTENT

Nous avons construit ce cours Developer Module 2 : Production-Grade Prompting, Agents & Tool-use pour vous aider à accomplir un vrai travail avec Claude. Traitez-le comme du contenu éducatif. Il ne constitue pas un conseil juridique, financier ou autre conseil professionnel, alors adaptez ce que vous apprenez à votre situation. Nos produits et services évoluent rapidement, donc certains contenus peuvent contenir des erreurs ou être obsolètes ; n'oubliez pas de vérifier sur le site Web ou la documentation d'Anthropic. Les exemples et scénarios utilisés dans le cours sont illustratifs et souvent fictifs. Si le matériel du cours mentionne une entreprise ou un produit, cela ne signifie pas qu'Anthropic les approuve, qu'ils approuvent Anthropic ou que nous sommes affiliés. Notez également que votre utilisation des produits et services d'Anthropic est couverte par nos conditions, politiques et documentation ; si quelque chose dans ce cours entre en conflit avec eux, ils contrôlent.

Screen 2: System prompts, XML, few-shot, and output constraints

TeachingPrompting Craft·20 min Invites système, XML, few-shot et contraintes de résultat Une invite qui fonctionne une fois lors d'une utilisation interactive se casse souvent lorsqu'elle s'exécute en production contre des entrées non testées. La correction pour cela n'est pas seulement d'ajouter plus de mots, c'est d'identifier quel élément structurel manque à l'invite et d'ajouter cet élément. Cette section examine comment lire une sortie échouée, puis parcourt les quatre techniques qui produisent les corrections.

Quatre techniques qui donnent à Claude une forme de résultat fiable Lorsqu'une réponse de première passe manque, l'instinct est souvent d'ajouter plus de mots à l'invite et de réessayer. Cependant, cet instinct peut rendre le problème plus difficile à isoler et résout rarement le problème. Reformuler change la façon dont vous dites quelque chose mais n'ajoute pas à l'élément structurel de l'invite qui manque. Par exemple, si Claude franchit la limite entre vos instructions et vos données d'entrée, une formulation plus claire ne le corrigera pas, et si le format de sortie continue de dériver, « veuillez formater ceci correctement » ne le corrigera pas non plus. Le mode de défaillance vous indique laquelle des quatre techniques est absente. Diagnostiquez d'abord comment votre invite échoue, puis ajoutez la technique spécifique qui résout cette défaillance. Les quatre techniques elles-mêmes sont définies complètement plus loin dans cet écran.

Ce que vous avez observéCe qui manque à l'inviteWhy this technique is the fix Le résultat revient dans la mauvaise forme : une phrase où vous attendiez une étiquette, de la prose où vous attendiez du JSON. Une contrainte de résultat. L'invite n'a jamais spécifié la forme, les noms de champs ou le point d'arrêt de la réponse. Une contrainte de résultat contrôle la forme de la réponse indépendamment de son contenu. Sans elle, Claude retourne du texte plausible que l'analyseur en aval n'a pas été construit pour accepter. Le contenu est incorrect : la portée dérive, le ton change ou Claude répond à une question plus large que celle que vous avez posée, et cela s'aggrave plus loin dans la conversation. Une invite système, ou une plus spécifique. Le contrat comportemental était trop vague pour tenir entre les tours. L'invite système définit les règles qui s'appliquent à chaque réponse indépendamment du tour de l'utilisateur. Lorsqu'elle est sous-spécifiée, il n'y a rien pour maintenir le rôle, la portée et le format constants à mesure que la conversation se poursuit. La tâche est correcte, mais la structure est inventée : Claude a compris ce qu'il fallait faire et a produit une sortie dans une forme que vous n'avez jamais demandée. Des exemples few-shot. Claude ne peut pas déduire une structure exacte à partir d'une description seule. Les exemples few-shot montrent le modèle plutôt que de le décrire. Une paire d'entrée-sortie correcte donne à Claude la forme exacte à correspondre, ce qu'une instruction écrite échoue souvent à épingler. La sortie est propre sur les entrées que vous avez testées mais se casse sur une variante : un cas limite, un champ inhabituel, une entrée que vous n'aviez pas anticipée. Une contrainte couvrant la variante. L'invite gère le chemin heureux et n'a pas de règle pour le cas où l'analyseur se casse. L'invite a été validée contre un ensemble étroit d'entrées. Nommer la variante dans la contrainte, ou ajouter un exemple qui la couvre, ferme l'écart que les entrées de test n'ont jamais exposé.

Diagnostiquer une invite de classification qui retourne la mauvaise forme de résultat La règle est simple : nommez la défaillance, ajoutez la technique qui la correspond, et réexécutez-la. Si elle échoue toujours, diagnostiquez à nouveau. Lorsqu'une invite devient plus longue à chaque passage, c'est le signe que vous sautez l'étape de diagnostic et que vous ajoutez simplement des mots. Le modèle ci-dessous est la première ligne du tableau en action : une invite qui produit le bon contenu dans une forme que le code en aval ne peut pas accepter. Le classificateur comprend la tâche et retourne la bonne catégorie, mais la forme de cette réponse varie d'une exécution à l'autre, donc le routeur qui la consomme échoue. La pièce manquante est une contrainte de résultat, et la correction tire dans deux des autres techniques pour verrouiller l'ensemble d'étiquettes et montrer le format. La procédure pas à pas passe de l'invite nue qui cause le problème à la version contrainte qui le résout.

Exemple travaillé : une invite de classification avant et après Un développeur a besoin que Claude classe les tickets d'assistance en trois catégories : facturation, technique et escalade. La première invite est une instruction nue sans contrainte sur la sortie :

System: "You are a support classifier. Classify the ticket. "

User: <ticket>I was charged twice for the same month. </ticket>

Claude retourne « Billing » sur certaines exécutions, « billing » sur d'autres, et occasionnellement une phrase complète comme « This looks like a billing issue. » Le routeur en aval s'attend à un ensemble fixe d'étiquettes et se casse sur l'incohérence. Lisez ceci par rapport au tableau ci-dessus, cette situation correspond à ce qui est décrit dans la première ligne : la sortie revient dans une forme que l'analyseur ne peut pas accepter, donc la pièce manquante est une contrainte de résultat. L'ajout de cette contrainte tire dans deux techniques supplémentaires, car verrouiller l'ensemble d'étiquettes et montrer le format sont des travaux que ces techniques font mieux qu'une instruction écrite ne peut. Les exemples few-shot montrent à Claude l'étiquette exacte et la casse à retourner, et les balises XML gardent ces exemples séparés de l'instruction afin que Claude ne les lise pas comme faisant partie de la tâche :

System: "You are a support classifier. Classify each ticket into exactly one of: BILLING, TECHNICAL, ESCALATION. Return only the label. No other text. "

<sample_input>My account shows two charges for April. </sample_input> <ideal_output>BILLING</ideal_output>

<sample_input>The API keeps returning a 429 error. </sample_input> <ideal_output>TECHNICAL</ideal_output>

User: <ticket>I was charged twice for the same month. </ticket>

Trois techniques font un travail distinct ici. L'invite système définit le contrat de sortie : exactement une étiquette d'un ensemble fixe, rien d'autre. Les balises XML marquent où chaque exemple se termine et le suivant commence, afin que Claude ne lise pas les exemples comme faisant partie de l'instruction. Les paires few-shot montrent la casse exacte et le format plutôt que de les décrire. Ensemble, ils produisent un résultat suffisamment cohérent pour être routé programmatiquement.

Le tableau ci-dessous montre comment nous pouvons empiler les quatre techniques ensemble, où l'invite doit être simplifiée et où nous devons diagnostiquer avant d'ajouter plus avant trop d'itérations.

Empiler les quatre techniquesEmpiler les quatre techniques contre un contrat de sortie clairement défini. Les tâches avec des formats bien spécifiés et des cas limites qui peuvent être couverts par des exemples. Simplifier l'inviteAjouter les quatre techniques à une tâche simple qui n'en a besoin que d'une. Une invite « résumez ce paragraphe » n'a pas besoin d'exemples few-shot et d'un schéma de sortie. Diagnostiquer avant d'ajouter plusLes invites qui deviennent plus longues à chaque itération plutôt que plus précises. Si vous avez réinvité cinq fois et que la sortie est toujours incorrecte, diagnostiquez le type de défaillance avant d'ajouter plus de texte.

Quand atteindre chaque technique Maintenant, comprenons mieux chacune de ces techniques et quand chacune s'applique :

Invites système Balises XML Exemples few-shot Contraintes de résultat

Les invites système portent le contrat comportemental pour toute la session. Écrivez-les une fois et traitez-les comme votre couche d'instruction persistante. Elles définissent le rôle de Claude, le format de sortie et toutes les règles qui ne doivent pas changer entre les conversations.

Les balises XML sont utilisées lorsque l'invite mélange les entrées avec les instructions. Une invite qui demande à Claude de déboguer du code en utilisant la documentation fournie en est un bon exemple ; sans balises, le code et la documentation se ressemblent pour Claude. Enveloppez-les avec des noms de balises descriptifs comme <my_code> et <docs> et la limite devient sans ambiguïté. Vous n'avez pas besoin d'utiliser des noms de balises XML officiels ; les noms descriptifs qui correspondent à votre contenu fonctionnent mieux.

Les exemples few-shot sont considérés comme utiles car ils montrent plutôt que de simplement dire. Au lieu d'essayer de décrire le format exact que vous voulez, vous fournissez une paire d'entrée-sortie correcte et laissez Claude déduire le modèle. Pour utiliser cela, enveloppez les exemples en utilisant une structure XML cohérente, par exemple <sample_input> et <ideal_output>, afin que la limite entre l'exemple et l'invite soit claire. Vous pouvez utiliser certains exemples de vos résultats d'évaluation les plus élevés plutôt que de les écrire à partir de zéro.

Les contraintes de résultat sont la dernière ligne de défense avant que la réponse de Claude n'atteigne votre analyseur. Vous devez spécifier exactement ce dont vous avez besoin, y compris les noms de champs, les types, les limites de longueur, s'il faut inclure un préambule et quoi faire lorsque les données sont absentes. Utilisez les fonctionnalités de sortie structurée dans les cas où le format doit être lisible par machine.

La boucle d'itération : Diagnostiquer avant de réinviter Lorsqu'une réponse de première passe manque la cible, l'instinct est d'ajouter plus de mots à l'invite et de réessayer. Cet instinct rend presque toujours le problème plus difficile à diagnostiquer et résout rarement le problème. Au lieu de cela, diagnostiquez d'abord le problème, puis réinvitez en fonction de vos conclusions. Le type de défaillance vous indique quelle technique manque :

Mauvais format : Ceci est causé par une contrainte de résultat manquante. L'invite n'a jamais spécifié la forme que le résultat devrait prendre. Contenu incorrect ou dérive de portée : Ceci est causé par une invite système sous-spécifiée ; le contrat comportemental était trop vague pour tenir entre les conversations. Tâche correcte mais structure halluccinée : Cela se produit lorsque des exemples few-shot sont nécessaires. Claude ne peut pas déduire la structure exacte à partir d'une description seule. Bonne sortie sur des entrées simples mais se casse sur des cas limites : L'invite gère le chemin heureux mais n'a pas de contrainte couvrant la variante où l'analyseur se casse.

La correction est structurelle, pas une question de formulation. Par exemple, si Claude ignore une limite entre vos instructions et votre contenu, une formulation plus claire ne le corrigera pas, et si le format de sortie continue de dériver, dire « veuillez formater ceci correctement » ne le corrigera pas non plus. Dans chaque cas, identifiez laquelle des quatre techniques est absente et ajoutez-la.

Déplacer le contrôle de sortie de l'invite vers l'API avec des résultats structurés Tout jusqu'à présent façonne la sortie en écrivant des instructions dans l'invite et en espérant que Claude les suive. Cela fonctionne la plupart du temps, mais l'invite est une demande, donc un modèle peut toujours retourner une phrase égarée, un mauvais nom de champ ou du JSON mal formé qui casse l'analyseur en aval. L'API Claude a un mécanisme séparé qui supprime cet écart pour le code de production. Il s'appelle résultats structurés, et au lieu de demander une forme en mots, vous remettez à l'API un schéma JSON, et le modèle est contraint au moment de la génération pour produire une sortie qui le correspond. Cette technique est le décodage contraint : à mesure que Claude génère chaque token, l'API n'autorise que les tokens qui maintiennent la sortie valide par rapport à votre schéma, donc une réponse qui viole le schéma ne peut pas être produite en premier lieu. Les résultats structurés couvrent deux situations qui apparaissent dans les pipelines réels. Chacun contraint une partie différente de ce que le modèle retourne, et vous pouvez les utiliser seuls ou ensemble dans la même demande.

Les résultats JSON contraignent la réponse finale. Vous définissez le paramètre output_config. format avec le type json_schema et votre schéma, et Claude retourne du JSON valide dans le texte de réponse qui correspond à ce schéma à chaque fois. Utilisez ceci lorsque le modèle lui-même produit la charge utile structurée que votre code consomme, comme l'extraction de champs d'un ticket d'assistance ou le formatage d'une réponse API, car cela supprime le code d'analyse et de nouvelle tentative que vous écririez autrement autour de chaque appel. L'utilisation d'outils strict contraint les entrées que Claude transmet à vos outils. Vous définissez strict à true sur une définition d'outil, et les arguments que Claude envoie à cet outil sont validés par rapport au schéma d'entrée avant que votre code ne s'exécute. Utilisez ceci dans les boucles agentic où un argument d'outil mal formé casserait la fonction ou déclencherait une mauvaise action ; cela aide à garantir que l'appel que votre code reçoit se conforme déjà au contrat que vous avez défini.

La raison pour laquelle cela appartient au code de production et non seulement à l'invite est la fiabilité sous les entrées que vous n'avez pas testées. Une instruction au niveau de l'invite pour retourner uniquement du JSON tient sur les cas que vous avez essayés puis glisse sur un cas limite que vous n'aviez pas, ce qui est exactement la défaillance que l'exemple de classification antérieur a parcourue. Une contrainte de schéma ne glisse pas, car l'API l'applique sur chaque token plutôt que de faire confiance au modèle pour se souvenir de l'instruction. Cela déplace la correction de sortie de quelque chose que vous vérifiez après coup à quelque chose que l'API exclut avant que cela ne se produise. La contrainte de génération a des coûts, et un développeur choisissant ceci en production doit les peser plutôt que de l'activer partout par défaut. Voici certains de ces coûts que vous devez considérer :

La première demande sur un nouveau schéma est plus lente. L'API compile votre schéma en une grammaire avant de pouvoir contraindre la sortie, et cette compilation ajoute de la latence au premier appel. Les grammaires compilées sont mises en cache pendant 24 heures à partir de la dernière utilisation, donc le trafic régulier sur un schéma stable paie le coût une fois, mais une charge de travail qui change constamment de schémas le paie à plusieurs reprises. Votre nombre de tokens d'entrée augmente. Lorsque les résultats structurés sont activés, l'API ajoute une invite système décrivant le format attendu, et cette invite injectée est facturée comme n'importe quelle autre token d'entrée. L'augmentation est faible par appel, mais elle vaut la peine d'être connue lorsque vous estimez le coût en volume. Un schéma garanti n'est pas un succès garanti. Deux cas retournent toujours une sortie qui ne correspond pas : un refus, où le modèle décline pour des raisons de sécurité et la réponse porte stop_reason refusal, et une troncature, où la réponse atteint la limite max_tokens et s'arrête au milieu de la structure avec stop_reason max_tokens. Votre code vérifie toujours stop_reason plutôt que de supposer que chaque réponse s'analyse. Il ne se combine pas avec le préfixage des messages. Les résultats JSON et le préfixage du message assistant sont incompatibles, donc un modèle qui démarre la réponse pour Claude et un modèle qui contraint la réponse entière à un schéma ne peuvent pas s'exécuter sur la même demande. Choisissez celui qui correspond à la tâche.

Screen 3: The prompt that grew longer instead of better

Watch OutPrompting Craft·5 min L'invite qui s'est allongée au lieu de s'améliorer

Setup Même si une invite semble prête pour la production, elle peut toujours produire des défaillances silencieuses. Parfois, les cas limites causent la disparition de champs ou l'ignorance de contraintes ; lorsque cela se produit, c'est souvent parce que les contraintes n'étaient pas spécifiées avec assez de précision.

Six passages de révision, chacun plus long que le précédent L'invite que nous avons utilisée dans l'exemple précédent est donnée ci-dessous : un développeur a besoin que Claude classe les tickets d'assistance en trois catégories : Facturation, technique et escalade. La première invite est une instruction nue : System: "You are a support classifier. Classify the ticket. " User: <ticket>I was charged twice for the same month. </ticket> La trace ci-dessous montre un développeur itérant sur une invite de classification, et bien que chaque passage ajoute plus de mots, la sortie continue de dériver. Ce modèle émerge lorsqu'un développeur ajoute à son invite sans tenir compte des spécifications de contrainte.

PassageQuoi a été ajoutéComportement de sortie 1« Classify this ticket as billing, technical, or escalation. »Retourne des phrases complètes : « This appears to be a billing issue. » L'analyseur se casse. 2Ajouté « Be concise. » et « Use only the category name. »Retourne « Billing » en majuscules parfois, « billing » en minuscules d'autres fois. Le routeur se casse sur l'inadéquation de casse. 3Ajouté trois paragraphes décrivant chaque catégorie en détail. Sortie correcte sur les tickets simples. Pour les tickets ambigus, retourne « billing/technical » au lieu d'une seule étiquette. L'analyseur se casse sur la barre oblique. 4Ajouté « Never return two categories. » et « If ambiguous, choose the most likely one. »Fonctionne sur 80 % des tickets. Échoue sur les tickets qui pourraient raisonnablement correspondre à deux catégories (par exemple, « I was charged but the feature also stopped working »). Ici, il retourne une explication complète au lieu d'une étiquette. 5Ajouté deux paragraphes supplémentaires sur les cas limites et un rappel d'être précis. L'invite verbeuse produit maintenant une sortie verbeuse, plus de 2 000 caractères par appel, car les invites longues et non ciblées ont tendance à produire des sorties longues et non ciblées. Le modèle calibre la longueur et le style de réponse pour correspondre à l'entrée. La latence a augmenté considérablement en raison de la longueur de sortie, mais la précision n'a pas amélioré. 6Remplacé toutes les instructions par un schéma JSON et deux exemples few-shot montrant des paires d'entrée/sortie exactesRetourne {"category": "billing"} sur chaque ticket. L'analyseur fonctionne. La latence baisse. La précision sur les tickets ambigus correspond au passage 4.

Deux choses se sont mal passées au cours de ces six passages et il vaut la peine de les identifier séparément. Le passage 4 est la défaillance diagnostique : le développeur a identifié le mauvais problème, a ajouté une description au lieu d'une contrainte, et la sortie est restée cassée. Le passage 5 est la défaillance d'ingénierie : l'invite est devenue assez verbeuse pour induire une régression de latence, et le modèle calibre la longueur de réponse pour correspondre à l'entrée, générant plus de 2 000 caractères par appel, sans gain de précision. La correction pour les deux est le même mouvement structurel : une contrainte de résultat et deux exemples few-shot, mais reconnaître que ce sont deux défaillances différentes importe parce que la seconde peut apparaître même lorsque la première a été résolue. Voici l'invite avec la contrainte de résultat et les exemples few-shot appliqués :

System: "You are a support classifier. Classify each ticket into exactly one of: BILLING, TECHNICAL, ESCALATION. Return only the label. No other text. "

<sample_input>My account shows two charges for April. </sample_input> <ideal_output>BILLING</ideal_output>

<sample_input>The API keeps returning a 429 error. </sample_input> <ideal_output>TECHNICAL</ideal_output>

User: <ticket>I was charged twice for the same month. </ticket>

What to Watch Out for Chaque passage a rendu l'invite plus longue et aucun d'eux n'a ajouté la contrainte de résultat manquante. Le développeur décrivait le problème plus précisément à chaque itération, mais Claude n'a pas besoin d'une description détaillée de ce qu'un ticket de facturation ressemble, au lieu de cela, il doit savoir que la seule réponse acceptable est un mot en majuscules. La correction est deux lignes : une contrainte de résultat spécifiant le format exact et un exemple few-shot couvrant le cas ambigu. La trace de six passages est un modèle à reconnaître tôt : si trois réinvites d'affilée n'ont pas fonctionné, arrêtez d'ajouter du texte et diagnostiquez quelle technique manque.

Screen 4: Checkpoint 1 · Fix the broken prompt

CheckpointPrompting Craft·4 min Checkpoint 1 · Corriger l'invite cassée L'invite montrée ici extrait un objet JSON d'un ticket d'assistance avec trois champs : catégorie, urgence et un résumé d'une phrase. Il contient un défaut. Écrivez l'invite système corrigée qui le corrige.

Broken prompt System: "You are a support ticket processor. Extract the key information from the ticket below. "

User: <ticket>My API key stopped working after I rotated it last night. I have a production deployment that is failing. This needs to be fixed immediately. </ticket>

Reveal model answer Skip for now

Screen 5: Extended Thinking: Turning reasoning on, calibrating effort, and reading it back

TeachingExtended Thinking·12 min Extended Thinking : Activer la réflexion, calibrer l'effort et la relire correctement Les techniques d'invite façonnent ce que Claude produit. La réflexion étendue façonne la quantité de travail que Claude fait avant de répondre. Activez-la, et le modèle écrit son raisonnement étape par étape en premier, puis vous donne la réponse finale. Votre travail est de décider quand ce travail supplémentaire vaut le coût et de gérer le raisonnement qu'il envoie.

Ce que fait la réflexion étendue Lorsque vous activez la réflexion étendue, le modèle « pense à haute voix » avant de répondre. Vous verrez ce raisonnement revenir comme son propre bloc de réflexion dans la réponse de l'API, positionné juste avant le bloc qui contient la réponse réelle. Sur les modèles les plus récents, le contenu du bloc de réflexion est omis par défaut ; vous devez demander un résumé lisible via le paramètre display pour le voir. Sur les modèles actuels, la réflexion est adaptative : vous l'activez avec le paramètre thinking où elle n'est pas déjà activée par défaut, et le modèle décide de la quantité de réflexion que chaque demande nécessite. Vous réglez la profondeur avec le paramètre effort plutôt qu'un budget de tokens fixe. Le contrôle budget_tokens plus ancien est déprécié et, sur les générations de modèles les plus récentes, retourne une erreur 400. Ce raisonnement n'est pas gratuit ; les tokens de réflexion coûtent le même prix que les tokens de sortie, donc exécuter une tâche simple avec un effort élevé signifie payer pour une précision dont vous n'avez pas besoin. Le choix ici reflète celui que vous avez déjà fait : faire correspondre l'outil à la tâche. N'utilisez pas la réflexion étendue par défaut, appliquez-la stratégiquement où elle est nécessaire.

Quand utiliser la réflexion étendue

Forme de tâcheAppel de réflexion étenduRaison Raisonnement multi-étapes où le modèle doit maintenir plusieurs contraintes à la fois : une dérivation mathématique, un problème de logique multi-sauts, planifier une séquence d'actions dépendantes. Activez-la, avec le niveau d'effort adapté à la profondeur du problème. Le passage de raisonnement est où le modèle travaille à travers les dépendances qu'il ignorerait autrement. Tâches mécaniques ou de recherche : classification, conversion de format, extraction d'un champ, réponses factuelles courtes. Laissez-la désactivée. La réflexion étendue n'améliorera pas la réponse, et vous paierez plus de tokens pour quelque chose dont vous n'aviez pas besoin. Une invite nue avec une contrainte de résultat est le bon outil. Boucles agentic où le modèle planifie plusieurs appels d'outils. Activez-la et budgétisez l'étape de planification plutôt que par appel. Le raisonnement avant un plan réduit la mauvaise sélection d'outils en aval. Notez la règle de report ci-dessous, qui s'applique dans chaque boucle d'utilisation d'outils.

La règle de report : les blocs de réflexion doivent revenir à l'API inchangés Lorsque la réflexion étendue est activée et que votre conversation utilise des outils, il y a une règle que vous ne pouvez pas ignorer : chaque bloc de réflexion que vous récupérez doit revenir à l'API exactement comme il est arrivé au tour suivant. Chaque bloc est accompagné d'une signature qui confirme que le raisonnement n'a pas été modifié. Si vous le modifiez, le résumez ou le supprimez, la signature cesse de correspondre et l'API rejette la demande. Les blocs de réflexion réduits fonctionnent de la même manière. Leur contenu est chiffré et n'est pas destiné à être lu par les humains, mais ils doivent toujours être retournés inchangés. C'est une exigence structurelle, pas un choix d'invite que vous pouvez faire. Le glissement le plus courant est de supprimer le bloc de réflexion pour économiser du contexte, ce qui finit par casser votre demande suivante. Si la vraie préoccupation est la quantité de contexte qui s'accumule à partir du raisonnement accumulé, la correction est le travail d'ingénierie du contexte que nous couvrirons dans ce module.

Forward pointer Cette leçon active le raisonnement et calibre son paramètre d'effort ; elle ne couvre pas la sélection du modèle. Choisir quel modèle exécuter, contrairement à la question de savoir s'il faut activer le raisonnement, est enseigné dans le module MSO Foundations qui précède celui-ci.

Gère bienLes tâches de raisonnement et de planification difficiles où une mauvaise réponse est coûteuse et où les tokens supplémentaires achètent de la précision. Ajoute du coût ou de la complexitéL'exigence de report dans les boucles d'utilisation d'outils, et un paramètre d'effort que vous devez maintenant calibrer. Utilisez une approche différentePour la classification, l'extraction et les tâches de format, une invite bien contrainte est moins chère et tout aussi précise.

Screen 6: Checkpoint 2 · Decide when extended thinking earns its cost

CheckpointExtended Thinking·3 min Checkpoint 2 · Décider quand la réflexion étendue vaut son coût Trois tâches sont décrites ci-dessous. Faites correspondre chaque tâche à gauche à la bonne décision de réflexion étendue à droite. Il y a un appel correct par tâche.

Classer 50 000 tickets d'assistance en trois étiquettes pendant la nuit. Ne faites jamais cela. Laissez-la désactivée. Activez-la, budgétisez l'étape de planification. Planifier une refonte multi-étapes où chaque étape dépend de la précédente. Ne faites jamais cela. Laissez-la désactivée. Activez-la, budgétisez l'étape de planification. Supprimer le bloc de réflexion de l'historique de conversation pour économiser du contexte avant l'appel d'outil suivant. Ne faites jamais cela. Laissez-la désactivée. Activez-la, budgétisez l'étape de planification.

Submit Skip for now

Screen 7: Tool Schemas Claude Selects Correctly: Definition, Loop, and Calling Patterns

TeachingTool-use and Schema Design·20 min Schémas d'outils que Claude sélectionne correctement : Définition, boucle et modèles d'appel Jusqu'à présent, le travail a porté sur la façon de façonner ce que Claude produit : encadrer la demande, donner des exemples, choisir la technique qui correspond à la sortie que vous voulez. Avec l'utilisation d'outils, vous ne guidez plus le langage vers une bonne réponse, vous remettez à Claude un ensemble d'actions et vous lui faites confiance pour choisir la bonne ; ce choix est piloté presque entièrement par ce que vous avez écrit dans le schéma.

Comment fonctionne la boucle d'utilisation d'outils L'idée fausse la plus courante sur l'utilisation d'outils est que Claude exécute les outils. Au lieu de cela, Claude lit vos définitions d'outils, décide laquelle correspond à la situation et indique à votre application ce qu'il faut appeler avec les entrées requises. Votre application exécute l'outil, obtient le résultat et le renvoie ; puis Claude utilise ce résultat pour continuer. Ce va-et-vient ne doit pas être ignoré en production : si votre application ne gère pas le retour correctement, Claude n'obtient jamais les données qu'il a demandées, et la boucle se casse. La limite entre ce que Claude possède et ce que votre code possède est l'endroit où vivent la plupart des bugs d'utilisation d'outils. Voici la séquence pour assurer une implémentation appropriée de l'utilisation d'outils.

Cliquez sur chaque étape pour voir ce qui se passe.

1Define schema 2Send message 3tool_use block 4Execute tool 5Return result 6Claude continues

Define schemaVous définissez un schéma avec un nom, une description et un schéma d'entrée. Claude lit ceci pour décider s'il faut et quand appeler l'outil.

Il est important de noter que la boucle n'est pas automatique et vous devez compléter la quatrième étape. Si le manque est systématique, la correction est à l'étape de définition du schéma.

Structure du bloc de message dans une conversation d'utilisation d'outils Une conversation d'utilisation d'outils est construite à partir de blocs structurés, pas de texte brut. Chaque tour assistant et tour utilisateur est une liste de blocs, et quatre types de blocs font le travail dans une session d'utilisation d'outils. Un bloc de texte porte la réponse en prose de Claude. Un bloc tool_use porte un appel d'outil, y compris le nom de l'outil, un ID unique et les arguments d'entrée. Un bloc tool_result porte ce que votre code a retourné après avoir exécuté l'outil. Un bloc de réflexion porte le raisonnement interne de Claude, et il n'apparaît que lorsque la réflexion étendue est activée. L'API applique un appairage spécifique entre ces blocs. Chaque bloc tool_use dans un tour assistant doit être répondu par un bloc tool_result avec un ID correspondant dans le tour utilisateur qui suit immédiatement. Si les ID ne correspondent pas, si le résultat est manquant ou si les tours sont dans le désordre, la demande échoue la validation. Ce n'est pas quelque chose que vous pouvez corriger en ajustant votre invite ; c'est structurel, et votre code doit produire la séquence correctement à chaque demande. Le tableau ci-dessous résume chaque type de bloc, ce qu'il contient et la règle qui régit la façon dont votre code doit le gérer.

Type de blocRôleContientRègle critique bloc de texteAssistant/ClaudeRéponse en prose de ClaudeClaudepeut retourner un bloc de texte aux côtés d'un bloc tool_use dans le même tour. Lorsqu'il le fait, votre code doit préserver le tableau de contenu complet, y compris le bloc de texte, lors de l'ajout de ce tour à l'historique de conversation. Supprimer le bloc de texte corrompt le contexte sur lequel Claude s'appuie pour les tours de suivi. bloc tool_useAssistant/ClaudeLe nom de l'outil, un ID unique et les arguments d'entrée que Claude veut transmettre à votre fonctionChaque bloc tool_use doit être répondu par un bloc tool_result dans le tour utilisateur immédiatement suivant. Le tool_result doit porter le même ID. Sans cet appairage, l'API rejette la demande suivante. bloc tool_resultUtilisateurID tool_use correspondant, le contenu du résultat et un drapeau is_error optionnel défini sur true lorsque l'appel d'outil échoueLa valeur tool_use_id doit correspondre exactement au bloc tool_use original. Claude utilise cet ID pour connecter chaque résultat à l'appel qui l'a produit, ce qui importe lorsqu'un tour assistant unique émet plusieurs appels d'outils et que les résultats arrivent dans un ordre différent. bloc de réflexionAssistant (réflexion étendue uniquement)/ClaudeRaisonnement interne de Claude, visible uniquement lorsque la réflexion étendue est activéeLe bloc doit être retourné à l'API inchangé dans les tours suivants. La signature vérifie que le raisonnement n'a pas été modifié, donc toute modification ou résumé casse la signature et l'API rejette le message. Les blocs de réflexion réduits suivent la même règle : les retourner tels que reçus, même si le contenu est chiffré et non lisible par l'homme.

L'invariant critique est que chaque bloc tool_use d'un tour assistant doit avoir un bloc tool_result correspondant dans le tour utilisateur immédiatement suivant. Les blocs tool_result manquants ou les blocs tool_result qui apparaissent dans un tour ultérieur plutôt que dans le tour utilisateur immédiatement suivant causent une erreur de validation de l'API.

Anatomie du schéma : Ce que Claude lit pour prendre une décision de sélection d'outil Un schéma d'outil a trois parties, y compris le nom, la description et input_schema. La description détermine si Claude sélectionne l'outil correctement ou non.

Nom : Un court identifiant qui doit être spécifique. Par exemple, get_account_balance est plus utile à Claude que get_data. Description : Une partie critique que Claude lit pour décider si un outil est requis ou non. Vous devez toujours écrire la description en deux parties, y compris quand utiliser et quand ne pas utiliser l'outil :

Une description qui dit « use this to find information » causera des sélections incorrectes car Claude ne peut pas la distinguer de tout autre outil qui récupère quelque chose. Une description qui dit « use this to retrieve the current balance for a specific account ID and do not use this for transaction history » donne à Claude une condition d'exclusion avec laquelle travailler et est appropriée descriptive.

input_schema : Définit les paramètres (les entrées que votre fonction d'outil accepte) en utilisant JSON Schema.

Vous devez marquer les paramètres comme requis lorsque Claude les nécessite pour appeler l'outil correctement. Vous pouvez marquer les paramètres comme optionnels lorsque l'outil peut fonctionner sans eux. Les types de paramètres qui se chevauchent entre les outils sont la source la plus courante d'appels d'outils incorrects.

Tableau de décision : Choix de conception du schéma Le schéma est ce que Claude lit pour décider quel outil appeler, quels arguments passer et s'il a suffisamment d'informations pour répondre. Un schéma vague, sous-décrit ou manquant de champs requis produira des appels d'outils qui semblent syntaxiquement corrects mais qui choisissent le mauvais outil, passent des entrées mal formées ou boucles inutilement. Les cinq décisions ci-dessous déterminent si votre implémentation se comporte de manière prévisible dans des conditions réelles. Le tableau note où l'appel séquentiel et parallèle divergent.

DécisionComment la gérerPourquoi c'est important Dépendance de sous-tâcheQuand la sortie d'un outil alimente le suivant, les appels doivent s'exécuter en séquence car le deuxième appel ne peut pas être construit jusqu'à ce que le premier résultat revienne. Lorsque les sous-tâches sont indépendantes les unes des autres, vous pouvez structurer l'ensemble d'outils afin que Claude émette plusieurs blocs tool_use dans un seul tour et que votre code les exécute simultanément. C'est la seule décision qui change la façon dont vous concevez le schéma. Les modèles Claude actuels par défaut aux appels parallèles lorsque les appels sont indépendants. Lorsqu'une vraie dépendance existe, modélisez-la comme des tours séparés afin que le premier résultat soit disponible avant que le prochain appel soit construit. Utilisez disable_parallel_tool_use pour forcer un appel d'outil par tour si nécessaire. Champs obligatoiresMarquez un champ comme requis uniquement lorsque l'appel n'a pas de sens sans lui. Placez-les dans le tableau required du schéma d'entrée. Marquer tout comme requis force Claude à fabriquer des valeurs pour les champs qu'il n'a aucune base pour remplir. Le tableau required est la façon dont vous dites à Claude quelles entrées sont non négociables. Champs optionnelsUtilisez les champs optionnels pour les paramètres avec des valeurs par défaut sensées ou où l'absence a une signification. Laissez-les hors du tableau required et donnez-leur des valeurs par défaut dans la signature de fonction. Les champs optionnels permettent à Claude d'omettre les informations qu'il n'a pas, au lieu de deviner. Si un champ est optionnel mais marqué comme requis, chaque appel doit inventer une valeur, ce qui peut causer de mauvaises entrées. Longueur de descriptionÉcrivez trois à quatre phrases par outil couvrant ce qu'il fait, quand Claude devrait l'utiliser et ce qu'il retourne. Incluez des exemples d'entrées valides où le format importe. Si la description est trop courte, Claude devine car il n'y a pas assez de signal pour distinguer votre outil des autres. Si la description est trop longue, les conditions de déclenchement se perdent sous les détails que Claude ne référence pas au moment de la décision. Types de paramètres qui se chevauchentQuand deux outils acceptent la même forme de paramètre, ajoutez un langage de désambiguïsation à chaque description qui nomme le domaine ou le déclencheur pour lequel l'outil est destiné. Claude route sur le nom plus la description, avec les types de paramètres comme signal secondaire. Lorsque les signatures sont identiques, le routage s'effondre à la description seule, et les descriptions qui sonnent similaires deviennent indistinguibles.

Exemple travaillé : Un schéma qui cause une mauvaise sélection d'outil et la correction Ceci est un exemple illustratif basé sur des modèles courants observés dans les implémentations d'utilisation d'outils. Les noms d'outils, les descriptions et les résultats de test sont construits pour démontrer le principe de désambiguïsation de sélection, non tirés d'un système de production spécifique. Un développeur enregistre deux outils, y compris search_knowledge_base et get_cached_result. Les noms d'outils sont distincts, mais la sélection d'outil de Claude pèse fortement les descriptions ; lorsque les descriptions se chevauchent, le nom seul n'est pas suffisant pour désambiguïser. Les deux ont des descriptions qui commencent par « use this to find information. » Sans conditions d'exclusion, Claude a fréquemment sélectionné le mauvais outil sur les entrées ambigus lors des tests de développement. Le problème est que les deux descriptions ressemblent à la même chose pour Claude au moment où la décision de sélection est prise. La correction consiste à ajouter une phrase supplémentaire par description :

search_knowledge_base: "Use this to search the knowledge base when the user asks a question that requires looking up current information. Do not use this if the result of a prior search in this session already covers the question. "

get_cached_result: "Use this to retrieve a result that was already fetched during this session. Only use this if search_knowledge_base was called earlier in this conversation for the same query. "

Les conditions d'exclusion donnent à Claude une règle de décision plutôt que deux options qui se ressemblent. Ces conditions s'appuient sur l'historique complet de la conversation étant transmis à chaque demande. Si les tours antérieurs sont tronqués ou supprimés, Claude ne peut pas les évaluer et la logique d'exclusion échoue silencieusement. Chaque outil supplémentaire que vous enregistrez augmente la surface que Claude doit raisonner, donc cette discipline ne paie que lorsque les outils sous-jacents sont distincts. Le tableau ci-dessous montre où la désambiguïsation par condition d'exclusion aide et où une approche différente est justifiée.

Gère bienLe routage de Claude vers le bon outil de manière fiable lorsque les descriptions sont spécifiques et que les conditions d'exclusion sont énoncées. Mauvais ajustement. Deux outils qui font des choses similaires et qui ont besoin de descriptions de plus en plus longues pour rester séparés : à ce stade, fusionnez-les en un seul outil avec un paramètre de type à la place.

Quand quelqu'un d'autre a déjà écrit vos outils : MCP comme alternative à la création manuelle de schémas Tout dans les sections précédentes suppose que vous écrivez vous-même les schémas d'outils : nom, description, input_schema et la fonction qui s'exécute lorsque Claude émet un bloc tool_use. Pour de nombreuses intégrations, vous n'avez pas besoin de le faire. Le Model Context Protocol, MCP, est une couche de communication standardisée qui déplace les définitions d'outils et l'exécution hors de votre code d'application et dans des serveurs dédiés. Lorsqu'un serveur MCP existe pour le service que vous souhaitez atteindre, vous pouvez vous connecter directement au serveur MCP plutôt que de construire l'intégration vous-même. Prenez une intégration GitHub comme cas concret. GitHub expose les référentiels, les demandes d'extraction, les problèmes, les projets et bien d'autres. Pour construire une intégration complète en utilisant l'approche de schéma d'outil de ce module, vous devriez écrire un schéma et une fonction d'exécution pour chaque élément de cette fonctionnalité et la maintenir à mesure que l'API de GitHub évolue. Un serveur MCP pour GitHub a déjà fait cela. Donc, votre application se connecte au serveur, reçoit la liste complète des outils disponibles et Claude sélectionne parmi eux en utilisant le même routage basé sur la description avec lequel vous avez déjà travaillé. Le mécanisme sous-jacent est identique, mais ce qui change, c'est qui l'a écrit et qui possède les définitions d'outils.

Comment MCP s'intègre dans la boucle d'utilisation d'outils La boucle que vous avez construite plus tôt dans ce module ne change pas lorsque vous introduisez MCP. Claude émet toujours un bloc tool_use, votre application exécute toujours l'outil et retourne un tool_result, et les règles d'appairage des blocs de message s'appliquent toujours. La différence est à l'étape de configuration. Au lieu d'enregistrer les schémas que vous avez écrits, votre client MCP envoie une ListToolsRequest au serveur MCP, reçoit la liste complète des outils en retour et transmet ces définitions à Claude. Du point de vue de Claude, ces outils sont indistinguibles de ceux que vous avez créés manuellement. Une implication pratique à noter : les serveurs MCP ajoutent des définitions d'outils à la fenêtre de contexte même lorsque les outils ne sont pas utilisés dans le tour actuel. Si vous connectez plusieurs serveurs à la fois, les définitions d'outils elles-mêmes consomment le budget avant que le premier message n'arrive. La discipline de conception de schéma des sections précédentes de ce module s'applique ici aussi. Enregistrez uniquement les serveurs que vous utilisez activement et vérifiez le coût du contexte par rapport à votre limite de fenêtre si vous connectez plusieurs serveurs dans la même session. Si vous utilisez le connecteur MCP de l'API, vous contrôlez le coût de chargement via un objet mcp_toolset dans le tableau tools. Le mcp_toolset porte un bloc default_config qui s'applique à chaque outil sur le serveur, et vous pouvez remplacer les outils individuels via des configs indexées par nom d'outil. Deux paramètres importent pour le coût du contexte :

Le booléen defer_loading, défini à l'intérieur de default_config ou d'une entrée par outil dans configs, retarde le chargement d'une définition d'outil jusqu'à ce que le modèle en ait besoin, ce qui réduit le coût du contexte initial lorsque vous connectez un serveur avec une grande liste d'outils. Le booléen enabled active ou désactive les outils individuels, afin que vous puissiez enregistrer un serveur mais exposer uniquement les outils que vous souhaitez que le modèle voie. Le connecteur MCP nécessite que l'en-tête bêta mcp-client-2025-11-20 soit défini sur la demande.

Sans cet en-tête, la configuration mcp_toolset ne s'appliquera pas comme décrit ici. L'autre élément à connaître à ce stade est la façon dont le client communique réellement avec le serveur. MCP s'exécute sur l'un des deux transports, et celui que vous utilisez dépend de l'endroit où le serveur se trouve. Les serveurs locaux utilisent stdio et votre application génère le serveur en tant que sous-processus et communique via l'entrée et la sortie standard. Les serveurs distants utilisent HTTP diffusable et votre application se connecte via le réseau via HTTP, en utilisant POST pour les messages client-vers-serveur et un flux SSE optionnel basé sur GET pour les messages initiés par le serveur. Un transport SSE uniquement plus ancien existe mais est déprécié, et les nouvelles intégrations doivent utiliser HTTP diffusable. Une contrainte à signaler si vous utilisez le connecteur MCP d'Anthropic dans l'API : seuls les serveurs exposés via HTTP sont pris en charge via le connecteur, et les serveurs stdio nécessitent de gérer vous-même la connexion client MCP via le SDK. Une fois la connexion établie et les définitions d'outils reçues, votre code d'application traite les deux transports de manière identique.

Utilisez MCP quand Un serveur MCP bien maintenu existe déjà pour le service dont vous avez besoin (vérifiez qu'il couvre les opérations spécifiques dont vous avez besoin et qu'il est activement maintenu par rapport à l'API actuelle du service. Écrire et posséder ces schémas vous-même ajoute une surcharge d'implémentation sans capacité supplémentaire. Notez que le connecteur MCP de l'API Claude ne prend en charge que les serveurs distants. Les serveurs stdio locaux nécessitent Claude Desktop ou Claude Code comme client ; ils ne peuvent pas être connectés directement via l'API.

Écrivez les schémas manuellement quand Aucun serveur MCP ne couvre votre cas d'utilisation, ou lorsque vous avez besoin d'un contrôle précis sur la portée et la qualité de la description des outils qu'un serveur à usage général ne fournit pas. Avant de choisir par défaut la création manuelle de schémas pour le contrôle de portée, notez que le connecteur MCP de l'API prend en charge la liste blanche et la liste noire d'outils spécifiques par serveur via la configuration MCPToolset. La création manuelle peut toujours être justifiée pour la qualité de la description, mais pas toujours pour la portée.

Utilisez les deux quand Connectez-vous à un serveur MCP pour la largeur, puis appliquez la discipline de réglage de la description des sections précédentes de ce module aux outils spécifiques que vous routez activement. MCP et la création manuelle de schémas ne s'excluent pas mutuellement car le serveur vous donne une couverture et vos descriptions vous donnent de la précision où elle importe. Appliquez la liste blanche d'outils via MCPToolset pour limiter la surface que Claude raisonne avant de superposer le réglage de la description. Réduire l'ensemble d'outils et affiner les descriptions sont deux leviers séparés, et vous devez utiliser les deux.

Screen 8: The description that sent Claude to the wrong tool

Watch OutTool-use and Schema Design·5 min La description qui a envoyé Claude au mauvais outil

Setup Un schéma peut sembler correct et échouer quand même. Les paramètres typés et les tests de chemin heureux vous disent que la structure est valide, mais ils ne vous disent pas si Claude peut choisir de manière fiable entre vos outils lorsqu'une entrée se situe près de la limite de deux descriptions qui se chevauchent. C'est le mode de défaillance que les tests initiaux manquent et celui le plus susceptible de faire surface pendant la production.

Un Developer est trois heures dans une revue de code lorsqu'il colle une conversation de canal interne dans une session de débogage. Ceci est un échange composite basé sur des modèles courants dans les conversations de débogage des développeurs. Le dialogue est construit pour illustrer le moment diagnostique où le chevauchement de description est nommé, non transcrit à partir d'une revue de code spécifique. Regardons l'échange ci-dessous qui se produit après qu'un Developer ait débogué des sélections d'outils incorrectes depuis le matin. Le Senior Developer pose une question qui reframe tout le problème :

Developer: "Why does Claude keep calling search_docs when the answer is already in the context? I've re-run this four times, and it keeps going to the wrong tool. " Senior Developer: "What does the description for search_docs say? " Developer: "'Use this to find information about the product. '" Senior Developer: "And what does get_context_summary say? " Developer: "'Use this to retrieve relevant information from the current session. '" Senior Developer: "Those descriptions are the same thing from Claude's perspective. Both say, 'find information. ' One of them needs to say when not to call it. " Developer: "So, I need to add an exclusion? " Senior Developer: "Right. Try using search_docs 'when the user asks a question that requires looking up content not already present in this conversation. Do not call this if the answer is available in the current session context. ' Then get_context_summary handles the in-context case. You will want to tighten get_context_summary's description the same way: add 'Only use this if the answer is already present in the current session. Do not use this to look up new information. ' Both tools need the boundary, not just one. " Developer: "That's two sentences. " Senior Developer: "Right. One to say when to use it, one to say when not to. That's the whole fix. "

What to Watch Out for Claude sélectionne un outil en raisonnant sur toutes les descriptions enregistrées dans le contexte du message complet. Lorsque deux descriptions se ressemblent, ce raisonnement n'a pas de signal fiable pour les distinguer, donc Claude choisit en fonction de petites différences de surface qui peuvent ne pas correspondre à la distinction que vous aviez l'intention. Lorsque la défaillance est des descriptions qui se chevauchent, la correction est cohérente : ajouter une phrase nommant quand ne pas appeler l'outil pour donner à Claude une limite de décision. Si les descriptions ne peuvent pas être nettement séparées même avec des conditions d'exclusion, les outils peuvent avoir besoin d'être fusionnés en un seul avec un paramètre de type à la place.

Screen 9: Checkpoint 3 · Spot and fix the schema bug

CheckpointTool-use and Schema Design·4 min Checkpoint 3 · Repérer et corriger le bug du schéma La trace de session ci-dessous montre un agent appelant un outil, recevant un résultat et échouant ensuite avec une erreur de validation de l'API à la demande suivante. Le schéma est valide, la description de l'outil est spécifique et le contenu du résultat de l'outil est correct. Une convention à connaître avant de lire la trace : les blocs tool_result sont toujours envoyés dans le rôle utilisateur, même si le contenu est généré par votre application plutôt que tapé par une personne. Le champ role marque qui envoie le message à Claude, pas qui a créé le contenu sous-jacent. Le tour 3 dans la trace est étiqueté « User (tool result) » pour rendre cette affectation explicite. Lisez la trace, identifiez quel bloc de message manque ou est mal ordonné, nommez la règle qui a été violée et sélectionnez la correction ciblée parmi les trois options ci-dessous.

Session trace Turn 1: User: [text]: "What is the current balance for account A-4471? "

Turn 2: Assistant: [text]: "I'll look that up. " [tool_use]: id="toolu_01", name="get_account_balance", input={"account_id": "A-4471"}

Turn 3: User (tool result): [tool_result]: tool_use_id="toolu_02", content="Balance: $1,240. 18"

Turn 4: API response: Error: invalid_request_error "tool_result block references unknown tool_use_id"

AMettre à jour la description sur get_account_balance pour ajouter une condition d'exclusion. BCorriger le tool_use_id sur le bloc tool_result afin qu'il corresponde à l'id émis dans le tour assistant. CAjouter un tableau required au input_schema de l'outil afin que account_id ne puisse pas être omis.

Submit Skip for now

Screen 10: Streaming responses and handling partial output without corrupting state

TeachingStreaming Responses·16 min Réponses en streaming et gestion de la sortie partielle sans corrompre l'état Chaque demande jusqu'à présent a attendu que la réponse complète arrive avant de faire quoi que ce soit avec elle. C'est bien, jusqu'à ce que la réponse soit longue ou qu'un utilisateur regarde un écran vide. Le streaming envoie la réponse en morceaux, les envoyant à mesure que le modèle les génère. Cela rend les choses plus rapides, mais cela donne aussi à votre code un nouveau travail : maintenant vous êtes chargé d'assembler la sortie finale vous-même en fonction de la série de résultats, et vous devez être préparé si la série s'arrête tôt.

Ce que le streaming change dans la réponse Dans une demande non diffusée, l'API vous remet un message complet avec chaque bloc de contenu, entièrement formé. Dans une demande diffusée, l'API envoie à la place une série d'événements qui décrivent le message au fur et à mesure de sa construction. Votre code écoute cette série et réassemble les blocs. Le message que vous finissez par obtenir est identique à ce qu'un appel non diffusé vous aurait donné, mais la différence est que vous devez assembler les pièces et vous décidez quoi faire si les événements s'arrêtent avant que le message soit terminé. Il aide de savoir ce qui ne se passe pas : le modèle ne tient pas un objet en direct ouvert pour vous. Chaque événement est son propre petit message décrivant un seul changement, un bloc a commencé, du texte ou une entrée a été ajouté à celui-ci, un bloc a terminé, le message entier a terminé. Votre gestionnaire prend chaque événement et l'applique à l'état partiel qu'il a construit.

La séquence d'événements et ce que votre gestionnaire fait avec chacun

ÉvénementCe qu'il signaleQuoi faire pour votre gestionnaire message_startUn nouveau message commence. Porte la coque du message avec un contenu vide et une utilisation initiale. Configurez un tableau de contenu vide pour collecter les blocs. content_block_startUn nouveau bloc de contenu s'ouvre, avec son type (texte, tool_use ou réflexion) et son index. Créez un emplacement à cet index pour le type de bloc nommé. Un bloc tool_use s'ouvre avec son nom et son id, mais pas encore d'entrée. content_block_deltaUn morceau supplémentaire d'un bloc : un fragment de texte, un fragment d'entrée JSON pour un appel d'outil ou un fragment de réflexion. Ajoutez le fragment au bloc à cet index. Les entrées d'appel d'outil arrivent sous forme de chaîne JSON partielle répartie sur plusieurs deltas, vous ne pouvez pas les analyser jusqu'à ce que le bloc se ferme. content_block_stopLe bloc à cet index est complet. Finalisez le bloc. Pour un bloc tool_use, c'est le premier moment où l'entrée JSON accumulée est suffisamment complète pour être analysée. message_deltaChangements au niveau du message : le stop_reason et les nombres d'utilisation finaux. Enregistrez le stop_reason. Il vous indique si le modèle a terminé ou s'il s'est arrêté pour une autre raison. message_stopLe stream est complet. Le tableau de contenu assemblé est maintenant le message terminé. À partir de là, traitez-le exactement comme une réponse non diffusée.

La règle qui empêche votre état de se corrompre : n'agissez pas sur un bloc partiel Le bloc tool_use est celui à surveiller. Son entrée apparaît sous forme de chaîne JSON partielle répartie sur de nombreux événements content_block_delta, et cette chaîne n'est pas du JSON valide jusqu'à ce que content_block_stop ferme le bloc. Si votre code essaie d'analyser l'entrée ou d'exécuter l'outil avant que le bloc se ferme, il s'étouffe soit sur du JSON mal formé, soit s'exécute avec la moitié des arguments manquants. Donc, la règle est simple : collectez les deltas et agissez uniquement après content_block_stop pour ce bloc. La même discipline s'applique lorsque vous ajoutez un tour assistant diffusé à votre historique de conversation. Ajoutez-le uniquement après message_stop, avec chaque bloc entièrement assemblé. Un tour construit à partir d'un stream qui a été coupé à mi-chemin est incomplet, et les règles d'appairage tool_use rejetteront votre demande suivante si un bloc tool_use à moitié construit se retrouve dans l'historique.

Quand le stream s'arrête tôt Les streams échouent parfois au milieu. Une connexion réseau interrompue, un délai d'attente ou une déconnexion client peuvent terminer la série d'événements avant que message_stop n'arrive. La défaillance qui mord vraiment est de traiter ce que vous avez collecté jusqu'à présent comme s'il était complet. Un bloc de texte partiel montré à un utilisateur n'est qu'un problème cosmétique et un bloc tool_use partiel écrit dans l'historique est un problème structurel qui corrompt le tour suivant.

Suivez l'achèvement à dessein. Un tour n'est utilisable qu'une fois que message_stop est arrivé. Jusqu'à là, traitez ce que vous avez accumulé comme provisoire. Sur un stream interrompu, jetez le tour assistant partiel au lieu de l'enregistrer dans l'historique, puis réessayez la demande. Valider un tour à moitié construit est exactement ce qui casse la demande suivante. Vérifiez le stop_reason de message_delta avant de continuer une boucle. Un stop_reason de tool_use signifie que vos appels d'outils assemblés sont prêts à s'exécuter ; toute autre valeur signifie que vous êtes sur un chemin différent, pas le chemin d'outil.

Gère bienLes réponses longues et les interfaces orientées utilisateur où afficher la sortie au fur et à mesure de sa génération supprime l'attente d'écran vide. Ajoute du coût ou de la complexitéVous assemblez les blocs vous-même, vous ne devez pas agir sur les blocs partiels et vous devez gérer explicitement l'interruption à mi-stream. Utilisez une approche différentePour les réponses courtes ou les travaux backend où personne n'attend la sortie, un appel non diffusé est plus simple et supprime le risque d'état partiel entièrement.

Screen 11: The stream that left a half-written tool call in the history

Watch OutStreaming Responses·5 min Le stream qui a laissé un appel d'outil à moitié écrit dans l'historique

Setup Une réponse diffusée peut sembler bien à l'écran et corrompre quand même la demande suivante. Le texte a été rendu, l'utilisateur a vu une réponse et le gestionnaire a ajouté le tour à l'historique. Ce que le gestionnaire n'a pas attrapé, c'est que le stream s'est arrêté au milieu du bloc, donc l'appel tool_use qu'il a stocké manquait la moitié de son entrée. La demande suivante échoue la validation et l'erreur pointe vers le tour suivant et non le stream qui l'a causé.

Autopsie : bloc tool_use partiel validé dans l'historique après un stream interrompu Un agent utilisait le streaming afin que ses opérateurs puissent regarder les réponses se générer en temps réel. Le gestionnaire a accumulé les événements content_block_delta et a ajouté le tour assistant à l'historique lorsque sa boucle de lecture s'est terminée. En test sur une connexion locale rapide, les streams s'exécutaient toujours jusqu'à la fin, donc la boucle s'arrêtait toujours à message_stop et les tours stockés étaient toujours complets. En production, un problème réseau a terminé un stream après que le bloc tool_use s'était ouvert et avait reçu une partie de son entrée JSON, mais avant content_block_stop. La boucle de lecture s'est terminée de la même manière qu'elle l'avait toujours fait, donc le gestionnaire a ajouté le tour : un tour assistant contenant un bloc tool_use dont la chaîne d'entrée était du JSON tronqué. L'opérateur a vu une réponse partielle et a réessayé. La demande de nouvelle tentative incluait ce tour corrompu dans l'historique, et l'API l'a rejeté avec une erreur de validation pointant vers le bloc tool_use mal formé. L'équipe a passé un après-midi à inspecter le schéma et la logique de nouvelle tentative, car l'erreur a fait surface sur la demande de nouvelle tentative. Cependant, la cause réelle était en amont : le gestionnaire traitait « la boucle de lecture s'est terminée » comme équivalent à « le message est complet », et ce ne sont pas les mêmes.

What to Watch Out for Un stream qui se termine n'est pas la même chose qu'un message qui se termine. Seul message_stop signifie que le message est complet. Si votre gestionnaire valide un tour chaque fois que sa boucle de lecture se termine, un stream interrompu écrit un bloc à moitié construit dans l'historique, et la défaillance apparaît à la demande suivante plutôt qu'à celle qui l'a causée. Portez l'ajout d'historique sur message_stop, jetez le tour partiel en cas d'interruption et réessayez à partir du dernier tour complet. Lorsqu'une erreur d'utilisation d'outil apparaît sur une nouvelle tentative, vérifiez si le tour antérieur a été assemblé à partir d'un stream avant de toucher le schéma.

Screen 12: Checkpoint 4 · Repair the broken stream handler

CheckpointStreaming Responses·4 min Checkpoint 4 · Réparer le gestionnaire de stream cassé Le gestionnaire ci-dessous diffuse une réponse et ajoute le tour assistant à l'historique de conversation. Il contient un défaut qui ne fait surface que lorsqu'un stream est interrompu. Identifiez le défaut et écrivez la version corrigée.

Broken handler blocks = {} stop_seen = False with client. messages. stream(model=model, max_tokens=4096, messages=messages, tools=tools) as stream: for event in stream: if event. type == "content_block_start": blocks[event. index] = init_block(event) elif event. type == "content_block_delta": apply_delta(blocks[event. index], event. delta) elif event. type == "message_stop": stop_seen = True messages. append({"role": "assistant", "content": assemble(blocks)})

Reveal model answer Skip for now

Screen 13: Model selection and keeping multi-turn sessions in budget

TeachingContext Engineering·16 min Sélection du modèle et maintien des sessions multi-tours dans le budget Vous faites un choix précoce : quel modèle exécute la charge de travail. La famille Claude couvre une gamme de compromis coût, latence et capacité, donc le modèle que vous choisissez définit le prix et le plancher de vitesse que chaque décision ultérieure se déplace. Une fois le modèle défini, la contrainte suivante est la fenêtre de contexte : l'étendue complète du texte que le modèle peut traiter à la fois, y compris votre invite, la conversation jusqu'à présent et chaque résultat d'outil. Chaque résultat d'outil que Claude retourne est ajouté à la fenêtre de contexte et y reste pour le reste de la session. Dans une invite à un seul tour, c'est invisible. Dans une session d'agent multi-étapes exécutant dix ou vingt appels d'outils, la fenêtre se remplit rapidement, et une fois qu'elle se remplit, l'agent soit compacte (perdant des détails) soit s'arrête avant que la tâche ne soit terminée. Donc, la question pour tout flux de travail d'agent est de savoir si vous avez décidé à l'avance ce qui entre dans la fenêtre de contexte, ce qui en sort sous forme de résumé et ce qui n'y entre jamais. Cet ensemble de choix est l'ingénierie du contexte.

Sélection du modèle : Commencez par Sonnet, avancez délibérément La famille de modèles Claude couvre actuellement quatre niveaux : Fable, Opus, Sonnet et Haiku, chacun optimisé pour différents compromis coût, latence et capacité. Sonnet est le défaut équilibré pour la plupart des charges de travail de production. Haiku est construit pour la vitesse et l'efficacité des coûts sur les tâches qui correspondent à son enveloppe de capacité. Opus gère le travail exigeant au-dessus de l'enveloppe Sonnet, et Fable est le modèle le plus capable d'Anthropic, construit pour les tâches les plus exigeantes, y compris le raisonnement complexe, le codage avancé, la synthèse de recherche et les flux de travail agentic sophistiqués où l'intelligence maximale est la priorité. Confirmez l'alignement actuel et les identifiants de modèle par rapport à platform. claude. com/docs au moment de la construction. Le point de départ par défaut est Sonnet. Passez à Opus uniquement lorsqu'un ensemble d'évaluation vous indique que Sonnet ne répond pas à votre barre de qualité. Passez à Haiku uniquement lorsqu'un ensemble d'évaluation vous indique que la régression de qualité est acceptable à votre tâche, pas seulement pour économiser des coûts. Votre décision de changer de modèle doit toujours être une décision mesurée.

La fenêtre de contexte n'est pas une ressource gratuite Pensez à la fenêtre de contexte comme la quantité d'espace que Claude peut tenir en mémoire de travail. Chaque message que vous envoyez, chaque résultat d'outil que vous retournez, chaque document que vous injectez et chaque réponse que Claude génère occupe de l'espace dans cette fenêtre. Si une demande est déjà plus grande que la fenêtre de contexte, l'API Messages la rejette avec une erreur de validation avant la génération ; si une demande s'adapte mais que la génération atteint le plafond à mi-chemin, les modèles actuels retournent la sortie générée jusqu'à présent avec une raison d'arrêt model_context_window_exceeded. Aucun chemin ne tronque silencieusement votre contenu le plus ancien. Si vous voulez qu'une session continue au-delà de la limite de fenêtre, votre application doit gérer cela elle-même en coupant ou en résumant l'historique avant que la demande suivante ne sorte. En développement, la fenêtre se remplit rarement car les entrées de test sont petites et les sessions sont courtes. En production, les résultats d'outils sont souvent trois à cinq fois plus longs que les fixtures de test, les sessions s'exécutent pendant plus de tours et la fenêtre se remplit au tour huit plutôt qu'au tour cinquante, ce qui signifie qu'elles se remplissent plus tôt que le développement. Le coût de ne pas planifier cela est une panne en production.

Quatre stratégies pour rester dans le budget La section précédente a plaidé pour déplacer l'état hors de la fenêtre de contexte en direct. La raison en est le budget. Chaque token dans la fenêtre coûte de l'argent en entrée et ajoute de la latence à la réponse, et une longue session compose les deux. Les quatre stratégies ci-dessous sont des façons concrètes de gérer ce budget, chacune adaptée à une forme différente de conversation.

StratégieQuoi elle faitQuand l'appliquerQuelle continuité vous perdez

Élagage Vous permet de revenir à un message antérieur et de continuer à partir de là, supprimant la conversation qui a suivi. Après que Claude soit allé sur un chemin improductif ou ait accumulé des allers-retours de débogage qui n'aideront pas la tâche suivante. Le travail effectué après le point de rembobinage est parti. Si Claude a appris quelque chose d'utile dans cette section, il doit le réapprendre.

Compaction (/compact dans Claude Code ; compaction côté serveur dans l'API, une stratégie bêta que la plateforme effectue pour vous, avec résumé manuel comme alternative côté client) Résume l'historique de conversation en une version condensée qui préserve les informations clés que Claude a apprises. Le résumé coûte moins de tokens que les tours originaux. Lorsque la session approche du plafond du contexte mais que vous souhaitez continuer à travailler sur la même fonctionnalité avec les connaissances que Claude a accumulées. Les détails peuvent être perdus dans la résumé. Tout ce qui n'est pas capturé dans le résumé ne sera pas disponible pour Claude à l'avenir.

Effacement (/clear dans Claude Code ; nouvelle session dans l'API) Démarre une nouvelle conversation avec un contexte vide. Rien de la session précédente ne se transporte. Lorsque la tâche suivante est complètement différente de la tâche actuelle et que le contexte antérieur n'introduirait que du biais ou de la confusion. Tout le contexte de session est parti. Tout ce que Claude doit se souvenir entre les sessions doit être mis quelque part de persistant, comme un fichier CLAUDE. md.

Transferts de sous-agents Génère un sous-agent dans sa propre fenêtre de contexte isolée avec uniquement la description de tâche et l'invite système dont il a besoin. Le sous-agent fait le travail et retourne un résumé. Lorsqu'une sous-tâche est suffisamment autonome pour être déléguée, en particulier le travail d'exploration où le voyage encombre le contexte principal mais la réponse est courte. Visibilité sur la façon dont le sous-agent a atteint sa conclusion. Les étapes intermédiaires sont jetées avec le contexte du sous-agent.

Deux leviers supplémentaires : mise en cache des invites et comptage des tokens Les quatre stratégies ci-dessus gèrent ce qui entre dans la fenêtre de contexte. Deux fonctionnalités de l'API réduisent ce que vous payez pour ce qui y est déjà. La mise en cache des invites stocke le travail de traitement effectué sur un préfixe stable de votre demande afin que les demandes de suivi puissent le réutiliser au lieu de retraiter les mêmes tokens. La première demande écrit le préfixe en cache ; les demandes suivantes qui envoient du contenu identique jusqu'à ce point paient une fraction du coût d'origine. Les candidats les plus forts sont les parties de la demande qui changent rarement entre les tours : une longue invite système, un grand ensemble de définitions d'outils ou un document de référence que vous interrogez à plusieurs reprises. Vous activez la mise en cache en marquant un point de rupture de cache avec un champ cache_control de type ephemeral sur le dernier bloc que vous souhaitez mettre en cache. Vous pouvez placer jusqu'à quatre points de rupture. Pour les sessions multi-tours avec une invite système stable et des schémas d'outils, mettre en cache ces préfixes une fois et les réutiliser entre les tours est la réduction de coût à plus haut effet de levier disponible. Le comptage des tokens vous permet de mesurer la pression du contexte avant qu'une demande ne sorte plutôt qu'après son échec. Le point de terminaison count_tokens prend le même corps de demande qu'un appel messages et retourne le nombre de tokens sans exécuter l'inférence. Utilisez-le pendant le développement pour vérifier que vos hypothèses de budget de contexte tiennent contre les résultats d'outils réels, pas seulement les fixtures de test, et en production pour bloquer les demandes qui dépasseraient la fenêtre avant qu'elles ne génèrent une erreur.

Les trois endroits où un chemin RAG peut se casser Le chemin a trois endroits où il peut mal tourner : le chunking, la correspondance d'embedding et l'assemblage dans l'invite.

Le chunking décide ce qu'est une unité de contexte récupérable. Divisez trop petit et un seul chunk manque du contexte environnant pour être utile. Divisez trop grand et un chunk dilue la correspondance avec du texte non lié. Le chunking basé sur les phrases ou les sections avec un peu de chevauchement est un défaut raisonnable. Le chevauchement importe car les faits qui franchissent une limite seraient autrement divisés et deviendraient difficiles à récupérer. La correspondance d'embedding décide quels chunks sont retournés. Elle utilise une recherche de similarité, elle récupère donc le contenu qui est sémantiquement proche. Ce n'est pas toujours ce qui contient le terme exact dont vous avez besoin. Une requête pour un identifiant spécifique peut manquer le chunk pertinent si un résultat sémantiquement plus similaire le dépasse. C'est pourquoi une correspondance lexicale est parfois exécutée aux côtés de la correspondance sémantique. L'étape d'assemblage est l'endroit où les chunks récupérés doivent atteindre le modèle dans la structure que l'invite attend, sinon le modèle répond de la mémoire au lieu du texte récupéré.

Le chemin fetch-once vous donne un système que vous pouvez raisonner : vous pouvez inspecter quels chunks ont été récupérés pour une requête et tester cette récupération directement. Le coût est l'infrastructure : l'index qui doit être construit, stocké, maintenu à jour à mesure que le corpus change et sécurisé où qu'il vive. Le chemin search-across-rounds supprime cette infrastructure et l'obsolescence qui en découle, puisque le modèle lit les fichiers actuels au moment de la requête, au coût de dépenser plus de tokens et de temps par requête et de vous donner un processus moins inspectable. Pour un corpus de référence stable interrogé avec des recherches simples, l'index vaut la peine d'être possédé. Pour un corpus changeant ou des questions multi-étapes, la recherche itérative est généralement le système plus simple malgré un coût plus élevé par requête. Le gain de performance signalé pour la recherche agentic à agent unique sur un index de récupération est une figure épinglée à la version du modèle. Confirmez-la par rapport à la couche de référence au moment de la construction plutôt que de vous fier au nombre dans ce module.

Maintenant, comprenons un peu deux des stratégies les plus courantes : la compaction et les transferts de sous-agents.

Application de la compaction : Ce qui est préservé dépend de la façon dont vous écrivez le résumeur Lorsque vous utilisez /compact dans Claude Code, l'outil décide ce qu'il faut inclure dans le résumé. Dans l'API, la stratégie documentée principale est la compaction côté serveur (bêta) : la plateforme résume la conversation pour vous lorsqu'elle est configurée sur la demande. Lorsque vous implémentez plutôt la compaction manuelle dans une session API, vous écrivez vous-même l'invite du résumeur. Cette invite détermine ce que l'agent saura dans les tours suivants.

L'invite du résumeur dit « résumez la conversation jusqu'à présent »Produit un résumé général qui peut perdre l'état critique de la tâche, les fichiers qui ont été modifiés, la décision prise à un point de branchement et l'erreur qui a été rencontrée et résolue. L'invite du résumeur dit « résumez la conversation, en préservant tous les chemins de fichiers modifiés, toutes les décisions prises et toutes les erreurs rencontrées et leurs résolutions »Produit un résumé que l'agent peut utiliser.

Ce n'est pas un cas limite ; la perte d'état critique de la tâche d'un résumeur sous-spécifié est l'une des sources les plus courantes d'échecs d'agents multi-sessions.

Transferts de sous-agents : Gestion des tâches à long horizon Lorsqu'une tâche est trop grande pour une seule fenêtre de contexte, augmenter la fenêtre n'est pas une solution. La solution est de décomposer la tâche et de transmettre uniquement le contexte pertinent à chaque sous-agent. Un sous-agent reçoit une tâche délimitée et le contexte minimum dont il a besoin, les résultats des étapes antérieures qui sont directement pertinents, les outils dont il a besoin pour accomplir sa tâche et des conditions de sortie claires. L'agent parent collecte les résultats. Ce modèle maintient le coût par tour bas et rend les tâches à long horizon tractables. Comme la compaction et l'élagage, les transferts de sous-agents ajoutent une surcharge d'implémentation, donc appliquez-les uniquement où le coût du contexte est une vraie contrainte : une invite simple à un seul tour ou un flux de travail court n'a pas besoin de cela.

Gère bienLes sessions d'agents multi-étapes qui dépassent le budget de tokens et ont besoin de décomposition. Mieux conçu au stade de l'architecture plutôt que corrigé en tant que correctif de production. Utilisez une approche différenteLes pipelines qui ne s'approchent jamais de la limite de fenêtre. Mesurez l'utilisation réelle des tokens par rapport à la limite de contexte de votre modèle avant d'ajouter une surcharge de gestion.

Forward pointer Les stratégies couvertes jusqu'à présent supposent que vous savez que votre budget de contexte est sous pression et que vous choisissez un outil pour le gérer. Le point critique ici est de ne pas savoir que la pression existe jusqu'à ce que la session se casse. Une charge de travail peut réussir chaque test en développement et échouer ensuite en production pour une raison : la sortie d'outil a augmenté, les sessions se sont allongées et la fenêtre de contexte qui tenait vingt tours proprement se remplit maintenant au tour huit. La section suivante parcourt exactement comment cela se produit, en utilisant une autopsie travaillée d'un agent qui s'est bien exécuté sur les fixtures de test puis a atteint son plafond une fois que les vrais documents ont commencé à circuler.

Screen 14: The session that ran fine in development, then hit a ceiling in production

Watch OutContext Engineering·5 min La session qui s'est bien déroulée en développement, puis a atteint un plafond en production

Setup Les résultats d'outils consomment du contexte de la même manière que les invites et les lectures de fichiers. La fenêtre de contexte est un budget fixe qui contient tout ce que Claude doit voir à un tour donné : l'invite système, l'historique de conversation et chaque appel d'outil et résultat d'outil accumulés jusqu'à présent. Lorsque les résultats d'outils sont courts, chaque tour ajoute une petite quantité à ce total courant et le budget dure longtemps. Lorsque les résultats d'outils deviennent plus grands, chaque tour ajoute plus au même total courant et le budget s'épuise plus rapidement. La fenêtre elle-même n'a pas changé ; ce qui a changé, c'est la quantité de budget que chaque tour dépense maintenant. Une session qui gère vingt tours proprement en développement peut commencer à échouer au tour huit en production pour exactement cette raison.

Autopsie : Budget de contexte jamais mesuré par rapport aux résultats d'outils de production Un agent a été construit pour traiter les reçus de vente sous un budget de fenêtre de contexte de 40k tokens, une limite que l'équipe a définie comme un contrôle de coût sur le contexte de l'agent plutôt que le plafond du modèle. Le modèle lui-même offrait beaucoup plus de place. Les modèles Claude API actuels portent au moins une fenêtre de contexte de 200k tokens, et les modèles phares les plus récents, Fable inclus, servent 1M tokens par défaut, donc la figure de 40k était une limite délibérée que l'équipe s'était imposée, pas une limite que le modèle leur forçait. Le développement a utilisé un ensemble de fixtures de test de vingt reçus, chacun retournant un résultat d'outil d'environ 800 tokens. La session complète de vingt tours a consommé environ 18 000 tokens, bien dans le budget de 40k tokens que l'équipe s'était imposé. En production, les reçus contenaient de la documentation de soutien, y compris les dossiers de transactions et la correspondance. La sortie d'outil moyenne a augmenté à environ 3 200 tokens par appel. Huit tours de sortie d'outil seuls ont totalisé environ 25 600 tokens, et une fois que l'invite système, les messages utilisateur et les messages assistant ont été ajoutés par-dessus, le total courant a atteint le budget de 40k de l'équipe. L'agent a atteint ce plafond au tour huit, avant de pouvoir terminer son analyse. La défaillance ressemblait à une dégradation de la sélection d'outil car l'agent a commencé à choisir les mauvais outils et à retourner des analyses incomplètes. Cependant, la cause sous-jacente était différente. L'invite système et les instructions précoces avaient été repoussées par les résultats d'outils accumulés qui n'avaient jamais été élagués après utilisation, et l'agent prenait des décisions sur une fenêtre de contexte qui ne contenait plus les conseils avec lesquels il avait commencé.

DéveloppementProduction Fenêtre de contexte disponible200k standard, 1M sur Opus et Sonnet actuels200k standard, 1M sur Opus et Sonnet actuels Budget de l'équipe40k tokens40k tokens Sortie d'outil moyenne~800 tokens par appel~3 200 tokens par appel Tours avant remplissage de la fenêtreLes sessions se terminent sans atteindre le capLe plafond est atteint au tour 8 Symptôme observéAucun. Les sessions se terminent proprement. Mauvaises sélections d'outils et sorties incomplètes à partir du tour 8 Cause racine identifiée parNon applicableAudit d'utilisation des tokens, deux jours après le déploiement CorrectifNon applicableÉlaguer les résultats d'outils après utilisation et appliquer la compaction de manière proactive avant que le plafond ne soit atteint

What to Watch Out for Les fixtures de test en développement étaient plus courtes que les données de production. C'est vrai pour presque chaque agent construit par rapport à un ensemble de fixtures. La correction est de mesurer le coût réel des tokens d'un résultat d'outil par rapport à la plus grande entrée que vous pouvez trouver dans vos données cibles avant que l'agent ne soit expédié. Le symptôme du débordement de contexte est souvent mal lu comme une défaillance de sélection d'outil, car la sortie se ressemble. Si vous voyez la sélection d'outil se dégrader après un nombre fixe de tours, vérifiez si la fenêtre de contexte se remplit avant de commencer à déboguer le schéma.

Screen 15: Checkpoint 5 · Diagnose the context failure

CheckpointContext Engineering·3 min Checkpoint 5 · Diagnostiquer la défaillance du contexte La trace de session ci-dessous montre une exécution d'agent multi-tours avec des sélections d'outils dégradées. Lisez la trace, identifiez quel tour a déclenché la défaillance, nommez le mécanisme et sélectionnez le correctif d'une ligne parmi les trois options ci-dessous.

Session trace Cliquez sur chaque tour pour l'inspecter.

TourOutil appeléTaille du résultat 1fetch_policy_document, sélection correcte2 400 tokens 2fetch_policy_document, sélection correcte2 400 tokens 3fetch_policy_document, sélection correcte2 400 tokens 4fetch_policy_document, sélection correcte2 400 tokens 5search_knowledge_base au lieu de apply_coverage_rule, mauvaise sélection1 800 tokens 6search_knowledge_base à nouveau, mauvaise sélection (même que le tour 5)1 800 tokens 7La session se termine sans résultatN/A

Tour 4fetch_policy_document, sélection correcte, 2 400 tokens. Dernier tour correct. Quatre résultats d'outils volumineux (9 600 tokens) sont maintenant assis dans la fenêtre de contexte, étouffant les instructions qui disent à Claude quel outil utiliser ensuite.

AAjouter une description plus claire à l'outil apply_coverage_rule. BÉlaguer les résultats fetch_policy_document après chaque tour afin que les résultats accumulés n'étouffent pas les instructions actuelles et appliquer la compaction avant le tour 5. CAugmenter max_tokens dans l'appel API pour donner à Claude plus de place pour répondre.

Submit Skip for now

Screen 16: Building a production agent: the loop, wiring paths, orchestration, and human-in

TeachingAgent Construction·22 min Construire un agent de production : la boucle, les chemins de câblage, l'orchestration et le human-in-the-loop Un agent est une boucle d'utilisation d'outils multi-étapes avec un contexte géré et un objectif défini. Vous avez déjà construit les pièces individuelles, y compris les schémas d'outils et la gestion du contexte. Cette section les connecte dans un système de travail et ajoute la couche que ni les sujets ne couvrent seuls. Lorsque les composants s'exécutent ensemble sur plusieurs tours, de nouveaux modes de défaillance apparaissent que les tests isolés ne détectent pas. Les décisions de routage qui fonctionnaient dans les tests à un seul tour commencent à se composer. Le contexte se remplit plus vite que prévu. Une étape qui dépend d'un résultat antérieur obtient la mauvaise entrée car un appel d'outil antérieur était structuré incorrectement. La question qui devrait précéder chaque construction d'agent est : ce problème nécessite-t-il un agent ? Les agents portent une surcharge de coordination, des coûts de contexte étendus et une plus grande surface pour la défaillance que les modèles plus simples. Répondre à cette question délibérément est la première décision de conception.

Flux de travail ou agent : Prenez cette décision avant d'écrire la première ligne L'erreur la plus critique dans le développement d'agents est de choisir le mauvais modèle au départ. Les flux de travail et les agents résolvent des problèmes différents : utiliser un agent lorsqu'un flux de travail suffirait ajoute une complexité comportementale sans ajouter de capacité. Utiliser un flux de travail lorsqu'un agent est nécessaire produit un système qui se casse chaque fois que l'entrée utilisateur s'écarte du chemin prédéterminé.

Choisissez un flux de travail quand…Choisissez un agent quand… Vous pouvez énumérer les étapes exactes dans le code. Vous pouvez spécifier l'objectif et les outils mais pas le chemin exact. Le coût d'erreur est réel et les garde-fous au niveau des étapes importent. Le chemin à travers le travail ne peut pas être énuméré à l'avance. L'observabilité avec les outils standard est requise. La non-déterminisme est acceptable et les actions possibles de l'agent sont contraintes par son ensemble d'outils enregistrés. Les entrées sont bien contraintes à un ensemble connu. Les entrées utilisateur varient de manière imprévisible en contenu et en structure. Chaque exécution de la tâche suit la même séquence. La tâche nécessite une séquence créative des outils disponibles.

L'agent est le modèle. Le chemin de câblage est un choix d'implémentation. Une fois que vous avez décidé que la tâche a besoin d'un agent, vous avez également décidé sur un modèle : une boucle qui appelle les outils, gère le contexte et s'exécute jusqu'à ce qu'un objectif soit atteint. Pour les systèmes à agent unique, ce modèle est constant sur les trois chemins de câblage. Les architectures multi-agents, où un planificateur, un exécuteur et un évaluateur s'exécutent en tant qu'agents séparés se transmettant via des artefacts structurés, introduisent des décisions de conception supplémentaires au-delà de la boucle elle-même. Ces modèles sont couverts plus tard dans cette piste. Ce modèle ne change pas en fonction de la façon dont vous le construisez, ce qui change est la quantité de la boucle que vous écrivez vous-même par rapport à la quantité que vous remettez à une bibliothèque ou à un service hébergé. Il y a trois chemins de câblage, et ils se situent sur un spectre de la quantité d'infrastructure que vous possédez. Vous pouvez écrire la boucle directement contre l'API Messages, ce qui vous donne le contrôle total et la responsabilité totale. Vous pouvez utiliser l'Agent SDK, qui exécute la même boucle à l'intérieur de votre propre processus et vous remet l'exécution des outils, la gestion du contexte et la structure d'itération déjà construites. Ou vous pouvez utiliser Claude Managed Agents (actuellement en bêta publique), où Anthropic exécute la boucle et le sandbox et votre application diffuse les événements et les résultats. Les sections qui suivent enseignent la boucle elle-même, car la boucle est ce qui reste constant. Le chemin que vous choisissez décide qui maintient les pièces autour d'elle.

Chemins de câblage : qui exécute la boucle et ce que vous prenez Les trois chemins diffèrent sur une variable : la quantité d'infrastructure d'exécution de l'agent que vous possédez. Le tableau est ordonné de haut en bas par la quantité d'infrastructure que vous remettez. Choisissez en fonction de votre déploiement et de vos contraintes de conformité, ne soyez pas tenté de choisir le chemin qui est juste le plus rapide à prototyper.

Boucle API Messages brute Agent SDK Claude Managed Agents

Qui exécute la boucle : Votre code exécute chaque itération. Vous envoyez la demande, lisez les blocs tool-use, exécutez les outils et ajoutez les résultats vous-même. Ce que vous possédez : La boucle complète, l'exécution des outils, la gestion du contexte, les nouvelles tentatives et les conditions de sortie. Rien n'est fourni pour vous. Choisissez ceci quand : Vous avez besoin d'un contrôle total sur chaque étape, vous avez des contraintes qu'une bibliothèque n'accommode pas, ou vous vous enseignez comment fonctionne la boucle avant d'ajouter une abstraction. Ce qu'il faut vérifier avant de s'engager : Le coût de maintenance est le vôtre. Chaque comportement que le SDK vous donnerait gratuitement, y compris la gestion du contexte et la gestion des outils parallèles, devient du code que vous écrivez et testez.

Qui exécute la boucle : Le SDK exécute la boucle à l'intérieur de votre propre processus. Il itère et gère le contexte, et votre code exécute toujours les outils que l'agent appelle. Ce que vous possédez : L'exécution des outils et l'application environnante. Le SDK fournit la structure de boucle, la gestion du contexte et l'échafaudage des outils. Choisissez ceci quand : Vous voulez la boucle, la gestion du contexte et l'échafaudage des outils qui alimentent Claude Code sans les reconstruire, et vous voulez que l'agent s'exécute dans votre propre environnement en Python ou TypeScript. Ce qu'il faut vérifier avant de s'engager : Si les fonctionnalités basées sur le système de fichiers comme CLAUDE. md et le chargement des compétences dans l'Agent SDK sont contrôlés par la configuration settingSources. Ne vous fiez pas à une valeur par défaut : définissez toujours settingSources explicitement aux sources que vous avez l'intention (par exemple, ["user", "project", "local"] pour correspondre au comportement de la CLI Claude Code, ou [] pour s'exécuter complètement isolé avec uniquement ce que vous transmettez programmatiquement). Confirmez le comportement par défaut actuel par rapport à la référence de l'Agent SDK au moment de la construction.

Qui exécute la boucle : Anthropic exécute la boucle et le sandbox. Votre application envoie des événements utilisateur et diffuse les résultats en retour via des événements envoyés par le serveur. Ce que vous possédez : La couche d'application et la définition de l'agent. Vous définissez le modèle, l'invite système, les outils, les serveurs MCP et les compétences une fois, puis référencez l'agent par ID entre les sessions. Choisissez ceci quand : Vous avez besoin d'une exécution longue mesurée en minutes ou en heures, vous voulez un sandbox géré ou vous voulez éviter de construire la boucle, le sandbox et la couche d'exécution des outils du tout. Également disponible sur Claude Platform sur AWS avec certaines différences de fonctionnalités, vérifiez la parité des capacités par rapport à votre surface de déploiement avant de vous engager. Ce qu'il faut vérifier avant de s'engager : Les sessions sont avec état et stockées côté serveur, ce qui signifie qu'elles ne sont actuellement pas éligibles pour la rétention zéro données ou un accord d'associé commercial HIPAA. (Voir la documentation de rétention des données de l'API Anthropic sur platform. claude. com, vérifiez à la publication. ) Actuellement en bêta publique, tous les points de terminaison nécessitent l'en-tête bêta managed-agents-2026-04-01 et les comportements peuvent être affinés entre les versions. Construisez avec un plan de migration en place.

Claude Managed Agents : quand utiliser Le tableau ci-dessus répertorie Managed Agents comme le troisième chemin. Rendons ce choix concret car pour certaines charges de travail, c'est le défaut correct. Voici la différence fondamentale : avec une boucle brute ou l'Agent SDK, votre code exécute l'itération. Vous envoyez chaque demande, lisez les blocs tool-use, exécutez les outils et ajoutez les résultats. Avec Managed Agents, Anthropic exécute la boucle et le sandbox pour vous. Votre application définit l'agent une fois (modèle, invite système, outils, serveurs MCP, compétences), le référence par ID, envoie des événements utilisateur et diffuse les résultats en retour via des événements envoyés par le serveur.

Ce que vous arrêtez de posséder et ce que vous prenez à la place

CatégorieQuoi vous arrêtez de posséderQuoi vous prenez à la place Exécution et infrastructureLa boucle d'itération, le sandbox d'exécution, les nouvelles tentatives à l'intérieur de la boucle et l'exécution des outils. Anthropic exécute tout cela côté serveur. Une définition d'agent gérée en tant que ressource API versionnée, plus une couche d'application qui envoie des événements et consomme les résultats en streaming. Durée de session et étatGestion de l'exécution longue. Les sessions peuvent s'exécuter pendant des minutes ou des heures sans que votre processus ne tienne la boucle ouverte. État de session côté serveur. Les sessions sont avec état et stockées par Anthropic, et sont soumises à ses politiques de traitement des données et ses contraintes (voir la note de contrainte ci-dessous). Cycle de vie du sandboxProvision et démantèlement du sandbox pour l'exécution des outils. Une dépendance sur les outils disponibles du sandbox géré et son modèle d'exécution, plutôt que votre propre environnement.

Choisissez Managed Agents quand

La tâche s'exécute longtemps. L'exécution mesurée en minutes ou en heures est maladroite à tenir ouverte dans votre propre processus, et la boucle gérée est construite exactement pour cela. Vous voulez un sandbox géré. Si vous construiriez autrement et sécuriseriez un environnement d'exécution pour les appels d'outils, utiliser Managed Agents enlève une grande pièce d'infrastructure de votre assiette. Vous préférez ne pas construire la boucle, le sandbox et la couche d'exécution des outils du tout, et vous êtes prêt à définir l'agent en tant que ressource API à la place.

La contrainte qui la décide pour le travail réglementé Les sessions Managed Agent sont avec état et stockées côté serveur. Ce stockage est la raison pour laquelle ces sessions ne sont actuellement pas éligibles pour la rétention zéro données ou un accord d'associé commercial HIPAA. Donc, si votre charge de travail porte PHI ou relève d'une exigence ZDR, ce chemin est exclu peu importe la façon dont il s'adapte opérationnellement, et vous routez vers l'Agent SDK ou une boucle brute sur une configuration couverte à la place. La contrainte gouvernante choisit le chemin avant que la commodité n'ait son mot à dire.

Une progression courante est de prototyper sur l'Agent SDK localement, puis de passer à Managed Agents pour la production. La définition d'agent principal se transporte conceptuellement. Ce qui change est le format : l'Agent SDK utilise la configuration au niveau du code et du système de fichiers, tandis que Managed Agents définit l'agent en tant que ressource API versionnée. Attendez-vous à une étape de réexpression, pas une exportation directe.

Gère bienLes agents longue durée et les charges de travail où vous préférez ne pas construire ou sécuriser un sandbox et une boucle vous-même. Ajoute du coût ou de la complexitéLes sessions avec état côté serveur, un format de définition d'agent en tant que ressource et une surface bêta qui peut changer entre les versions. Utilisez une approche différentePour les charges de travail PHI ou ZDR, ou lorsque vous avez besoin d'un contrôle complet en processus, restez sur l'Agent SDK ou une boucle brute sur une configuration couverte.

Câblage de la boucle : les quatre étapes qui tiennent sur chaque chemin Les quatre étapes ci-dessous définissent une boucle d'agent de travail peu importe quel chemin vous construisez. Lorsque vous écrivez la boucle contre l'API Messages, vous implémentez les quatre vous-même. Lorsque vous utilisez l'Agent SDK, il fournit la structure pour enregistrer les outils, définir l'invite système et itérer la boucle, et votre code gère toujours l'exécution des outils. Les étapes sont les mêmes ; ce qui diffère est la quantité que vous écrivez par rapport à ce que vous héritez.

Enregistrer les outils : Chaque outil suit la même structure de schéma. Le SDK les enregistre par rapport à l'agent, afin que Claude sache ce qui est disponible. Définir l'invite système : Délimitez-la à la tâche de l'agent. Une invite système large produit un routage d'outils plus large et moins fiable. Une invite système qui nomme la tâche spécifique et les outils disponibles pour elle produit un comportement plus cohérent. Gérer la boucle d'utilisation d'outils : Que vous itériez la boucle vous-même ou que le SDK l'itère pour vous, votre code gère l'exécution. Chaque appel d'outil que Claude émet doit être exécuté par votre code et retourné dans un bloc tool-result. Définir les conditions de sortie : La boucle d'agent s'exécute jusqu'à ce qu'elle reçoive une condition d'arrêt. Sans conditions de sortie explicites, l'agent continuera à demander des appels d'outils au-delà de ce que la tâche nécessite. Vous devez définir quand terminé signifie terminé.

Liste de contrôle du câblage de la boucle : vérifiez ceci peu importe le chemin

#ÉlémentsQuoi vérifier 1Outils enregistrésChaque outil que l'agent peut avoir besoin est dans la liste d'enregistrement. Aucun outil non enregistré n'est référencé dans l'invite système. 2Invite système délimitéeL'invite système nomme la tâche et les outils disponibles. Elle ne décrit pas les outils que l'agent n'a pas. Elle n'omet pas les outils que l'agent a qui nécessitent des conseils de délimitation. 3Boucle d'utilisation d'outils implémentéeVotre code gère chaque bloc tool-use que Claude émet et retourne un bloc tool-result pour chacun avant le tour assistant suivant. Tous les blocs tool-use d'un seul tour assistant doivent être résolus ensemble. 4Point d'insertion HITL définiAu moins un point dans la boucle a une vérification human-in-the-loop. Voir la section ci-dessous pour où l'insérer. 5Conditions de sortie définiesLa boucle a un critère d'arrêt clair qui ne dépend pas de Claude se portant volontaire pour s'arrêter.

Human-in-the-loop (HITL) : Points d'insertion et quand chacun s'applique Un point de contrôle human-in-the-loop met en pause l'exécution de l'agent et route vers une étape d'examen humain avant de procéder. La question qui détermine où l'insérer est : quel est le pire résultat possible si cette étape s'exécute sans vérification humaine ?

Point d'insertionQuoi déclenche la vérificationNiveau de risque qu'il aborde Avant un appel d'outil destructifL'agent est sur le point d'exécuter une opération d'écriture, de suppression ou d'envoi. Élevé : actions irréversibles où un appel incorrect ne peut pas être annulé Après une étape de planificationL'agent a généré un plan et est sur le point de commencer à l'exécuter. Moyen : les plans incorrects qui produiraient le mauvais résultat même si toutes les étapes s'exécutent correctement Sur une sortie inattendueLe résultat de l'outil contient un drapeau d'erreur, un résultat vide ou une valeur en dehors des limites attendues. Variable : capture les modes de défaillance que la logique de nouvelle tentative seule ne résoudra pas

Orchestration des outils : Sur-outillage et sous-outillage Le comportement de routage de l'agent est façonné par deux choses, y compris la façon dont les outils sont décrits et le nombre d'outils enregistrés. Trop d'outils avec des descriptions qui se chevauchent produisent un routage erratique. Trop peu d'outils forcent l'agent à soit halluciner un chemin soit retourner un résultat incomplet. Le sur-outillage est le problème le plus courant dans les agents de production. Les équipes enregistrent chaque outil dont elles pourraient avoir besoin « juste au cas où » et découvrent que la qualité de sélection de Claude se dégrade à mesure que la surface d'outils augmente. Commencez par l'ensemble minimum requis pour la tâche et ajoutez des outils uniquement lorsqu'une lacune de capacité spécifique est confirmée.

Quand les agents sont le bon appel Ce que vous prenez quand vous utilisez un Agent Quand choisir un flux de travail à la place

Les tâches orientées vers un objectif où le chemin exact ne peut pas être énuméré à l'avance. Gérer les entrées variables qui nécessiteraient des douzaines de branches conditionnelles dans un flux de travail. Les agents ajoutent une complexité comportementale : le chemin à travers la tâche émerge du raisonnement du modèle sur le contexte accumulé plutôt que de la logique de branchement explicite dans votre code. L'observabilité nécessite des outils au niveau des transcriptions plutôt que la journalisation opérationnelle standard. Quand vous pouvez énumérer les étapes dans le code, utilisez un flux de travail. Les agents sont la dernière étape de la progression. Commencez par le modèle le plus simple qui résout le problème, un seul appel API, puis un flux de travail, puis un agent. Et avancez uniquement lorsque le modèle plus simple ne peut pas gérer la variabilité que la tâche nécessite.

Les contraintes de données réglementées définissent votre route de livraison et vos identifiants avant que vous écriviez le câblage Si vos données doivent être traitées avec des contraintes spécifiques (par exemple, secret professionnel avocat-client, HIPAA, GDPR, FedRAMP ou une politique de résidence des données interne), cette contrainte décide quel point de terminaison votre code appelle, quels identifiants il porte et où ses journaux atterrissent avant que vous ne fassiez un seul choix de conception sur les invites, les outils ou la mémoire. En tant que développeur, vous ne choisissez généralement pas la surface, mais vous écrivez le code qui cible un point de terminaison spécifique, attache les identifiants, configure la région et émet les journaux. Obtenez la contrainte gouvernante nommée au départ, car la mauvaise configuration du client est beaucoup plus coûteuse à annuler après que l'agent soit câblé que de le définir correctement la première fois. Les cinq contraintes ci-dessous couvrent les cas que vous êtes le plus susceptible de rencontrer en production.

ContrainteQuoi elle tend à exclure dans le codeQuoi survit généralement à une revue de code Secret professionnel avocat-clientLes appels à partir d'une surface Claude. ai de qualité consommateur que le cabinet ne peut pas auditer de bout en bout. Les chemins de code qui envoient du contenu de document privilégié à n'importe quel point de terminaison que le cabinet n'a pas approuvé pour le matériel privilégié, peu importe la façon dont l'invite ou le message système est structuré. Les appels directs de l'API ou du SDK depuis l'intérieur de l'application propre du cabinet, authentifiés via SSO, routés via une passerelle LLM approuvée par le cabinet avec journalisation complète des demandes et des réponses. Notez que le contenu de conversation de conformité d'Anthropic (invites, réponses et charges utiles d'appels d'outils) n'est pas capturé par Anthropic par défaut sur le trafic API direct, donc l'organisation doit implémenter la journalisation des conversations dans la couche d'application et la router vers une destination de journal approuvée. Les appels d'outils et les résultats d'outils restent à l'intérieur du chemin audité. Confirmez la conception de journalisation finale avec votre équipe de compte Anthropic. HIPAA (traitement PHI)Le code qui envoie des informations de santé protégées à n'importe quel point de terminaison ou chemin de livraison non couvert par un accord d'associé commercial pour la configuration spécifique en utilisation. Cela inclut n'importe quel chemin de journalisation ou de rétention auquel votre code écrit qui n'a pas été délimité sous le même BAA. Les appels directs de l'API ou du SDK sur une configuration couverte par BAA. La couverture BAA pour l'accès API de première partie d'Anthropic est arrangée avec Anthropic, qui provisionne une organisation HIPAA-activée dédiée qui applique les restrictions de fonctionnalités de son propre côté. Confirmez la configuration couverte avec votre équipe de compte Anthropic. Une alternative est une route médiatisée par le cloud via AWS Bedrock ou GCP Vertex sur le compte cloud HIPAA-éligible existant du partenaire. Notez : le BAA ne couvre pas Console, Workbench, les fonctionnalités bêta ou les plans consommateurs. Pas toutes les fonctionnalités de l'API sont couvertes par le BAA, vérifiez la liste actuelle d'éligibilité des fonctionnalités dans le guide d'implémentation d'Anthropic avant de configurer. GDPR et résidence des donnéesLes routes de livraison où la région d'exécution du modèle ne peut pas être épinglée dans le code, ou où la demande peut être servie à partir d'une région en dehors de la limite géographique approuvée. Le défaut à un point de terminaison global sans spécifier la région est le modèle courant qui se casse ici. Une route médiatisée par le cloud telle que Bedrock ou Vertex, avec la région épinglée dans la configuration du client à une juridiction couverte. L'API Anthropic directe est un cas séparé ; elle ne fournit actuellement pas de résidence des données de l'UE, donc les partenaires avec des exigences de résidence des données de l'UE doivent router via Bedrock ou Vertex plutôt que d'appeler l'API directement. FedRAMP et gouvernementN'importe quel chemin de code qui appelle un point de terminaison non sur un environnement cloud autorisé au niveau d'impact requis. Cela inclut les chemins de développement et de test qui frappent le point de terminaison commercial tandis que la production frappe celui autorisé, car les identifiants et les modèles de code fuient entre eux. Trois routes autorisées existent au moment de la publication. Claude for Government (C4G) porte une autorisation FedRAMP High directe détenue via Palantir Federal Cloud Service – Supporting Services (PFCS-SS). Claude via Amazon Bedrock GovCloud est approuvé pour les charges de travail FedRAMP High et DoD IL4/5. Claude via Vertex AI Assured Workloads est également autorisé par FedRAMP. Claude Enterprise sur AWS Marketplace n'est pas autorisé par FedRAMP, donc les équipes nécessitant la conformité FedRAMP doivent utiliser l'une des trois routes ci-dessus. Vérifiez l'état d'autorisation actuel sur trust. anthropic. com avant de configurer. Politique de résidence des données interneAppels à partir de n'importe quel client SDK configuré par rapport à un fournisseur de cloud en dehors de la liste approuvée du partenaire, peu importe si la capacité technique sous-jacente supporterait la charge de travail. Les contraintes au niveau de l'approvisionnement régissent le chemin de code avant que les préférences d'ingénierie n'entrent dans la conversation. La route de livraison sur le fournisseur de cloud approuvé du partenaire. En termes de code, c'est quel que soit le client SDK et la configuration de point de terminaison que leur CIO a déjà approuvés. Construisez par rapport à celui-ci plutôt que de changer à mi-projet parce qu'une autre route semble plus facile.

Ce tableau couvre les contraintes qui déterminent directement la sélection du point de terminaison et la configuration des identifiants. SOC 2 n'est pas en scope ici. Il régit la façon dont vos systèmes sont construits et exploités, pas quel point de terminaison votre code appelle, et est couvert dans le Module 4 aux côtés d'autres exigences de posture de sécurité et d'audit.

Forward pointer Le Module 4 (Production Engineering, Evals & Security) approfondit les modèles de conception sécurisés par défaut pour IAM et la confidentialité, les défenses contre l'injection d'invite à partir d'entrées non fiables, les garde-fous d'exécution et le durcissement des agents. Le rôle de cette section est plus étroit : faire surface à la contrainte au moment du build où elle exclut réellement les options, ce qui est lorsque vous choisissez le point de terminaison, la configuration du client SDK et les identifiants que votre agent porte en production.

Screen 17: The agent that edited a production file

Watch OutAgent Construction·5 min L'agent qui a modifié un fichier de production

Setup L'agent fonctionne de bout en bout en test car votre environnement de test est indulgent, mais la production ne l'est pas. L'agent a les mêmes outils, la même boucle et la même invite système, mais le point de contrôle HITL manque car les tests n'ont jamais exposé un cas d'utilisation qui l'exigeait.

Un agent d'édition de fichiers, testé dans un répertoire de travail, déployé dans un environnement client Un développeur a construit un agent qui pouvait lire, modifier et écrire des fichiers de configuration. L'invite système lui donnait accès à trois outils, y compris read_file, write_file et validate_config. La boucle de l'agent était simple. Après chaque écriture, il réexécuterait validate_config, et si la config échouait toujours la validation, l'agent ajusterait son édition et écrirait à nouveau, jusqu'à un plafond de dix itérations avant de s'arrêter. L'agent a été testé par rapport à un répertoire de travail avec une copie de la config cible. Il a fonctionné correctement sur chaque cas de test, convergeant généralement vers une config valide en deux ou trois itérations. Lorsqu'il a été déployé dans un environnement client, l'agent a correctement identifié qu'un paramètre de configuration était hors limites. Il a proposé une correction, a appelé write_file, a réexécuté validate_config et a obtenu un passage. La boucle s'est terminée proprement après une seule itération, exactement comme conçu. Le plafond de dix itérations n'a jamais été atteint car il n'a jamais été nécessaire. La conception de la boucle était correcte, mais la condition de sortie était le problème. Le paramètre que l'agent a corrigé était une limite de débit sur laquelle l'application du client s'appuyait. validate_config a vérifié que la valeur était dans la plage autorisée du schéma, ce qu'elle était maintenant. Ce que validate_config n'a pas vérifié, et n'a jamais été conçu pour vérifier, c'est si les systèmes en aval dépendaient de l'ancienne valeur. Quelques minutes après l'écriture, l'application du client a commencé à échouer car les demandes étaient limitées à un débit que l'application n'était pas construite pour gérer. La boucle de l'agent a fait exactement ce que le développeur lui a demandé. Il a modifié, validé et s'est arrêté lorsque la validation a réussi. La défaillance n'était pas dans la boucle. La défaillance était que la condition de sortie de la boucle (validate_config retourne pass) était délimitée au fichier que l'agent modifiait, et il n'y avait pas de point de contrôle entre « la validation a réussi sur ce fichier » et « l'écriture s'est engagée dans l'environnement client en direct ». La pièce manquante était un point de contrôle dans la conception de la boucle : avant que le premier appel write_file ne frappe la config client en direct, mettez en pause et exposez le changement proposé pour examen humain. En pratique, cela signifie que la boucle a besoin d'une branche explicite entre « changement proposé prêt » et « écriture engagée », un état que le développeur n'a jamais ajouté car les tests n'ont jamais produit un cas qui l'exigeait.

What to Watch Out for Le modèle que cet incident illustre est une question de permissions qui n'a jamais été posée pendant la conception. L'agent avait accès en écriture car la tâche impliquait l'édition de fichiers, et la tâche elle-même était légitime. Ce que l'équipe a manqué était l'écart entre un agent qui propose un changement et un qui l'engage. Dans un environnement de test jetable, cet écart ne fait jamais surface car rien qu'une « mauvaise écriture » touche des questions en test, mais la production est différente. La question de conception qui n'a jamais été posée : « Quel est le pire résultat si write_file s'exécute sans vérification humaine ? » La réponse à cette question détermine si un point de contrôle human-in-the-loop est requis avant que l'outil ne s'exécute. Si un outil peut prendre une action irréversible en production, il a besoin d'un point de contrôle avant de s'exécuter. Enregistrez cette contrainte pendant la conception, lorsque vous délimitez la surface d'outils, pas après le premier incident.

Screen 18: Checkpoint 6 · Complete the agent wiring

CheckpointAgent Construction·4 min Checkpoint 6 · Compléter le câblage de l'agent L'implémentation d'agent partielle ci-dessous a deux lacunes. Écrivez le contenu manquant pour chaque lacune : (1) la description pour update_record, et (2) le code du point de contrôle HITL.

Partial implementation tools = [ { "name": "read_record", "description": "Use this to read a customer record by customer_id. ", "input_schema": { "type": "object", "properties": { "customer_id": {"type": "string"} }, "required": ["customer_id"] } }, { "name": "update_record", "description": [BLANK, write the description for this tool], "input_schema": { "type": "object", "properties": { "customer_id": {"type": "string"}, "field": {"type": "string"}, "new_value": {"type": "string"} }, "required": ["customer_id", "field", "new_value"] } } ]

def run_agent_loop(user_request): messages = [{"role": "user", "content": user_request}]

while True: response = client. messages. create( model=model, max_tokens=4096, tools=tools, messages=messages )

if response. stop_reason == "end_turn": return response

if response. stop_reason == "tool_use": messages. append({"role": "assistant", "content": response. content})

tool_results = [] for block in response. content: if block. type == "tool_use":

[BLANK, insert HITL checkpoint before executing update_record]

result = execute_tool(block. name, block. input) tool_results. append({ "type": "tool_result", "tool_use_id": block. id, "content": result })

messages. append({"role": "user", "content": tool_results})

Gap 1: Write the description for update_record

Gap 2: Write the HITL checkpoint code

Reveal model answers Skip for now

Screen 19: Choosing the right scope for state that survives sessions

TeachingAgent Memory·8 min Choisir la bonne portée pour l'état qui survit aux sessions L'agent de la section précédente s'exécute correctement dans une seule session. Ce qu'il ne peut pas faire, c'est se souvenir de quoi que ce soit lorsque cette session se termine. La portée de la mémoire est la façon dont vous décidez ce que l'agent devrait savoir au début de la session suivante et combien cela coûte de porter cette connaissance.

Modèles de mémoire et quand chacun est correct Au-delà de la portée de la mémoire, le blueprint regroupe plusieurs modèles de conception d'agent sous cet objectif, et vous avez déjà construit chacun plus tôt dans ce module. La boucle d'utilisation d'outils, où le modèle appelle un outil, lit le résultat et continue, est le modèle principal du cluster d'utilisation d'outils et de construction d'agents. La décomposition de tâches multi-étapes divise un objectif en sous-tâches ordonnées, et la planification-et-exécution sépare la décision du plan de sa réalisation, la même division que le contrôle human-in-the-loop après une étape de planification garde. La portée de la mémoire, couverte ensuite, est le modèle qui décide quel état survit une fois que la boucle se termine. La portée de la mémoire définit ce qu'un agent sait lorsqu'une nouvelle session commence. Faire le mauvais choix a deux modes de défaillance, et ils tirent dans des directions opposées :

Trop d'état en contexte gonfle chaque appel API, car le modèle relit la conversation complète à chaque tour et la facture s'adapte à la longueur de la session. Trop peu d'état en stockage persistant dépouille l'agent de la mémoire entre les sessions, car tout ce qui n'est pas écrit disparaît au moment où la conversation se termine.

PortéeQuoi persisteCoûtQuand l'utiliser Mémoire en contexteL'état vit dans la conversation active et survit les tours dans une seule session. Zéro surcharge de récupération ; gonfle le coût des tokens à mesure que la conversation grandit. Les sessions courtes où tout l'état que l'agent a besoin s'adapte à l'intérieur de la fenêtre de contexte et rien n'a à se transporter entre les redémarrages. Tout une fois que la session se termine. Une commande claire ou une nouvelle session efface l'état. Stockage externeL'état est écrit dans une base de données et relue au démarrage de la session ou à la demande. Chaque appel de base de données ajoute une latence de récupération, et vous prenez le travail d'ingénierie de la logique de lecture et d'écriture. L'état qui doit survivre entre les sessions, se déplacer entre les utilisateurs ou être partagé entre plusieurs instances d'agent. Rien du côté de la persistance. Le coût apparaît comme une latence sur chaque appel et une complexité d'implémentation continue. Mémoire résumée Une version condensée de la conversation antérieure est générée et injectée au début de la session suivante. Coût de tokens inférieur par session que la relecture de l'historique complet, mais l'étape de résumé perd des détails qui étaient dans l'original. Les agents conversationnels longue durée où l'historique complet dépasserait le budget de contexte avant la fin de la conversation. Tout détail que le résumeur n'a pas préservé. L'agent ne voit que ce que l'invite de résumé a choisi de conserver. Pas de mémoire persistante (sans état)Rien. Chaque session est indépendante. Aucune surcharge du tout, puisqu'il n'y a rien à récupérer ou stocker. Les agents d'exécution de tâches qui se terminent et se ferment, ou les pipelines où chaque session est complètement indépendante par conception. Tout contexte antérieur. Si un suivi dépend de quelque chose d'une session antérieure, l'agent n'a aucun moyen de l'atteindre.

Choisir une portée de mémoire au moment de la conception de l'agent Le choix de la façon dont un agent se souvient des interactions antérieures appartient à la phase de conception, pas au refactorisation de production. Un agent qui aide le même utilisateur sur plusieurs jours doit porter l'état entre les sessions, ce qui signifie stocker des résumés ou l'historique complet en dehors de la fenêtre de contexte du modèle afin que la session suivante puisse les relire. Un agent qui reçoit un seul travail, le termine et le ferme n'a pas de session antérieure à rappeler, donc il s'exécute sans état. Le chemin par défaut semble raisonnable au premier abord. Vous stockez l'historique complet de la conversation dans le tableau messages, l'envoyez à chaque appel API et le prototype fonctionne. Il continue de fonctionner pendant un certain temps. Le problème commence plus loin, lorsque le coût des tokens s'adapte à chaque tour supplémentaire, la latence grimpe à mesure que la fenêtre de contexte se remplit, et finalement une longue session atteint la limite dure et l'agent cesse de répondre. À ce moment, vous avez besoin de refactoriser : tirez l'état de conversation accumulé hors du contexte en direct, mettez-le en stockage externe et injectez uniquement ce que chaque tour a besoin. La refactorisation elle-même est mécanique, quelques centaines de lignes de code et une base de données que l'équipe a déjà. Ce qu'elle coûte est le timing. Le travail se produit sous pression de production, généralement avec une date limite déjà en mouvement, et chaque heure passée à restructurer la mémoire est une heure non passée sur ce que l'agent est censé faire ensuite. Faire l'appel pendant la phase de conception est bon marché, tandis que le faire quand il est temps de refactoriser est plus cher. Le contenu ci-dessous décrit trois approches de mémoire et les conditions où chacune s'adapte, la surcharge que chacune porte et l'hypothèse qui pousse le plus souvent les équipes vers le mauvais choix.

Gère bienLa portée de la mémoire correspond à la tâche au moment de la conception. Utilisez le stockage externe lorsque l'agent continue un fil entre les sessions. Utilisez sans état lorsque chaque travail est autonome. Utilisez en contexte lorsque la session est courte et n'a pas besoin de survivre à un redémarrage. Ajoute du coût ou de la complexitéLe stockage externe ajoute une latence de récupération et la logique de lecture/écriture qui en découle. La mémoire résumée dépend d'une invite de résumeur bien spécifiée ; sans elle, l'état critique de la tâche se perd à chaque compression. Aucune approche n'est gratuite, donc pesez les coûts et choisissez judicieusement. Utilisez une approche différenteTenir tout l'état en contexte en supposant que la fenêtre sera assez grande. Le coût des tokens grandit à chaque tour supplémentaire car le contexte complet est envoyé à chaque appel API. Sans mise en cache ou compaction, les sessions longues accumulent des coûts plus rapidement que les équipes ne s'y attendent lorsqu'elles mesurent uniquement les premiers tours. Mesurez l'utilisation réelle des tokens de session par rapport à la limite de fenêtre avant de vous engager.

Compétences : ensembles d'instructions réutilisables qui se chargent à la demande sans gonfler chaque session Le tableau de portée de la mémoire ci-dessus couvre la façon dont un agent porte l'état entre les sessions. Il y a un problème connexe mais distinct : comment vous portez les instructions répétables entre les tâches sans payer pour les injecter dans chaque session. Le modèle pour cela est une Compétence, un fichier markdown réutilisable qui enseigne à Claude comment gérer un type de tâche spécifique une fois. Claude charge la Compétence automatiquement lorsqu'une demande correspond à sa description. Les instructions se trouvent sur le disque jusqu'à ce qu'elles soient nécessaires ; elles ne sont pas résidentes dans chaque conversation. Une Compétence vit dans un fichier SKILL. md à l'intérieur d'un répertoire identifié. Le fichier a deux parties : un bloc frontmatter avec un nom et une description, et les instructions ci-dessous. La description est le critère de correspondance. Lorsque vous envoyez une demande, Claude lit le nom et la description de chaque Compétence disponible, les compare par rapport à votre message et charge les instructions complètes uniquement lorsqu'il y a une correspondance. Si les instructions ne sont pas pertinentes pour la demande actuelle, elles n'entrent jamais dans la fenêtre de contexte. C'est le contraste clé avec les modèles de mémoire du tableau ci-dessus. La mémoire en contexte est toujours présente et grandit à chaque tour. Le comportement CLAUDE. md dépend de l'endroit où vous exécutez Claude Code. Dans la CLI Claude Code, un fichier CLAUDE. md se charge dans chaque session peu importe quelle tâche s'exécute. Dans l'Agent SDK, si les paramètres du système de fichiers y compris CLAUDE. md se chargent est contrôlé par la configuration settingSources. Ne vous fiez pas à une valeur par défaut : définissez-la explicitement aux sources que vous avez l'intention, et confirmez le comportement par défaut actuel par rapport à la référence de l'Agent SDK au moment de la construction. Une Compétence, en contraste, se charge uniquement lorsque la tâche l'appelle, dans les deux environnements. Pour les ensembles d'instructions qui s'appliquent à des tâches récurrentes spécifiques plutôt qu'à chaque session, les Compétences sont un modèle à surcharge inférieure que l'une ou l'autre alternative.

Compétences vs. CLAUDE. md vs. instructions en contexte : choisir le bon modèle

ModèleQuand il se chargeCoût du contexteIdéal pour Compétence (SKILL. md)À la demande lorsque la demande correspond à la description de la compétenceBas. Seul le nom et la description se chargent au démarrage ; le contenu complet se charge uniquement en cas de correspondance. L'expertise spécifique à la tâche qui ne devrait pas gonfler les sessions où elle n'est pas nécessaire. Les exemples incluent les formats de sortie spécifiques au domaine, les listes de contrôle d'examen spécialisées et les flux de travail qui s'appliquent à un sous-ensemble de tâches plutôt qu'à chaque interaction. CLAUDE. mdChaque session, sans conditionSurcharge fixe par session peu importe la tâcheLes normes de projet toujours activées qui s'appliquent à tout. Les exemples incluent les conventions de codage que l'équipe a standardisées, les règles de format de sortie que le projet nécessite et les contraintes qui tiennent entre toutes les tâches du codebase. Instructions en contexteprésent pour chaque tour dans cette sessionGrandit avec la longueur de la session ; ne survit pas à la fin de la sessionLes sessions courtes où l'historique complet s'adapte à l'intérieur de la fenêtre et rien n'a besoin de persister. Les exemples incluent le travail exploratoire ponctuel et les tâches délimitées à une seule conversation.

Disponibilité actuelle : Compétences sur l'API Messages Les Compétences sont disponibles sur l'API Messages aujourd'hui, mais l'intégration est en bêta et la configuration n'est pas la même que les chemins Claude Code ou Agent SDK. Deux en-têtes bêta sont requis sur la demande API : code-execution-2025-08-25 et skills-2025-10-02. Les Compétences invoquées de cette manière s'exécutent à l'intérieur du conteneur d'exécution de code plutôt que dans l'environnement de l'application appelante, ce qui a des implications pour les outils et l'accès au système de fichiers sur lesquels la Compétence peut compter. Les en-têtes bêta sont versionnés et changent à mesure que les fonctionnalités se rapprochent de la disponibilité générale. Avant de construire par rapport à cette configuration en production, vérifiez la documentation actuelle de l'API Anthropic pour confirmer les valeurs d'en-tête, si la fonctionnalité a atteint la disponibilité générale et si le conteneur d'exécution de code est toujours le chemin d'exécution. Une contrainte importante : les sous-agents n'héritent pas automatiquement des Compétences de la session parent. Lorsque vous déléguez une tâche à un sous-agent, il commence avec un contexte propre. Notez que bien que les Compétences et l'historique de conversation ne se transportent pas, les sous-agents héritent du contexte de permission de la session parent ; la portée de permission n'est pas réinitialisée à la délégation. Si le sous-agent a besoin d'une Compétence, vous devez l'énumérer explicitement dans la configuration du sous-agent. Cela importe au moment de la conception de l'agent : si vous câblez un sous-agent pour effectuer une tâche qui dépend d'instructions spécifiques, ces instructions doivent être enregistrées par rapport au sous-agent, pas supposées se transporter du parent.

Screen 20: The agent that filled the window on session four

Watch OutAgent Memory·2 min L'agent qui a rempli la fenêtre à la session quatre

Setup L'agent s'exécute parfaitement en développement car vous l'exécutez dans une seule longue session continue. La fenêtre de contexte ne se remplit jamais, donc la mémoire en contexte tient tout. Mais maintenant, la production exécute plusieurs sessions plus courtes avec plus de tours sur plus de jours, et la fenêtre se remplit à la session quatre.

Autopsie : L'état en contexte gonfle jusqu'à ce que la fenêtre se ferme Un agent a été construit pour aider un ingénieur d'assistance avec les cas d'escalade en cours. Le développement a exécuté des sessions continues de 10 à 15 tours. L'état en contexte tenait correctement l'historique complet. Le développeur a expédié sans mesurer l'utilisation des tokens par session. En production, chaque session était plus courte, mais l'état s'accumulait entre les sessions. À la session quatre, l'historique en contexte injecté dépassait 40 000 tokens avant que l'agent n'ait traité un seul appel d'outil. Combiné avec l'invite système et les schémas d'outils enregistrés, plus de 45 000 tokens du budget de contexte ont été consommés avant le premier tour productif de la session. À mesure que les appels d'outils s'accumulaient au cours de la session, le budget restant s'épuisait avant que l'agent ne puisse terminer son analyse. L'agent a commencé à retourner des résultats incomplets, un symptôme qui ressemblait initialement à une défaillance de sélection d'outil plutôt qu'à un problème d'architecture de mémoire. La correction était une refactorisation d'une heure vers le stockage externe : tirez l'historique de session accumulé hors du contexte en direct, persistez-le dans une base de données et injectez uniquement le sous-ensemble pertinent au démarrage de la session. La refactorisation sous pression de production a pris considérablement plus de temps qu'elle n'aurait pris au moment de la conception. La couche de stockage, la logique de récupération et la gestion de session avaient tous besoin de décisions qui auraient dû être prises avant le premier déploiement.

What to Watch Out for Le développement a utilisé une seule longue session. La production a utilisé de nombreuses sessions courtes avec l'état accumulé. Ce sont des formes différentes, et la mémoire en contexte les gère différemment. Mesurez la taille d'état attendue par session (historique plus invite système plus schémas d'outils) par rapport à la limite de contexte avant de choisir en contexte comme défaut.

Screen 21: Checkpoint 7 · Choose the right memory pattern

CheckpointAgent Memory·3 min Checkpoint 7 · Choisir le bon modèle de mémoire Lisez les trois cas d'utilisation d'agent ci-dessous. Faites correspondre chaque cas d'utilisation d'agent à gauche à la bonne portée de mémoire à droite. Il y a une portée correcte par cas d'utilisation.

Un agent d'assistance client assiste le même utilisateur lors des vérifications quotidiennes sur deux semaines. Chaque session commence où la précédente s'est arrêtée. Mémoire en contexte : tout l'état vit dans la conversation active. Stockage externe : écrivez l'état dans une base de données à la fin de la session, puis relisez-le au démarrage de la session. Pas de mémoire persistante (sans état) : chaque session commence à zéro. Un formateur de document reçoit un fichier, applique une transformation, retourne la sortie et se termine. Chaque travail est complètement indépendant. Mémoire en contexte : tout l'état vit dans la conversation active. Stockage externe : écrivez l'état dans une base de données à la fin de la session, puis relisez-le au démarrage de la session. Pas de mémoire persistante (sans état) : chaque session commence à zéro. Un assistant de codage travaille avec un développeur au cours d'une session multi-heures. La session ne continuera pas après sa fin. Mémoire en contexte : tout l'état vit dans la conversation active. Stockage externe : écrivez l'état dans une base de données à la fin de la session, puis relisez-le au démarrage de la session. Pas de mémoire persistante (sans état) : chaque session commence à zéro.

Submit Skip for now

Screen 22: Cumulative debug task · Identify each bug

CumulativeDebug Task·8 min Tâche de débogage cumulative · Identifier chaque bug L'implémentation d'agent ci-dessous a quatre bugs plantés, un dans chacune des quatre couches : la couche de schéma, la couche de streaming où la réponse est assemblée et validée, la couche de contexte où la structure du message est construite et la couche de mémoire. Travaillez à travers les deux étapes ci-dessous. Cet écran couvre l'étape 1 : identifier chaque bug. L'étape 2, écrire la version corrigée, est sur l'écran suivant.

Buggy implementation

tools = [ { "name": "get_customer_data", "description": "Gets data. ", "input_schema": { "type": "object", "properties": { "id": {"type":"string"} }, "required": ["id"] } } ]

def run_agent(user_request, session_history): messages = session_history + [{"role":"user","content":user_request}] while True: blocks = {} stop_seen = False with client. messages. stream( model=model, max_tokens=4096, tools=tools, messages=messages, thinking={"type": "adaptive"} ) as stream: for event in stream: if event. type == "content_block_start": blocks[event. index] = init_block(event) elif event. type == "content_block_delta": apply_delta(blocks[event. index], event. delta) elif event. type == "message_stop": stop_seen = True assistant_content = [b for b in assemble(blocks) if b["type"] ! = "thinking"] messages. append({"role": "assistant", "content": assistant_content}) response = finalize(blocks) if response. stop_reason == "end_turn": return response for block in response. content: if block. type == "tool_use": result = execute_tool(block. name, block. input) messages. append({"role":"user","content":[{"type":"tool_result", "tool_use_id":block. id,"content":result}]})

def build_session_history(prior_sessions):

full_history = [] for session in prior_sessions: full_history. extend(session["messages"]) return full_history

Stage 1: Identify each bug L'implémentation ci-dessus a quatre bugs, un dans chacune des quatre couches. Pour chaque bug : nommez la couche à laquelle il appartient et écrivez une phrase décrivant ce qu'il cause à l'exécution.

Reveal model answer Skip for now

Screen 23: Cumulative debug task · Write the corrected version

CumulativeDebug Task·10 min Tâche de débogage cumulative · Écrire la version corrigée Étape 2 : écrivez la version corrigée de chaque bug identifié sur l'écran précédent. Pour chacun, montrez le code corrigé et nommez ce qu'il change.

Buggy implementation (for reference)

tools = [ { "name": "get_customer_data", "description": "Gets data. ", "input_schema": { "type": "object", "properties": { "id": {"type":"string"} }, "required": ["id"] } } ]

def run_agent(user_request, session_history): messages = session_history + [{"role":"user","content":user_request}] while True: blocks = {} stop_seen = False with client. messages. stream( model=model, max_tokens=4096, tools=tools, messages=messages, thinking={"type": "adaptive"} ) as stream: for event in stream: if event. type == "content_block_start": blocks[event. index] = init_block(event) elif event. type == "content_block_delta": apply_delta(blocks[event. index], event. delta) elif event. type == "message_stop": stop_seen = True assistant_content = [b for b in assemble(blocks) if b["type"] ! = "thinking"] messages. append({"role": "assistant", "content": assistant_content}) response = finalize(blocks) if response. stop_reason == "end_turn": return response for block in response. content: if block. type == "tool_use": result = execute_tool(block. name, block. input) messages. append({"role":"user","content":[{"type":"tool_result", "tool_use_id":block. id,"content":result}]})

def build_session_history(prior_sessions):

full_history = [] for session in prior_sessions: full_history. extend(session["messages"]) return full_history

Reveal model answer Skip for now

Screen 24: Images, PDFs, and high-volume processing

TeachingMultimodal and Batch Ingestion·13 min Images, PDFs et traitement à haut volume Jusqu'à présent, vous avez géré ce que Claude se souvient entre les tours. L'ingestion multimodale déplace la question à ce que vous envoyez : chaque image et PDF consomme le budget de contexte avant que Claude ne lise un seul caractère de votre invite, ce qui change la façon dont vous structurez les demandes et ce que vous pouvez adapter dans une. La deuxième moitié de ce sujet traite du côté opposé du même problème. Lorsque vous avez des milliers d'entrées à traiter, envoyer une demande à la fois et attendre chaque réponse cesse d'avoir du sens, et l'API Batch est la façon dont vous gérez ce volume sans bloquer votre application.

Coût des tokens d'image : Calculez avant de vous engager Les images ne sont pas gratuites en termes de budget de contexte. Claude voit les images en patchs : chaque bloc de pixels 28×28 de l'image est un token visuel, donc une image coûte ⌈largeur / 28⌉ × ⌈hauteur / 28⌉ tokens visuels. Une image de 1 000 × 1 000 pixels est ⌈1000/28⌉ × ⌈1000/28⌉ = 36 × 36 patchs, environ 1 296 tokens visuels. À ce rythme, dix captures d'écran haute résolution consomment autant de contexte qu'une invite système détaillée. Chaque modèle a également une résolution d'image native maximale, exprimée comme une limite de bord long et une limite de token visuel, et ces limites diffèrent par niveau de modèle. Les modèles les plus récents acceptent des images considérablement plus grandes que le niveau standard. Les images plus grandes que l'une ou l'autre limite sont réduites avant le traitement, donc la formule s'exécute sur les dimensions mises à l'échelle. Confirmez les limites actuelles par niveau par rapport à la page Vision (Résolution et coût des tokens) au moment de la construction ; les limites ont changé entre les générations de modèles et changeront à nouveau. Le calcul importe au moment de la conception. Si vous construisez un pipeline qui traite les images, mesurez le coût des tokens d'une image de production typique par rapport à la limite de contexte de votre modèle avant d'écrire le code d'ingestion. La correction pour un pipeline sur budget est souvent une étape de redimensionnement d'image de dix minutes. Si vous découvrez cela après le déploiement, cela prend encore plus longtemps.

Différentes façons d'envoyer une image : Quand chacune est correcte

Base64 en ligne Référence URL API Files

Comment ça fonctionne : Encodez les octets de l'image en tant que chaîne base64 et incluez les données directement dans le bloc de message. Surcharge : La charge utile encodée complète se déplace avec chaque demande, ce qui gonfle la taille de la demande et compte contre la latence sur les grandes images. Quand l'utiliser : Idéal pour les images ponctuelles où l'ajout d'une étape de téléchargement ajouterait de la complexité sans avantage. La même image envoyée à plusieurs reprises multiplie le coût, donc utilisez une méthode différente si la réutilisation est probable.

Comment ça fonctionne : Passez une URL accessible au public dans le bloc source, et Claude récupère l'image au moment de la demande. Surcharge : Aucune charge utile ne se déplace avec la demande, mais vous prenez la dépendance que l'URL doit être stable, publique et accessible au moment où Claude essaie de la récupérer. Quand l'utiliser : Idéal lorsque l'image est déjà hébergée à une URL publique stable que vous contrôlez. Ignorez-le pour tout ce qui est derrière l'authentification, tout ce qui est signé avec une expiration courte ou tout ce que vous ne pouvez pas garantir sera accessible lorsque la demande s'exécute.

Comment ça fonctionne : Téléchargez le fichier une fois via un appel API séparé, recevez un file_id et référencez cet ID dans n'importe quel message futur. Surcharge : Le téléchargement est un coût unique ; chaque demande ultérieure porte l'ID au lieu des octets, donc la surcharge de charge utile tombe à près de zéro à partir de ce moment. Actuellement en bêta et non disponible sur Bedrock ou Vertex AI ; vérifiez la disponibilité pour votre plateforme de déploiement. Quand l'utiliser : Idéal lorsque la même image ou PDF apparaît dans plusieurs demandes, ou lorsque l'actif est assez grand pour que le renvoi dominerait la taille de la demande. Aussi, le choix le plus propre lorsque vous voulez que la gestion des actifs vive séparément des appels d'inférence, et le bon choix pour les images qui apparaissent dans plusieurs tours de conversation, puisque le file_id ne porte aucun poids de charge utile à mesure que l'historique grandit.

Envoi de PDF : Le bloc de document Pour les PDF, le type de bloc est document plutôt que image. La structure source suit le même modèle que les images, ce qui signifie qu'elle peut être base64, une URL ou un file_id de l'API Files. Il n'y a pas de champ de nom requis sur un bloc de document. Le bloc accepte un champ title optionnel pour un nom de document lisible et un champ context optionnel pour les métadonnées supplémentaires, mais aucun n'est requis pour envoyer un PDF. Toute autre mécanique, y compris les considérations de coût des tokens et la réutilisation de l'API Files, s'applique de la même manière.

{ "type": "document", "source": { "type": "base64", "media_type": "application/pdf", "data": "<base64-encoded-pdf-bytes>" }, "title": "contract_review. pdf" }

Application des techniques d'invite à l'entrée multimodale Les mêmes techniques d'invite de la première section s'appliquent à l'analyse d'image et de PDF. Une invite nue « décrivez cette image » produit une sortie superficielle pour la même raison qu'une invite de texte nue le ferait car Claude n'a pas de structure cible vers laquelle viser. La différence est que les images portent une ambiguïté que le texte ne peut pas, y compris les objets qui se chevauchent, les relations de profondeur et spatiales et l'occlusion partielle. Une invite pour l'analyse visuelle devrait nommer comment Claude devrait gérer chaque type d'ambiguïté. « Si les objets se chevauchent, décrivez chacun séparément et notez le chevauchement » est une contrainte concrète qu'une invite de texte seul n'aurait jamais besoin.

L'API Message Batches : Traitement asynchrone à haut volume Lorsque vous avez besoin d'exécuter le même modèle d'invite contre des centaines ou des milliers d'entrées, l'API synchrone est le mauvais modèle. Chaque appel synchrone se bloque jusqu'à la fin. À l'échelle, cela signifie que votre application brûle des threads ou exécute des milliers de connexions simultanées par rapport aux limites de débit. L'API Message Batches accepte jusqu'à 100 000 ou 256 MB de demandes (selon ce qui vient en premier) dans un seul appel de lot. Vous soumettez le lot, recevez un batch_id et interrogez la fin. Lorsque le lot se termine, vous téléchargez les résultats. Le coût par token pour les demandes de lot est inférieur à celui des demandes synchrones. Le compromis est la latence : le traitement par lot est non déterministe et peut prendre jusqu'à 24 heures, souvent beaucoup plus rapide. Le modèle convient aux pipelines hors ligne, aux exécutions d'évaluation et aux travaux de traitement de données, pas aux interactions en temps réel avec l'utilisateur.

Cas d'utilisationModèle API correctPourquoi Un utilisateur télécharge une photo et s'attend à une classification immédiate. API synchroneUne réponse en temps réel est requise. La latence du lot est inacceptable pour l'utilisation interactive. Un pipeline nocturne classe 5 000 dossiers de clientsAPI Message BatchesLa latence n'est pas une contrainte. La réduction des coûts du lot et le traitement asynchrone sont tous deux précieux. Une exécution d'évaluation teste une nouvelle invite par rapport à 2 000 exemplesAPI Message BatchesUne tâche hors ligne sans exigence en temps réel. Le lot est le modèle correct. Un chatbot génère une réponse au message d'un utilisateurAPI synchroneL'utilisateur attend ; le lot introduirait un délai inacceptable.

Quand le multimodal et le lot s'adaptent ensemble, et quand ils ne le font pas La combinaison fonctionne pour les charges de travail hors ligne qui réutilisent les mêmes actifs et ont besoin d'une sortie structurée sur des milliers d'entrées. Un pipeline nocturne classant les images par rapport à une taxonomie fixe est le cas d'école : l'API Files supprime les téléchargements redondants, l'API Batches absorbe la latence, les techniques de sortie structurée gardent les résultats lisibles par machine. Deux modes de défaillance cassent l'ajustement.

Le premier est une mauvaise lecture de la latence : utiliser le lot dans n'importe quel flux orienté utilisateur avec une image produit un système qui réussit les tests et échoue en production, car l'utilisateur attend et le lot ne l'est pas. Le second est une sous-estimation du coût du contexte : les images et les PDF consomment le budget avant que Claude ne traite du texte, donc les pipelines chargeant plusieurs grandes images par demande dépassent les limites de tokens à l'échelle. Mesurez le coût des tokens sur les entrées à l'échelle de production avant de construire.

Screen 25: The batch job that was not actually a batch

Watch OutMultimodal and Batch Ingestion·4 min Le travail par lot qui n'était pas réellement un lot

Setup Diviser un travail en morceaux et les traiter un après l'autre n'est pas un traitement par lot ; c'est une sérialisation avec des étapes supplémentaires. L'API Message Batches existe pour les charges de travail à haut volume précisément parce que boucler sur les entrées par rapport à l'API synchrone se heurte aux limites de débit au moment où le volume devient réel, peu importe comment vous divisez la liste d'entrée.

Une conversation de canal interne sur un travail nocturne qui continuait à atteindre les limites de débit Un développeur a réexécuté le même travail de classification nocturne pendant trois nuits et continue à atteindre les erreurs de limite de débit à peu près au même moment à chaque fois. Le développeur senior pose une question qui fait surface le problème réel.

Developer: "My nightly job keeps hitting rate limits. I've already split it into smaller chunks. What else can I do? " Senior Developer: "How are you submitting them? " Developer: "I'm looping over the list and calling the API for each item. " Senior Developer: "That is not batching. That is serial calls against the synchronous endpoint. Splitting the list into chunks does not change what the API sees: it still sees one request per item, back to back. " Developer: "So the rate limit is firing because I am making thousands of synchronous calls? " Senior Developer: "Right. The Message Batch API takes up to 100,000 requests or 256 MB per batch in a single batch call, returns a batch_id, and processes them asynchronously. You poll for completion, which means your code repeatedly checks the status of the batch on a schedule until the API tells you it's done. The per-token cost is lower than synchronous, and the rate limit does not fire because you are not making thousands of individual requests. " Developer: "And the tradeoff? " Senior Developer: "Latency is non-deterministic. Batch processing can take hours. If this were a real-time user interaction, it would be the wrong tool. However, this is perfect for a nightly classification run. "

What to Watch Out for Diviser une liste et boucler sur l'API synchrone n'est pas un traitement par lot, même si cela semble devoir l'être. Il produit le même nombre d'appels API que la version non divisée et se heurte aux mêmes limites de débit. L'API Message Batches est un modèle de soumission différent, pas une taille de lot plus petite. Utilisez-la chaque fois que la charge de travail est à haut volume et hors ligne et utilisez l'API synchrone uniquement lorsqu'un utilisateur attend de l'autre côté. Les résultats reviennent dans un ordre arbitraire, pas l'ordre dans lequel les demandes ont été soumises. Utilisez le champ custom_id sur chaque demande pour faire correspondre les résultats aux entrées.

Screen 26: Checkpoint 8 · Select the right input encoding for each scenario

CheckpointMultimodal and Batch Ingestion·3 min Checkpoint 8 · Sélectionner le bon encodage d'entrée pour chaque scénario Lisez les trois scénarios d'entrée ci-dessous. Pour chaque scénario d'entrée, sélectionnez la méthode d'encodage correcte. La rétroaction de chaque élément nomme le coût du mauvais choix.

Un diagramme de produit de référence utilisé dans chaque demande que votre pipeline faitAPI Message Batches : soumettre toutes les demandes dans un appel de lot, interroger la fin. API Files : télécharger une fois, référencer file_id dans chaque demande. Base64 en ligne : encoder et inclure directement dans le bloc de message. Une capture d'écran ponctuelle d'un bug d'interface utilisateur, soumise par un ingénieur d'assistance dans une seule demandeAPI Message Batches : soumettre toutes les demandes dans un appel de lot, interroger la fin. API Files : télécharger une fois, référencer file_id dans chaque demande. Base64 en ligne : encoder et inclure directement dans le bloc de message. Un travail classant 5 000 réponses de commentaires clientsAPI Message Batches : soumettre toutes les demandes dans un appel de lot, interroger la fin. API Files : télécharger une fois, référencer file_id dans chaque demande. Base64 en ligne : encoder et inclure directement dans le bloc de message.

Submit Skip for now

Screen 27: Eight takeaways, one per enabling objective

RecapEight takeaways·3 min Huit points clés, un par objectif d'activation

1

Lorsqu'une invite échoue, le type de défaillance vous indique quelle technique manque. La sortie dans la mauvaise forme pointe vers une contrainte de résultat manquante, la dérive entre les tours pointe vers une invite système sous-spécifiée et une structure halluccinée pointe vers l'absence d'exemples few-shot. L'instinct de reformuler l'instruction et de réessayer fonctionne rarement, car aucune de ces défaillances ne sont des problèmes de formulation. Diagnostiquez d'abord le type de défaillance, puis ajoutez la technique qui l'aborde. Lorsque les instructions au niveau de l'invite ne suffisent pas car les entrées non testées cassent toujours l'analyseur, déplacez le contrôle de sortie dans l'API avec des résultats structurés : les résultats JSON contraignent la réponse finale par rapport à un schéma, et l'utilisation d'outils strict valide les arguments que Claude transmet à vos outils, au coût de la latence de compilation du premier appel et des tokens d'entrée ajoutés.

2

Faites correspondre la profondeur du raisonnement à la tâche avant de régler l'invite. Activez le raisonnement uniquement lorsqu'une passe de raisonnement change la réponse et calibrez le paramètre d'effort au problème plutôt que de l'augmenter à chaque appel. Rappelez-vous que les blocs de réflexion reviennent à l'API inchangés ou la demande suivante échoue. Choisir quel modèle exécuter, contrairement à la question de savoir s'il faut activer le raisonnement, est enseigné dans le module MSO Foundations qui précède celui-ci.

3

Un stream qui se termine n'est pas un message qui se termine. Le streaming achète la latence perçue au coût d'assembler la réponse vous-même à partir d'événements partiels. Agissez sur un bloc uniquement après sa fermeture, validez un tour à l'historique uniquement après message_stop et en cas de stream interrompu, jetez le tour partiel et réessayez. Le mode de défaillance à reconnaître est une erreur d'utilisation d'outil à la nouvelle tentative qui remonte à un bloc à moitié construit d'un stream interrompu, pas au schéma.

4

Chaque mauvaise sélection d'outil remonte au schéma, et la plupart du temps à la description. Claude choisit un outil en lisant le champ description et en le faisant correspondre à la demande de l'utilisateur, ce qui signifie que deux outils qui disent tous les deux « use this to find information » sont indistinguibles du côté de Claude même lorsque les schémas d'entrée se ressemblent en rien. La phrase qui résout la plupart des bugs de mauvaise sélection d'outil est la condition d'exclusion : une ligne dans chaque description nommant quand ne pas appeler l'outil, écrite dans le schéma au moment de la conception plutôt qu'après que le premier appel incorrect ne s'affiche dans un journal. Lorsque quelqu'un d'autre a déjà écrit les outils, MCP vous permet de connecter un serveur maintenu au lieu de créer chaque schéma à la main, mais chaque serveur connecté ajoute ses définitions d'outils à la fenêtre de contexte que les outils soient utilisés ou non, donc connectez-vous délibérément et contrôlez le coût de chargement.

5

Le contexte est un budget fixe, et les résultats d'outils le dépensent plus vite que n'importe quoi d'autre dans la boucle. Les résultats d'outils de production s'exécutent trois à cinq fois plus longtemps que les fixtures, donc une session qui tient ensemble proprement sur cinquante tours en test peut atteindre le plafond au tour huit une fois qu'elle est expédiée. L'élagage, la compaction et les transferts de sous-agents achètent chacun de l'espace de manière différente, et celui à appliquer dépend de si vous avez toujours besoin de l'état antérieur. Lorsque la sélection d'outil commence à se dégrader après un nombre fixe de tours, la fenêtre est le premier endroit à regarder, pas le schéma.

6

La décision flux de travail-ou-agent définit le coût de tout ce qui suit, et les points de contrôle humains appartiennent à la conception. Un flux de travail est le bon appel lorsque vous pouvez écrire les étapes exactes dans le code, et un agent est le bon appel lorsque vous pouvez spécifier l'objectif et les outils mais pas le chemin entre eux. Choisir mal dans l'une ou l'autre direction ne fait surface qu'en production : les agents où les flux de travail feraient ajouter du coût de contexte et un comportement qui vit dans les transcriptions, et les flux de travail où les agents sont nécessaires cassent la première fois qu'une entrée sort du chemin. Si un outil peut prendre une action irréversible, le point de contrôle human-in-the-loop va avant que la boucle soit câblée, pas après que la première écriture atteigne un environnement client.

7

La portée de la mémoire est décidée par la forme de la session, pas par ce qui est le plus facile à implémenter. La mémoire en contexte est le modèle le plus simple à écrire, ce qui est aussi pourquoi c'est celui qui échoue le plus tôt lorsque les sessions de production s'avèrent être plus courtes et plus nombreuses que les longues sessions continues utilisées en développement. Le stockage externe ajoute une latence mais l'état survit entre les sessions, la mémoire résumée réduit les coûts mais perd tout ce que l'invite du résumeur n'a pas préservé, et sans état est correct pour les travaux qui se terminent et se ferment. La refactorisation de en contexte à externe sous pression de production prend environ une heure, et faire le même choix délibérément au moment de la conception prend environ vingt minutes. Porter les instructions répétables entre les tâches est un problème distinct de porter l'état, et le modèle pour cela est une Compétence : un fichier markdown que Claude charge à la demande en faisant correspondre sa description, plutôt que des instructions injectées dans chaque session.

8

Calculez le coût d'une entrée multimodale avant d'écrire le code d'ingestion et faites correspondre l'API à la charge de travail. Une image coûte ⌈largeur / 28⌉ × ⌈hauteur / 28⌉ tokens visuels, et le plafond par image diffère par niveau de modèle. Un original haute résolution sur les modèles les plus récents peut coûter plusieurs fois ce qu'une miniature coûte dans votre ensemble de test, donc la formule doit s'exécuter par rapport à la plus grande entrée que vous attendez en production plutôt que les entrées que vous avez sous la main. Base64 en ligne s'adapte aux images ponctuelles, l'API Files s'adapte aux actifs réutilisés entre les demandes, et l'API Message Batches gère le travail hors ligne à un coût par token inférieur en échange d'une latence non déterministe. L'erreur à éviter est d'appeler l'API synchrone dans une boucle et de traiter cela comme un traitement par lot.

Ce qui vient ensuite Ce module a établi la bibliothèque primitive Developer, y compris cinq types d'interaction que tous les modules Developer suivants tirent. Les modèles introduits ici, y compris la création d'invites, les schémas d'outils, l'ingénierie du contexte, la construction d'agents, la portée de la mémoire et l'ingestion multimodale, forment la base de chaque module qui suit.

Sources

Claude 101 (Skilljar): Fondamentaux de l'invite, bases de l'utilisation d'outils, aperçu des agents et des flux de travail, concepts de fenêtre de contexte. Claude Code 101 In Action (Skilljar): Gestion du contexte (/compact, /clear), boucle d'agent Claude Code, modèles d'agents de production. AI Fluency Framework Foundations (Skilljar): Techniques d'invite, exemples few-shot, spécification de contrainte. Building with the Claude API (Skilljar): Schémas d'outils, structure des blocs de message, streaming, résultats structurés, API Files, API batch, construction d'agents. platform. claude. com: Référence canonique pour l'utilisation d'outils, les agents, le contexte, MCP, la mécanique de l'API. Tirez à la publication et re-vérifiez. Anthropic Blog: "Building Effective Agents": Sous-modèles de flux de travail (chaînage, routage, parallélisation, optimiseur-évaluateur), conseils de conception d'agents.

Vous pouvez maintenant prendre un prototype Claude en production. Les invites prêtes pour la production, les boucles d'utilisation d'outils, le streaming, la gestion du contexte et de la mémoire, et les boucles d'agents avec points de contrôle tiennent maintenant bon lors d'une utilisation réelle.

Screen 28: Key terms from this module

GlossaryKey Terms·3 min Termes clés de ce module Alphabétique. Cliquez sur un terme pour développer sa définition.

Claude Agent SDKA managed agent runtime distributed as @anthropic-ai/claude-agent-sdk (Typescript) / claude-agent-sdk (Python). It gives a partner programmatic access to the same agent loop that powers Claude Code: iteration, tool execution, observation, termination, so the partner can embed an agent inside their own product instead of running Claude Code in a terminal. Distinct from the Anthropic SDK, which is a thin convenience wrapper over the API and does not run an agent loop. Fenêtre de contexteNombre total de tokens qu'un modèle peut traiter dans une seule demande, y compris l'invite système, l'historique de conversation, les définitions d'outils, les résultats d'outils et la sortie du modèle lui-même. Lorsque le total courant atteint la limite, le contenu antérieur doit être supprimé ou résumé avant que le nouveau contenu ne puisse être ajouté. Signature de fonctionLa signature de fonction est un terme de programmation qui signifie la déclaration d'une fonction : son nom plus la liste des paramètres qu'elle accepte, y compris leurs noms, types et toutes les valeurs par défaut. HITLHuman-in-the-loop fait référence à l'insertion d'une étape d'examen ou d'approbation humaine dans un processus automatisé avant qu'une action conséquente ne soit prise. RefactoriserRefactoriser fait référence à la modification de la structure interne du code sans changer ce qu'il fait de l'extérieur. Vous réorganisez, renommez ou réécrivez l'implémentation pour la rendre plus propre, plus rapide, plus facile à tester ou plus facile à étendre, mais le comportement que le reste du système voit reste le même. SOC 2Service Organization Control 2 est un cadre d'audit développé par l'American Institute of Certified Public Accountants (AICPA) pour évaluer la façon dont une organisation de services gère les données des clients. C'est la norme la plus couramment citée lorsqu'un fournisseur SaaS ou un fournisseur de services cloud est invité à démontrer que ses pratiques de sécurité répondent à une barre reconnue. ÉtatL'état est l'information qu'un agent porte entre les tours : la conversation jusqu'à présent, ce que l'utilisateur a demandé, les résultats des appels d'outils antérieurs. Stop_reasonUn champ dans la réponse de l'API qui indique à votre code pourquoi le modèle a cessé de générer. Les deux valeurs les plus pertinentes pour les boucles agentic sont end_turn, ce qui signifie que Claude a terminé et ne demande pas d'action supplémentaire, et tool_use, ce qui signifie que Claude a émis un ou plusieurs blocs tool_use et attend les résultats avant de continuer. Sous-agentUne instance d'agent séparée générée par un agent orchestrateur pour gérer une sous-tâche discrète. Les sous-agents n'héritent pas de l'historique de conversation, des compétences ou du contexte de la session parent, chacun commence propre et doit être configuré explicitement avec les instructions et les outils dont il a besoin. Les résultats sont retournés à l'orchestrateur, qui les incorpore dans la tâche plus large. TokenL'unité que Claude utilise pour mesurer et traiter le texte. La moyenne de caractères par token dépend du tokenizer du modèle en question et diffère entre les générations de modèles. Traitez toute règle de caractères par token comme dépendante du modèle et confirmez le comportement actuel du tokenizer au moment de la construction. Les tokens sont consommés par tout dans la fenêtre de contexte : les invites, les réponses, les schémas d'outils et les résultats d'outils. Ils sont la base des calculs de prix et de budget de contexte. Bloc tool_useUn bloc de contenu retourné par l'assistant lorsque Claude veut appeler une fonction. Contient le nom de l'outil, un ID unique et les arguments d'entrée que Claude veut transmettre à votre code. Chaque bloc tool_use doit être répondu par un bloc tool_result correspondant dans le tour utilisateur immédiatement suivant, avec le même ID préservé exactement.

Screen 29: Congrats! You've successfully completed this module.

Module CompleteDeveloper Path·2 min Félicitations ! Vous avez réussi à terminer ce module. Vous pouvez maintenant écrire des invites prêtes pour la production, câbler une boucle d'utilisation d'outils qui survit aux conditions réelles, gérer le streaming en toute sécurité, gérer le contexte et la mémoire à l'échelle et construire une boucle d'agent avec les bons points de contrôle aux bons endroits. Les décisions d'ingénierie dans ce module sont celles qui séparent un prototype d'un système qui tient bon en production.

0 of ? checkpoints passed

M1

MSO Foundations Tokens, context windows, sampling, model tiers, prompting modes, and the API transport mechanics.

M2

Production-Grade Prompting, Agents & Tool-use Production-ready prompts, tool-use loops, streaming, context and memory management, and checkpointed agent loops.

You Are Here

M3

Claude Code, MCP & Integration Permission modes, durable project context, plugin packaging, and MCP integration without leaking credentials.

Up Next

M4

Production Engineering, Evals, and Security Evals, tracing, failure handling, cost and orchestration budgets, and security boundaries that hold in production.

M5

Accelerators and IP Contribution Package accelerators, prepare verifiable contributions, choose deployment platforms, and mark trust boundaries.

Review module Start over Start Module 3 → Return to course home

Module 2 complete.