Héberger l'Agent SDK

​

Le modèle de sous-processus

query({ prompt, options: { cwd: "/work/session-a" } })

​

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

​

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

​

Conteneur multi-agent

​

Provisionner le conteneur

​

Sandboxing basé sur conteneur

• Qui exécute le sandbox : un fournisseur 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.

• Modal Sandbox, avec une implémentation de démonstration
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

​

Dépendances d’exécution

• Python 3.10+ pour le SDK Python, ou Node.js 18+ pour le SDK TypeScript
• Les deux packages SDK incluent un binaire Claude Code natif pour la plateforme hôte, donc aucune installation séparée de Claude Code ou Node.js n’est nécessaire pour le CLI généré

​

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 magasin reçoit une copie de chaque lot. Les écritures locales restent faisant autorité.
• Messages mirror_error : si le magasin rejette ou expire, le SDK émet un message { type: "system", subtype: "mirror_error" } et continue la requête sans nouvelle tentative. Alertez sur ceux-ci si la durabilité du magasin est importante.

​

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 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 Aperçu 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 en dehors 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 afin qu’aucun paramètre du système de fichiers ne se charge.
• Définissez CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 dans env. Auto memory à ~/.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.
• 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",
    },
  },
})) {
  // ...
}

​

Limitations connues

​

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