Claude Agent SDK : construire des coéquipiers IA persistants

Quand Anthropic a lancé Claude Tag le 23 juin 2026, l'éditeur a remplacé l'ancienne application « Claude in Slack » par quelque chose d'architecturalement neuf : une identité Claude partagée par canal, une mémoire persistante entre coéquipiers, et un mode ambiant où Claude publie de sa propre initiative sans qu'on l'interpelle. C'est la même boucle d'agent qui anime Claude Code, reconditionnée en coéquipier longue durée dans une surface de discussion.

La bonne nouvelle pour les développeurs : les briques sont publiques. Le Claude Agent SDK expose la même boucle, les mêmes outils, sessions et plomberie MCP que Claude Tag utilise en interne. Vous pouvez vous en servir pour livrer des coéquipiers persistants dans votre propre produit — un bot Discord qui trie les incidents, un agent WhatsApp qui relance les devis, un agent d'espace de travail qui surveille votre CRM et pingue les ventes quand une affaire s'éteint.

Ce guide parcourt les quatre primitives nécessaires pour assembler un coéquipier persistant : identité, mémoire, outils et déclencheurs.

Le pattern du coéquipier persistant

Un coéquipier n'est pas un chatbot. Trois propriétés les séparent :

Identité partagée, pas par utilisateur. Un canal Slack a un seul @Claude auquel chaque coéquipier parle et avec qui chacun partage le contexte — pas une instance séparée par personne. C'est l'inverse du modèle « assistant IA par utilisateur ».
Une mémoire qui survit à la conversation. Ce que l'agent apprend dans le fil de lundi est disponible vendredi, à un autre coéquipier, sans qu'on le réamorce.
Agence ambiante. L'agent peut agir sans être interpellé. Il observe l'environnement et décide ce que les humains doivent savoir.

Ces trois propriétés sont étonnamment difficiles à rétro-équiper sur une API LLM sans état. L'Agent SDK les fournit comme concepts de première classe.

Installation et démarrage

Le SDK existe en TypeScript et en Python. Le paquet TypeScript embarque un binaire natif Claude Code, donc un seul npm install suffit.

npm install @anthropic-ai/claude-agent-sdk
# ou
pip install claude-agent-sdk

Définissez votre clé API en variable d'environnement. Le SDK accepte aussi des fournisseurs tiers — Amazon Bedrock, Google Vertex AI, Microsoft Foundry, Claude Platform on AWS — via des indicateurs dédiés. Pour les équipes MENA qui routent par Bahreïn (AWS) ou Émirats Nord (Azure) au titre de la résidence des données, c'est la voie de moindre friction.

export ANTHROPIC_API_KEY=your-api-key

Une boucle d'agent minimale en TypeScript ressemble à ceci :

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Résume les tickets ouverts dans #engineering cette semaine",
  options: { allowedTools: ["Read", "WebFetch", "Grep"] }
})) {
  console.log(message);
}

query retourne un itérateur asynchrone sur le flux de messages — tours assistant, appels d'outils, résultats d'outils, et un message result final. Le SDK gère la boucle d'outils en entier. Comparez avec le Client SDK Anthropic brut, où il faudrait écrire votre propre boucle while (response.stop_reason === "tool_use"), marshaller les résultats et les renvoyer à la main.

Identité scopée au canal

Pour transformer cette requête one-shot en coéquipier de canal, il faut une identité stable rattachée à une surface de discussion. Deux patterns marchent :

Un processus par canal. Un worker longue durée garde la boucle d'agent chaude.
Une session par canal. Worker sans état, mais chaque message reprend un identifiant de session sauvegardé.

