Claude Agent SDK: where agent logic breaks in production
An agent on Claude Agent SDK looks reliable in a demo: it calls a tool, gets a result, responds. In production on a stream of requests, the picture changes — it is not the model that breaks, but the agent layer around it: context management, call routing, session lifetime.
The most frequent failure is loss of dialogue context. When the conversation grows, the history goes beyond the model window, and the agent re-asks for data already provided or confuses the current request number with the previous one.
The client sees an inattentive operator, although the cause is in the history compaction strategy and in which facts remain in memory at all.
The second class is an incorrect tool call: the agent passes arguments to the record system that do not exist there, or selects the wrong method. The error does not fail immediately but surfaces in the data later, when the request has already moved further through the process.
The third is a hung agent session: an external service did not respond, no timeout is set, the task holds the worker and does not free the queue.
The fourth is duplicate actions: a retry after a network failure creates a second request or a repeated operation because the step was not made idempotent.
For the request processing process, this results in a growing queue, manual review, and loss of trust in automation. Below we analyze how each of these failures is closed at the level of the agent schema, and not with patches in the instruction.
Measurable effect: share of automatic responses and response time
First we fix the baseline: how many requests are currently closed without an operator, how long a typical request takes, and how often the dialogue breaks off. We compare all changes only with these values — otherwise “it got better” cannot be distinguished from a change in load. For production agents on Claude Agent SDK, we take these metrics before and after each release.
Speed and share of automatic responses
- Time to process a typical request decreases: the agent itself retrieves context from the request history and does not return the person to what has already been answered.
- The share of automatic responses grows due to scenarios where an operator was previously mandatory: a human is involved only on branches with ambiguous conditions.
- The failure class “agent is silent” disappears — each step has an explicit result, and unexpected input routes the dialogue to a fallback branch, not into silence.
Predictability under load and observability
- Under peak load, behavior does not change: the queue of requests is processed evenly, without “lucky or not.”
- Agent observability — for each request, the route, triggered steps, points of clarification requests, and the basis for the decision are visible.
- Regressions are caught on a test set of dialogues before rollout, so logic edits do not turn into a surprise in production.
Agent operating modes: interactive, batch, event-driven
Interactive, batch, and event-driven launches differ not only in the invocation method but also in how the agent receives context and when it returns the result. The choice of mode determines where an error can be caught at all.
| Option | When it fits | Limitations |
|---|---|---|
| Interactive | Dialogue with a client, request review, clarifying questions | Session is open, there is a context limit, a fast response is needed |
| Batch | Mass processing of similar records: documents, classification, data enrichment | There is no dialogue — an error cannot be corrected on the fly, a rerun is needed |
| Event-driven | Reaction to a change in an external system: request, email, status | Depends on the event source; on failure, a queue and retry are needed |
In all three modes, the same agent loop in Claude Agent SDK works — only the way the task is submitted and the stopping policy change.
Autonomy limitations
Autonomy is defined not by the mode but by boundaries: how many steps the agent takes without confirmation, which tools are available to it, and what it is not authorized to change.
We fix the step limit, a whitelist of actions, and mandatory confirmation for operations that change data in external systems. Exceeding the limit is not a failure but a signal: the task is formulated too broadly or there is not enough data.
Handing the dialogue to a human
Handing the dialogue to a human is a pre-designed rule, not an emergency scenario.
The agent hands over the dialogue when confidence is low, a question repeats, or a request comes that it is not authorized to confirm, and the operator receives a summary: what the user asked for, what the agent managed to do, and which step is not closed. Without such a summary, the handoff turns into a repeat review from scratch.
Stages of implementing the agent layer: from audit to handover
Implementation of the agent layer on Claude Agent SDK starts not with code but with an analysis of how the process is structured now.
At this step, we document operations, participants, data sources, and places where manual checks already exist — these become control points for the agent. The work proceeds in iterations, and each stage ends with an artifact that the customer can verify.
- Process and data audit. We analyze the task flow, input formats, result owners, and typical exceptions — the result is a list of operations that the agent can perform without risk.
- Tool call schema. We determine which functions are available to the agent, which parameters it fills in itself, and what comes from the system; deterministic checks remain in code, not in the model.
- Limits and access rights. The agent receives only the necessary visibility scopes, a step limit in the chain, and a prohibition on writing to critical systems without confirmation — this keeps the cost of an error low.
- Pilot launch on a limited flow. We enable the first version on part of the requests or on one channel, in parallel with the current manual loop, and compare the share of operations removed from humans.
- Failure testing. A separate stage: tool failure, empty or contradictory response, duplicate requests, retries, rollback. We look at how the agent degrades and what goes to manual review based on an individual calculationTransfer to support and team training. We hand over schemas, configurations, change regulations, and incident analysis; the customer's team learns to edit the agent's instructions itself and read its journal.
After handover, the agent lives as an ordinary service: with an owner, metrics, and a change procedure. This is the difference between a prototype that impresses in a demo and a solution that works stably in industrial operation.
Agent configurations, integration schemas, and escalation regulations
In production, the agent does not live on its own but inside a set of artifacts: configurations, schemas, and regulations.
We hand them over together with the working agent on Claude Agent SDK — the support team changes behavior and analyzes failures without reconstructing the logic from chat history.
- agent configuration — role, available tools, limits per step and number of iterations; stored in a shared repository and versioned together with the code;
- integration schema — a map of connections with systems and queues: call initiator, timeouts, behavior when a related system is unavailable;
- data access policies — which sources the agent reads, what is closed, where masking is triggered, and which data does not leave the perimeter;
- escalation regulation — conditions for stopping the agent and handing the dialogue to a human, the responsible person, and the response time;
- support documentation — how to bring up the environment, roll back a configuration, where to view logs and traces;
- set of checks — scenarios and failure branches that are run before rolling out a new version of the agent.
How to read the integration schema
The schema is read along the request flow: entry point, tool calls, response, writing to the customer's systems. Each edge is marked with whether it is a synchronous or deferred call, who is responsible for retry on error, and where the load limit is set.
What to do during changes
Before making an edit, one checks against the access policies and escalation regulation. Some changes affect only the agent configuration, while others require running checks and coordinating with the data owner.
Case: request processing by an agent — metrics before and after
Case — a service company with a stream of similar incoming requests: some requests require reconciling data across several record systems, others require a human decision.
The agent was built on Claude Agent SDK, with a set of tools described to it: reading the request, finding the client, exporting conditions, generating a response, and recording the result.
Initial situation
Before implementation, the operator reviewed the request: opened the card, reconciled data in two systems, and manually assembled the response. One request took 9–12 minutes, during peak hours the queue grew, and the first response to the client went out several hours later. Measurements showed that about 70% of requests are typical and do not require a human decision.
What changed in the metrics
The agent closes typical requests entirely — finds data, generates a response, and records the result in the record system. Only those with ambiguous conditions go to an operator.
The share of manual operations dropped to 20–25%, the average request review time — to two minutes, and the first response to the client goes out within a few minutes.
The load on operators shifted: instead of a stream of similar cards, they handle complex cases that require expertise.
The boundaries were set immediately: the agent does not make decisions on disputed charges and does not change contract terms — such requests go to a human with the full dialogue context.
How does Agent SDK differ from a custom agent loop?
A custom agent loop is your code: you implement tool calls, model error handling, generation interruption, streaming response delivery, and context usage accounting yourself.
Claude Agent SDK covers this layer with a ready runtime, so starting comes down to describing tools and rules, not reproducing the mechanics of the loop.
| Criterion | Custom loop | Claude Agent SDK |
|---|---|---|
| Time to production | weeks on the framework until the first scenario works | the loop works immediately, time goes to domain logic |
| Amount of your own code | all of it: loop, errors, state, retries | tools, prompts, and access rules |
| Control over logic | absolute, down to the order of steps | full within the boundaries of the loop, intervention through extension points |
| Support | grows with every new scenario and protocol change | runtime updates are handled by the vendor |
| Barrier to entry | requires an engineer who is confident with asynchronous code | sufficient command of the model and tool descriptions |
The boundary of responsibility is the same in both options: decision logic, the tool set, access rights, and domain error handling remain with you.
The difference is how much team resource is spent on the scaffolding instead of the task itself — and how quickly this scaffolding becomes outdated when the model changes.
Therefore, the choice more often rests not on technology but on the development mode: one agent with a non-standard protocol is cheaper to run with your own loop, several agents with shared scaffolding — on a ready runtime.
We discuss your scenarios on a call and name which option will give a smaller amount of code in support.
Common technical questions before starting a project
Starting the integration of the agent layer rests on five engineering questions, and the scope of work depends on the answers. Below is how we solve them in practice: the same solutions transfer to a project almost without changes.
How do you know that a task has actually been completed?
We fix the completion criterion before development begins: a set of validation scenarios, the expected result for each, and the acceptable deviation rate in a series of runs.
Acceptance is based on a repeatable test, not on one successful dialogue — this shows that the agent is stable, not lucky.
What do you do if the model passed incorrect call parameters?
The tool call schema is validated before execution: an incomplete or contradictory set of arguments does not go further but is returned to the agent with an error description for clarification.
The original attempt and the reason for rejection are written to the log, and no destructive actions occur on failed validation.
How is the agent's access to our systems limited?
The agent receives only the operations needed for the task and works under a separate service account with reduced rights. We limit the data scope with filters on the service side, not with an instruction in the request, and keep a log of every call indicating the initiator.
Can you connect to a running request system?
Yes, through its standard software interface. The first stage is read-only: the agent collects data and proposes actions without changing anything. Then we selectively enable write operations, one at a time, with result control. Your system is not restructured.
How do you roll back unsuccessful changes?
Agent configurations, tool descriptions, and prompts are versioned like code. There is a kill switch for instant shutdown and switching to the previous version — rollback takes minutes, not hours. Writes to your systems go with a request key, so a rerun does not create duplicates.
Let's discuss the task: what to send for assessment and a work plan
Assessment and work plan rely on how the process is structured now, not on a general description of the task. One email with the inputs is enough — and we will return not with clarifying questions but with stages, timelines, and a list of risks.
- Process schema: steps from the appearance of a request to the result, who makes the decision at each step, and where time is currently lost.
- 20–50 examples of real requests — including atypical ones and those that are currently handled manually despite the regulation.
- Available systems and data: where knowledge is stored, in what form it is exported, whether there is a test environment and an anonymized copy.
- Autonomy boundaries: which actions the agent performs itself, and where human confirmation is mandatory.
- Project constraints: deadlines, data placement requirements, access policy, security approvals.
- Customer's team composition: who is responsible for the process, who issues access, who accepts the result by stages.
- Current metrics: share of manual operations, response time, error criticality — so that after launch there is something to compare against.
If some data is closed or access takes a long time, this does not block the start: we will analyze what is available and clarify the rest as the work proceeds. Describe the task and attach what you have — we will return with an assessment and a work plan.