SpyBara
Go Premium

agent-sdk/hosting.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 138 additions and 81 deletions.

2026
Wed 9 22:58 Fri 18 23:58 Tue 22 23:59

Héberger l'Agent SDK

Déployez l'Agent SDK en production : architecture de sous-processus, persistance des sessions, mise à l'échelle, observabilité et isolation multi-locataire pour Docker, Kubernetes et fournisseurs de sandbox.

L'Agent SDK crée et supervise un sous-processus claude CLI qui possède un shell, un répertoire de travail et des fichiers de session sur le disque. L'héberger n'est pas comme héberger un wrapper API sans état. Chaque agent en cours d'exécution est un processus de longue durée lié à l'état local, ce qui façonne la façon dont vous allouez les ressources, persistez les sessions et mettez à l'échelle entre les locataires.

Cette page couvre l'auto-hébergement sur votre propre infrastructure. Pour les Dockerfiles et manifestes Kubernetes déployables, consultez le guide d'hébergement.

Si vous n'avez pas besoin de contrôle d'infrastructure, d'isolation personnalisée ou de votre propre plan de données, envisagez plutôt les Agents gérés : une API REST hébergée où Anthropic exécute l'agent et le sandbox, de sorte que votre application envoie des événements et reçoit les résultats en streaming sans infrastructure d'hébergement à exploiter.

Le modèle de sous-processus

Chaque décision d'hébergement sur cette page découle de la façon dont le SDK exécute l'agent. Lorsque votre code appelle query(), le SDK lance un processus CLI claude séparé et communique avec lui via stdio. Ce sous-processus possède le shell, le répertoire de travail et les transcriptions de session JSONL sur le disque local.

Flux de requête : du client à votre application, qui lance un sous-processus CLI claude via stdio à l'intérieur du conteneur ; le sous-processus écrit sur le disque local et appelle api.anthropic.com via HTTPS Flux de requête : du client à votre application, qui lance un sous-processus CLI claude via stdio à l'intérieur du conteneur ; le sous-processus écrit sur le disque local et appelle api.anthropic.com via HTTPS

Une session d'agent correspond à un sous-processus. L'exécution de N sessions concurrentes signifie N sous-processus, chacun avec son propre arborescence de processus et son fichier de transcription. Par défaut, ils héritent tous du répertoire de travail de votre application. Lorsque les sessions ont besoin de systèmes de fichiers distincts, transmettez un cwd distinct dans les options de l'appel query() de chaque session :

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

for await (const message of query({
prompt: "Summarize the files in this directory",
options: { cwd: "/work/session-a" },
})) {
console.log(message);
}

Les exemples TypeScript sur cette page utilisent await au niveau supérieur, donc enregistrez-les en tant que fichiers .mts ou définissez "type": "module" dans package.json.

État qui réside sur le disque local

Trois types d'état d'agent résident par défaut sur le système de fichiers du conteneur. Aucun d'entre eux ne survit à un redémarrage de conteneur, à une réduction d'échelle ou à un déplacement vers un nœud différent.

État Emplacement par défaut
Transcriptions de session ~/.claude/projects/, ou le répertoire projects/ sous CLAUDE_CONFIG_DIR s'il est défini
Fichiers mémoire CLAUDE.md ~/.claude/CLAUDE.md pour le niveau utilisateur et le répertoire de travail de la session pour le niveau projet
Artefacts du répertoire de travail Le répertoire de travail de la session

Pour persister les transcriptions entre les hôtes, configurez un adaptateur SessionStore. Les fichiers mémoire et autres artefacts du répertoire de travail ont besoin de leur propre stratégie de stockage, comme un volume monté ou une synchronisation de magasin d'objets.

Pour savoir comment les sessions, la reprise et la bifurcation fonctionnent au niveau de l'API, consultez Sessions.

Choisir un modèle de session

Ces quatre modèles couvrent le cycle de vie de la session : la durée de vie d'un conteneur par rapport aux sessions qu'il dessert. Pour savoir où le conteneur s'exécute, le guide d'hébergement contient du code déployable pour Docker local, Modal et Kubernetes. Choisissez un modèle de session ici et une cible de déploiement à partir du guide.

Sessions éphémères

