Claude Agent SDK: Production Patterns Guide 2026

The Five Patterns Production Teaches You

Every agent we have shipped to production has surfaced the same five missing pieces, in roughly the same order. The list is short because the failure modes cluster: almost every production incident we have seen traces back to a gap in one of these five categories.

Pattern 1: Durable State Persistence

The SDK holds conversation history, pending tool calls, and intermediate reasoning in memory. That is convenient for local development and demos. In production, the moment you deploy behind a serverless function, a horizontally scaled service, or a resumable task queue, the in-memory assumption breaks.

The rule we enforce with every client is: the conversation log is the source of truth, the SDK session is ephemeral. That means every turn's messages, tool calls, and tool results go to durable storage before the next model call. Postgres works well for small-to-medium agents with moderate concurrency; Redis is a good fit for short-lived interactive sessions with strict latency budgets; object storage handles long-running background tasks with many large tool results.

What Needs to Persist

• Full message history including system prompt, user messages, assistant messages, and every tool call and tool result.
• Tool use IDs and order — the SDK is strict about matching tool_use and tool_result blocks; partial persistence corrupts the next turn.
• Running cost counters so cost caps survive resumption.
• Task state metadata — current goal, sub-task progress, and any agent-generated plan so a resumed session continues the existing plan rather than re-planning from scratch.
• Permission scope granted to this session so the agent cannot escalate by restarting.

Resumption Is a Product Feature

Once state is durable, resumption becomes free. A user who closed the tab mid-task can return hours later and pick up where the agent left off. A long-running background task that crashed can restart from the last persisted turn. The pattern also unlocks handoff scenarios: one agent starts a task, another finishes it, and the conversation log is the contract between them. See our guide on multi-agent orchestration patterns for the producer-consumer shapes that rely on this.

Pattern 2: Hard Cost Caps

A runaway agent can burn through a full month's budget in an hour. The fix is not a monthly spending alert; it is hard caps enforced inside the agent harness, checked before every model call, with clean termination and useful error messages when a cap trips.

We run every production agent with three tiers of cap, each checked on the inbound request:

Implementation Sketch

Every model call is wrapped by a small harness that reads current spend counters, compares them to the applicable caps, and either proceeds or raises a typed CostCapExceeded exception. Spend is recorded after each response using the usage object the Claude API returns.

async function callAgent(session, input) {
  const spend = await getSpend(session);
  if (spend.task >= CAPS.perTask) throw new CostCapExceeded("task");
  if (spend.user >= CAPS.perUser) throw new CostCapExceeded("user");
  if (spend.tenant >= CAPS.perTenant) throw new CostCapExceeded("tenant");

  const response = await claude.messages.create({ /* ... */ });

  await recordSpend(session, response.usage);
  return response;
}

Keep the spend ledger in the same durable store as session state. Caps enforced against stale counters are caps you can race past.

Pattern 3: Circuit Breakers for Runaway Loops

Cost caps end runaway loops eventually. Circuit breakers end them fast. The difference matters: a tight loop at high effort can spend hundreds of dollars before tripping a generous per-task cap. Circuit breakers catch the pathology before it scales.

Iteration Limits

A hard numeric ceiling on agent iterations in a single task — we default to 25 — covers the common case where the model keeps calling tools without making progress. Pick the default by looking at your traces: if legitimate tasks routinely need more than 20 turns, raise the cap; if they rarely pass 10, lower it. The goal is a ceiling tight enough to catch pathology but loose enough to avoid false trips.

Repetition Detection

Numeric iteration caps miss the most expensive failure mode: a model that loops on the same tool call with minor argument variations. A simple detector — hash the last N tool calls by name and canonicalized arguments, trip when any hash appears three times — catches this cheaply. When it fires, persist state, return a structured error to the caller, and alert the on-call channel.

Stop Conditions and Explicit Done Signals

The cleanest circuit breaker is the agent itself deciding it is done. Prompt the agent to emit a structured completion signal — a specific tool call, a sentinel string, or an end_task marker — and treat its absence after the iteration cap as a failure. This turns a vague "did the agent finish?" question into a deterministic check the harness can make.

Pattern 4: Tool Permissioning with Least Privilege

Every tool the agent can reach is a surface area for prompt injection and mis-scoped actions. Least-privilege tool permissioning is the same principle applied to agents that SREs already apply to service accounts: grant the smallest capability set that does the job, scope it per session, and log every call.

Scope Tools Per Session

The set of tools passed to the SDK should reflect the current session's task and tenant, not the union of every capability the system supports. A billing-support agent does not need a filesystem write tool. A code-review agent does not need a payments API tool. The session builder composes the allowed tool list based on the task type, tenant permissions, and user role before the SDK is called.

Tool-Level Allow-Lists

For tools that accept open-ended arguments — a shell executor, an HTTP fetcher, a database query runner — add an allow-list inside the tool implementation that rejects prohibited commands, domains, or SQL patterns before executing. The SDK is the wrong place to enforce this; your tool wrapper is the right one. The Claude Code auto-mode permissions guide shows the pattern in detail for the autonomous coding case.

Defend Against Prompt Injection

