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. A working agent loop still needs application-level review before launch.

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. This guide covers the application controls to inspect around the SDK.

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. A broad tool can leave the model deciding behavior that should have been constrained by the application.

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

Check whether permissions are enforced by the runtime or only requested in the prompt. 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.

Test these three guards against repeated-call failures:

• 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. Test repeated delivery before enabling external writes.

Cost is a context problem

Check input-token spend for repeated content: 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. Include observed failures and use synthetic cases to cover important gaps; compare what each set tests. 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. Include those controls in the implementation scope and verify them before relying on the agent.

A working agent loop still needs review of the application around it. If you have a stalled product build that has to work for a real customer, pilot, or launch, send the project brief. Scope and price are agreed before work starts.

Frequently asked