Créez un conteneur pour chaque tâche utilisateur et détruisez-le lorsque la tâche est terminée. Idéal pour les tâches ponctuelles. L'utilisateur peut toujours interagir avec l'IA pendant que la tâche se termine, mais une fois terminée, le conteneur est détruit.

Les charges de travail d'exemple incluent l'investigation et la correction de bogues, l'extraction de factures et de reçus, la traduction de documents et la transformation de médias.

Le conteneur exécute un point d'entrée unique qui lit la tâche à partir de la variable d'environnement TASK_PROMPT, appelle le SDK et se termine.

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

const prompt = process.env.TASK_PROMPT!;
for await (const message of query({ prompt, options: { maxTurns: 20 } })) {
console.log(message);
}

Le script affiche chaque message à son arrivée, y compris un message de résultat dont le subtype est success lorsque la tâche se termine dans la limite de tours. Si la tâche atteint plutôt la limite de 20 tours, le subtype du message de résultat est error_max_turns et l'appel query() lève une erreur après l'avoir cédé, donc enveloppez la boucle dans un bloc try si le conteneur doit se terminer correctement. Consultez Gérer le résultat pour les sous-types d'erreur.

Sessions longue durée

Exécutez des instances de conteneur persistantes, souvent hébergeant plusieurs processus SDK par conteneur, pour servir le travail en cours. Idéal pour les agents qui prennent des mesures autonomes, servent du contenu ou gèrent des flux de messages à haut volume.

Les charges de travail d'exemple incluent un agent de messagerie qui trie et répond aux messages entrants, un générateur de sites qui héberge un site modifiable par utilisateur via les ports du conteneur, et un chatbot qui gère le trafic continu d'une plateforme comme Slack.

Le conteneur expose un point de terminaison HTTP ou WebSocket et mappe chaque session active à une requête longue durée et au sous-processus derrière elle. En TypeScript, utilisez streamInput() pour ajouter des tours à une session active et startup() pour préchauffer les sous-processus avant le trafic entrant. En Python, utilisez ClaudeSDKClient pour maintenir une session ouverte entre les tours. Dimensionnez le conteneur pour qu'il puisse contenir le nombre maximum de sessions simultanées en mémoire.

Sessions hybrides

Conteneurs éphémères qui s'hydratent à partir d'un SessionStore au démarrage et persistent les mises à jour en retour. Idéal pour les sessions qui s'étendent sur de nombreuses interactions mais restent inactives entre elles. Le conteneur s'arrête pendant les périodes d'inactivité et redémarre lorsque l'utilisateur revient.

Les charges de travail d'exemple incluent un gestionnaire de projet personnel avec des vérifications intermittentes, une recherche approfondie qui s'interrompt et reprend sur des heures, et un agent d'assistance client qui charge l'historique des tickets entre les interactions.

Ajustez le délai d'inactivité de votre fournisseur à la fréquence à laquelle vous vous attendez à ce que les utilisateurs reviennent. L'arrêt d'un conteneur sans SessionStore configuré perd la transcription avec lui, donc le magasin est requis pour ce modèle, pas optionnel.

Le modèle repose sur la reprise d'une session par ID avec un magasin partagé attaché :

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

declare const userInput: string;
declare const sessionId: string;          // looked up from your database by user
declare const sessionStore: SessionStore; // S3, Redis, Postgres, or your own adapter

for await (const message of query({
prompt: userInput,
options: { resume: sessionId, sessionStore },
})) {
// ...
}

Conteneur multi-agent

Exécutez plusieurs sous-processus SDK à l'intérieur d'un conteneur. Idéal pour les agents qui doivent collaborer étroitement, par exemple les simulations multi-agents où les agents interagissent les uns avec les autres dans un environnement partagé.

Donnez à chaque agent son propre répertoire de travail pour qu'ils ne se réécrivent pas les fichiers les uns des autres, et isolez le chargement des paramètres pour que les fichiers CLAUDE.md par agent ne fuient pas entre les agents. Consultez Isolation multi-locataire pour les options spécifiques.

Provisionner le conteneur

Sandboxing basé sur conteneur

Exécutez le SDK à l'intérieur d'un conteneur en sandbox pour l'isolation des processus, les limites de ressources, le contrôle du réseau et un système de fichiers éphémère.

