DEV Community

Eldar Muratov
Eldar Muratov

Posted on Edited on

AI Agents in Production for Newbies: Tools, RAG, Reliability and Evals

An agent solves a task in 30 steps: it calls the model, searches, writes to the database, calls the model again. Say each step fails once in a hundred times: the network blinked, the API answered "overloaded". Then the whole task gets to the end 74% of the time. One task in four fails. At 3% failures per step, only 40% get to the end.


A back-of-the-envelope calculation: step failures are independent and transient.

In a demo the agent gets through 10 steps out of 10. In production it runs thousands of tasks, and everything surfaces at once. The model mixes up tools, the context is full of junk, search doesn't find what's needed. The process crashes halfway, and a prompt tweak breaks something that used to work.

This is the second part of a series. In the first we looked at how the agent loop works and what it costs. This one collects the practices that separate a demo from production: tools, context, RAG, loop control, reliability, observability, evals and security. Reliability takes up the most space. Almost all of it is familiar from backend work, but an agent has a sharper trap than usual. What hurts is not the crash but the repeat.

TL;DR

  • Fewer tools, but bigger ones. Short responses, and errors written so the model can fix them.
  • Keep only what's needed in the context: load things as you go, compress the history, hand big chunks to subagents.
  • A knowledge base under 200,000 tokens fits into the prompt whole. If it's bigger, search by meaning and by keywords and rerank: at Anthropic this cut retrieval failures from 5.7% to 1.9%.
  • Start with a chain, not an agent. Give an agent a turn limit, a dollar budget and a plan B: a stuck agent at 100 turns costs 5.3 times as much as a normal task.
  • Retry transient errors and only idempotent actions. Keep progress outside the process (Temporal and similar), and write sagas for rollback.
  • Put sending, payments and deletion behind a human approval. Keep the wait for the answer in Temporal, not in process memory.
  • Write a trace of every step and count the cost of a successful task, not of one call. Run evals on every prompt change.
  • Don't give an agent private data, untrusted content and a way out all at once.

Tools: fewer, but bigger

All the model knows about a tool is its name, description, parameter schema and what it returned. From these it decides what to call and with which parameters. That's why a tool for an agent is written differently from an API for a programmer. Anthropic collected the rules in Writing effective tools for agents.

Don't make one tool per endpoint. Instead of list_users, list_events and create_event, one schedule_event that finds a free slot and creates the meeting by itself is better. The model makes one call instead of three, and no extra lists end up in the context. The more similar tools there are, the easier it is for the model to mix them up.

Keep tool responses short. Return names, not internal uuids. Cut long lists with pagination and filters. A response format parameter helps. In Anthropic's example, a Slack tool in concise mode returned 72 tokens instead of 206. Claude Code truncates any tool's response to 25,000 tokens by default. And every token of a response goes into the history and, as we calculated in part 1, gets paid for again on every following turn.

A tool writes its errors for the model too. A traceback or a bare 400 code tells it nothing. A message like "the date must be in 2026-11-09 format, got 09.11" is something the model will fix on its own on the next turn. And name parameters unambiguously: user_id is clearer than user.

A tool call is structured model output: JSON that follows a schema. Validate it against the schema before running it, like any user input.

Context: fewer tokens, more signal

The context window is finite, and the fuller it gets, the worse the model works with each token. Anthropic's article on context engineering puts the goal like this: find the smallest set of tokens that helps the most with the task. In part 1 we calculated what an extra token costs. But extra tokens also get in the way of the model's thinking.

Three techniques help. The first is loading as you go. Don't put everything into the prompt up front. Keep references in it (file paths, document ids) and give the agent a tool that loads what's needed. That's how Claude Code works: CLAUDE.md is in the context from the start, and the agent finds the rest through glob and grep.

The second is compaction. When the history has grown, it gets summarized. In Claude Code, compaction keeps decisions, open bugs and implementation details, and throws out old tool responses. The third is notes. The agent keeps a file like NOTES.md outside the context and rereads it when needed.

