Claude Agent SDK : les patterns d'orchestration qui tiennent en prod

Depuis un an, “agent” est devenu un mot fourre-tout. Sur le terrain, 90 % de ce qu’on appelle agent est une boucle while autour d’un appel LLM. Pas forcément un problème — sauf en prod, où chaque raccourci se paie cash. Voici ce que j’ai retenu après plusieurs intégrations du Claude Agent SDK pour des clients B2B.

Pourquoi passer au SDK plutôt qu’une boucle maison

Une boucle while avec tool_use tient tant que le périmètre est court : trois outils, deux tours, un timeout. Au-delà, on réinvente à la main la gestion du contexte, la compaction, les budgets de tokens, le retry par outil, le logging structuré. Le SDK vous donne ça d’entrée, et surtout il impose une discipline : on pense en sous-agents, permissions d’outils et sessions, pas en “je rappelle l’API”.

Le vrai gain n’est pas la performance. C’est la lisibilité opérationnelle. Quand un agent plante à 2 h du matin, je veux savoir quel outil a été appelé, avec quel input, dans quelle session, et pourquoi le modèle a décidé de l’appeler. Sans ce minimum, le debug devient de la voyance.

Les trois patterns qui tiennent

Agent unique avec budget d’outils borné

Le pattern le plus sous-estimé. Un seul agent, 3 à 5 outils maximum, un budget de tours explicite. Pour la majorité des cas métier (extraction, classification avec recherche, assistance ciblée), c’est suffisant — et souvent meilleur que plus sophistiqué.

import { query } from "@anthropic-ai/claude-agent-sdk";

const result = await query({
  prompt: userRequest,
  options: {
    model: "claude-sonnet-4-6",
    maxTurns: 6,
    allowedTools: ["search_crm", "read_contract", "create_ticket"],
    systemPrompt: TICKET_AGENT_PROMPT,
  },
});

Le maxTurns n’est pas du zèle. Sans lui, un agent qui boucle sur une erreur d’outil peut brûler 200 k tokens en silence. J’ai vu la facture.

Orchestrateur + sous-agents en fan-out

Dès qu’une tâche se découpe en sous-tâches indépendantes, le pattern orchestrateur devient rentable. Un agent principal délègue à des sous-agents spécialisés, chacun avec son contexte et ses outils. Le bénéfice n’est pas la parallélisation : c’est l’isolation de contexte. Un sous-agent qui avale 50 pages de doc ne pollue pas le raisonnement de l’orchestrateur.

Ma règle : si deux sous-tâches n’ont pas besoin de partager de contexte intermédiaire, elles vont dans deux sous-agents. Sinon on paie le contexte deux fois et on brouille le raisonnement du modèle.

Human-in-the-loop aux points critiques

Tout ce qui écrit dans un système métier — envoi d’email, création de facture, modification de CRM — passe par une confirmation humaine explicite. Pas par un “l’utilisateur peut annuler après”. Le SDK expose des hooks de permission par outil, je les utilise systématiquement :

const result = await query({
  prompt: userRequest,
  options: {
    allowedTools: ["draft_email", "send_email"],
    canUseTool: async (toolName, input) => {
      if (toolName === "send_email") {
        return await askUserConfirmation(input);
      }
      return { behavior: "allow", updatedInput: input };
    },
  },
});

Un agent qui envoie un mail à côté de la plaque à un client, c’est une engueulade. Un agent qui propose un brouillon et attend confirmation, c’est un gain de productivité. La différence tient en dix lignes de code.

MCP : utile ou hype

MCP (Model Context Protocol) est sur-vendu sur les cas simples et sous-utilisé sur le seul cas où il brille : partager un même inventaire d’outils entre plusieurs agents et plusieurs clients.

Si votre agent vit dans un seul service Node avec trois outils internes, écrivez-les en TypeScript direct. Un serveur MCP pour ça, c’est de la plomberie qui ralentit le prototypage. En revanche, dès que les mêmes outils doivent tourner dans Claude Code, dans votre agent custom et dans un futur outil de support, MCP devient rentable. Le seuil est clair : plusieurs consommateurs ou rien.

Les garde-fous non négociables

Trois choses que je refuse de livrer sans :

1. Logging structuré par session. Chaque tool call, input, output, latence, tokens. Sans ça, impossible de debugger un agent qui part en vrille.
2. Budget tokens par session. Un hard cap côté application, en plus du maxTurns. Protège contre les prompts injectés et les boucles d’outils récalcitrantes.
3. Isolation des permissions. Un agent “lecture seule” n’a pas accès aux outils d’écriture. Même si ça complique la config. Les arbres de permission du SDK sont faits pour ça — utilisez-les.

On peut empiler OpenTelemetry, rate limiter par utilisateur, fallback sur un modèle plus petit pour les tâches simples. Mais ces trois-là sont le minimum viable prod. Pas de négociation.

Par où commencer

Si vous hésitez :

• Prenez un workflow interne bien cadré (tri de tickets, qualification de leads, extraction depuis contrats).
• Écrivez-le d’abord en agent unique avec 3 outils et maxTurns: 6.
• Mesurez sur 50 à 100 cas réels : taux de succès, coût moyen, latence p95.
• Ne passez à l’orchestrateur + sous-agents qu’après avoir atteint un plafond clair du pattern simple.

La plupart des projets d’agents qui cassent en prod ne souffrent pas d’un manque de sophistication. Ils souffrent d’une sophistication prématurée. Un agent simple, bien instrumenté, avec un humain au bon endroit, bat presque toujours une architecture multi-agents sans garde-fous.

Si vous avez un cas d’usage précis et hésitez sur le pattern, cadrez-le en une page (input, output attendu, outils disponibles, risque métier si l’agent se trompe). On en parle.