Questions à répondre lors du choix d'un fournisseur :

  • Qui exécute le sandbox : un fournisseur de sandbox-as-a-service exploite l'infrastructure pour vous, tandis que les options auto-hébergées vous donnent un logiciel à exécuter sur votre propre infrastructure.
  • Latence de démarrage à froid : combien de temps entre « créer un sandbox » et « prêt à accepter la première requête ». Les modèles éphémères nécessitent des démarrages infra-seconde. Les modèles de longue durée tolèrent davantage.
  • Stockage persistant : si le fournisseur offre des volumes durables ou seulement un disque éphémère. Le modèle hybride a besoin de stockage durable quelque part, que ce soit dans le sandbox ou à côté.
  • Modèle de tarification : facturation à la seconde, à la requête ou forfaitaire horaire. La tarification à la seconde convient aux charges de travail éphémères par rafales. La tarification horaire convient aux sessions de longue durée.
  • Réseau : support des règles de sortie personnalisées, des proxies sortants et de l'appairage VPC privé pour les environnements réglementés.

Pour les options auto-hébergées telles que Docker, gVisor et Firecracker, et la configuration d'isolation détaillée, consultez Technologies d'isolation.

Dépendances d'exécution

Le conteneur a besoin du runtime de langage de votre SDK :

  • Python 3.10+ pour le SDK Python, ou Node.js 18+ pour le SDK TypeScript
  • Les deux SDK TypeScript et Python regroupent un binaire Claude Code natif pour la plupart des installations, et le CLI généré n'a besoin d'aucune installation Node.js séparée. Consultez la note d'installation du démarrage rapide pour les installations qui nécessitent une installation Claude Code native séparée.

Le binaire regroupé est épinglé à la version du package SDK, donc la mise à jour du SDK est la façon de mettre à jour le CLI. Le SDK suit semver : prenez les versions de correctif en continu et consultez le changelog TypeScript ou Python avant de prendre une version mineure.

Ressources

1 GiB de RAM, 5 GiB de disque et 1 CPU par agent est un point de départ raisonnable pour une instance fraîchement démarrée. L'utilisation de la mémoire augmente avec la durée de la session et l'activité des outils, donc dimensionnez pour les durées de session et la concurrence que vous avez réellement besoin plutôt que la ligne de base inactive. Consultez Mise à l'échelle et concurrence pour savoir comment calculer les agents par hôte.

Réseau

Le SDK a besoin d'une sortie HTTPS vers api.anthropic.com, ou vers le point de terminaison régional de votre fournisseur lors de l'exécution sur Amazon Bedrock ou la plateforme Agent de Google Cloud. Si vos agents utilisent des serveurs MCP ou des outils externes, ils ont également besoin d'un accès sortant à ces points de terminaison. Pour la production, acheminez le trafic sortant via un proxy de sortie qui applique les listes d'autorisation de domaines, injecte les identifiants et enregistre les requêtes. Consultez Déploiement sécurisé pour le modèle complet.

Pour le trafic entrant, exposez un port HTTP ou WebSocket sur le conteneur. Votre application gère les requêtes des clients sur ce port et appelle le SDK en interne ; le sous-processus lui-même n'écoute pas sur le réseau.

Gérer les préoccupations de production

Travaillez sur ces décisions avant de déployer un agent auto-hébergé.

Persistance des sessions et de l'état

Le disque local par défaut est perdu au redémarrage, à la réduction d'échelle ou au déplacement vers un nœud différent. Pour toute session qu'un utilisateur s'attend à reprendre, mettez en miroir la transcription vers un stockage durable avec un adaptateur SessionStore. Consultez Implémentations de référence pour les adaptateurs S3, Redis et Postgres ainsi qu'une suite de conformité pour la vôtre.

Trois choses à savoir sur le comportement de SessionStore :

  • Transcriptions uniquement : SessionStore met en miroir les transcriptions, pas les fichiers mémoire CLAUDE.md ou autres artefacts du répertoire de travail. Montez un volume partagé ou synchronisez-les séparément.
  • Miroir, pas remplacement : le sous-processus écrit d'abord sur le disque local, et le SDK transfère une copie de chaque lot au magasin. La transcription locale d'une nouvelle session survit à l'exécution ; une exécution reprise à partir du magasin supprime sa copie locale à la fin, de sorte que le magasin détient la seule copie durable. Consultez Architecture à double écriture.
  • Messages mirror_error : lorsque le SDK ne peut pas livrer un lot au magasin, il abandonne le lot, émet un message { type: "system", subtype: "mirror_error" } et continue la requête. Alertez sur ces messages si la durabilité du magasin est importante. Consultez Les écritures en miroir sont au mieux des efforts pour le comportement de nouvelle tentative et d'expiration.