For big tasks there are subagents. Each one works through its part in its own context and returns a summary of 1–2 thousand tokens. The main agent sees conclusions, not hundreds of pages of search results.

RAG and search

RAG (retrieval-augmented generation) means finding the right pieces of knowledge before answering and putting them into the context. First decide whether you need it at all. Anthropic gives a threshold. If the knowledge base is under 200,000 tokens (about 500 pages), you can put the whole thing into the prompt and cache it. No search needed.

If the base is bigger, the classic setup goes like this. Documents are cut into chunks of a few hundred tokens. Each chunk is turned into an embedding, a vector of meaning, and stored in a vector database. For a question, the nearest chunks are found and handed to the model. But a cut-out chunk loses its context. The sentence "revenue grew 3% over the previous quarter" is useless without the company name and the quarter.

What helps, per Anthropic's measurements in Contextual Retrieval:

  • Search by meaning is combined with keyword search (BM25). Embeddings catch meaning well but can miss an exact string like the error code TS-999.
  • Before indexing, the model adds 50–100 tokens of context to each chunk: which document it's from and what it's about. With prompt caching, this costs about a dollar per million document tokens.
  • The results are reranked by a separate model, and the model gets the top 20 chunks.


Anthropic's measurement on their datasets. A failure means the right chunk didn't make the top 20.

Test retrieval separately from the answer. If the answer is bad, you need to know who's at fault: search didn't find the right chunk, or the model used it badly. Build a set of questions where you know where the answer lives, and count how often the right chunk lands in the results. That's the metric Anthropic used to measure its 5.7% and 1.9%.

You don't always need an index. Early versions of Claude Code ran on RAG with a local vector database. The team switched to agentic search: the model finds files by itself through glob and grep. According to Boris Cherny, this works better and gets rid of the problems with a stale index, privacy and security. But that's experience with code, where text has names and structure. For a base of documents in plain language, classic RAG still makes sense, and opinions differ here.

Keeping the loop and the money under control

Agents often get built where a chain would have been enough. In Building effective agents, Anthropic advises starting with the simplest solution. Often one model call with retrieval and examples is enough. An agent picks its own steps and pays for that in latency and money. 12-Factor Agents puts it more bluntly: most agents in production are mostly ordinary code, with the model called at a few points. It also advises building small agents of 3–10 steps.

If you do need an agent, put limits on it. The main reason is money. Every turn rereads the whole history, so the cost grows faster than the number of turns. The task from part 1 costs $0.51 for 30 turns. An agent that got stuck and made 100 turns costs $2.68. That's 3.3 times the turns and 5.3 times the money. On the last turn it reads almost 300,000 tokens.


A back-of-the-envelope calculation for the part 1 scenario: Sonnet 5.5, caching, +2,900 tokens per turn.

There are three limiters:

  • A turn limit. In the OpenAI Agents SDK the default is 10 turns, after which it raises MaxTurnsExceeded. The Claude Agent SDK has no default limit; you set one with the max_turns parameter.
  • A dollar budget. In the Claude Agent SDK it's max_budget_usd: when the spend estimate reaches the threshold, the task stops with error_max_budget_usd. The estimate is computed on the client and can overshoot the threshold a little, so the docs advise leaving some margin.
  • A timeout on the whole task, not just on a single call.

Take the values from real tasks: look at how many turns and how much money a normal one uses, and add a margin. OWASP's risk list has unbounded resource consumption as a separate item.

Return a tool error to the model as a result instead of crashing the loop. The model will often fix the parameters itself or take another route. In Anthropic's experience this works surprisingly well. But count consecutive errors: if the model keeps repeating the same failed call over and over, stop.

And decide up front where a task goes when it runs out of attempts, turns or budget. The options: a fallback model or provider, a simple chain without an agent, a human.

Reliability: why an agent breaks more often than a regular service

