Skip to content
ClPy

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.


  1. Resilience
  2. Cost control
  3. Observability
  4. Deployment
  5. Security
  6. Scaling
  7. Troubleshooting

FailureHow 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 reacheda ResultMessage with subtype "error_max_turns" / "error_max_budget_usd", then ResultError
CLI missingCLINotFoundError before anything runs
CLI crashed without a resultProcessError with exit_code and stderr
Garbled output lineCLIJSONDecodeError

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.

import asyncio
import random
from 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.

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 asyncio
from 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))

fallback_model="claude-sonnet-5-5" lets the CLI switch models when the primary is overloaded, rather than failing the 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.

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.)

In rough order of impact:

  1. 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.
  2. Use cheaper models for subagents. Give AgentDefinition(model="sonnet") or "haiku" to reading-heavy or routine subagents and keep the main loop on claude-opus-5-5.
  3. 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.
  4. Trim the tool set. Fewer tools means a smaller prompt; tools=[] for pure text tasks.
  5. Cap turns. Many runaway costs are loops; max_turns is 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})

Log one line per tool call and one per result. Everything you need is on the messages:

import json
import logging
import time
from 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 result

Pass stderr=lambda line: log.debug("cli: %s", line) in the options to capture the CLI’s own diagnostics.

Logging in hooks catches tool calls made by subagents too, and runs before permission decisions. See Recipe 13.

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
})
  • 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.

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 /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt # pins claude-agent-sdk==0.2.183
COPY --chown=agent:agent . .
USER agent
ENV HOME=/home/agent PYTHONUNBUFFERED=1
EXPOSE 8000
CMD ["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).

service.py
import uuid
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from 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.)

  • 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_KEY in a Secret and expose it as an environment variable; never bake it into the image.
  • Use a readOnlyRootFilesystem with writable emptyDir volumes for /work and $HOME.
  • Set terminationGracePeriodSeconds longer than your longest expected run, and stop accepting work on SIGTERM.
  • 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_store so a later request can resume the session in a new container.
  • Long-lived conversations. A chat UI holds a ClaudeSDKClient open per active conversation. Keep conversations sticky to one worker while they are active, and fall back to resume= (backed by a session_store) when a worker restarts or the conversation moves.

An agent with Bash and Write can do anything the process user can. Layer the controls:

  1. Least tool privilege. Start from tools=[...] with only what the task needs. Pre-approve narrowly ("Bash(pytest:*)", not "Bash").
  2. Explicit permission mode. Use "default" with a can_use_tool callback, or "dontAsk" to deny anything not pre-approved. Reserve bypassPermissions for disposable sandboxes.
  3. Sandbox Bash. sandbox={"enabled": True, "network": {"allowedDomains": [...]}} adds OS-level filesystem and network isolation.
  4. Isolate settings. setting_sources=[] (or an explicit list) so a stray ~/.claude/settings.json or a repository’s .claude/ cannot change behaviour.
  5. Treat inputs as untrusted. Content fetched from the web, files in a repository and tool results can contain prompt injection. Set verbatim_prompts=True when you inline untrusted text into prompts, so @path expansions and slash commands in that text are not acted on.
  6. Hooks as a policy layer. A PreToolUse hook that denies writes outside the working directory, or network commands, is easy to test and applies to subagents as well.
  7. Secrets. Pass credentials through env= or the process environment, not the prompt. Deny Read on .env and 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,
)

  • Concurrency is processes. Bound it with an asyncio.Semaphore per 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 RateLimitEvent in the stream.
  • Sessions across hosts. session_store= mirrors transcripts to shared storage so any worker can resume a session. The comprehensive guide has a SQLite/Postgres adapter and its conformance test; InMemorySessionStore is for tests.
  • Workspaces. Give each run its own directory (cwd), and clean it up afterwards. Use add_dirs for read-only shared inputs.

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.