Hosting des Agent SDK

​

Das Subprocess-Modell

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

​

Status, der auf der lokalen Festplatte gespeichert ist

​

Wählen Sie ein Sitzungsmuster

​

Ephemere Sitzungen

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

​

Langfristige Sitzungen

​

Hybrid-Sitzungen

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

​

Multi-Agent-Container

​

Container bereitstellen

​

Container-basiertes Sandboxing

• Wer betreibt die Sandbox: Ein Sandbox-as-a-Service-Anbieter betreibt die Infrastruktur für Sie, während selbst gehostete Optionen Ihnen Software zur Verfügung stellen, die Sie auf Ihren eigenen Systemen ausführen können.
• Cold-Start-Latenz: Wie lange dauert es von „Sandbox erstellen” bis „bereit, die erste Anfrage zu akzeptieren”. Kurzlebige Muster benötigen Sub-Sekunden-Starts. Langfristige Muster tolerieren mehr.
• Persistenter Speicher: Ob der Anbieter dauerhafte Volumes oder nur kurzlebige Festplatte anbietet. Das Hybrid-Muster benötigt dauerhaften Speicher irgendwo, ob in der Sandbox oder daneben.
• Preismodell: Pro-Sekunde, Pro-Anfrage oder pauschale stündliche Abrechnung. Pro-Sekunde-Preisgestaltung eignet sich für bursty kurzlebige Workloads. Stündlich eignet sich für langfristige Sitzungen.
• Netzwerk: Unterstützung für benutzerdefinierte Egress-Regeln, ausgehende Proxys und privates VPC-Peering für regulierte Umgebungen.

• Modal Sandbox, mit einer Demo-Implementierung
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

​

Laufzeit-Abhängigkeiten

• Python 3.10+ für das Python SDK oder Node.js 18+ für das TypeScript SDK
• Beide SDK-Pakete enthalten eine native Claude Code-Binärdatei für die Host-Plattform, daher ist keine separate Claude Code- oder Node.js-Installation für die erzeugte CLI erforderlich

​

Ressourcen

​

Netzwerk

​

Produktionsbedenken behandeln

​

Sitzungs- und Zustandspersistenz

• Nur Transkripte: SessionStore spiegelt Transkripte, nicht CLAUDE.md-Speicherdateien oder andere Arbeitsverzeichnis-Artefakte. Mounten Sie ein gemeinsames Volume oder synchronisieren Sie diese separat.
• Spiegelung, keine Ersetzung: Der Unterprozess schreibt zuerst auf die lokale Festplatte, und der Store erhält eine Kopie jedes Batches. Lokale Schreibvorgänge bleiben maßgeblich.
• mirror_error-Meldungen: Wenn der Store ablehnt oder eine Zeitüberschreitung auftritt, gibt das SDK eine { type: "system", subtype: "mirror_error" }-Meldung aus und setzt die Abfrage ohne Wiederholung fort. Warnen Sie vor diesen, wenn die Store-Dauerhaftigkeit wichtig ist.

​

Observability

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

​

Authentifizierung und Geheimnisse

• Anthropic API: Der Unterprozess liest ANTHROPIC_API_KEY aus seiner Umgebung. Stellen Sie es von Ihrem Secret Manager bereit, oder setzen Sie ANTHROPIC_BASE_URL, um Modellaufrufe durch einen Proxy zu leiten, der den Schlüssel außerhalb des Containers injiziert. Siehe Credential Management für das Proxy-Muster und SDK-Übersicht für unterstützte Authentifizierungsmethoden.
• Eingehend: Setzen Sie Authentifizierung an einem Gateway vor dem Agent-Container. Der Agent sollte vorauthentifizierte Anfragen erhalten und sollte nicht die Komponente sein, die Benutzer-Token validiert.
• Ausgehende Werkzeuge: Halten Sie Werkzeug-Anmeldedaten aus der Agent-Umgebung. Leiten Sie ausgehende Aufrufe durch einen Proxy, der API-Schlüssel injiziert, nachdem die Anfrage den Container verlässt. Der Agent tätigt den Aufruf; der Proxy fügt die Anmeldedaten hinzu.

​

Skalierung und Parallelität

Agenten pro Host = (Host-RAM - Overhead) / (RAM-Obergrenze pro Sitzung)

​

Kosten

​

Multi-Tenant-Isolation

• Übergeben Sie settingSources: [] in TypeScript oder setting_sources=[] in Python, damit keine Dateisystem-Einstellungen geladen werden.
• Setzen Sie CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in env. Auto Memory bei ~/.claude/projects/<project>/memory/ wird unabhängig von settingSources in den System-Prompt geladen. Siehe Was settingSources nicht steuert für die anderen Eingaben, die bedingungslos geladen werden.
• Zeigen Sie CLAUDE_CONFIG_DIR auf ein mandantenspezifisches Verzeichnis, damit Mandanten die globale Konfiguration ~/.claude.json nicht teilen.
• Verwenden Sie ein mandantenspezifisches Arbeitsverzeichnis. Übergeben Sie cwd explizit bei jedem query()-Aufruf.
• Wenden Sie mandantenspezifische Egress-Regeln bei Ihrem Proxy an, wie z. B. unterschiedliche ausgehende IPs, Anmeldedaten oder Domain-Allowlists, damit ein kompromittierter Mandant keine Daten über die ausgehende Richtlinie eines anderen Mandanten exfiltrieren kann.

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

​

Bekannte Einschränkungen

​

Nächste Schritte

• Hosting-Cookbook: Notebook-Anleitung mit bereitstellbarem Code für Docker, Modal und Kubernetes.
• Sitzungsspeicher: Persistieren Sie Transkripte über Hosts hinweg mit einem SessionStore-Adapter.
• Observability: Exportieren Sie OTEL-Traces, Metriken und Protokolle zu Ihrem Collector.
• Sichere Bereitstellung: Netzwerkkontrollen, Verwaltung von Anmeldedaten und Isolationshärtung.
• Kostenverfolgung: Token- und Kostenabrechnung pro Sitzung.