A regular backend request makes one or two external calls. An agent lives longer and calls more. The loop in part 1 had 30 turns, and almost every one had two calls: the model and a tool. Anthropic writes about this in its article on its research system: agents run for a long time and keep state across many calls. A minor failure that a service would just return to the user can derail an agent's whole task.

The model call itself is unreliable too. The Claude API answers with errors like any external service:

  • 429: you hit a limit;
  • 529: the API is overloaded by overall traffic;
  • 500: an internal error;
  • 504: the request timed out.

It gets trickier. With streaming, an error can arrive in the middle of the response, after the server has already returned 200.

The third reason is that an agent has state. Surviving an error isn't enough; you have to not lose what's been done. Anthropic rejected restarting from scratch because it's expensive and frustrates users. Their agents resume from where the error happened.

Retries: what to repeat and what not to

Only transient failures are worth retrying. A permanent error comes back the same on a retry.


Per Anthropic's docs as of 2026-11-02.

There's a subtlety with 429. Usually it's a per-minute limit, and the response has a retry-after header: how many seconds to wait. But 429 also comes when the monthly spend cap is exhausted. That response has no retry-after, and the error body has the code enforced_spend_limit_reached. Retrying is pointless until next month. A retry that can't tell the difference will hammer the API for hours.

The pause between attempts should grow. Otherwise retries just add load to an API that's already overloaded. Usually the pause doubles: 1, 2, 4, 8 seconds and on up to a ceiling. That's how Temporal works by default (more on it below): it starts at one second, with a multiplier of 2 and a ceiling of 100 seconds. Ten retries take about seven minutes.

The official Anthropic SDK already retries transient failures by itself: twice by default, with a growing pause and respecting retry-after. For a single call that's enough. For a 30-step agent, you decide: how many attempts per step, and what to do when they run out.

# Pseudocode: retrying a model call
TRANSIENT = {429, 500, 504, 529}

def call_model(request, attempts=5):
    pause = 1
    for attempt in range(attempts):
        response = api.messages(request)
        if response.ok:
            return response
        if response.code not in TRANSIENT or is_429_without_retry_after(response):
            raise PermanentError(response)       # fix it, don't retry it
        sleep(response.retry_after or pause)
        pause = min(pause * 2, 100)
    raise OutOfAttempts()
Enter fullscreen mode Exit fullscreen mode

The calculation at the start of the article has a weak spot: failures aren't always independent. If the provider is down entirely, three quick retries won't help. You need a longer pause or a fallback provider.

One more link to part 1. Claude API limits are counted in tokens per minute. For most models, cached tokens don't count toward the input limit. The docs give an example. With a limit of 2 million tokens per minute and an 80% cache hit rate, you can process 10 million. Caching cuts both the bill and the number of 429 errors.

The main danger: repeating an action

Take a send_email tool. The email went out, but the response got lost on the way. The harness retries the call, and the customer gets a second email. With charge_card, the money gets charged twice. Retries save you from failures, but they cause errors of their own when an action can't be safely repeated.


The same failure without an idempotency key and with one.

The property "a repeat doesn't change the result" is called idempotency. A read is idempotent by itself. An action with consequences is made idempotent with a key. That's how the Stripe API works. The client creates a unique key and sends it with the request. The server remembers the response to the first request with that key. On a repeat, it returns the saved response and doesn't run the operation a second time. If the key is the same but the parameters differ, Stripe returns an error.

For an agent, the key already exists. Every tool call comes from the model with its own id, and it doesn't change on a retry. My advice, not a rule from the docs: pass this id as the idempotency key into the tool and on into the external system.

# Pseudocode: an idempotent tool
def send_email(to, text, key):
    if already_done(key):                 # this call has already run
        return saved_result(key)
    result = mail.send(to, text, idempotency_key=key)
    save(key, result)
    return result

send_email(email.to, email.text, key=call.id)
Enter fullscreen mode Exit fullscreen mode

This check has a hole. If the process crashes between sending the email and the save line, it won't catch the duplicate. It's most reliable when the external system itself understands the key, like Stripe. If it doesn't, it's better to hand that action to a human for approval.