Observabilité

Les agents du SDK Agent sont des processus de longue durée qui génèrent des appels d'outils sur de nombreux allers-retours API. Sans télémétrie, vous ne pouvez pas voir quels outils ont été exécutés, combien de temps ils ont pris ou où une session s'est bloquée.

Le SDK hérite de la configuration OpenTelemetry de l'environnement. Définissez les variables d'environnement OTEL au niveau du conteneur ou de l'orchestrateur afin que chaque appel query() exporte des spans, des métriques et des événements de journal vers votre collecteur. L'exemple ci-dessous active l'export OTLP pour les trois signaux. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA est requis uniquement pour les traces ; omettez-le si vous exportez uniquement des métriques et des journaux.

CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318

Le texte d'invite et les entrées d'outils ne sont pas inclus dans les exports par défaut. Consultez Contrôler les données sensibles dans les exports pour les drapeaux d'opt-in et Observabilité pour le catalogue complet des signaux.

Authentification et secrets

Trois préoccupations d'authentification sont importantes au moment de l'hébergement :

  • API Anthropic : le sous-processus lit ANTHROPIC_API_KEY à partir de son environnement. Fournissez-le à partir de votre gestionnaire de secrets, ou définissez ANTHROPIC_BASE_URL pour acheminer les appels de modèle via un proxy qui injecte la clé en dehors du conteneur. Consultez Gestion des identifiants pour le modèle de proxy et Configuration dans le démarrage rapide du SDK pour les méthodes d'authentification prises en charge.
  • Entrant : mettez l'authentification à une passerelle devant le conteneur de l'agent. L'agent doit recevoir des requêtes pré-authentifiées et ne doit pas être le composant qui valide les jetons utilisateur.
  • Outils sortants : gardez les identifiants d'outils hors de l'environnement de l'agent. Acheminez les appels sortants via un proxy qui injecte les clés API après que la requête quitte le conteneur. L'agent effectue l'appel ; le proxy ajoute l'identifiant.

Mise à l'échelle et concurrence

Chaque session s'exécute dans son propre sous-processus, de sorte que la concurrence sur un hôte est limitée par le nombre de sous-processus que sa RAM peut contenir.

Dimensionnez chaque hôte avec cette formule :

agents par hôte = (RAM hôte - surcharge) / (plafond RAM par session)

Mesurez le plafond par session en exécutant une session représentative jusqu'à votre longueur cible sous votre charge d'outils attendue et en enregistrant le RSS de pointe. Le point de départ de 1 GiB dans Ressources est un plancher, pas le plafond.

Le routage à l'échelle horizontale dépend de votre modèle. Pour les sessions de longue durée, où les conteneurs contiennent de nombreuses sessions, exécutez un pool de conteneurs derrière un équilibreur de charge et épinglez chaque session à un conteneur en utilisant le hachage cohérent sur sessionId. Une session épinglée continue à frapper le même conteneur, et donc le même sous-processus en cours d'exécution, jusqu'à ce qu'il soit évincé ou que le conteneur redémarre.

Coût

Le coût des jetons Anthropic domine généralement le coût de l'infrastructure du conteneur d'un ordre de grandeur ou plus. Un conteneur minimalement provisionné coûte environ 0,05 $ par heure, tandis qu'une seule session d'agent longue peut dépenser des dollars en jetons. Consultez Suivi des coûts pour la comptabilité des jetons par session.

Isolation multi-locataire

Le comportement par défaut du SDK lit les paramètres et les fichiers mémoire CLAUDE.md à partir du système de fichiers. Dans un conteneur partagé qui sert plusieurs locataires, ces fichiers peuvent fuir le contexte d'un locataire dans la session d'un autre locataire.

