Lesson 3.5
Agent SDK in Production
What the Claude Agent SDK gives you, how it differs from the API tool runner and Managed Agents, and the sandboxing, permission, cost and observability controls needed to run it as a service.
The Claude Agent SDK packages the Claude Code harness as a library for Python and TypeScript. You supply a prompt and options; it supplies the agent loop, built-in tools for files, shell, search and web, context management, subagents, hooks, permissions and sessions. It is the fastest route to a capable coding or operations agent, and also the easiest way to give a model a shell on a production host. This lesson covers running it responsibly.
Positioning
| Option | Harness | Tools | Deployment |
|---|---|---|---|
| Messages API tool runner | SDK loop over your tools | Only yours | You host |
| Agent SDK | Claude Code harness | Built-in file, shell, search and web tools plus MCP and yours | You host |
| Managed Agents | Anthropic's orchestration | Anthropic sandbox plus yours | Anthropic hosts |
Choose the Agent SDK when the task is filesystem- or shell-shaped, when you want the Claude Code behaviours (CLAUDE.md, skills, subagents) in a service, and when the compute must stay on your infrastructure. Choose Managed Agents when you want the loop and sandbox operated for you. Choose the plain tool runner when your tools are domain APIs and no shell is needed.
The core call
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(
system_prompt="...",
allowed_tools=["Read", "Grep", "Glob"],
permission_mode="default",
max_turns=40,
cwd="/work/repo",
)
async for message in query(prompt="Summarise the open TODOs", options=options):
handle(message)
Messages stream back as structured events: assistant turns, tool calls, results, and a final result with cost and usage. Options control the system prompt, the tool allowlist, permission behaviour, MCP servers, working directory, turn limits, model and session handling. Exact option names are in the SDK docs and differ slightly between Python and TypeScript.
Permissions
The harness has permission modes ranging from asking for every sensitive action to accepting edits automatically to bypassing checks entirely. In a service there is no human at a terminal, so decide explicitly:
- Use allow and deny rules to constrain tools and paths (for example, allow read tools everywhere, allow shell only for a fixed set of commands, deny secrets paths).
- Provide a permission callback that applies your policy programmatically and can escalate to a human approval queue for actions outside it.
- Never use the bypass mode outside an isolated, disposable sandbox with no credentials worth stealing.
Hooks as policy enforcement
Hooks run your code at lifecycle points: before and after tool use, on user prompt submission, on stop, on subagent completion, before compaction, at session start and end. In production they are the mechanism for:
- Blocking or rewriting dangerous commands before execution.
- Logging every tool call with inputs, outputs and timing to your observability stack.
- Injecting context (ticket details, environment facts) at session start.
- Enforcing budgets by stopping the session when a cost threshold is reached.
Hooks are deterministic code and therefore the right place for controls that must not depend on the model's cooperation.
Sandboxing and secrets
Run each agent in an isolated container or VM with a minimal filesystem, a non-privileged user, and network egress limited to what the task needs. Mount only the repository or data the task requires. Provide credentials through short-lived tokens injected by the orchestrator, never through files the agent can read and echo. Treat the container as disposable: destroy it after the run and keep only the artefacts you chose to export.
Cost and runaway control
Set a maximum number of turns and a budget per run. Record the cost reported in the final result against a job ID. Add a watchdog that kills sessions that exceed wall-clock limits. For fleets, cap concurrency to stay within rate limits and use workspaces to isolate the agent service's limits from interactive traffic.
Sessions, resume and state
Sessions can be resumed by ID, which allows a long task to survive a worker restart and allows a human to pick up where an agent paused. Persist session IDs with your job records. Decide what state survives: the conversation (resumable), the working directory (export artefacts explicitly), and any memory files the agent wrote (review before reuse).
Subagents and MCP
Subagents give parallelism and context isolation inside a run; define them with their own tools and prompts and keep their output contracts tight. MCP servers extend the tool set; in a service, configure them centrally and apply the same governance as any other MCP deployment, including per-server allowlists.
Observability
Emit structured events per run: start, each tool call, each subagent, compaction, stop, with the session ID and a job trace ID. Capture token usage and cost. Sample full transcripts for quality review and keep them under the same retention rules as any log containing customer data.
Exam focus
- The Agent SDK is the Claude Code harness as a library with built-in tools; you host it. It differs from the tool runner (your tools only) and Managed Agents (hosted by Anthropic).
- Permission modes and allow/deny rules are mandatory design decisions in headless use; bypass mode belongs only in disposable sandboxes.
- Hooks are deterministic enforcement points for blocking, logging, context injection and budgets.
- Sandboxing, minimal mounts, short-lived credentials and disposable containers are the baseline for production.
- Turn limits, budgets, watchdogs and concurrency caps bound cost and protect rate limits.
- Sessions resume by ID; persist IDs with job records and export artefacts deliberately.
Check yourself
5 questions
1.A team ships an internal automation built on the Claude Agent SDK. To avoid interactive prompts in production they run it with permission checks fully bypassed, on a shared server that also holds production credentials. A security review objects. Which configuration BEST balances automation and safety?
2.An Agent SDK application must never run destructive version-control or database commands, regardless of what the model decides. The team currently relies on a system prompt instruction. Which mechanism provides a deterministic guarantee?
3.An agent behaves well when a developer runs it locally with Claude Code, which reads the repository's project instructions file and project settings. When the same prompt is run through the Agent SDK in a container, the agent ignores the project conventions. What is the MOST likely cause?
4.A production agent occasionally enters a long loop retrying a failing approach, consuming a large amount of tokens before a human notices. Which combination of controls MOST effectively limits the blast radius?
5.An Agent SDK application needs the agent to call an internal pricing service with typed parameters. A developer proposes letting the agent run a shell command that invokes a command-line client for the service. Which design is MORE appropriate for production?