Héberger l'Agent SDK

​

Le modèle de sous-processus

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);
}

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt="Summarize the files in this directory",
        options=ClaudeAgentOptions(cwd="/work/session-a"),
    ):
        print(message)


asyncio.run(main())

​

État qui réside sur le disque local

​

Choisir un modèle de session

​

Sessions éphémères

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);
}

import asyncio
import os

from claude_agent_sdk import ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt=os.environ["TASK_PROMPT"],
        options=ClaudeAgentOptions(max_turns=20),
    ):
        print(message)


asyncio.run(main())

​

Sessions longue durée

​

Sessions hybrides

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 },
})) {
  // ...
}

from claude_agent_sdk import query, ClaudeAgentOptions, SessionStore
import asyncio

user_input: str = ...
session_id: str = ...              # looked up from your database by user
session_store: SessionStore = ...  # S3, Redis, Postgres, or your own adapter


async def main():
    async for message in query(
        prompt=user_input,
        options=ClaudeAgentOptions(
            resume=session_id,
            session_store=session_store,
        ),
    ):
        ...


asyncio.run(main())

​

Conteneur multi-agent

​

Provisionner le conteneur

​

Sandboxing basé sur conteneur

• 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.

​

Dépendances d’exécution

• 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.

​

Ressources

​

Réseau

​

Gérer les préoccupations de production

​

Persistance des sessions et de l’état

• 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é

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

​

Authentification et secrets

• 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

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

​

Coût

​

Isolation multi-locataire

• 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.

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",
    },
  },
})) {
  // ...
}

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio

prompt: str = ...
tenant_dir: str = ...
config_dir: str = ...


async def main():
    async for message in query(
        prompt=prompt,
        options=ClaudeAgentOptions(
            cwd=tenant_dir,
            setting_sources=[],
            env={
                "CLAUDE_CONFIG_DIR": config_dir,
                "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
            },
        ),
    ):
        ...


asyncio.run(main())

​

Limitations connues

​

Dépanner les défaillances de déploiement

• 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

• Carnet de recettes d’hébergement : parcours du carnet avec code déployable pour Docker, Modal et Kubernetes.
• Stockage des sessions : persistez les transcriptions entre les hôtes avec un adaptateur SessionStore.
• Observabilité : exportez les traces OTEL, les métriques et les journaux vers votre collecteur.
• Déploiement sécurisé : contrôles réseau, gestion des identifiants et renforcement de l’isolation.
• Suivi des coûts : comptabilité des jetons et des coûts par session.