Durable execution and Temporal: not losing what's done

A retry saves one step. But if the agent's process itself crashes, there's nothing to retry. The history, the step number and the tool results were in memory and they're gone. Progress has to be kept outside the process. This approach is called durable execution. I'll walk through it with Temporal.

In Temporal, code is split into two parts. A workflow is the logic: the agent loop, branches, waits. Activities are everything that touches the outside world: an API call, a database write, an email, a charge. Every event is written to a history. If a worker crashes, another one takes the history, replays the workflow code and continues from where it crashed. Finished steps don't run a second time: their results come from the history.


On recovery, steps 1–3 don't run again: their results come from the history.

This leads to two requirements. Workflow code must be deterministic, since Temporal replays it. Random numbers, the current time and network requests live only in activities. And activities must be idempotent: the step where everything crashed will be run again. By default, Temporal retries activities with no limit on the number of attempts.

An agent fits this scheme naturally. The loop lives in the workflow. The model call and every tool call become activities with their own retry policy.

# Pseudocode: the agent loop as a workflow
@workflow
def agent(task):
    history = [task]
    while True:
        response = activity(call_model, history, retries=model_policy)
        history.append(response)
        if response.stop_reason != "tool_use":
            return response
        for call in response.calls:
            result = activity(run_tool, call, key=call.id)
            history.append(result)
Enter fullscreen mode Exit fullscreen mode

Now the cost. The loop from part 1 with caching costs $0.51. If the process crashed on turn 25 and the task was started from scratch, it comes to $0.93, 81% more.


A back-of-the-envelope calculation for the part 1 scenario: 30 turns, Sonnet 5.5, caching.

The money is the lesser problem. On a restart, the 25 actions already done run again, and each non-idempotent one produces a duplicate.

A large tech company went through this in production. Its research agent, built into its AI assistant, works for up to 20 minutes and goes through dozens of websites. In the first version, state was kept locally: the process crashed, and everything started over, along with the tokens already burned. The team moved to Temporal to recover from the history. And it immediately ran into what the previous section is about: Temporal can run an activity again, so side effects have to be idempotent.

Temporal isn't the only option. LangGraph has its own mechanism: it saves state at every step and, after a crash, continues from the last checkpoint. There are other engines too: Restate, DBOS, Inngest. I haven't compared them. And keep in mind that most of the writing about durable execution for agents comes from the engine authors themselves, Temporal included.

Sagas: rolling back what's already done

Durable execution gets a process to the end, even if it crashed along the way. But the end can be a failure. The agent booked a hotel, bought a ticket, and then the card was declined at payment. There's no shared transaction across the hotel, the airline and the bank. You can't undo it all with one ROLLBACK.

That's what a saga is for. Garcia-Molina and Salem described the pattern back in 1987. A long process is split into steps, and each one gets a compensation written in advance. If something breaks, the system undoes what's been done in reverse order. A compensation doesn't erase history. It undoes the operation in business terms: return the ticket, cancel the booking, refund the money.


Compensations run in reverse order.

# Pseudocode: a saga
compensations = []
try:
    booking = book_hotel()
    compensations.append(lambda: cancel_booking(booking))
    ticket = buy_ticket()
    compensations.append(lambda: return_ticket(ticket))
    charge_payment()
except Error:
    for undo in reversed(compensations):
        undo()          # compensations must be idempotent too
    raise
Enter fullscreen mode Exit fullscreen mode

You can't take back a sent email. Put actions like that last, when everything else has already worked, or hand them to a human for approval. That's the next section.

Human approval of an action

Some actions an agent shouldn't take silently: sending an email to a customer, charging money, deleting data, deploying code. OWASP lists the opposite situation as a separate risk, Excessive Agency: the agent has more permissions and autonomy than the task needs.

Two questions decide what to approve: can the action be undone, and what does a mistake cost. Reads and drafts don't need approval. Sending, payments and deletion do.

