The Claude Agent SDK in production

The Claude Agent SDK removes the part of agent building that used to eat the first week. The loop, tool schemas, session handling, and context management are handled. You can have something impressive running before lunch.

Which is exactly why so many teams ship the impressive thing and then discover the second job. Production agents fail in ways demos cannot show you, and almost all of that failure lives outside the model call. Here is what I have learned putting SDK-based agents in front of real traffic.

Tool design is the actual product

An agent is only as good as the tools you hand it, and tool quality is mostly about narrowness. Every time I have had an agent behave erratically, the root cause was a tool that was too general.

A tool called query_database that takes arbitrary SQL will eventually be handed something creative. A tool called get_invoice_by_number that takes one string cannot be. The second tool also produces better decisions, because the name tells the model what it is for.

• One tool, one job. If the description needs the word "or", split it.
• Return structured data with a stable shape, not prose. Include an explicit status field so failures are legible.
• Make error returns instructive. not_found plus a hint about what identifiers are valid stops a retry spiral.
• Cap result size. A tool that can return 200 rows will fill the context window and the agent will forget the task.

Permissions belong in the runtime, not the prompt

This is the single most common production mistake I see. The system prompt says never to delete records, and for a while it does not delete records. Then an ambiguous instruction, a poisoned document, or a long session pushes it across the line.

Instructions are guidance. Capability is the control. If the agent's credential cannot delete, no phrasing can make it delete. That is the whole security model, and it is the same argument I make in detail in prompt injection is not a prompt problem.

1. Give each agent its own service credential, scoped to its tools.
2. Run any code execution or file work in a sandbox with no network egress by default.
3. Put irreversible operations behind an approval queue that a person clears, or behind a signed token issued per task.
4. Log every tool call with arguments and outcome. This is your audit trail and, later, your eval dataset.

Loops, budgets, and the circuit breaker

Agents do not crash. They spin. The failure mode is a run that keeps calling the same tool with slightly different arguments, burning tokens and doing nothing, until someone notices the bill.

Three cheap guards eliminate nearly all of it:

• Max turns. Hard ceiling on iterations per run. Pick a number, then look at your traces and lower it.
• Token budget per run. Track cumulative spend inside the loop and abort with a clear terminal state when you cross it.
• Repeat detection. Hash tool name plus arguments. Two identical calls in a row is a bug, not a strategy. Break the loop and return a partial result.

Aborting is not failure. A run that stops at 70 percent with a clear reason is far more useful than one that finishes wrong or never finishes at all.

Idempotency, because runs will be retried

Any agent wired to a queue or a webhook will eventually process the same job twice. If its write tools are not idempotent, that means duplicate emails, duplicate invoices, duplicate refunds.

The fix is unglamorous and non-negotiable: derive a stable key from the job, pass it to every write tool, and make the underlying operation an upsert or a no-op on a repeated key. I have never regretted building this early. I have twice regretted building it late.

Cost is a context problem

Nearly all agent spend is input tokens, and most input tokens are the same content sent over and over: system prompt, tool definitions, reference material, conversation history.

• Cache the stable prefix. System prompt and tool schemas are identical across runs, so they should not be paid for at full price on every turn.
• Summarize history past a threshold instead of carrying raw turns forever.
• Route by difficulty. Classification and routing do not need your best model. Extraction and drafting do.

The mechanics of that, with the ordering that actually matters, are in prompt caching, and the rest of the bill.

The agent did nothing wrong. It used the tool exactly as written. The tool should not have existed in that shape.

Evals, or you are flying blind

Model versions change. Your prompts change. Your tools change. Without a suite of real cases with known outcomes, you cannot tell an improvement from a regression, and you will find out from a customer instead.

Build the suite from your own trace logs, which is why logging tool calls from day one pays off twice. Fifty real cases beat a thousand synthetic ones. The full approach is in LLM evals that actually catch regressions, and the logging spec is in AI agent observability.

The short version

The SDK gives you the agent. You still have to build the system: narrow tools, runtime permissions, sandboxing, loop guards, idempotent writes, cost caps, traces, and evals. That is two weeks of unglamorous work on top of an afternoon of exciting work, and it is the entire difference between a demo and something you can charge for.

If you have an agent that works in testing and misbehaves in production, the AI production readiness audit is designed exactly for that gap. If you want one built properly, see custom AI agent development. Still deciding what to build on, read choosing an AI agent framework in 2026 first.

Frequently asked