Hosting the Agent SDK changedagent-sdk/hosting
Nearest release: v2.1.252, published 11 hours after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+29added
Lines−5removed
From line
16
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits18to this page, all time
The whole hunk
from line 16, old and new numbered
/
from line 16
1616
1717<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" />
1818
19One 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, so pass `cwd` on each `query()` call when sessions need separate filesystems:
19One 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:
2020
2121<CodeGroup>
2222 ```typescript TypeScript theme={null}
23 query({ prompt, options: { cwd: "/work/session-a" } })
23 import { query } from "@anthropic-ai/claude-agent-sdk";
24
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 }
2431 ```
2532
2633 ```python Python theme={null}
27 query(prompt=prompt, options=ClaudeAgentOptions(cwd="/work/session-a"))
34 import asyncio
35
36 from claude_agent_sdk import ClaudeAgentOptions, query
37
38
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)
45
46
47 asyncio.run(main())
2848 ```
2949</CodeGroup>
3050
51The TypeScript examples on this page use top-level `await`, so save them as `.mts` files or set `"type": "module"` in `package.json`.
52
3153### State that lives on local disk
3254
3355Three kinds of agent state live on the container's filesystem by default. None of them survive a container restart, a scale-down, or a move to a different node.
from line 74
5274
5375Example workloads include bug investigation and fix, invoice and receipt extraction, document translation, and media transformation.
5476
55The container runs a one-shot entrypoint that calls the SDK and exits. In TypeScript, save the file as `entrypoint.mts` or set `"type": "module"` in `package.json` so top-level `await` is available.
77The container runs a one-shot entrypoint that reads the task from the `TASK_PROMPT` environment variable, calls the SDK, and exits.
5678
5779<CodeGroup>
5880 ```typescript TypeScript theme={null}
from line 105
83105 ```
84106</CodeGroup>
85107
108The 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.
109
86110### Long-running sessions
87111
88112Run persistent container instances, often hosting multiple SDK processes per container, to serve ongoing work. Best for agents that take autonomous action, serve content, or handle high-volume message streams.
from line 336
312336
313337| Limitation | What to do |
314338| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
315| No top-level session timeout | A session does not time out on its own. Set `maxTurns` in `Options` to bound how many tool-use round trips the agent takes before stopping. |
339| No top-level session timeout | A session does not time out on its own. Set `maxTurns` in TypeScript or `max_turns` in Python to bound how many tool-use round trips the agent takes before stopping. |
316340| Memory growth over long sessions | Cap session length or recycle subprocesses periodically. See [Scaling and concurrency](#scaling-and-concurrency). |
317341| Large parallel-subagent fanouts can hit rate limits | Break work into smaller batches rather than issuing one wide dispatch. |
318342| No per-subagent wall-clock deadline | Cap each [subagent](/docs/en/agent-sdk/subagents) with `maxTurns` in its `AgentDefinition`. For background subagents only, `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` sets a stall watchdog that fires when a `run_in_background` subagent stops producing output; it is not a total-runtime deadline. |
No line in this hunk matches that.