Any tool result that flows back into the conversation is untrusted input. Fetched web pages, database rows, file contents, and user messages can all contain injected instructions. The three-layer defense is: scope tools so a successful injection cannot do catastrophic damage, run an evaluation hook on every turn that flags suspicious tool-call sequences, and never interpolate tool results directly into the system prompt. Full taxonomy in our prompt injection taxonomy.

Pattern 5: Structured Evaluation Hooks

Offline evals catch regressions before you ship. Online evaluation hooks catch drift, prompt injection, and hallucinated tool calls in production. A production agent needs both, running on the same eval definitions so the signal is comparable.

Offline Evaluation Suite

The offline suite runs on every pull request that changes prompts, tool schemas, model versions, or agent orchestration code. It covers happy-path tasks, known-hard tasks from production incidents, and adversarial inputs designed to probe prompt injection and tool misuse. Scoring can be a mix of exact-match checks for deterministic outputs, LLM-judge scoring for open-ended tasks, and task-specific graders.

Online Evaluation on Every Turn

Online evaluation hooks run lightweight checks after every production turn. They do not block the response — that would add latency users feel — but they write scores and flags to an observability pipeline for dashboards and alerting. Useful signals include: tool-call validity (did the model call a tool that exists, with valid arguments?), trajectory coherence (do the last N turns look like progress toward the task goal?), and injection heuristics (does a tool result contain instruction-like text that matches known injection patterns?).

Wire In Traces From Day One

Every turn emits a structured trace with the model input, tool calls, tool results, and eval scores. Traces plus spend ledger plus audit log are the three data sources that make agent incidents debuggable. Our agent observability guide covers the full stack.

Reference Deployment: Vercel Functions

Vercel Functions are the fastest path to shipping an Agent SDK workload when the agent fits inside the function duration tier and the product shape is interactive. Fluid Compute plus the longer duration tiers cover most conversational agents and short-running task agents without the operational overhead of managing long-lived workers.

Shape the Architecture Around Stateless Turns

Each function invocation loads session state, runs one agent turn (or a small handful of turns), persists state, and returns. The browser client holds the session ID and reconnects for the next turn. For long tool chains that exceed a single invocation, checkpoint between tool calls and return early with a continuation token. This keeps each invocation well inside the duration limit and makes resumption free.

Reference Deployment: AWS Lambda and Fargate

For teams already on AWS, the Agent SDK runs comfortably on Lambda for short-running turns and on Fargate for medium-length tasks that exceed Lambda's ceiling. The split between the two is usually duration and memory: Lambda for interactive turns, Fargate for background tasks that can run 10 to 60 minutes.

Lambda Specifics

• 15-minute ceiling is the hard limit; keep tasks well inside it with checkpoint-and-resume between tool calls.
• Memory tuning matters — allocate at least 1 GB for SDK overhead plus room for tool results and streaming buffers.
• Provisioned concurrency for latency-sensitive endpoints; cold starts on the Anthropic SDK import are noticeable.

Fargate Specifics

• SQS-driven workers consume tasks, run the full agent loop, persist state, and acknowledge the message only on clean completion or final failure.
• Graceful shutdown on task termination — catch SIGTERM, persist the current turn, and let the task scheduler resume on another worker.
• Autoscaling on queue depth rather than CPU, since the agent workload is API-bound.

Reference Deployment: Long-Running Container Worker

For agents that legitimately run for hours — deep research agents, multi-step refactors, long-horizon autonomous workflows — a dedicated container worker is the right shape. The SDK is happy inside any orchestrator: Kubernetes, ECS, Nomad, or a bare VM with a process manager.

When to Pick This Shape

The deciding factor is whether the agent's task duration and memory footprint comfortably fit a function-shaped runtime. If a single task routinely runs longer than the function ceiling, spawns many subagents, or accumulates large tool result buffers, pay the operational cost of running workers rather than contorting the agent to fit a function. Our enterprise agent platform reference architecture walks through the full queue-plus-worker topology for teams committing to this shape at scale.

For teams evaluating orchestration frameworks on top of the SDK — LangGraph, CrewAI, OpenAI Agents — our agent SDK comparison matrix maps each framework's assumptions against the Claude Agent SDK's primitives.

Digital Applied Operational Playbook

The checklist below is what we hand every client on day one of an Agent SDK rollout. It condenses the five patterns into actions ordered by the order in which their absence will hurt you in production.

For clients integrating agents into existing CRM and pipeline automation, our CRM automation practice pairs the SDK rollout with the downstream integrations, and our web development team builds the interactive surfaces that wrap the agent.

Conclusion

The Claude Agent SDK is deliberately minimal. It gives you the primitives to build a production agent without locking you into anyone's opinion about state, cost, or observability. The flip side is that the five patterns above are table stakes for any production rollout, and skipping them is the most reliable way to ship an agent that works in staging and fails expensively under real traffic.

Treat durable state, hard cost caps, circuit breakers, tool permissioning, and evaluation hooks as non-negotiable. Pick the deployment shape that fits the agent's runtime profile, not the other way around. And wire observability from day one — by the time an agent is in production, you want the traces, the spend ledger, and the audit log already flowing.

Frequently Asked Questions