12-Factor Agents advises asking a human through the same mechanism as tools. The model calls a tool like request_approval with a description of the action, and the code pauses the task and waits for an answer. In the Claude Agent SDK there's the can_use_tool callback for this (canUseTool in TypeScript). The SDK calls it for every tool call that the rules haven't allowed or denied in advance. The callback shows the action to a human and returns "allow" or "deny". On a denial, the model sees the reason and can take another route. The rules are set as lists: allowed_tools lets calls through without asking, disallowed_tools always denies. For an agent with no human nearby, there's the dontAsk mode: anything that would require asking is denied right away.

A human answers slowly: minutes, hours, sometimes a whole night. The SDK callback can wait as long as it takes, but the process has to stay alive the whole time. The docs say outright that for a long wait you should defer the call through a hook, let the process exit, and resume the saved session later. Keeping a process in memory for hours is risky: a deploy will restart it or a failure will kill it. Temporal helps here again. The workflow waits for a signal, an asynchronous message to a workflow that's already running. The wait is recorded in the history and survives crashes and deploys. The wait has a timeout. Temporal Agent Harness works the same way: the agent pauses until the human decides and continues even if the answer came hours later.

# Pseudocode: human approval in Temporal
@workflow
class SendInvoice:
    decision = None

    @signal
    def human_decision(self, answer):   # comes from the UI when the human clicks a button
        self.decision = answer

    @run
    def run(self, customer, amount):
        email = activity(prepare_email, customer, amount)
        activity(show_to_human, email)          # recipient, amount and the full text
        got_answer = wait_condition(lambda: self.decision, timeout=one_day)
        if not got_answer or self.decision != "approve":
            return "not sent"                   # no answer, no action
        return activity(send_email, email, key=email.id)
Enter fullscreen mode Exit fullscreen mode

Three rules. Show the human what will actually run: the recipient, the amount and the text, not the model's paraphrase. If there's no answer before the timeout, the action doesn't run. And make the execution after "yes" idempotent too, since someone can click the button twice.

A deploy in the middle of a task

The last source of failures is one you create yourself: you roll out a new version while agents are working. Anthropic rolls out its system gradually, which is called rainbow deployments. The new version runs next to the old one, and agents that are already running finish on the old one. Temporal has its own constraint. New workflow code must replay old steps the same way the old code did, or recovery will break. So workflow logic with unfinished tasks gets changed carefully.

Observability: seeing every step

The agent crashed on turn 17. Without a trace, all you'll know is that the task didn't get done. A trace shows every step: what went into the model, what it answered, which tool was called, how long it took and what it cost.

You don't need to invent a format. OpenTelemetry has GenAI conventions: separate spans for a model call, an agent (invoke_agent) and a tool (execute_tool), plus attributes for the model and tokens. Their status is still Development, so they may change. Under the standard, prompt and response texts are recorded only when explicitly turned on, since they can contain personal data.

What to measure on the money side:

  • The cost of the whole task, not of one call. The Claude Agent SDK returns it in the final message: total_cost_usd and num_turns. It's an estimate on the client side, not a bill.
  • The cost of a successful task. Failed tasks cost money too: the steps before the failure are already paid for. At 1% failures per step without retries, a successful task costs $0.60 instead of $0.51. At 3%, it's $0.84, 63% more. That's the number to compare with the cost of manual work.
  • Cache share. Look at cache_read_input_tokens in usage. If it's almost always zero, caching isn't working, and in the part 1 example it made the task 6.6 times cheaper.
  • Turns and retries per task. Tasks with far more turns than usual are the first candidates for a loop.
  • The share of tasks that went to plan B.

Keep prompts in git and write their version into the trace. Otherwise you won't be able to tell which change made quality drop.

Evals: tests for nondeterministic code

You changed one word in a prompt or a tool description, and the agent started making more mistakes somewhere else. Evals catch this. Anthropic's guide to agent evals advises not waiting for a perfect set: 20–50 simple tasks from real failures are already a good start. Take them from the bug tracker and support tickets.

