4 4
5# Hosting des Agent SDK5# Hosting des Agent SDK
6 6
7> Bereitstellung des Agent SDK in der Produktion: Subprocess-Architektur, Sitzungspersistenz, Skalierung, Observability und Multi-Tenant-Isolation für Docker, Kubernetes und Sandbox-Provider.7> Stellen Sie das Agent SDK in der Produktion bereit: Subprocess-Architektur, Sitzungspersistenz, Skalierung, Observability und Multi-Tenant-Isolation für Docker, Kubernetes und Sandbox-Provider.
8 8
9Das Agent SDK spawnt und überwacht einen `claude` CLI-Subprocess, der eine Shell, ein Arbeitsverzeichnis und Sitzungsdateien auf der Festplatte besitzt. Das Hosting unterscheidet sich vom Hosting eines zustandslosen API-Wrappers. Jeder laufende Agent ist ein langlebiger Prozess, der an lokalen Zustand gebunden ist, was beeinflusst, wie Sie Ressourcen zuordnen, Sitzungen persistieren und über Mandanten skalieren.9Das Agent SDK spawnt und überwacht einen `claude` CLI-Subprocess, der eine Shell, ein Arbeitsverzeichnis und Sitzungsdateien auf der Festplatte besitzt. Das Hosting unterscheidet sich vom Hosting eines zustandslosen API-Wrappers. Jeder laufende Agent ist ein langlebiger Prozess, der an lokale Zustände gebunden ist, was beeinflusst, wie Sie Ressourcen zuordnen, Sitzungen persistieren und über Mandanten hinweg skalieren.
10 10
11Diese Seite behandelt das Self-Hosting auf Ihrer eigenen Infrastruktur: verstehen Sie [das Subprocess-Modell](#the-subprocess-model), [wählen Sie ein Sitzungsmuster](#choose-a-session-pattern), [stellen Sie den Container bereit](#provision-the-container) und [behandeln Sie Produktionsbedenken](#handle-production-concerns) wie Persistenz, Observability, Authentifizierung und Multi-Tenant-Isolation. Für bereitstellbare Dockerfiles und Kubernetes-Manifeste siehe das [Hosting-Cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting).11Diese Seite behandelt das Self-Hosting auf Ihrer eigenen Infrastruktur. Für bereitstellbare Dockerfiles und Kubernetes-Manifeste siehe das [Hosting-Cookbook](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting).
12 12
13Wenn Sie keine Infrastrukturkontrolle, benutzerdefinierte Isolation oder Ihre eigene Datenebene benötigen, erwägen Sie stattdessen [Managed Agents](https://platform.claude.com/docs/de/managed-agents/overview): eine gehostete REST-API, bei der Anthropic den Agent und die Sandbox ausführt, sodass Ihre Anwendung Ereignisse sendet und Ergebnisse zurückstreamt, ohne dass Sie eine Hosting-Infrastruktur betreiben müssen.13Wenn Sie keine Infrastrukturkontrolle, benutzerdefinierte Isolation oder Ihre eigene Datenebene benötigen, erwägen Sie stattdessen [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview): eine gehostete REST-API, bei der Anthropic den Agent und die Sandbox betreibt, sodass Ihre Anwendung Ereignisse sendet und Ergebnisse zurückstreamt, ohne dass Sie eine Hosting-Infrastruktur betreiben müssen.
14
15<Info>
16 Für Sicherheitshärtung über grundlegendes Sandboxing hinaus, einschließlich Netzwerkkontrollen, Verwaltung von Anmeldedaten und Isolationsoptionen, siehe [Sichere Bereitstellung](/de/agent-sdk/secure-deployment).
17</Info>
18 14
19<h2 id="the-subprocess-model">15<h2 id="the-subprocess-model">
20 Das Subprocess-Modell16 Das Subprocess-Modell
22 18
23Jede Hosting-Entscheidung auf dieser Seite folgt aus der Art und Weise, wie das SDK den Agent ausführt. Wenn Ihr Code `query()` aufruft, spawnt das SDK einen separaten `claude` CLI-Prozess und kommuniziert mit ihm über stdio. Dieser Subprocess besitzt die Shell, das Arbeitsverzeichnis und die JSONL-Sitzungstranskripte auf der lokalen Festplatte.19Jede Hosting-Entscheidung auf dieser Seite folgt aus der Art und Weise, wie das SDK den Agent ausführt. Wenn Ihr Code `query()` aufruft, spawnt das SDK einen separaten `claude` CLI-Prozess und kommuniziert mit ihm über stdio. Dieser Subprocess besitzt die Shell, das Arbeitsverzeichnis und die JSONL-Sitzungstranskripte auf der lokalen Festplatte.
24 20
25<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/hosting-subprocess.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=9dac857ca9d3b1410c3734900c386004" alt="Request-Fluss: Client zu Ihrer App, die einen claude CLI-Subprocess über stdio im Container spawnt; der Subprocess schreibt auf die lokale Festplatte und ruft api.anthropic.com über HTTPS auf" width="920" height="220" data-path="images/agent-sdk/hosting-subprocess.svg" />21<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/hosting-subprocess.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=9dac857ca9d3b1410c3734900c386004" className="dark:hidden" alt="Request flow: client to your app, which spawns a claude CLI subprocess over stdio inside the container; the subprocess writes to local disk and calls api.anthropic.com over HTTPS" width="920" height="220" data-path="images/agent-sdk/hosting-subprocess.svg" />
22
23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agent-sdk/hosting-subprocess-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=3fdeff3d7f44b2b67762668acfbb25f5" className="hidden dark:block" alt="Request flow: client to your app, which spawns a claude CLI subprocess over stdio inside the container; the subprocess writes to local disk and calls api.anthropic.com over HTTPS" width="920" height="220" data-path="images/agent-sdk/hosting-subprocess-dark.svg" />
26 24
27Eine Agent-Sitzung wird einer Subprocess zugeordnet. Das Ausführen von N gleichzeitigen Sitzungen bedeutet N Subprozesse, jeder mit seinem eigenen Prozessbaum und einer Transkriptdatei. Standardmäßig erben sie alle das Arbeitsverzeichnis Ihrer Anwendung. Übergeben Sie daher `cwd` bei jedem `query()`-Aufruf, wenn Sitzungen separate Dateisysteme benötigen:25Eine Agent-Sitzung wird einem Subprocess zugeordnet. Das Ausführen von N gleichzeitigen Sitzungen bedeutet N Subprozesse, jeder mit seinem eigenen Prozessbaum und seiner eigenen Transkriptdatei. Standardmäßig erben sie alle das Arbeitsverzeichnis Ihrer Anwendung. Wenn Sitzungen separate Dateisysteme benötigen, übergeben Sie ein unterschiedliches `cwd` in den Optionen des `query()`-Aufrufs jeder Sitzung:
28 26
29<CodeGroup>27<CodeGroup>
30 ```typescript TypeScript theme={null}28 ```typescript TypeScript theme={null}
31 query({ prompt, options: { cwd: "/work/session-a" } })29 import { query } from "@anthropic-ai/claude-agent-sdk";
30
31 for await (const message of query({
32 prompt: "Summarize the files in this directory",
33 options: { cwd: "/work/session-a" },
34 })) {
35 console.log(message);
36 }
32 ```37 ```
33 38
34 ```python Python theme={null}39 ```python Python theme={null}
35 query(prompt=prompt, options=ClaudeAgentOptions(cwd="/work/session-a"))40 import asyncio
41
42 from claude_agent_sdk import ClaudeAgentOptions, query
43
44
45 async def main():
46 async for message in query(
47 prompt="Summarize the files in this directory",
48 options=ClaudeAgentOptions(cwd="/work/session-a"),
49 ):
50 print(message)
51
52
53 asyncio.run(main())
36 ```54 ```
37</CodeGroup>55</CodeGroup>
38 56
57Die TypeScript-Beispiele auf dieser Seite verwenden Top-Level-`await`, daher speichern Sie sie als `.mts`-Dateien oder setzen Sie `"type": "module"` in `package.json`.
58
39<h3 id="state-that-lives-on-local-disk">59<h3 id="state-that-lives-on-local-disk">
40 Status, der auf der lokalen Festplatte gespeichert ist60 Zustand, der auf der lokalen Festplatte lebt
41</h3>61</h3>
42 62
43Drei Arten von Agent-Status befinden sich standardmäßig im Dateisystem des Containers. Keine von ihnen überlebt einen Container-Neustart, ein Scale-Down oder einen Wechsel zu einem anderen Knoten.63Drei Arten von Agent-Zustand leben standardmäßig im Dateisystem des Containers. Keiner von ihnen überlebt einen Container-Neustart, ein Scale-Down oder einen Wechsel zu einem anderen Knoten.
44 64
45| Status | Standardort |65| Zustand | Standardort |
46| ---------------------------- | ------------------------------------------------------------------------------------------------------- |66| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
47| Sitzungstranskripte | `~/.claude/projects/`, oder das Verzeichnis `projects/` unter `CLAUDE_CONFIG_DIR`, falls gesetzt |67| Sitzungstranskripte | `~/.claude/projects/`, oder das Verzeichnis `projects/` unter `CLAUDE_CONFIG_DIR`, falls gesetzt |
48| `CLAUDE.md` Speicherdateien | `~/.claude/CLAUDE.md` für die Benutzerebene und das Arbeitsverzeichnis der Sitzung für die Projektebene |68| `CLAUDE.md` Speicherdateien | `~/.claude/CLAUDE.md` für die Benutzerebene und das Arbeitsverzeichnis der Sitzung für die Projektebene |
49| Arbeitsverzeichnis-Artefakte | Das Arbeitsverzeichnis der Sitzung |69| Artefakte im Arbeitsverzeichnis | Das Arbeitsverzeichnis der Sitzung |
50 70
51Um Transkripte über Hosts hinweg zu persistieren, konfigurieren Sie einen [`SessionStore`-Adapter](/de/agent-sdk/session-storage). Speicherdateien und andere Arbeitsverzeichnis-Artefakte benötigen ihre eigene Speicherstrategie, wie z. B. ein bereitgestelltes Volume oder eine Objektspeicher-Synchronisierung.71Um Transkripte über Hosts hinweg zu persistieren, konfigurieren Sie einen [`SessionStore`-Adapter](/docs/de/agent-sdk/session-storage). Speicherdateien und andere Artefakte im Arbeitsverzeichnis benötigen ihre eigene Speicherstrategie, wie z. B. ein bereitgestelltes Volume oder eine Objektspeicher-Synchronisierung.
52 72
53Informationen dazu, wie Sitzungen, Wiederaufnahme und Forking auf API-Ebene funktionieren, finden Sie unter [Sitzungen](/de/agent-sdk/sessions).73Informationen dazu, wie Sitzungen, Wiederaufnahme und Forking auf API-Ebene funktionieren, finden Sie unter [Sitzungen](/docs/de/agent-sdk/sessions).
54 74
55<h2 id="choose-a-session-pattern">75<h2 id="choose-a-session-pattern">
56 Wählen Sie ein Sitzungsmuster76 Wählen Sie ein Sitzungsmuster
59Diese vier Muster decken den Sitzungslebenszyklus ab: wie lange ein Container im Verhältnis zu den Sitzungen, die er bedient, existiert. Für den Ort, an dem der Container ausgeführt wird, hat das [Hosting-Kochbuch](https://github.com/anthropics/claude-cookbooks/blob/main/claude_agent_sdk/07_Hosting_the_agent.ipynb) [bereitstellbaren Code](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting) für lokales Docker, Modal und Kubernetes. Wählen Sie hier ein Sitzungsmuster und ein Bereitstellungsziel aus dem Kochbuch.79Diese vier Muster decken den Sitzungslebenszyklus ab: wie lange ein Container im Verhältnis zu den Sitzungen, die er bedient, existiert. Für den Ort, an dem der Container ausgeführt wird, hat das [Hosting-Kochbuch](https://github.com/anthropics/claude-cookbooks/blob/main/claude_agent_sdk/07_Hosting_the_agent.ipynb) [bereitstellbaren Code](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting) für lokales Docker, Modal und Kubernetes. Wählen Sie hier ein Sitzungsmuster und ein Bereitstellungsziel aus dem Kochbuch.
60 80
61<h3 id="ephemeral-sessions">81<h3 id="ephemeral-sessions">
62 Ephemere Sitzungen82 Kurzlebige Sitzungen
63</h3>83</h3>
64 84
65Erstellen Sie einen Container für jede Benutzeraufgabe und zerstören Sie ihn, wenn die Aufgabe abgeschlossen ist. Am besten für einmalige Aufgaben. Der Benutzer kann möglicherweise noch mit der KI interagieren, während die Aufgabe abgeschlossen wird, aber nach Abschluss wird der Container zerstört.85Erstellen Sie einen Container für jede Benutzeraufgabe und zerstören Sie ihn, wenn die Aufgabe abgeschlossen ist. Am besten für einmalige Aufgaben. Der Benutzer kann weiterhin mit der KI interagieren, während die Aufgabe abgeschlossen wird, aber nach Abschluss wird der Container zerstört.
66 86
67Beispielworkloads umfassen Fehleruntersuchung und -behebung, Rechnungs- und Belegextraktion, Dokumentenübersetzung und Medientransformation.87Beispielworkloads umfassen Fehleruntersuchung und -behebung, Rechnungs- und Belegextraktion, Dokumentübersetzung und Medientransformation.
68 88
69Der Container führt einen einmaligen Einstiegspunkt aus, der das SDK aufruft und beendet wird. Das folgende Beispiel zeigt eine minimale TypeScript-Version. Speichern Sie es als `entrypoint.mts` oder setzen Sie `"type": "module"` in `package.json`, damit `await` auf oberster Ebene verfügbar ist.89Der Container führt einen einmaligen Einstiegspunkt aus, der die Aufgabe aus der Umgebungsvariablen `TASK_PROMPT` liest, das SDK aufruft und beendet wird.
70 90
71```typescript theme={null}91<CodeGroup>
72import { query } from "@anthropic-ai/claude-agent-sdk";92 ```typescript TypeScript theme={null}
93 import { query } from "@anthropic-ai/claude-agent-sdk";
73 94
74const prompt = process.env.TASK_PROMPT!;95 const prompt = process.env.TASK_PROMPT!;
75for await (const message of query({ prompt, options: { maxTurns: 20 } })) {96 for await (const message of query({ prompt, options: { maxTurns: 20 } })) {
76 console.log(message);97 console.log(message);
77}98 }
78```99 ```
100
101 ```python Python theme={null}
102 import asyncio
103 import os
104
105 from claude_agent_sdk import ClaudeAgentOptions, query
106
107
108 async def main():
109 async for message in query(
110 prompt=os.environ["TASK_PROMPT"],
111 options=ClaudeAgentOptions(max_turns=20),
112 ):
113 print(message)
114
115
116 asyncio.run(main())
117 ```
118</CodeGroup>
119
120Das Skript gibt jede Nachricht aus, wenn sie ankommt, einschließlich einer Ergebnismeldung, deren `subtype` `success` ist, wenn die Aufgabe innerhalb des Turnus abgeschlossen wird. Wenn die Aufgabe stattdessen das 20-Turnus-Limit erreicht, ist der `subtype` der Ergebnismeldung `error_max_turns` und der `query()`-Aufruf löst einen Fehler aus, nachdem er ihn ausgegeben hat. Wickeln Sie daher die Schleife in einen Try-Block ein, wenn der Container sauber beendet werden muss. Siehe [Behandeln Sie das Ergebnis](/docs/de/agent-sdk/agent-loop#handle-the-result) für die Fehlersubtypen.
79 121
80<h3 id="long-running-sessions">122<h3 id="long-running-sessions">
81 Langfristige Sitzungen123 Langfristige Sitzungen
85 127
86Beispielworkloads umfassen einen E-Mail-Agenten, der eingehende Post sortiert und beantwortet, einen Website-Builder, der eine pro Benutzer bearbeitbare Website über Container-Ports hostet, und einen Chatbot, der kontinuierlichen Datenverkehr von einer Plattform wie Slack verarbeitet.128Beispielworkloads umfassen einen E-Mail-Agenten, der eingehende Post sortiert und beantwortet, einen Website-Builder, der eine pro Benutzer bearbeitbare Website über Container-Ports hostet, und einen Chatbot, der kontinuierlichen Datenverkehr von einer Plattform wie Slack verarbeitet.
87 129
88Der Container stellt einen HTTP- oder WebSocket-Endpunkt bereit und ordnet jede aktive Sitzung einer langlebigen Abfrage und dem dahinter liegenden Unterprozess zu. In TypeScript verwenden Sie [`streamInput()`](/de/agent-sdk/typescript#query-object), um Züge zu einer aktiven Sitzung hinzuzufügen, und [`startup()`](/de/agent-sdk/typescript#startup), um Unterprozesse vor eingehendem Datenverkehr vorzuwärmen. In Python verwenden Sie [`ClaudeSDKClient`](/de/agent-sdk/python#claudesdkclient), um eine Sitzung über Züge hinweg offen zu halten. Dimensionieren Sie den Container so, dass er die maximale Anzahl gleichzeitiger Sitzungen im Speicher halten kann.130Der Container stellt einen HTTP- oder WebSocket-Endpunkt bereit und ordnet jede aktive Sitzung einer langlebigen Abfrage und dem dahinter stehenden Unterprozess zu. In TypeScript verwenden Sie [`streamInput()`](/docs/de/agent-sdk/typescript#query-object), um Züge zu einer aktiven Sitzung hinzuzufügen, und [`startup()`](/docs/de/agent-sdk/typescript#startup), um Unterprozesse vor eingehendem Datenverkehr vorzuwärmen. In Python verwenden Sie [`ClaudeSDKClient`](/docs/de/agent-sdk/python#claudesdkclient), um eine Sitzung über Züge hinweg offen zu halten. Dimensionieren Sie den Container so, dass er die maximale Anzahl gleichzeitiger Sitzungen im Speicher halten kann.
89 131
90<h3 id="hybrid-sessions">132<h3 id="hybrid-sessions">
91 Hybrid-Sitzungen133 Hybrid-Sitzungen
92</h3>134</h3>
93 135
94Ephemere Container, die beim Start aus einem [`SessionStore`](/de/agent-sdk/session-storage) rehydriert werden und Updates zurück persistieren. Am besten für Sitzungen, die viele Interaktionen umfassen, aber zwischen ihnen untätig sind. Der Container wird während Leerlaufperioden heruntergefahren und wieder hochgefahren, wenn der Benutzer zurückkehrt.136Kurzlebige Container, die beim Start aus einem [`SessionStore`](/docs/de/agent-sdk/session-storage) rehydriert werden und Updates zurück persistieren. Am besten für Sitzungen, die viele Interaktionen umfassen, aber zwischen ihnen untätig sind. Der Container wird während Leerlaufperioden heruntergefahren und wieder hochgefahren, wenn der Benutzer zurückkehrt.
95 137
96Beispielworkloads umfassen einen persönlichen Projektmanager mit gelegentlichen Check-ins, tiefe Recherche, die über Stunden pausiert und fortgesetzt wird, und einen Kundenservice-Agenten, der die Tickethistorie über Interaktionen hinweg lädt.138Beispielworkloads umfassen einen persönlichen Projektmanager mit gelegentlichen Check-ins, tiefe Forschung, die über Stunden pausiert und fortgesetzt wird, und einen Kundenservice-Agenten, der die Tickethistorie über Interaktionen hinweg lädt.
97 139
98Stimmen Sie das Leerlauf-Timeout Ihres Anbieters darauf ab, wie häufig Sie erwarten, dass Benutzer zurückkehren. Das Herunterfahren eines Containers ohne konfiguriertes `SessionStore` verliert das Transkript damit, daher ist der Store für dieses Muster erforderlich, nicht optional.140Stimmen Sie das Leerlauf-Timeout Ihres Anbieters darauf ab, wie häufig Sie erwarten, dass Benutzer zurückkehren. Das Herunterfahren eines Containers ohne konfiguriertes `SessionStore` verliert das Transkript damit, daher ist der Store für dieses Muster erforderlich, nicht optional.
99 141
100Das Muster basiert auf der Wiederaufnahme einer Sitzung nach ID mit einem angehängten gemeinsamen Store:142Das Muster hängt davon ab, eine Sitzung nach ID mit einem angehängten gemeinsamen Store fortzusetzen:
101 143
102<CodeGroup>144<CodeGroup>
103 ```typescript TypeScript theme={null}145 ```typescript TypeScript theme={null}
116 ```158 ```
117 159
118 ```python Python theme={null}160 ```python Python theme={null}
119 from claude_agent_sdk import query, ClaudeAgentOptions161 from claude_agent_sdk import query, ClaudeAgentOptions, SessionStore
162 import asyncio
163
164 user_input: str = ...
165 session_id: str = ... # looked up from your database by user
166 session_store: SessionStore = ... # S3, Redis, Postgres, or your own adapter
120 167
168
169 async def main():
121 async for message in query(170 async for message in query(
122 prompt=user_input,171 prompt=user_input,
123 options=ClaudeAgentOptions(172 options=ClaudeAgentOptions(
124 resume=session_id, # looked up from your database by user173 resume=session_id,
125 session_store=session_store, # S3, Redis, Postgres, or your own adapter174 session_store=session_store,
126 ),175 ),
127 ):176 ):
128 ...177 ...
178
179
180 asyncio.run(main())
129 ```181 ```
130</CodeGroup>182</CodeGroup>
131 183
132Siehe [Sitzungsspeicher](/de/agent-sdk/session-storage) für die vollständige `SessionStore`-Schnittstelle und Referenzadapter.
133
134<h3 id="multi-agent-container">184<h3 id="multi-agent-container">
135 Multi-Agent-Container185 Multi-Agent-Container
136</h3>186</h3>
147 Container-basiertes Sandboxing197 Container-basiertes Sandboxing
148</h3>198</h3>
149 199
150Führen Sie das SDK in einem sandboxierten Container aus, um Prozessisolation, Ressourcenlimits, Netzwerkkontrolle und ein kurzlebiges Dateisystem zu erreichen. Mehrere Anbieter spezialisieren sich auf sandboxierte Container-Umgebungen, die zum Modell des Agent SDK passen.200Führen Sie das SDK in einem Sandbox-Container aus, um Prozessisolation, Ressourcenlimits, Netzwerkkontrolle und ein kurzlebiges Dateisystem zu erreichen.
151 201
152Fragen, die Sie bei der Wahl eines Anbieters beantworten sollten:202Fragen, die Sie bei der Wahl eines Anbieters beantworten sollten:
153 203
154* **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.204* **Wer betreibt die Sandbox**: Ein Sandbox-as-a-Service-Anbieter betreibt die Infrastruktur für Sie, während Self-Hosted-Optionen Ihnen Software zum Ausführen auf Ihren eigenen Systemen bieten.
155* **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.205* **Cold-Start-Latenz**: wie lange es dauert, von „Sandbox erstellen" bis „bereit, die erste Anfrage zu akzeptieren". Kurzlebige Muster benötigen Sub-Sekunden-Starts. Langfristige Muster tolerieren mehr.
156* **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.206* **Persistenter Speicher**: ob der Anbieter dauerhafte Volumes oder nur kurzlebige Festplatte anbietet. Das Hybrid-Muster benötigt irgendwo dauerhaften Speicher, entweder in der Sandbox oder daneben.
157* **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.207* **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.
158* **Netzwerk**: Unterstützung für benutzerdefinierte Egress-Regeln, ausgehende Proxys und privates VPC-Peering für regulierte Umgebungen.208* **Netzwerk**: Unterstützung für benutzerdefinierte Egress-Regeln, ausgehende Proxys und privates VPC-Peering für regulierte Umgebungen.
159 209
160Anbieter zur Evaluierung:210Für Self-Hosted-Optionen wie Docker, gVisor und Firecracker sowie detaillierte Isolationskonfiguration siehe [Isolationstechnologien](/docs/de/agent-sdk/secure-deployment#isolation-technologies).
161
162* [Modal Sandbox](https://modal.com/docs/guide/sandbox), mit einer [Demo-Implementierung](https://modal.com/docs/examples/claude-slack-gif-creator)
163* [Cloudflare Sandboxes](https://github.com/cloudflare/sandbox-sdk)
164* [Daytona](https://www.daytona.io/)
165* [E2B](https://e2b.dev/)
166* [Fly Machines](https://fly.io/docs/machines/)
167* [Vercel Sandbox](https://vercel.com/docs/functions/sandbox)
168
169Für selbst gehostete Optionen wie Docker, gVisor und Firecracker sowie detaillierte Isolationskonfiguration siehe [Isolationstechnologien](/de/agent-sdk/secure-deployment#isolation-technologies).
170 211
171<h3 id="runtime-dependencies">212<h3 id="runtime-dependencies">
172 Laufzeit-Abhängigkeiten213 Laufzeit-Abhängigkeiten
173</h3>214</h3>
174 215
175Der Container benötigt nur die Laufzeit Ihres SDK:216Der Container benötigt die Sprachlaufzeit Ihres SDK:
176 217
177* Python 3.10+ für das Python SDK oder Node.js 18+ für das TypeScript SDK218* Python 3.10+ für das Python SDK oder Node.js 18+ für das TypeScript SDK
178* 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 erforderlich219* Sowohl das TypeScript als auch das Python SDK bündeln eine native Claude Code-Binärdatei für die meisten Installationen, und die erzeugte CLI benötigt keine separate Node.js-Installation. Siehe die [Installationsnotiz des Schnellstarts](/docs/de/agent-sdk/quickstart) für die Installationen, die eine separate native Claude Code-Installation benötigen.
179 220
180Die gebündelte Binärdatei ist an die SDK-Paketversion gebunden, daher ist das Aktualisieren des SDK die Methode zum Aktualisieren der CLI. Das SDK folgt semver: Nehmen Sie Patch-Releases kontinuierlich an und überprüfen Sie das [TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md)- oder [Python](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md)-Changelog, bevor Sie ein Minor-Release annehmen.221Die gebündelte Binärdatei ist an die SDK-Paketversion gebunden, daher ist das Aktualisieren des SDK die Möglichkeit, die CLI zu aktualisieren. Das SDK folgt semver: Nehmen Sie Patch-Releases kontinuierlich an und überprüfen Sie das [TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md)- oder [Python](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md)-Changelog, bevor Sie ein Minor-Release annehmen.
181 222
182<h3 id="resources">223<h3 id="resources">
183 Ressourcen224 Ressourcen
184</h3>225</h3>
185 226
1861 GiB RAM, 5 GiB Festplatte und 1 CPU pro Agent ist ein angemessener Ausgangspunkt für eine neu gestartete Instanz. Der Speicherverbrauch wächst mit der Sitzungsdauer und der Tool-Aktivität, daher sollten Sie für die Sitzungslängen und Parallelität dimensionieren, die Sie tatsächlich benötigen, anstatt für die untätige Baseline. Siehe [Skalierung und Parallelität](#scaling-and-concurrency), um zu erfahren, wie Sie Agents pro Host berechnen.2271 GiB RAM, 5 GiB Festplatte und 1 CPU pro Agent ist ein angemessener Ausgangspunkt für eine neu gestartete Instanz. Die Speichernutzung wächst mit der Sitzungslänge und der Tool-Aktivität, daher sollten Sie für die Sitzungslängen und Parallelität dimensionieren, die Sie tatsächlich benötigen, anstatt für die untätige Baseline. Siehe [Skalierung und Parallelität](#scaling-and-concurrency), um zu erfahren, wie Sie Agents pro Host berechnen.
187 228
188<h3 id="network">229<h3 id="network">
189 Netzwerk230 Netzwerk
190</h3>231</h3>
191 232
192Das SDK benötigt ausgehende HTTPS zu `api.anthropic.com` oder zu Ihrem regionalen Endpunkt des Anbieters, wenn Sie auf Amazon Bedrock oder Google Cloud's Agent Platform ausführen. Wenn Ihre Agents [MCP-Server](/de/agent-sdk/mcp) oder externe Tools verwenden, benötigen sie auch ausgehenden Zugriff auf diese Endpunkte. Für die Produktion leiten Sie ausgehenden Datenverkehr durch einen Egress-Proxy, der Domain-Allowlists durchsetzt, Anmeldeinformationen injiziert und Anfragen protokolliert. Siehe [Sichere Bereitstellung](/de/agent-sdk/secure-deployment) für das vollständige Muster.233Das SDK benötigt ausgehende HTTPS zu `api.anthropic.com` oder zu Ihrem regionalen Endpunkt des Anbieters, wenn es auf Amazon Bedrock oder Google Cloud's Agent Platform ausgeführt wird. Wenn Ihre Agents [MCP-Server](/docs/de/agent-sdk/mcp) oder externe Tools verwenden, benötigen sie auch ausgehenden Zugriff auf diese Endpunkte. Für die Produktion leiten Sie ausgehenden Datenverkehr durch einen Egress-Proxy weiter, der Domain-Allowlists erzwingt, Anmeldeinformationen injiziert und Anfragen protokolliert. Siehe [Sichere Bereitstellung](/docs/de/agent-sdk/secure-deployment) für das vollständige Muster.
193 234
194Für eingehenden Datenverkehr stellen Sie einen HTTP- oder WebSocket-Port auf dem Container bereit. Ihre Anwendung verarbeitet Client-Anfragen auf diesem Port und ruft das SDK intern auf; der Unterprozess selbst lauscht nicht im Netzwerk.235Für eingehenden Datenverkehr stellen Sie einen HTTP- oder WebSocket-Port auf dem Container bereit. Ihre Anwendung verarbeitet Client-Anfragen auf diesem Port und ruft das SDK intern auf; der Unterprozess selbst lauscht nicht im Netzwerk.
195 236
197 Produktionsbedenken behandeln238 Produktionsbedenken behandeln
198</h2>239</h2>
199 240
200Arbeiten Sie diese Entscheidungen durch, bevor Sie einen selbstgehosteten Agenten bereitstellen.241Arbeiten Sie diese Entscheidungen durch, bevor Sie einen selbstgehosteten Agent bereitstellen.
201 242
202<h3 id="session-and-state-persistence">243<h3 id="session-and-state-persistence">
203 Sitzungs- und Zustandspersistenz244 Sitzungs- und Zustandspersistenz
204</h3>245</h3>
205 246
206Der standardmäßige lokale Datenträger geht bei Neustart, Herunterskalierung oder Verschiebung auf einen anderen Knoten verloren. Für jede Sitzung, die ein Benutzer fortsetzen möchte, spiegeln Sie das Transkript mit einem [`SessionStore`-Adapter](/de/agent-sdk/session-storage) auf dauerhaften Speicher. Siehe [Referenzimplementierungen](/de/agent-sdk/session-storage#reference-implementations) für S3-, Redis- und Postgres-Adapter sowie eine Konformitätssuite für Ihre eigenen.247Der Standard-lokale Datenträger geht bei Neustart, Herunterskalierung oder Verschiebung auf einen anderen Knoten verloren. Für jede Sitzung, die ein Benutzer fortsetzen möchte, spiegeln Sie das Transkript mit einem [`SessionStore`-Adapter](/docs/de/agent-sdk/session-storage) zu dauerhaftem Speicher. Siehe [Referenzimplementierungen](/docs/de/agent-sdk/session-storage#reference-implementations) für S3-, Redis- und Postgres-Adapter sowie eine Konformitätssuite für Ihre eigenen.
207 248
208Drei Dinge, die Sie über das Verhalten von `SessionStore` wissen sollten:249Drei Dinge, die Sie über das Verhalten von `SessionStore` wissen sollten:
209 250
210* **Nur Transkripte**: `SessionStore` spiegelt Transkripte, nicht `CLAUDE.md`-Speicherdateien oder andere Arbeitsverzeichnis-Artefakte. Mounten Sie ein gemeinsames Volume oder synchronisieren Sie diese separat.251* **Nur Transkripte**: `SessionStore` spiegelt Transkripte, nicht `CLAUDE.md`-Speicherdateien oder andere Artefakte im Arbeitsverzeichnis. Mounten Sie ein gemeinsames Volume oder synchronisieren Sie diese separat.
211* **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.252* **Spiegelung, keine Ersetzung**: Der Unterprozess schreibt zuerst auf die lokale Festplatte, und das SDK leitet eine Kopie jedes Batches an den Speicher weiter. Das lokale Transkript einer neuen Sitzung überlebt den Lauf; ein aus dem Speicher fortgesetzter Lauf löscht seine lokale Kopie am Ende, sodass der Speicher die einzige dauerhafte Kopie enthält. Siehe [Dual-Write-Architektur](/docs/de/agent-sdk/session-storage#dual-write-architecture).
212* **`mirror_error`-Meldungen**: Ein Batch, den der Store ablehnt, wird insgesamt bis zu dreimal gesendet, mit einer kurzen Backoff-Zeit vor jedem Wiederholungsversuch; ein Aufruf mit Zeitüberschreitung wird nicht wiederholt. Wenn der Batch immer noch fehlschlägt, verwirft das SDK ihn, gibt eine `{ type: "system", subtype: "mirror_error" }`-Meldung aus und setzt die Abfrage fort. Warnen Sie vor diesen, wenn die Store-Dauerhaftigkeit wichtig ist.253* **`mirror_error`-Meldungen**: Wenn das SDK einen Batch nicht an den Speicher liefern kann, verwirft es den Batch, gibt eine `{ type: "system", subtype: "mirror_error" }`-Meldung aus und setzt die Abfrage fort. Warnen Sie vor diesen, wenn die Speicherdauerhaftigkeit wichtig ist. Siehe [Spiegelschreibvorgänge sind Best-Effort](/docs/de/agent-sdk/session-storage#mirror-writes-are-best-effort) für das Wiederholungs- und Timeout-Verhalten.
213 254
214<h3 id="observability">255<h3 id="observability">
215 Observability256 Observability
216</h3>257</h3>
217 258
218Agent SDK-Agenten sind langlebige Prozesse, die Werkzeugaufrufe über viele API-Roundtrips hinweg spawnen. Ohne Telemetrie können Sie nicht sehen, welche Werkzeuge ausgeführt wurden, wie lange sie dauerten oder wo eine Sitzung stecken blieb.259Agent SDK-Agenten sind langlebige Prozesse, die Werkzeugaufrufe über viele API-Roundtrips hinweg erzeugen. Ohne Telemetrie können Sie nicht sehen, welche Werkzeuge ausgeführt wurden, wie lange sie dauerten oder wo eine Sitzung stecken blieb.
219 260
220Das SDK erbt die OpenTelemetry-Konfiguration aus der Umgebung. Legen Sie die OTEL-Umgebungsvariablen auf Container- oder Orchestrator-Ebene fest, damit jeder `query()`-Aufruf Spans, Metriken und Log-Ereignisse an Ihren Collector exportiert. Das folgende Beispiel aktiviert OTLP-Export für alle drei Signale. `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` ist nur für Traces erforderlich; lassen Sie es weg, wenn Sie nur Metriken und Logs exportieren.261Das SDK erbt die OpenTelemetry-Konfiguration aus der Umgebung. Legen Sie die OTEL-Umgebungsvariablen auf Container- oder Orchestrator-Ebene fest, damit jeder `query()`-Aufruf Spans, Metriken und Log-Ereignisse an Ihren Collector exportiert. Das folgende Beispiel aktiviert OTLP-Export für alle drei Signale. `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` ist nur für Traces erforderlich; lassen Sie es weg, wenn Sie nur Metriken und Logs exportieren.
221 262
222```bash title=".env' theme={null}263```bash title=".env" theme={null}
223CLAUDE_CODE_ENABLE_TELEMETRY=1264CLAUDE_CODE_ENABLE_TELEMETRY=1
224CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1265CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
225OTEL_TRACES_EXPORTER=otlp266OTEL_TRACES_EXPORTER=otlp
229OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318270OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318
230```271```
231 272
232Eingabetext und Werkzeugeingaben sind standardmäßig nicht in Exporten enthalten. Siehe [Sensible Daten in Exporten steuern](/de/agent-sdk/observability#control-sensitive-data-in-exports) für die Opt-in-Flags und [Observability](/de/agent-sdk/observability) für den vollständigen Signalkatalog.273Eingabetext und Werkzeugeingaben sind standardmäßig nicht in Exporten enthalten. Siehe [Sensible Daten in Exporten steuern](/docs/de/agent-sdk/observability#control-sensitive-data-in-exports) für die Opt-in-Flags und [Observability](/docs/de/agent-sdk/observability) für den vollständigen Signalkatalog.
233 274
234<h3 id="auth-and-secrets">275<h3 id="auth-and-secrets">
235 Authentifizierung und Geheimnisse276 Authentifizierung und Geheimnisse
237 278
238Drei Authentifizierungsbedenken sind zum Zeitpunkt des Hostings wichtig:279Drei Authentifizierungsbedenken sind zum Zeitpunkt des Hostings wichtig:
239 280
240* **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](/de/agent-sdk/secure-deployment#credential-management) für das Proxy-Muster und [SDK-Übersicht](/de/agent-sdk/overview#get-started) für unterstützte Authentifizierungsmethoden.281* **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](/docs/de/agent-sdk/secure-deployment#credential-management) für das Proxy-Muster und [Setup im SDK-Schnellstart](/docs/de/agent-sdk/quickstart#setup) für unterstützte Authentifizierungsmethoden.
241* **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.282* **Eingehend**: Platzieren Sie die Authentifizierung an einem Gateway vor dem Agent-Container. Der Agent sollte vorauthentifizierte Anfragen erhalten und sollte nicht die Komponente sein, die Benutzer-Token validiert.
242* **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.283* **Ausgehende Werkzeuge**: Halten Sie Werkzeugzugangsanmeldedaten 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 führt den Aufruf durch; der Proxy fügt die Anmeldedaten hinzu.
243 284
244<h3 id="scaling-and-concurrency">285<h3 id="scaling-and-concurrency">
245 Skalierung und Parallelität286 Skalierung und Parallelität
250Dimensionieren Sie jeden Host mit dieser Formel:291Dimensionieren Sie jeden Host mit dieser Formel:
251 292
252```text theme={null}293```text theme={null}
253Agenten pro Host = (Host-RAM - Overhead) / (RAM-Obergrenze pro Sitzung)294agents per host = (host RAM - overhead) / (per-session RAM ceiling)
254```295```
255 296
256Messen Sie die RAM-Obergrenze pro Sitzung, indem Sie eine repräsentative Sitzung bis zu Ihrer Zieldauer unter Ihrer erwarteten Werkzeuglast ausführen und den Peak-RSS aufzeichnen. Der 1-GiB-Startpunkt in [Ressourcen](#resources) ist ein Minimum, nicht die Obergrenze.297Messen Sie die Pro-Sitzungs-Obergrenze, indem Sie eine repräsentative Sitzung bis zu Ihrer Zieldauer unter Ihrer erwarteten Werkzeuglast ausführen und den Peak-RSS aufzeichnen. Der 1-GiB-Startpunkt in [Ressourcen](#resources) ist ein Minimum, nicht die Obergrenze.
257
258Horizontal-Skalierungs-Routing hängt von Ihrem Muster ab. Für lang laufende Sitzungen, bei denen Container viele Sitzungen halten, führen Sie einen Pool von Containern hinter einem Load Balancer aus und heften Sie jede Sitzung mit konsistentem Hashing auf `sessionId` an einen Container. Eine angeheftete Sitzung trifft immer wieder auf denselben Container und daher auf denselben laufenden Unterprozess, bis er entfernt oder der Container neu gestartet wird.
259 298
260Große Fanouts von gleichzeitigen [Subagenten](/de/agent-sdk/subagents) aus einer einzelnen Sitzung können API-Ratenlimits treffen. Teilen Sie die Arbeit in kleinere Batches auf, anstatt eine breite Verteilung auszugeben.299Das horizontale Skalierungs-Routing hängt von Ihrem Muster ab. Bei langlebigen Sitzungen, bei denen Container viele Sitzungen halten, führen Sie einen Pool von Containern hinter einem Load Balancer aus und heften Sie jede Sitzung mit konsistentem Hashing auf `sessionId` an einen Container. Eine angeheftete Sitzung trifft immer wieder auf denselben Container und daher auf denselben laufenden Unterprozess, bis er entfernt oder der Container neu gestartet wird.
261 300
262<h3 id="cost">301<h3 id="cost">
263 Kosten302 Kosten
264</h3>303</h3>
265 304
266Die Anthropic-Token-Kosten dominieren typischerweise die Container-Infrastrukturkosten um eine Größenordnung oder mehr. Ein minimal bereitgestellter Container läuft ungefähr \$0,05 pro Stunde, während eine einzelne lange Agent-Sitzung Dollar in Token ausgeben kann. Siehe [Kostenverfolgung](/de/agent-sdk/cost-tracking) für Token-Buchhaltung pro Sitzung.305Die Anthropic-Token-Kosten dominieren typischerweise die Container-Infrastrukturkosten um eine Größenordnung oder mehr. Ein minimal bereitgestellter Container läuft ungefähr \$0,05 pro Stunde, während eine einzelne lange Agent-Sitzung Dollar in Token ausgeben kann. Siehe [Cost Tracking](/docs/de/agent-sdk/cost-tracking) für die Token-Abrechnung pro Sitzung.
267 306
268<h3 id="multi-tenant-isolation">307<h3 id="multi-tenant-isolation">
269 Multi-Tenant-Isolation308 Multi-Tenant-Isolation
270</h3>309</h3>
271 310
272Das standardmäßige SDK-Verhalten liest Einstellungen und `CLAUDE.md`-Speicherdateien aus dem Dateisystem. In einem gemeinsamen Container, der mehrere Mandanten bedient, können diese Dateien den Kontext eines Mandanten in die Sitzung eines anderen Mandanten durchsickern lassen.311Das Standard-SDK-Verhalten liest Einstellungen und `CLAUDE.md`-Speicherdateien aus dem Dateisystem. In einem gemeinsamen Container, der mehrere Mandanten bedient, können diese Dateien den Kontext eines Mandanten in die Sitzung eines anderen Mandanten durchsickern lassen.
273 312
274Um Mandanten in einem gemeinsamen Container zu isolieren:313Um Mandanten in einem gemeinsamen Container zu isolieren:
275 314
276* Übergeben Sie `settingSources: []` in TypeScript oder `setting_sources=[]` in Python, damit keine Dateisystem-Einstellungen geladen werden.315* Übergeben Sie `settingSources: []` in TypeScript oder `setting_sources=[]` in Python, um Benutzer-, Projekt- und lokale Einstellungen zu überspringen.
277* Setzen Sie `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` in `env`. [Auto Memory](/de/memory#auto-memory) bei `~/.claude/projects/<project>/memory/` wird unabhängig von `settingSources` in den System-Prompt geladen. Siehe [Was settingSources nicht steuert](/de/agent-sdk/claude-code-features#what-settingsources-does-not-control) für die anderen Eingaben, die bedingungslos geladen werden.316* Setzen Sie `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` in `env`. [Auto Memory](/docs/de/memory#auto-memory) bei `~/.claude/projects/<project>/memory/` wird unabhängig von `settingSources` in den System-Prompt geladen. Siehe [Was settingSources nicht steuert](/docs/de/agent-sdk/claude-code-features#what-settingsources-does-not-control) für die anderen Eingaben, die bedingungslos geladen werden.
278* Zeigen Sie `CLAUDE_CONFIG_DIR` auf ein mandantenspezifisches Verzeichnis, damit Mandanten die globale Konfiguration `~/.claude.json` nicht teilen.317* Zeigen Sie `CLAUDE_CONFIG_DIR` auf ein mandantenspezifisches Verzeichnis, damit Mandanten die globale Konfiguration `~/.claude.json` nicht teilen. Wenn jedes Konfigurationsverzeichnis ein Arbeitsverzeichnis bedient und Sie keinen [`SessionStore`](/docs/de/agent-sdk/session-storage) über Mandanten hinweg teilen, können Sie auch [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/de/sessions#name-the-project-directory-yourself) in `env` setzen, um die Transkriptpfade darunter kurz zu halten. Erfordert TypeScript Agent SDK v0.3.234 oder später oder Python Agent SDK v0.2.140 oder später.
279* Verwenden Sie ein mandantenspezifisches Arbeitsverzeichnis. Übergeben Sie `cwd` explizit bei jedem `query()`-Aufruf.318* Verwenden Sie ein mandantenspezifisches Arbeitsverzeichnis. Übergeben Sie `cwd` explizit bei jedem `query()`-Aufruf.
280* 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.319* 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.
281 320
282Das folgende Beispiel wendet die vier SDK-Ebenen-Optionen zusammen an. Konstruieren Sie `tenantDir` und `configDir` so, dass jeder Mandant einen Pfad erhält, den kein anderer Mandant lesen kann. In TypeScript ersetzt `env` die Unterprozess-Umgebung, daher verteilen Sie `...process.env`, um geerbte Variablen wie `PATH` und `ANTHROPIC_API_KEY` zu behalten. In Python wird `env` auf die geerbte Umgebung zusammengeführt.321Das folgende Beispiel wendet die Einstellungen-, Auto-Memory-, Konfigurationsverzeichnis- und Arbeitsverzeichnisoptionen zusammen an. Konstruieren Sie `tenantDir` und `configDir` so, dass jeder Mandant einen Pfad erhält, den kein anderer Mandant lesen kann. In TypeScript ersetzt `env` die Unterprozessumgebung, daher verteilen Sie `...process.env`, um geerbte Variablen wie `PATH` und `ANTHROPIC_API_KEY` zu behalten. In Python wird `env` auf die geerbte Umgebung zusammengeführt.
283 322
284<CodeGroup>323<CodeGroup>
285 ```typescript TypeScript theme={null}324 ```typescript TypeScript theme={null}
307 346
308 ```python Python theme={null}347 ```python Python theme={null}
309 from claude_agent_sdk import query, ClaudeAgentOptions348 from claude_agent_sdk import query, ClaudeAgentOptions
349 import asyncio
310 350
351 prompt: str = ...
352 tenant_dir: str = ...
353 config_dir: str = ...
354
355
356 async def main():
311 async for message in query(357 async for message in query(
312 prompt=prompt,358 prompt=prompt,
313 options=ClaudeAgentOptions(359 options=ClaudeAgentOptions(
320 ),366 ),
321 ):367 ):
322 ...368 ...
369
370
371 asyncio.run(main())
323 ```372 ```
324</CodeGroup>373</CodeGroup>
325 374
326Für mandantenspezifische Netzwerkkontrollen siehe [Sichere Bereitstellung](/de/agent-sdk/secure-deployment).
327
328<h2 id="known-limitations">375<h2 id="known-limitations">
329 Bekannte Einschränkungen376 Bekannte Einschränkungen
330</h2>377</h2>
331 378
332Berücksichtigen Sie diese in Ihrem Bereitstellungsdesign.379Berücksichtigen Sie diese in Ihrem Bereitstellungsdesign.
333 380
334| Einschränkung | Was zu tun ist |381| Einschränkung | Maßnahme |
335| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |382| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
336| Kein Sitzungs-Timeout auf oberster Ebene | Eine Sitzung läuft nicht automatisch ab. Legen Sie `maxTurns` in `Options` fest, um zu begrenzen, wie viele Tool-Use-Rundläufe der Agent durchführt, bevor er stoppt. |383| Kein Sitzungs-Timeout auf oberster Ebene | Eine Sitzung läuft nicht automatisch ab. Setzen Sie `maxTurns` in TypeScript oder `max_turns` in Python, um zu begrenzen, wie viele Tool-Use-Rundläufe der Agent durchführt, bevor er stoppt. |
337| Speicherwachstum über lange Sitzungen | Begrenzen Sie die Sitzungslänge oder recyceln Sie Subprozesse regelmäßig. Siehe [Skalierung und Parallelität](#scaling-and-concurrency). |384| Speicherwachstum über lange Sitzungen | Begrenzen Sie die Sitzungslänge oder recyceln Sie Subprozesse regelmäßig. Siehe [Skalierung und Parallelität](#scaling-and-concurrency). |
338| Große parallele Subagent-Ausfächerungen können Ratenlimits treffen | Teilen Sie die Arbeit in kleinere Batches auf, anstatt eine breite Verteilung auszugeben. |385| Große parallele Subagent-Fanouts können Ratenlimits treffen | Teilen Sie die Arbeit in kleinere Batches auf, anstatt eine breite Verteilung auszugeben. |
339| Keine Wanduhr-Frist pro Subagent | Begrenzen Sie jeden [Subagent](/de/agent-sdk/subagents) mit `maxTurns` in seiner `AgentDefinition`. Nur für Hintergrund-Subagenten setzt `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` einen Stall-Watchdog, der aktiviert wird, wenn ein `run_in_background`-Subagent keine Ausgabe mehr produziert; dies ist keine Gesamtlaufzeit-Frist. |386| Keine Wanduhr-Frist pro Subagent | Begrenzen Sie jeden [Subagent](/docs/de/agent-sdk/subagents) mit `maxTurns` in seiner `AgentDefinition`. `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` setzt einen Stall-Watchdog, der ausgelöst wird, wenn ein Subagent keine Ausgabe mehr produziert; es ist keine Gesamtlaufzeit-Frist. |
387
388<h2 id="troubleshoot-deployment-failures">
389 Bereitstellungsfehler beheben
390</h2>
391
392Verwenden Sie diesen Abschnitt, wenn ein Agent, der auf Ihrem Computer funktioniert, in einem bereitgestellten Dienst fehlschlägt. Jedes Element unten benennt einen Fehler und verlinkt den Eintrag, der ihn behandelt:
393
394* **CLI nicht gefunden beim Dienstart**: In Python führt ein Container oder Service-Manager Ihre Anwendung mit einem anderen `PATH` aus als Ihre Shell, daher ist eine lokal funktionierende Installation für den Prozess nicht sichtbar. In TypeScript hat der Image-Build die optionalen Abhängigkeiten des SDK übersprungen, oder `pathToClaudeCodeExecutable` verweist auf eine Datei, die im Image nicht vorhanden ist. Siehe [Claude Code nicht gefunden](/docs/de/agent-sdk/troubleshooting#clinotfounderror-claude-code-not-found).
395* **CLI im Image vorhanden, wird aber nicht gestartet**: Claude Code kann nicht von einer Binärdatei gestartet werden, die nicht der Architektur oder libc des Containers entspricht, oder von einer Datei, die während des Image-Builds ihre Ausführungsberechtigung verloren hat. Siehe [Claude Code konnte nicht gestartet werden](/docs/de/agent-sdk/troubleshooting#cliconnectionerror-failed-to-start-claude-code).
396* **Claude Code-Prozess beendet sich während der Ausführung**: Der Fehler, den Ihre Anwendung erhält, hängt von der SDK-Sprache und davon ab, ob die CLI zuerst ein Fehlerergebnis gemeldet hat. Die Einträge unter [CLI-Prozessbeendigung](/docs/de/agent-sdk/troubleshooting#cli-process-exit) behandeln jede Nachricht.
340 397
341<h2 id="next-steps">398<h2 id="next-steps">
342 Nächste Schritte399 Nächste Schritte
343</h2>400</h2>
344 401
345* [Hosting-Cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/claude_agent_sdk/07_Hosting_the_agent.ipynb): Notebook-Anleitung mit [bereitstellbarem Code](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting) für Docker, Modal und Kubernetes.402* [Hosting-Cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/claude_agent_sdk/07_Hosting_the_agent.ipynb): Notebook-Anleitung mit [bereitstellbarem Code](https://github.com/anthropics/claude-cookbooks/tree/main/claude_agent_sdk/hosting) für Docker, Modal und Kubernetes.
346* [Sitzungsspeicher](/de/agent-sdk/session-storage): Persistieren Sie Transkripte über Hosts hinweg mit einem `SessionStore`-Adapter.403* [Sitzungsspeicher](/docs/de/agent-sdk/session-storage): Persistieren Sie Transkripte über Hosts hinweg mit einem `SessionStore`-Adapter.
347* [Observability](/de/agent-sdk/observability): Exportieren Sie OTEL-Traces, Metriken und Protokolle zu Ihrem Collector.404* [Observability](/docs/de/agent-sdk/observability): Exportieren Sie OTEL-Traces, Metriken und Protokolle zu Ihrem Collector.
348* [Sichere Bereitstellung](/de/agent-sdk/secure-deployment): Netzwerkkontrollen, Verwaltung von Anmeldedaten und Isolationshärtung.405* [Sichere Bereitstellung](/docs/de/agent-sdk/secure-deployment): Netzwerkkontrollen, Verwaltung von Anmeldedaten und Isolationshärtung.
349* [Kostenverfolgung](/de/agent-sdk/cost-tracking): Token- und Kostenabrechnung pro Sitzung.406* [Kostenverfolgung](/docs/de/agent-sdk/cost-tracking): Token- und Kostenabrechnung pro Sitzung.