Claude Agent SDK (Python) — Production Guide
Running Python Claude Agent SDK services in production: resilience, cost control, observability, containers, security and scaling.
Verified against claude-agent-sdk 0.2.183 (checked 2026-11-19).
The Agent SDK runs the Claude Code CLI as a child process for every query() call or ClaudeSDKClient session. Most production concerns follow from that: each run costs a process, a working directory and some memory; each run can execute tools on the host; and each run has a cost you can measure precisely from its ResultMessage.
Contents
Section titled “Contents”Resilience
Section titled “Resilience”Know what can fail
Section titled “Know what can fail”| Failure | How it surfaces |
|---|---|
| Model API error (overload, 5xx, rate limit, auth) | The CLI retries transient errors itself. If it gives up, the SDK yields a ResultMessage with is_error=True, subtype="success", the error text in result and the HTTP status in api_error_status, then raises ResultError with the same fields |
| Turn or budget limit reached | a ResultMessage with subtype "error_max_turns" / "error_max_budget_usd", then ResultError |
| CLI missing | CLINotFoundError before anything runs |
| CLI crashed without a result | ProcessError with exit_code and stderr |
| Garbled output line | CLIJSONDecodeError |
The order matters: the error ResultMessage comes first and the exception after it, when the CLI exits. A loop that returns on the first ResultMessage never sees the exception, and returns the error text as if it were the answer.
Retry only what is worth retrying
Section titled “Retry only what is worth retrying”import asyncioimport randomfrom claude_agent_sdk import ( query, ClaudeAgentOptions, ResultMessage, CLINotFoundError, CLIConnectionError, ProcessError, ResultError,)
RETRYABLE_STATUS = {408, 429, 500, 502, 503, 504, 529}LIMIT_SUBTYPES = {"error_max_turns", "error_max_budget_usd", "error_max_structured_output_retries"}
def is_transient(e: ResultError) -> bool: if e.subtype in LIMIT_SUBTYPES: return False # a limit you set: retrying hits it again if e.api_error_status is not None: return e.api_error_status in RETRYABLE_STATUS # 400, 401, 403 ... will fail again return e.terminal_reason == "api_error" # e.g. a timeout with no HTTP status
async def run_resilient(prompt: str, options: ClaudeAgentOptions, attempts: int = 4) -> ResultMessage: for attempt in range(1, attempts + 1): try: result = None async for message in query(prompt=prompt, options=options): if isinstance(message, ResultMessage): result = message # do not return yet: a failed run raises ResultError next if result is None: raise RuntimeError("agent finished without a result") return result except CLINotFoundError: raise # deployment problem except ResultError as e: # before ProcessError: it is a subclass if not is_transient(e) or attempt == attempts: raise except (CLIConnectionError, ProcessError): # the CLI died without reporting a result if attempt == attempts: raise await asyncio.sleep(min(30, 2 ** attempt) + random.random()) raise AssertionError("unreachable")Behaviour, checked against a stub CLI that fails in each way: an overloaded API (529) is retried and the run succeeds once the stub recovers; a 401, error_max_turns and error_max_budget_usd each raise ResultError after a single attempt; a crash without a result is retried, then raised as ProcessError.
Retrying an agent run is not free: it repeats tool calls, which may have side effects. For agents that write files or call external systems, prefer resuming the failed session (resume=result.session_id) with a prompt such as “continue from where you stopped”, or make tools idempotent.
Timeouts
Section titled “Timeouts”Wrap runs in asyncio.timeout() (Python 3.11+) or asyncio.wait_for(). Cancelling the task tears down the CLI process; since 0.2.111 the SDK shields that clean-up from cancellation so no orphaned claude processes are left behind.
import asynciofrom claude_agent_sdk import ClaudeAgentOptions
async def run_with_deadline(prompt: str, seconds: float = 300): async with asyncio.timeout(seconds): return await run_resilient(prompt, ClaudeAgentOptions(max_turns=40))Model fallback
Section titled “Model fallback”fallback_model="claude-sonnet-5-5" lets the CLI switch models when the primary is overloaded, rather than failing the run.
Cost control
Section titled “Cost control”Hard limits per run
Section titled “Hard limits per run”from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions( max_turns=30, # stop runaway loops max_budget_usd=2.00, # stop when the run's cost passes $2 task_budget={"total": 200_000}, # tell the model its token budget so it paces itself)max_budget_usd is enforced by Claude Code, which ends the run once the limit is passed; task_budget is advisory and helps the model finish gracefully before a hard limit cuts it off.
Measure from ResultMessage
Section titled “Measure from ResultMessage”Do not hard-code prices. Each run reports its own cost, and model_usage splits it by model. Use model_usage rather than usage for accounting: usage covers only the main loop, not subagents or compaction.
from claude_agent_sdk import ResultMessage
def record_cost(result: ResultMessage, tenant: str) -> None: metrics.counter("agent_cost_usd", result.total_cost_usd or 0.0, tags={"tenant": tenant}) for model, usage in (result.model_usage or {}).items(): metrics.counter("agent_tokens_in", usage.get("inputTokens", 0), tags={"model": model}) metrics.counter("agent_tokens_out", usage.get("outputTokens", 0), tags={"model": model}) metrics.counter("agent_cache_read", usage.get("cacheReadInputTokens", 0), tags={"model": model})(metrics stands for whatever client you use: StatsD, Prometheus, OpenTelemetry metrics.)
Spend less per task
Section titled “Spend less per task”In rough order of impact:
- Lower effort before changing model.
effort="low"or"medium"on a capable model often matches a cheaper model at higher effort, and keeps one cache namespace. - Use cheaper models for subagents. Give
AgentDefinition(model="sonnet")or"haiku"to reading-heavy or routine subagents and keep the main loop onclaude-opus-5-5. - Keep the system prompt stable. Use
{"type": "preset", "preset": "claude_code", "exclude_dynamic_sections": True}or a fixed string, so prompt caching works across runs. Timestamps or request IDs in the system prompt defeat it. - Trim the tool set. Fewer tools means a smaller prompt;
tools=[]for pure text tasks. - Cap turns. Many runaway costs are loops;
max_turnsis the cheapest guard.
A simple routing helper:
from claude_agent_sdk import ClaudeAgentOptions
PROFILES = { "simple": dict(model="claude-haiku-5-5", effort="low"), "standard": dict(model="claude-sonnet-5-5", effort="medium"), "complex": dict(model="claude-opus-5-5", effort="high"),}
def options_for(kind: str, **overrides) -> ClaudeAgentOptions: return ClaudeAgentOptions(**{**PROFILES[kind], **overrides})Observability
Section titled “Observability”Structured logs from the message stream
Section titled “Structured logs from the message stream”Log one line per tool call and one per result. Everything you need is on the messages:
import jsonimport loggingimport timefrom claude_agent_sdk import ( query, ClaudeAgentOptions, AssistantMessage, UserMessage, ResultMessage, SystemMessage, ToolUseBlock, ToolResultBlock,)
log = logging.getLogger("agent")
async def run_logged(prompt: str, options: ClaudeAgentOptions, request_id: str) -> ResultMessage | None: started = time.monotonic() result = None async for message in query(prompt=prompt, options=options): if isinstance(message, SystemMessage) and message.subtype == "init": log.info(json.dumps({"rid": request_id, "event": "init", "session": message.data.get("session_id"), "model": message.data.get("model")})) elif isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, ToolUseBlock): log.info(json.dumps({"rid": request_id, "event": "tool_use", "tool": block.name, "id": block.id})) elif isinstance(message, UserMessage) and isinstance(message.content, list): for block in message.content: if isinstance(block, ToolResultBlock) and block.is_error: log.warning(json.dumps({"rid": request_id, "event": "tool_error", "id": block.tool_use_id})) elif isinstance(message, ResultMessage): result = message log.info(json.dumps({ "rid": request_id, "event": "result", "ok": not message.is_error, "subtype": message.subtype, "terminal_reason": message.terminal_reason, "turns": message.num_turns, "cost_usd": message.total_cost_usd, "duration_ms": message.duration_ms, "wall_ms": int((time.monotonic() - started) * 1000), })) return resultPass stderr=lambda line: log.debug("cli: %s", line) in the options to capture the CLI’s own diagnostics.
Hooks for policy-level auditing
Section titled “Hooks for policy-level auditing”Logging in hooks catches tool calls made by subagents too, and runs before permission decisions. See Recipe 13.
Tracing
Section titled “Tracing”If opentelemetry-api is installed and a span is active when a run starts, the SDK passes the W3C trace context (TRACEPARENT) to the CLI, so the CLI’s telemetry joins your trace. Enable the CLI’s exporter with its standard environment variables:
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(env={ "CLAUDE_CODE_ENABLE_TELEMETRY": "1", "OTEL_METRICS_EXPORTER": "otlp", "OTEL_LOGS_EXPORTER": "otlp", "OTEL_EXPORTER_OTLP_ENDPOINT": "http://otel-collector:4317", "CLAUDE_AGENT_SDK_CLIENT_APP": "orders-agent/1.4.0", # shows up in the User-Agent})What to alert on
Section titled “What to alert on”- error rate by
subtype/terminal_reason; - p95 cost and turns per run (a sudden rise usually means a prompt or tool regression);
RateLimitEvents in the stream;- tool error rate per tool.
Deployment
Section titled “Deployment”Container image
Section titled “Container image”The platform wheels bundle the CLI, so a slim Python image is enough. Run as a non-root user, and give the agent a dedicated working directory.
FROM python:3.12-slim
RUN useradd --create-home agent \ && apt-get update && apt-get install -y --no-install-recommends git ripgrep \ && rm -rf /var/lib/apt/lists/*
WORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txt # pins claude-agent-sdk==0.2.183
COPY --chown=agent:agent . .USER agentENV HOME=/home/agent PYTHONUNBUFFERED=1
EXPOSE 8000CMD ["uvicorn", "service:app", "--host", "0.0.0.0", "--port", "8000"]Session transcripts are written under $HOME/.claude/. Mount a volume there if sessions must survive restarts, or use a SessionStore (below).
A small HTTP service
Section titled “A small HTTP service”import uuidfrom fastapi import FastAPI, HTTPExceptionfrom pydantic import BaseModelfrom claude_agent_sdk import ClaudeAgentOptions, ResultError
app = FastAPI()
class Task(BaseModel): prompt: str session_id: str | None = None
@app.post("/run")async def run(task: Task) -> dict: options = ClaudeAgentOptions( model="claude-sonnet-5-5", cwd="/work", setting_sources=[], # do not read settings from the image allowed_tools=["Read", "Glob", "Grep"], max_turns=20, max_budget_usd=1.0, resume=task.session_id, ) try: result = await run_logged(task.prompt, options, request_id=str(uuid.uuid4())) except ResultError as e: raise HTTPException(status_code=502, detail={"subtype": e.subtype, "session": e.session_id}) return {"answer": result.result, "session_id": result.session_id, "cost_usd": result.total_cost_usd}
@app.get("/healthz")async def healthz() -> dict: return {"ok": True}(run_logged is the function from Observability.)
Kubernetes notes
Section titled “Kubernetes notes”- Requests and limits: size replicas by concurrent runs, not requests per second, and measure the memory of one run under your own workload before setting limits (each run is a separate CLI process).
- Put
ANTHROPIC_API_KEYin aSecretand expose it as an environment variable; never bake it into the image. - Use a
readOnlyRootFilesystemwith writableemptyDirvolumes for/workand$HOME. - Set
terminationGracePeriodSecondslonger than your longest expected run, and stop accepting work onSIGTERM.
Hosting patterns
Section titled “Hosting patterns”- One run per job. A worker takes a job, runs
query()in a fresh working directory, stores the result and session ID, and deletes the directory. Simple, and nothing needs to survive the container. - Ephemeral container per session. For untrusted code or per-customer isolation, start a container (or sandbox VM) for each session and destroy it afterwards. Configure a
session_storeso a later request can resume the session in a new container. - Long-lived conversations. A chat UI holds a
ClaudeSDKClientopen per active conversation. Keep conversations sticky to one worker while they are active, and fall back toresume=(backed by asession_store) when a worker restarts or the conversation moves.
Security
Section titled “Security”An agent with Bash and Write can do anything the process user can. Layer the controls:
- Least tool privilege. Start from
tools=[...]with only what the task needs. Pre-approve narrowly ("Bash(pytest:*)", not"Bash"). - Explicit permission mode. Use
"default"with acan_use_toolcallback, or"dontAsk"to deny anything not pre-approved. ReservebypassPermissionsfor disposable sandboxes. - Sandbox Bash.
sandbox={"enabled": True, "network": {"allowedDomains": [...]}}adds OS-level filesystem and network isolation. - Isolate settings.
setting_sources=[](or an explicit list) so a stray~/.claude/settings.jsonor a repository’s.claude/cannot change behaviour. - Treat inputs as untrusted. Content fetched from the web, files in a repository and tool results can contain prompt injection. Set
verbatim_prompts=Truewhen you inline untrusted text into prompts, so@pathexpansions and slash commands in that text are not acted on. - Hooks as a policy layer. A
PreToolUsehook that denies writes outside the working directory, or network commands, is easy to test and applies to subagents as well. - Secrets. Pass credentials through
env=or the process environment, not the prompt. DenyReadon.envand credential paths.
from claude_agent_sdk import ClaudeAgentOptions
hardened = ClaudeAgentOptions( cwd="/work/job-123", setting_sources=[], tools=["Read", "Glob", "Grep", "Edit", "Bash"], allowed_tools=["Read", "Glob", "Grep", "Bash(pytest:*)"], disallowed_tools=["WebFetch", "WebSearch", "Read(./.env)"], permission_mode="dontAsk", sandbox={"enabled": True, "network": {"allowedDomains": []}}, verbatim_prompts=True, max_turns=40, max_budget_usd=3.0,)Scaling
Section titled “Scaling”- Concurrency is processes. Bound it with an
asyncio.Semaphoreper worker and a queue (Celery, RQ, SQS, Pub/Sub) in front of the workers. - Rate limits are per organisation and model. Spread load across models where quality allows, and watch for
RateLimitEventin the stream. - Sessions across hosts.
session_store=mirrors transcripts to shared storage so any worker canresumea session. The comprehensive guide has a SQLite/Postgres adapter and its conformance test;InMemorySessionStoreis for tests. - Workspaces. Give each run its own directory (
cwd), and clean it up afterwards. Useadd_dirsfor read-only shared inputs.
Troubleshooting
Section titled “Troubleshooting”429s or RateLimitEvents. Reduce concurrency, add jittered back-off, move subagents to a different model, or request higher limits.
Context grows until runs slow down. Check await client.get_context_usage(); large tool results are the usual cause. Narrow tools (Grep with patterns rather than Read on whole directories), give reading-heavy work to subagents (each has its own context), and keep auto-compaction on.
Runs hang after a background subagent finishes. Fixed in 0.2.127 and 0.2.160; upgrade.
can_use_tool never fires. The tool is in allowed_tools, or the mode is bypassPermissions; both approve the call before the callback is reached, and the SDK emits CanUseToolShadowedWarning. PreToolUse hooks still run for pre-approved tools (hooks are checked first), so gate those calls with a hook rather than the callback.
Different behaviour between laptop and server. With setting_sources omitted, the CLI loads user, project and local settings, so ~/.claude/settings.json and CLAUDE.md differ between machines. Set setting_sources explicitly, or [].
Results vary run to run. Agents are not deterministic. Use output_format for machine-read results, pin the model ID, set effort explicitly, and test with assertions that tolerate wording changes.