Pour isoler les locataires dans un conteneur partagé :

  • Passez settingSources: [] en TypeScript ou setting_sources=[] en Python pour ignorer les paramètres utilisateur, projet et locaux.
  • Définissez CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 dans env. La mémoire automatique à ~/.claude/projects/<project>/memory/ se charge dans l'invite système indépendamment de settingSources. Consultez Ce que settingSources ne contrôle pas pour les autres entrées qui se chargent sans condition.
  • Pointez CLAUDE_CONFIG_DIR vers un répertoire par locataire afin que les locataires ne partagent pas la configuration globale ~/.claude.json. Lorsque chaque répertoire de configuration sert un répertoire de travail et que vous ne partagez pas un SessionStore entre les locataires, vous pouvez également définir CLAUDE_CODE_PROJECT_DIR_NAME dans env pour garder les chemins de transcription sous celui-ci courts. Nécessite TypeScript Agent SDK v0.3.234 ou ultérieur, ou Python Agent SDK v0.2.140 ou ultérieur.
  • Utilisez un répertoire de travail par locataire. Passez cwd explicitement à chaque appel query().
  • Appliquez des règles de sortie par locataire à votre proxy, telles que des adresses IP sortantes distinctes, des identifiants ou des listes blanches de domaines, afin qu'un locataire compromis ne puisse pas exfiltrer les données via la politique sortante d'un autre locataire.

L'exemple ci-dessous applique les options de paramètres, de mémoire automatique, de répertoire de configuration et de répertoire de travail ensemble. Construisez tenantDir et configDir afin que chaque locataire obtienne un chemin qu'aucun autre locataire ne peut lire. En TypeScript, env remplace l'environnement du sous-processus, donc propagez ...process.env pour conserver les variables héritées comme PATH et ANTHROPIC_API_KEY. En Python, env est fusionné au-dessus de l'environnement hérité.

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

declare const prompt: string;
declare const tenantDir: string;
declare const configDir: string;

for await (const message of query({
prompt,
options: {
cwd: tenantDir,
settingSources: [],
env: {
...process.env,
CLAUDE_CONFIG_DIR: configDir,
CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
},
},
})) {
// ...
}

Limitations connues

Planifiez autour de ces éléments dans votre conception de déploiement.

Limitation Que faire
Pas de délai d'expiration de session au niveau supérieur Une session n'expire pas d'elle-même. Définissez maxTurns en TypeScript ou max_turns en Python pour limiter le nombre de cycles d'utilisation d'outils que l'agent effectue avant de s'arrêter.
Croissance de la mémoire au cours de longues sessions Limitez la longueur de la session ou recyclez les sous-processus périodiquement. Voir Mise à l'échelle et concurrence.
Les grands déploiements parallèles de sous-agents peuvent atteindre les limites de débit Divisez le travail en lots plus petits plutôt que d'émettre un seul envoi large.
Pas de délai limite d'horloge murale par sous-agent Limitez chaque sous-agent avec maxTurns dans sa AgentDefinition. CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS définit un chien de garde de stagnation qui se déclenche lorsqu'un sous-agent cesse de produire une sortie ; ce n'est pas un délai d'exécution total.

Dépanner les défaillances de déploiement

Utilisez cette section lorsqu'un agent qui fonctionne sur votre machine échoue dans un service déployé. Chaque élément ci-dessous nomme une défaillance et établit un lien vers l'entrée qui la couvre :

  • CLI introuvable au démarrage du service : en Python, un conteneur ou un gestionnaire de services exécute votre application avec un PATH différent de celui de votre shell, donc une installation qui fonctionne localement n'est pas visible pour le processus. En TypeScript, la génération d'image a ignoré les dépendances optionnelles du SDK, ou pathToClaudeCodeExecutable pointe vers un fichier qui n'existe pas dans l'image. Voir Claude Code introuvable.
  • CLI présente dans l'image mais ne se lance pas : Claude Code ne peut pas démarrer à partir d'un binaire qui ne correspond pas à l'architecture ou à la libc du conteneur, ou à partir d'un fichier qui a perdu sa permission d'exécution lors de la génération d'image. Voir Échec du démarrage de Claude Code.
  • Le processus Claude Code se termine en cours d'exécution : l'erreur que votre application reçoit dépend du langage du SDK et du fait que la CLI ait d'abord signalé un résultat d'erreur. Les entrées sous Sortie du processus CLI couvrent chaque message.

Étapes suivantes