The SDK hands a team Claude Code's agent loop, and the work left is the infrastructure around it. Before an SDK agent serves users, follow this playbook for the hosting pattern and session store. It also covers permission rules and hooks that gate tools, plus turn limits, cost tracking, and tracing.
When you need this
- An agent built on the SDK is moving from a laptop to containers that other people's requests reach.
- Sessions must survive a container restart or move between hosts.
- The agent can run shell commands, change files, or call systems that hold customer data.
Evaluation criteria
Hosting pattern
How long does a container live relative to the sessions it serves?
Look forPick ephemeral containers per task, long-running containers holding many sessions, or hybrid containers that hydrate from a store. Spotify runs Honk in Kubernetes pods that host many concurrent sessions. Glide's VP of Engineering reports that worker runtimes that cannot spawn processes needed heavy workarounds.
Sizing
How many sessions fit on one host?
Look forStart from Anthropic's floor of 1 GiB RAM, 5 GiB disk, and 1 CPU per agent, then record peak memory on a session of real length. One builder reported crashes in streaming mode inside cloud containers that were hard to trace.
Session storage
What happens to a conversation when its container stops?
Look forConfigure a SessionStore adapter so transcripts live in your database or object store. Before it existed, one team synced session files to PostgreSQL by hand on Kubernetes, and another saw resume silently start a new session on shared NFS. Test resume across hosts.
Permissions and sandboxing
Which tool calls run without a person?
Look forHooks run first, then deny rules, ask rules, the permission mode, and canUseTool. Crystallize sandboxes every shell command at the operating system and keeps credentials in its orchestrator, after finding that an allowlist of safe commands could be bypassed.
System prompt
Should the agent behave like Claude Code?
Look forWith no system prompt the SDK uses a minimal tool-calling prompt. The claude_code preset adds Claude Code's prompt and safety rules, and a custom prompt replaces both. Builders report a hidden default prompt and an identity line they cannot remove, so test the prompt your users will see.
Turn and spend limits
What stops a run that loops?
Look forSet a turn limit on every query and a budget per run, and read usage from result messages. Reconcile against the Usage and Cost API, since total_cost_usd is an estimate. Reconcile SDK cost figures with billing after upgrades: Moon Banking saw logged cost triple between two minor versions because the older one undercounted. On a Claude plan, check the result text for the limit message, since one builder's hit quota came back as a successful result.
Prompt caching
Are cache reads happening on turn two?
Look forCheck cache read tokens on multi-turn runs. Builders report caches rewritten every turn, one fixed by passing a stable session ID, and a bundled CLI that wrote cache without reading it in headless runs.
Tracing
Can you see which subagent ran which tool?
Look forEnable OpenTelemetry export from the CLI process; traces need the beta flag. Laminar built a local proxy to capture prompts and subagent runs because the subprocess hid them.
Questions to ask vendors
- Which hosting pattern does each agent use, and what is its peak memory per session?
- Where are transcripts stored, and has resume been tested on a different host?
- Which tools are denied outright, and which go through canUseTool or a sandbox?
- What turn limit and budget does every query carry, and who reconciles cost against billing?
- Which SDK version is pinned, and who reads the changelog before an upgrade?
Red flags
- Session transcripts on a container's local disk with no SessionStore.
- bypassPermissions in production with shell access and no sandbox.
- Credentials in the environment the agent's shell can read.
- No turn limit or budget on queries that users can trigger.
- Unpinned SDK versions in production.
Products in this piece
Sources
- Official documentation
- 9
- Public source
- 12
- Agent SDK docs: Hosting (subprocess model, session patterns, sizing)
- Agent SDK docs: Work with sessions
- Agent SDK docs: Persist sessions to external storage
- Agent SDK docs: Configure permissions
- Agent SDK docs: Hooks
- Agent SDK docs: Modifying system prompts
- Agent SDK docs: Track cost and usage
- Agent SDK docs: Observability with OpenTelemetry
- Agent SDK docs: Securely deploying AI agents
- Spotify Engineering: Coding Is No Longer the Constraint, on Honk and the Agent SDK (Jun 3, 2026)
- Ryan Daigle (Glide) on X: the SDK's subprocesses in a worker runtime (Apr 12, 2026)
- Hacker News comment on running the SDK in cloud containers and building session storage around it (Mar 10, 2026)
- Claude Agent SDK TypeScript issue #97: session storage for Kubernetes deployments (Dec 11, 2025)
- Claude Agent SDK Python issue #555: resume silently starts a new session (Feb 7, 2026)
- Sébastien Morel (Crystallize): How We Gave an AI Agent Our Codebase Without Giving It the Keys (Oct 13, 2026)
- Claude Agent SDK TypeScript issue #468: no way to omit the injected SDK identity line (Sep 22, 2026)
- Claude Agent SDK TypeScript issue #93: cost tripled between 0.1.30 and 0.1.60 (Dec 6, 2025)
- samael_voolt on X: a stable session ID restores prompt caching (Oct 8, 2026)
- Claude Agent SDK Python issue #974: bundled CLI never reads the prompt cache in headless runs (May 20, 2026)
- Dinmukhamed Mailibay (Laminar): How we instrumented Claude Agent SDK using a tiny Rust proxy (Dec 3, 2025)
- arthurain on X: a hit 5-hour quota returned as a successful result (Oct 1, 2026)