Construire un agent
Quand un agent est justifié, comment concevoir sa surface d’outils, gérer son contexte sur la durée, et quelles briques choisir entre boucle maison, agents gérés et SDK.
À la fin de ce chapitre, vous saurez
- Décider si un agent est vraiment nécessaire, ou si un enchaînement suffit
- Concevoir une surface d’outils qui permet de contrôler ce qui compte
- Gérer le contexte d’un agent qui tourne longtemps
- Choisir entre boucle maison, agents gérés et SDK
Dans ce chapitre
Le mot « agent » recouvre beaucoup de choses. Ici, il désigne précisément ceci : un modèle qui décide lui-même de la suite d’actions à mener, en boucle, jusqu’à atteindre un objectif.
C’est le niveau le plus puissant et le plus coûteux. Ce chapitre commence donc par la question qu’on saute trop souvent.
Faut-il vraiment un agent ?
Quatre critères. Une seule réponse négative suffit à redescendre d’un niveau.
Le chemin est-il imprévisible ? Si vous connaissez les étapes, codez-les. Un enchaînement d’appels est plus prévisible, moins cher, testable, et il se débogue.
Le résultat justifie-t-il le coût ? Un agent multiplie les appels, donc la latence et la facture. Sur une tâche à faible valeur, l’arithmétique ne tient pas.
Claude est-il bon à cette tâche ? L’agentivité n’ajoute pas de compétence. Un modèle mauvais sur votre domaine sera mauvais en boucle, plus longtemps.
Une erreur est-elle rattrapable ? C’est le critère éliminatoire. Sans mécanisme de détection — tests, revue, vérification automatique —, un agent qui se trompe le fait en silence et à grande échelle.
| Situation | Le bon niveau |
|---|---|
| Classer, extraire, résumer, répondre | Un appel |
| Enchaînement dont vous connaissez les étapes | Plusieurs appels orchestrés par votre code |
| Chemin dépendant des résultats intermédiaires | Un agent |
| Tâche longue avec état, fichiers, reprise | Un agent géré |
Concevoir la surface d’outils
C’est la décision de conception la plus structurante, et elle se prend au niveau du harnais, pas du modèle.
Claude émet des appels d’outils ; votre code les reçoit. La forme de ces appels détermine ce que votre code peut faire.
Un outil shell générique donne une grande liberté au modèle — et une chaîne de caractères opaque à votre harnais. Impossible de valider, de gater, de journaliser proprement : toutes les actions se ressemblent.
Promouvoir une action en outil dédié donne à l’inverse des arguments typés, que le harnais peut intercepter.
Quatre raisons de promouvoir une action :
Une frontière de sécurité. envoyer_email(destinataire, objet, corps) se soumet à confirmation ; bash("curl -X POST ...") ne se contrôle pas.
Une vérification d’état. Un outil d’édition peut refuser d’écrire si le fichier a changé depuis la dernière lecture. Une commande shell ne peut pas garantir cet invariant.
Un rendu particulier. Une demande de validation présentée comme une boîte de dialogue plutôt que comme du texte.
L’ordonnancement. Un outil de lecture peut être marqué parallélisable ; un outil qui écrit doit être sérialisé. Passées par un shell générique, ces deux actions sont indistinguables.
La règle : commencez large pour la couverture, promouvez en outil dédié dès qu’il faut gater, vérifier, afficher ou paralléliser.
Gérer le contexte dans la durée
Une session agentique remplit sa fenêtre plus vite qu’une conversation : chaque résultat d’outil s’y accumule. Le chapitre 3 s’applique, avec des leviers spécifiques.
Nettoyer les résultats devenus inutiles. Un mécanisme d’édition de contexte permet de retirer les anciens résultats d’outils, dont on n’a plus besoin une fois exploités. C’est différent d’un résumé : c’est une suppression.
Condenser. À l’approche de la limite, l’historique ancien est remplacé par un résumé produit côté serveur. Point technique important : il faut rejouer le contenu complet de la réponse, blocs de condensation compris. N’extraire que le texte perd l’état de condensation, et la conversation repart de travers.
Sortir l’état durable des messages. C’est le levier le plus efficace, et le moins utilisé. Un agent qui écrit ses conclusions dans des fichiers plutôt que de les garder dans l’historique peut tourner beaucoup plus longtemps — et reprendre après interruption.
# Ce qui reste dans l'historique : les décisions.
# Ce qui part dans des fichiers : les données, les résultats, les brouillons.Les trois façons de construire
Trois approches, et la question qui les sépare n’est pas la puissance : c’est qui fournit la boucle, et qui fournit l’hébergement.
La boucle manuelle
Vous écrivez le while stop_reason == "tool_use" du chapitre 30. Contrôle total, aucune dépendance.
Pour qui : un contrôle de flux que rien d’autre ne permet, ou le refus d’une dépendance en version d’essai.
L’exécuteur d’outils de la bibliothèque
La bibliothèque fournit la boucle ; vous fournissez les fonctions. Chaque tour vous est exposé avant l’exécution, ce qui permet d’insérer une validation, une interception d’erreur, une modification de résultat, un nouvel essai.
Pour qui : la grande majorité des agents à outils maison. C’est le défaut raisonnable.
Les agents gérés
Anthropic fournit la boucle et héberge un bac à sable par session : système de fichiers, exécution de commandes, exécution de code. Vous définissez une configuration d’agent — persistante et versionnée — puis vous ouvrez des sessions qui la référencent.
Pour qui : les sessions longues avec état, les agents qui doivent manipuler des fichiers, ceux qui tournent selon un calendrier, ceux dont la configuration doit être versionnée et partagée.
Le point structurant : l’agent est un objet persistant, créé une fois. L’anti-modèle le plus fréquent est de le recréer à chaque exécution — vous accumulez des objets orphelins et vous perdez tout le bénéfice du versionnement.
Les agents multiples
Question qui arrive vite : faut-il un agent ou plusieurs ?
Un seul, la plupart du temps. Les agents multiples ajoutent de la coordination, donc des modes de défaillance.
Plusieurs, quand les contextes doivent rester séparés. Un agent qui explore et un agent qui vérifie ont intérêt à ne pas partager de contexte : le vérificateur doit lire le travail avec un œil neuf, exactement comme la revue du chapitre 27.
Plusieurs, quand le travail est réellement parallèle. Vingt éléments indépendants à traiter.
Le motif le plus utile en pratique est producteur–vérificateur : un agent produit, un autre contrôle avec ses propres critères et son propre contexte. C’est aussi la réponse partielle au quatrième critère du début de chapitre — la détection d’erreur.
Un agent de triage d’incidents
La situation
Les alertes de production arrivent la nuit. Vous voulez qu’un agent fasse le premier diagnostic : rassembler le contexte, éliminer les fausses alertes, et préparer un rapport pour l’astreinte.
Les quatre critères, honnêtement
Chemin imprévisible ? Oui : ce qu’il faut regarder dépend de l’alerte. Valeur ? Oui : cela évite un réveil sur deux. Claude est-il bon ? Oui, sur la corrélation de journaux et de métriques. Erreur rattrapable ? Oui, à condition que l’agent ne puisse rien modifier.
Ce dernier point détermine toute la conception.
La surface d’outils
outils = [
# Lecture — large, sans danger
{"name": "chercher_logs", "description":
"Recherche dans les journaux sur une fenêtre de temps. Toujours "
"commencer par là. Renvoie au maximum 200 lignes."},
{"name": "lire_metriques", "description":
"Séries temporelles d'une métrique. À utiliser pour situer le "
"début de l'anomalie."},
{"name": "historique_deploiements", "description":
"Déploiements des dernières 24 h. À consulter systématiquement : "
"un déploiement récent est la cause la plus fréquente."},
{"name": "incidents_similaires", "description":
"Incidents passés ressemblant à la signature fournie."},
# Écriture — un seul outil, sans conséquence externe
{"name": "ecrire_rapport", "description":
"Enregistre le rapport de triage. Seule action d'écriture "
"autorisée. N'alerte personne."},
]Aucun outil ne redémarre un service, ne modifie une configuration ni ne contacte qui que ce soit. Ce n’est pas une consigne : c’est l’absence d’outil. Le modèle ne peut pas faire ce qu’il n’a pas les moyens de faire.
L’instruction système qui structure le travail
SYSTEME = """Tu fais le premier triage d'une alerte de production.
Méthode obligatoire, dans cet ordre :
1. Vérifier s'il y a eu un déploiement dans les 2 h. C'est la cause la
plus fréquente.
2. Situer le début exact de l'anomalie dans les métriques.
3. Chercher dans les journaux sur une fenêtre encadrant ce début.
4. Chercher un incident similaire passé.
Ta conclusion prend obligatoirement l'une de ces trois formes :
- FAUSSE_ALERTE, avec ce qui l'établit
- CAUSE_IDENTIFIEE, avec les preuves et le lien de causalité
- DIAGNOSTIC_INSUFFISANT, avec ce que tu as éliminé et ce qu'il
faudrait regarder
N'invente jamais une corrélation. Si deux événements coïncident sans
que tu puisses établir un lien, dis-le explicitement.
Tu ne peux modifier aucun système. Si une action corrective s'impose,
écris-la dans le rapport ; ne cherche pas à l'exécuter.
"""Les trois formes de conclusion sont le mécanisme de détection : DIAGNOSTIC_INSUFFISANT est une réponse acceptable et fréquente, ce qui évite le diagnostic inventé pour ne pas rendre copie blanche.
Le vérificateur
Un second agent, contexte séparé, lit le rapport et les mêmes sources :
VERIFICATEUR = """Tu vérifies un rapport de triage produit par un autre
agent. Tu as accès aux mêmes sources.
Pour chaque affirmation du rapport :
- Est-elle étayée par les données que tu peux consulter ?
- La causalité est-elle établie, ou seulement une coïncidence ?
- Quelle hypothèse n'a pas été explorée ?
Conclus par : CONFIRMÉ, CONFIRMÉ_AVEC_RÉSERVES, ou NON_ÉTAYÉ.
Sois hostile. Un rapport que tu confirmes réveillera quelqu'un.
"""Le résultat
L’astreinte reçoit un rapport et son verdict de vérification. Les NON_ÉTAYÉ sont traités comme des alertes brutes — on n’a rien perdu. Les CONFIRMÉ font gagner vingt minutes de recherche en pleine nuit.
Et surtout : aucun agent ne peut aggraver l’incident, parce qu’aucun n’a d’outil pour le faire.
Ce qu’il faut retenir
Vérifier que c’est passé
3 questions. Rien n’est enregistré, rien n’est envoyé : c’est pour vous.
Le test des quatre critères
Prenez un projet d’agent que vous envisagez. Répondez par écrit aux quatre questions : la tâche est-elle réellement impossible à décomposer à l’avance ? Le résultat justifie-t-il le surcoût en latence et en jetons ? Claude est-il bon à ce type de tâche ? Une erreur peut-elle être détectée et rattrapée ? Si une seule réponse est non, écrivez plutôt l’enchaînement — et gardez ce document, il vous évitera de recommencer le débat dans six mois.
Un indice, si vous bloquez
La quatrième question est celle qui élimine le plus de projets : sans mécanisme de détection, un agent qui se trompe le fait en silence et à grande échelle.