You can grade with code (the answer matched, the test passed), with a model (an LLM judges against criteria) or with a human. Code is fast and unambiguous, a model is more flexible, a human is more accurate but more expensive. The model is nondeterministic, so one attempt proves nothing. You need two metrics. pass@k: at least one of k attempts succeeds. pass^k: all k succeed. For an agent that acts on its own, the second one matters.

Run evals in CI on every change to a prompt, a tool or the model, like unit tests. Add every production failure to the set. And read transcripts regularly: it's the only way to see that an eval measures what it should.

Security: the agent will follow someone else's instructions

The model can't reliably tell your instructions apart from text it came across along the way. Prompt injection is first in the 2025 OWASP Top 10 for LLM Applications. Indirect injection is the most dangerous: the instruction comes not from the user but in a tool response. It can be a web page, an email or a document from RAG.

MCP has its own version of the attack. Invariant Labs demonstrated tool poisoning: an instruction is hidden in an MCP tool's description, visible to the model but not to the user. In their demo, a harmless addition tool asked the model to read ~/.ssh/id_rsa and pass the contents in a parameter. On top of that, the description can change after you've approved the server.

Injection filters give no guarantee. Simon Willison writes that in security, catching 95% of attacks is a failing grade. He proposes the "lethal trifecta" rule. An agent is dangerous when it has three things at once: access to private data, untrusted content and a way to send data out.


Based on Simon Willison's article, June 2025.

The rest is familiar from backend work. Give tools minimal permissions: if read access is enough, don't give write access. Run code the agent writes in a sandbox. Validate model output before passing it to SQL, a shell or a browser. Don't write secrets and personal data to logs and traces. Hand irreversible actions to a human, as in the section on approval.

Checklist: an agent from demo to production

Design

  1. First try a chain or a single call with retrieval. Use an agent only where you can't do without one.
  2. Big tools with no overlap. Short responses, and errors that hint how to fix the call.
  3. If the knowledge base is under 200,000 tokens, put it into the prompt with caching. If it's bigger, search by meaning and by keywords, rerank, and test retrieval separately.
  4. A turn limit, a dollar budget and a task timeout, with a margin over a normal task. Decide where a task goes when they run out.

Reliability

  1. Retry only transient errors: 429 with retry-after, 529, 500, 504, network. Increase the pause.
  2. For each tool, decide whether it can be repeated. Pass the idempotency key (the call id) all the way to the external system.
  3. Keep progress outside the process: durable execution, checkpoints, or at least a step log. Only deterministic logic in the workflow.
  4. For actions across several systems, write compensations in advance. Put the irreversible last.
  5. Put sending, payments and deletion behind a human approval: show the exact action, and do nothing without an answer before the timeout.

Operations

  1. A trace of every step, with the prompt version in it. Cost per task, cost per successful task, cache share, turns per task.
  2. 20–50 tasks from real failures in CI on every change to a prompt, a tool or the model.
  3. Don't give an agent private data, untrusted content and external communication all at once. Minimal permissions, a sandbox, no secrets in logs.
  4. Turn on prompt caching: it cuts both the bill and the number of 429 errors.

An agent that gets through 10 steps out of 10 in a demo runs thousands of 30-step tasks in production. That's where the arithmetic from the start of the article kicks in: 1% failures per step, and without retries one task in four doesn't get to the end. Retries fix exactly that. The other practices decide how much a task costs and how much damage the agent can do along the way.

Which of these practices did you only adopt after getting burned?

Series "AI Engineering for Newbies"

This is a series of three articles.

  1. "AI Engineering for Newbies: Agents, MCP, Tokens and Caching, With Numbers"
  2. "AI Agents in Production for Newbies: Tools, RAG, Reliability and Evals" (you are reading it now)
  3. "Agent Systems for Newbies: Building a Support Agent From One File to Temporal, Sagas and a Circuit Breaker"

Top comments (0)