Hosting the Agent SDK changedagent-sdk/hosting
Nearest release: v2.1.284, published 16 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 28 Sep 2026 00:41 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+139added
Lines−149removed
From line
12
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits15to this page, all time
The whole hunk
from line 12, old and new numbered
/
from line 12
1212
1313Every hosting decision on this page follows from how the SDK runs the agent. When your code calls `query()`, the SDK spawns a separate `claude` CLI process and talks to it over stdio. That subprocess owns the shell, the working directory, and the JSONL session transcripts on local disk.
1414
15<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" />
15
1616
17<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" />
18
1917One agent session maps to one subprocess. Running N concurrent sessions means N subprocesses, each with its own process tree and transcript file. By default they all inherit your application's working directory. When sessions need separate filesystems, pass a distinct `cwd` in the options of each session's `query()` call:
2018
21<CodeGroup>
22 ```typescript TypeScript theme={null}
23 import { query } from "@anthropic-ai/claude-agent-sdk";
19```typescript TypeScript theme={null}
20import { query } from "@anthropic-ai/claude-agent-sdk";
2421
25 for await (const message of query({
26 prompt: "Summarize the files in this directory",
27 options: { cwd: "/work/session-a" },
28 })) {
29 console.log(message);
30 }
31 ```
22for await (const message of query({
23 prompt: "Summarize the files in this directory",
24 options: { cwd: "/work/session-a" },
25})) {
26 console.log(message);
27}
28```
3229
33 ```python Python theme={null}
34 import asyncio
30```python Python theme={null}
31import asyncio
3532
36 from claude_agent_sdk import ClaudeAgentOptions, query
33from claude_agent_sdk import ClaudeAgentOptions, query
3734
3835
39 async def main():
40 async for message in query(
41 prompt="Summarize the files in this directory",
42 options=ClaudeAgentOptions(cwd="/work/session-a"),
43 ):
44 print(message)
36async def main():
37 async for message in query(
38 prompt="Summarize the files in this directory",
39 options=ClaudeAgentOptions(cwd="/work/session-a"),
40 ):
41 print(message)
4542
4643
47 asyncio.run(main())
48 ```
49</CodeGroup>
44asyncio.run(main())
45```
5046
5147The TypeScript examples on this page use top-level `await`, so save them as `.mts` files or set `"type": "module"` in `package.json`.
5248
from line 72
7672
7773The container runs a one-shot entrypoint that reads the task from the `TASK_PROMPT` environment variable, calls the SDK, and exits.
7874
79<CodeGroup>
80 ```typescript TypeScript theme={null}
81 import { query } from "@anthropic-ai/claude-agent-sdk";
75```typescript TypeScript theme={null}
76import { query } from "@anthropic-ai/claude-agent-sdk";
8277
83 const prompt = process.env.TASK_PROMPT!;
84 for await (const message of query({ prompt, options: { maxTurns: 20 } })) {
85 console.log(message);
86 }
87 ```
78const prompt = process.env.TASK_PROMPT!;
79for await (const message of query({ prompt, options: { maxTurns: 20 } })) {
80 console.log(message);
81}
82```
8883
89 ```python Python theme={null}
90 import asyncio
91 import os
84```python Python theme={null}
85import asyncio
86import os
9287
93 from claude_agent_sdk import ClaudeAgentOptions, query
88from claude_agent_sdk import ClaudeAgentOptions, query
9489
9590
96 async def main():
97 async for message in query(
98 prompt=os.environ["TASK_PROMPT"],
99 options=ClaudeAgentOptions(max_turns=20),
100 ):
101 print(message)
91async def main():
92 async for message in query(
93 prompt=os.environ["TASK_PROMPT"],
94 options=ClaudeAgentOptions(max_turns=20),
95 ):
96 print(message)
10297
10398
104 asyncio.run(main())
105 ```
106</CodeGroup>
99asyncio.run(main())
100```
107101
108102The script prints each message as it arrives, including a result message whose `subtype` is `success` when the task completes within the turn limit. If the task hits the 20-turn limit instead, the result message's `subtype` is `error_max_turns` and the `query()` call raises an error after yielding it, so wrap the loop in a try block if the container needs to exit cleanly. See [Handle the result](/docs/en/agent-sdk/agent-loop#handle-the-result) for the error subtypes.
109103
from line 124
130124
131125The pattern hinges on resuming a session by ID with a shared store attached:
132126
133<CodeGroup>
134 ```typescript TypeScript theme={null}
135 import { query, type SessionStore } from "@anthropic-ai/claude-agent-sdk";
127```typescript TypeScript theme={null}
128import { query, type SessionStore } from "@anthropic-ai/claude-agent-sdk";
136129
137 declare const userInput: string;
138 declare const sessionId: string; // looked up from your database by user
139 declare const sessionStore: SessionStore; // an object store, key-value store, database, or your own adapter
130declare const userInput: string;
131declare const sessionId: string; // looked up from your database by user
132declare const sessionStore: SessionStore; // an object store, key-value store, database, or your own adapter
140133
141 for await (const message of query({
142 prompt: userInput,
143 options: { resume: sessionId, sessionStore },
144 })) {
145 // ...
146 }
147 ```
134for await (const message of query({
135 prompt: userInput,
136 options: { resume: sessionId, sessionStore },
137})) {
138 // ...
139}
140```
148141
149 ```python Python theme={null}
150 from claude_agent_sdk import query, ClaudeAgentOptions, SessionStore
151 import asyncio
142```python Python theme={null}
143from claude_agent_sdk import query, ClaudeAgentOptions, SessionStore
144import asyncio
152145
153 user_input: str = ...
154 session_id: str = ... # looked up from your database by user
155 session_store: SessionStore = ... # an object store, key-value store, database, or your own adapter
146user_input: str = ...
147session_id: str = ... # looked up from your database by user
148session_store: SessionStore = ... # an object store, key-value store, database, or your own adapter
156149
157150
158 async def main():
159 async for message in query(
160 prompt=user_input,
161 options=ClaudeAgentOptions(
162 resume=session_id,
163 session_store=session_store,
164 ),
165 ):
166 ...
151async def main():
152 async for message in query(
153 prompt=user_input,
154 options=ClaudeAgentOptions(
155 resume=session_id,
156 session_store=session_store,
157 ),
158 ):
159 ...
167160
168161
169 asyncio.run(main())
170 ```
171</CodeGroup>
162asyncio.run(main())
163```
172164
173165### Multi-agent container
174166
from line 275
283275
284276The example below applies the settings, auto memory, config directory, and working directory options together. Construct `tenantDir` and `configDir` so each tenant gets a path no other tenant can read. In TypeScript, `env` replaces the subprocess environment, so spread `...process.env` to keep inherited variables like `PATH` and `ANTHROPIC_API_KEY`. In Python, `env` is merged on top of the inherited environment.
285277
286<CodeGroup>
287 ```typescript TypeScript theme={null}
288 import { query } from "@anthropic-ai/claude-agent-sdk";
278```typescript TypeScript theme={null}
279import { query } from "@anthropic-ai/claude-agent-sdk";
289280
290 declare const prompt: string;
291 declare const tenantDir: string;
292 declare const configDir: string;
281declare const prompt: string;
282declare const tenantDir: string;
283declare const configDir: string;
293284
294 for await (const message of query({
295 prompt,
296 options: {
297 cwd: tenantDir,
298 settingSources: [],
299 env: {
300 ...process.env,
301 CLAUDE_CONFIG_DIR: configDir,
302 CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
303 },
285for await (const message of query({
286 prompt,
287 options: {
288 cwd: tenantDir,
289 settingSources: [],
290 env: {
291 ...process.env,
292 CLAUDE_CONFIG_DIR: configDir,
293 CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
304294 },
305 })) {
306 // ...
307 }
308 ```
295 },
296})) {
297 // ...
298}
299```
309300
310 ```python Python theme={null}
311 from claude_agent_sdk import query, ClaudeAgentOptions
312 import asyncio
301```python Python theme={null}
302from claude_agent_sdk import query, ClaudeAgentOptions
303import asyncio
313304
314 prompt: str = ...
315 tenant_dir: str = ...
316 config_dir: str = ...
305prompt: str = ...
306tenant_dir: str = ...
307config_dir: str = ...
317308
318309
319 async def main():
320 async for message in query(
321 prompt=prompt,
322 options=ClaudeAgentOptions(
323 cwd=tenant_dir,
324 setting_sources=[],
325 env={
326 "CLAUDE_CONFIG_DIR": config_dir,
327 "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
328 },
329 ),
330 ):
331 ...
310async def main():
311 async for message in query(
312 prompt=prompt,
313 options=ClaudeAgentOptions(
314 cwd=tenant_dir,
315 setting_sources=[],
316 env={
317 "CLAUDE_CONFIG_DIR": config_dir,
318 "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
319 },
320 ),
321 ):
322 ...
332323
333324
334 asyncio.run(main())
335 ```
336</CodeGroup>
325asyncio.run(main())
326```
337327
338328## Known limitations
339329
No line in this hunk matches that.