Pour la plupart des équipes, le second pattern est moins cher et plus simple à opérer. Le SDK persiste les sessions en JSONL sur votre système de fichiers, et vous les reprenez par identifiant.

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function handleMessage(channelId: string, userText: string, savedSessionId?: string) {
  let sessionId: string | undefined;
 
  for await (const message of query({
    prompt: userText,
    options: {
      resume: savedSessionId,
      allowedTools: ["Read", "WebFetch", "Grep", "Bash"]
    }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }
    if ("result" in message) {
      await postToChannel(channelId, message.result);
    }
  }
 
  await saveSessionId(channelId, sessionId);
}

L'agent dans #engineering devient une identité distincte de #support — mémoire différente, outils différents, prompt système différent — mais chacun est durable d'un message à l'autre. Plusieurs coéquipiers qui postent dans le même canal partagent le même Claude.

Mémoire : CLAUDE.md plus le journal de session

Le SDK expose deux couches de mémoire et vous devez utiliser les deux.

La mémoire projet vit dans .claude/CLAUDE.md (ou CLAUDE.md à la racine du répertoire de travail). Le SDK la charge dans chaque session comme contexte système. Utilisez-la pour les faits qui ne doivent jamais changer entre conversations : qui est l'équipe, ce que fait le produit, vos conventions, les règles d'escalade. Pour un coéquipier de canal, écrivez un CLAUDE.md différent par canal.

La mémoire de session est le journal JSONL de chaque tour dans une session reprise. Elle porte la vue qu'a le modèle des conversations passées, fichiers lus, résultats d'outils reçus. Le SDK gère la compaction quand la fenêtre de contexte se remplit.

Une troisième couche pragmatique est votre propre base de données. Les sessions peuvent croître sans limite, et vous ne voulez pas qu'un journal emballé devienne la vision du monde de l'agent. Pattern courant : résumer en quelques paragraphes les sessions plus anciennes qu'une semaine, écrire ces paragraphes dans CLAUDE.md, et démarrer un nouvel identifiant de session. L'agent garde le savoir durable et laisse tomber le bruit.

Sandboxing d'outils avec MCP

Le Model Context Protocol est la part de l'Agent SDK qui rend les coéquipiers persistants dignes d'être lancés en production. MCP est un standard ouvert pour connecter les agents à des systèmes externes — bases de données, suivis de tickets, navigateurs, vos APIs internes — sans écrire d'implémentations d'outils sur mesure.

Connecter un serveur MCP tient en une ligne de configuration :

for await (const message of query({
  prompt: "Qu'est-ce qui a changé dans le dépôt depuis hier ?",
  options: {
    mcpServers: {
      github: { command: "npx", args: ["@modelcontextprotocol/server-github"] },
      slack: { command: "npx", args: ["@modelcontextprotocol/server-slack"] }
    },
    allowedTools: ["Read", "Grep"]
  }
})) {
  if ("result" in message) console.log(message.result);
}

Pour un coéquipier de canal, vous voulez presque toujours un scopage d'outils par canal. L'agent #finance ne doit pas avoir d'écriture GitHub. L'agent #engineering ne doit pas voir de PII client. Le pattern : calculer mcpServers et allowedTools à partir des métadonnées du canal avant chaque requête — pas livrer un méga-agent avec tout allumé.

L'autre contrôle clé est permissionMode. Le défaut est d'inviter ; acceptEdits auto-approuve les éditions ; bypassPermissions est réservé à l'automatisation de confiance. Pour un agent ambiant de canal, exposez un ensemble étroit d'outils pré-approuvés et exigez une confirmation humaine pour tout ce qui franchit une frontière (un paiement, un post public, une suppression).

Hooks : la piste d'audit dont vous aurez besoin

Tout coéquipier persistant finit par devoir répondre à « qu'a fait l'agent la semaine dernière, au juste ? ». Les hooks sont les callbacks de cycle de vie du SDK pour ça. PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit — chacun se déclenche de manière synchrone et vous laisse logger, valider ou bloquer.

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";
 
const logToolUse: HookCallback = async (input) => {
  const tool = (input as any).tool_name;
  const args = JSON.stringify((input as any).tool_input);
  await appendFile("./audit.log", `${new Date().toISOString()} ${tool} ${args}\n`);
  return {};
};
 
for await (const message of query({
  prompt: "Traite les notes de frais de la semaine",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PreToolUse: [{ matcher: ".*", hooks: [logToolUse] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Pour la conformité INPDP en Tunisie et PDPL en Arabie saoudite, ce n'est pas optionnel. Chaque appel d'outil contre un système contenant des données personnelles — votre CRM, votre outil de facturation, votre boîte support — a besoin d'un enregistrement de ce qui a été lu, par quel agent, dans quel canal, pour le compte de qui. Un hook PostToolUse qui streame vers votre table d'audit couvre le cas standard.

Mode ambiant : déclencheurs, pas prompts

La part la plus dure d'un coéquipier persistant n'a rien à voir avec l'Agent SDK. Le SDK vous donne la boucle ; à vous de lui donner des raisons de se réveiller.

Trois sources de déclencheurs couvrent la plupart des cas d'usage :

Webhooks. Nouveau message Slack, nouveau ticket GitHub, nouveau prélèvement Stripe. Le handler webhook reprend la session du canal avec un prompt du genre « Un ticket haute priorité vient d'être ouvert ; revois et trie ».
Cron. Chaque jour ouvré à 9h, reprendre la session avec « Résume les logs d'astreinte de la nuit et publie tout ce qui mérite d'être signalé ». C'est ainsi qu'on obtient les bilans de fin de journée et les briefings du matin.
Moniteurs internes. Un petit processus qui surveille une file, une métrique ou un calendrier, et reprend la session quand un seuil est franchi. C'est le plus proche du « mode ambiant » de Claude Tag.

Le fil rouge est que le déclencheur, c'est votre code. L'Agent SDK ne s'abonne à rien en votre nom. Vous décidez ce qui compte comme événement, le déclencheur tire query({ resume: sessionId, prompt: "..."}), et l'agent raisonne sur sa mémoire accumulée avant de répondre.

Pour empêcher le mode ambiant de devenir du spam, conditionnez chaque post proactif à une vérification de confiance. Pattern simple : demander au modèle « dois-je poster ceci dans le canal, oui ou non, et pourquoi » en seconde passe, parser la réponse, et ne poster que sur oui. Ajoutez un rate limit par canal.

Sous-agents pour le travail parallèle

Les coéquipiers longue durée doivent souvent se ramifier. L'agent de tri dans #support peut avoir besoin de lire le profil client, fouiller la doc et vérifier les déploiements récents en parallèle. Le SDK fournit des sous-agents — agents enfants délégués avec leur propre contexte — pour modéliser cela.

for await (const message of query({
  prompt: "Trie le ticket d'acme.corp posté dans ce canal",
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Agent"],
    agents: {
      "doc-searcher": {
        description: "Cherche dans la doc produit et les changelogs.",
        prompt: "Trouve les passages de doc les plus pertinents pour la question utilisateur.",
        tools: ["Read", "Glob", "Grep"]
      },
      "deploy-checker": {
        description: "Vérifie les déploiements et incidents récents.",
        prompt: "Liste les déploiements et incidents des dernières 24 heures susceptibles d'affecter ce client.",
        tools: ["Bash", "WebFetch"]
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Chaque sous-agent tourne dans sa propre fenêtre de contexte, donc le parent ne paie pas en tokens le transcript complet de la recherche de doc — seulement le résumé que le sous-agent retourne. Les messages venant d'un sous-agent portent un parent_tool_use_id qui permet d'attribuer logs et coûts correctement.

SDK ou Managed Agents

Si faire tourner le stockage de sessions et les sandboxes dans votre propre infra ressemble à plus que ce que vous voulez opérer, la Claude Platform propose aussi Managed Agents — une API REST hébergée où Anthropic exécute la boucle d'agent et une sandbox par session pour vous. Vous envoyez des événements, vous recevez les résultats en streaming.

Le partage est simple :

Agent SDK quand l'agent doit toucher votre filesystem, vos services, vos bases de données accessibles seulement par VPN. Prototypage local. Outils sur mesure en code natif.
Managed Agents quand vous voulez zéro infra, des sessions longue durée out-of-the-box, et Anthropic qui opère la sandbox. Échelle de production sans construire votre propre stockage de sessions.

Le chemin courant est de prototyper sur l'Agent SDK en local, puis de déplacer les agents chauds vers Managed Agents une fois la forme claire.

Par où commencer

Si vous partez de zéro, le plus petit coéquipier persistant utile, c'est environ :

Un canal, un identifiant de session stocké en base indexé par canal.
Un CLAUDE.md décrivant le but du canal et ses règles.
Deux ou trois serveurs MCP, scopés au canal.
Un webhook qui reprend la session sur les nouveaux messages.
Un hook PostToolUse qui écrit une ligne d'audit.
Un cron qui poste un résumé matinal.

C'est environ deux jours de travail et vous obtenez un coéquipier qui se souvient de ce dont vous avez parlé hier, sait quels outils il a le droit de toucher, et peut publier sans qu'on le lui demande. À partir de là, chaque canal supplémentaire est de la configuration, pas du code.

Le glissement architectural que représente Claude Tag — des assistants par utilisateur vers des coéquipiers partagés, persistants, ambiants — est désormais de l'infrastructure ouverte. La vraie question n'est pas s'il faut en construire un, mais où dans votre produit une identité partagée à mémoire longue changerait la façon dont l'équipe travaille réellement.