DEV Community: Gabriel Anhaia

What to Capture on an Agent Span (and What to Redact)

Gabriel Anhaia — Sat, 04 Jul 2026 09:59:16 +0000

Book: Observability for LLM Applications — Tracing, Evals, and Shipping AI You Can Trust
Also by me: Agents in Production — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You get paged. A support agent wrote the wrong refund amount into a
customer email. You open your tracing backend, find the trajectory,
and start reading the spans. Every span is green. Every tool call
returned. And there, on the chat span three turns in, sits the raw
customer message with a full credit-card number in the prompt, now
copied into your observability vendor, your log pipeline, and the
screenshot you just pasted into Slack.

Two problems in one trace. You could not tell where the agent went
wrong because the span did not record the decision. And you leaked
PII because the span recorded the payload verbatim. Those two
failures pull in opposite directions, and getting the balance right
is most of what span design for agents is about.

The rest is knowing which attributes are safe to record raw, and
which need a redaction pass before they leave the process.

Start with the four attributes you will actually query

An agent turn is not one LLM call. It is a loop: the model decides,
a tool runs, the result comes back, the model decides again. The
span that wraps the whole loop is your invoke_agent parent. Attach
four attributes to it and you can answer almost every operational
question later.

from opentelemetry import trace

tracer = trace.get_tracer("support-agent")

with tracer.start_as_current_span(
    "invoke_agent support-agent"
) as span:
    span.set_attribute("gen_ai.agent.id", "asst_01H3K")
    span.set_attribute("gen_ai.agent.name", "support-agent")
    span.set_attribute(
        "gen_ai.agent.description",
        "Answers billing questions.",
    )
    span.set_attribute("gen_ai.agent.version", "2.1.0")
    # run the loop; emit child chat/tool spans

id is what you file a bug against. name is the label in the UI.
description is a one-line summary of the system prompt, not the
whole prompt. version is the one people skip and regret. Agents
regress quietly: a prompt tweak, a new tool on the whitelist, a
model swap between two minor revisions. When an eval score drops,
the first thing you do is filter by gen_ai.agent.version to see if
the agent rev moved. Without it, you are guessing.

Record the decision, not just the response

On a plain LLM call, the attribute you care about is what the model
said. On an agent's chat span, the model rarely produced the
user-facing answer. It produced a decision: call this tool with
these arguments, hand off to that agent, or stop. That decision is
the thing worth recording, and it has structure.

span.set_attribute("gen_ai.agent.step", 3)
span.set_attribute("gen_ai.agent.decision", "call_tool")
span.set_attribute(
    "gen_ai.agent.decision.tool", "lookup_order"
)
span.set_attribute(
    "gen_ai.agent.decision.reason",
    "user asked about a refund",
)

Keep decision to a small fixed vocabulary your harness defines and
uses everywhere: call_tool, handoff, final_answer, reflect,
stop. Keep decision.reason short and derived from the model's own
rationale if you have it. These are not stable in the OpenTelemetry
GenAI conventions yet, but the agent backends already read them under
gen_ai.agent.*, and your eval pipeline later scores trajectories by
grouping on gen_ai.agent.decision. That query is impossible if the
attribute was never emitted.

One more on the parent: set gen_ai.agent.step.count when you exit
the loop. It is one integer, the final turn count, and it is what
your "agent exceeded 25 steps" alert keys off. If the loop dies on a
recursion limit, set it in the exception handler before re-raising so
the span still carries the truth.

Your child chat spans keep the numbers that let you cost a run:
gen_ai.request.model, gen_ai.usage.input_tokens,
gen_ai.usage.output_tokens. Your execute_tool spans keep
gen_ai.tool.name and gen_ai.tool.call.id. None of that is
sensitive. Record it all.

Payloads are where it goes wrong

The attributes above are metadata. The temptation is to also record
every prompt and every completion in full, because the one time you
did not, that was the trace you needed. Resist the full-fidelity
version. Two reasons.

The first is size. A late-loop chat span on an agent can carry
tens of thousands of tokens of accreted context. Most span exporters
and backends silently truncate or drop attributes past a limit
(OpenTelemetry defaults to 128 attributes and a per-value length cap
you can configure). A 40 KB prompt string on every span is how you
blow your ingest bill and lose the small attributes that mattered.

The second is the leak. The prompt is exactly where user PII lives.
Record it raw and you have copied names, emails, card numbers, and
health details into a third-party vendor that was never in scope for
that data.

So cap the payload before it goes on the span. A blunt truncation
with a marker beats an unbounded string:

MAX_CHARS = 2048

def clip(text: str, limit: int = MAX_CHARS) -> str:
    if len(text) <= limit:
        return text
    kept = len(text) - limit
    return text[:limit] + f"... [+{kept} chars clipped]"

Record the clipped payload for debuggability, plus the true length as
its own attribute so you never mistake a clipped span for a short
one:

span.set_attribute("gen_ai.prompt.length", len(prompt))
span.set_attribute("gen_ai.prompt.preview", clip(prompt))

Now the span tells you the input was 9,000 characters and shows you
the first 2,000. That is usually enough to see the shape of what went
in without hauling the whole thing across the wire.

Redact PII without blinding the trace

Truncation caps size. It does not remove the card number in the
first 2,000 characters. You need a redaction pass that runs on the
value before it ever reaches set_attribute. The trick is redacting
the identity of the data while keeping its shape, because shape
is what makes a trace debuggable. "The email was malformed" is a real
bug you want to still see after redaction.

import re

PATTERNS = {
    "EMAIL": re.compile(r"[\w.+-]+@[\w-]+\.[\w.-]+"),
    "CARD": re.compile(r"\b(?:\d[ -]?){13,16}\b"),
    "PHONE": re.compile(r"\b\+?\d[\d ()-]{8,}\d\b"),
}

def redact(text: str) -> str:
    for label, pat in PATTERNS.items():
        text = pat.sub(f"[{label}]", text)
    return text

Feeding "charge card 4111 1111 1111 1111 for a.b@x.io" through this
returns "charge card [CARD] for [EMAIL]". You kept the sentence
structure, the tool intent, and the fact that a card and an email
were present. You dropped the values. A reviewer reading that span in
your vendor sees a well-formed request and no regulated data.

Chain the two passes so redaction runs first, then the size cap:

def safe(text: str) -> str:
    return clip(redact(text))

span.set_attribute("gen_ai.prompt.preview", safe(prompt))
span.set_attribute(
    "gen_ai.completion.preview", safe(completion)
)

Regex catches the formatted classes: cards, emails, phones, IBANs,
SSNs. It will not catch a free-text name or a home address, so treat
it as the floor, not the ceiling. For the harder classes, run a
lightweight structured-output pass with Claude to tag spans before
export, or allowlist which tool arguments are safe to record at all.
The lookup_order tool's order_id is fine to keep raw. Its
billing_address is not.

Do it once, at the boundary

Sprinkling safe() across your codebase means one forgotten call is
a leak. Put the redaction in a custom SpanProcessor so the prompt
and completion previews pass through it on the way out, even when a
caller forgets:

from opentelemetry.sdk.trace import SpanProcessor

SENSITIVE = {"gen_ai.prompt.preview",
             "gen_ai.completion.preview"}

class RedactingProcessor(SpanProcessor):
    def on_end(self, span):
        for key in SENSITIVE:
            val = span.attributes.get(key)
            if isinstance(val, str):
                span._attributes[key] = safe(val)

    def on_start(self, span, parent_context=None):
        pass

Register it before your exporter in the pipeline and those two fields
get redacted across every agent and every tool, even when a developer
forgets the safe() call. It only covers the keys in SENSITIVE, so
add any other free-text attribute you record to that set. The same
idea works in TypeScript with a custom SpanExporter wrapper that
maps over span.attributes before delegating to the real OTLP
exporter.

The balance

The cheap attributes are safe to record in full, and they buy you the
difference between a fifteen-minute debug session and a two-hour one.
The payloads are the ones that need a cap and a redaction pass at the
export boundary. Get that split right and you get a trace that shows
you what the agent decided without showing you your customer's card
number: the one you can actually paste into Slack at 3am.

If you are building the agent, Agents in Production
walks through the harness that emits these spans and the tool loop
underneath them. If you are wiring up the tracing, evals, and cost
accounting around it, Observability for LLM Applications
is the companion volume. They are the two halves of The AI
Engineer's Library, and span design like this is the seam where they
meet.

Trace Sampling for Agents: Keeping the Trajectories That Matter

Gabriel Anhaia — Sat, 04 Jul 2026 09:57:26 +0000

Book: Observability for LLM Applications — Tracing, Evals, and Shipping AI You Can Trust
Also by me: Agents in Production — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You get paged. The triage agent is writing wrong labels. You open your backend, filter to the last hour, and find the failing run. You click it. Half the trace is there. Five chat spans, no tool spans, no invoke_agent parent. Someone turned on head sampling to cut the bill, and the sampler kept a random 10% of spans without caring which trace they belonged to. The one trajectory you need to read is a fragment. You cannot debug what you cannot see, so you spend the next hour reading raw spans instead of the fifteen minutes it should have taken.

That is the failure that trace sampling for agents exists to prevent. The goal is not "keep less data." The goal is to keep every trajectory that teaches you something and drop the ones that do not, without ever keeping half of one.

Why head sampling breaks on agents

Head sampling decides at the start of a trace, before anything has happened. Roll a die on the first span, keep 10%, drop the rest. It works for high-volume web traffic where one request looks like the next and the failures are already caught by your error tracker.

Agents break both assumptions. A single run spans thirty spans across five seconds and fourteen decisions. When you make the keep-or-drop call at span one, you have no idea yet whether this run will loop search_kb twenty times, blow past its token budget, or quietly emit a wrong answer. The information you would sample on does not exist until the trajectory finishes.

So a random 10% at the head throws away 90% of your failures and keeps 10% of your boring successes. That is backwards. You want the opposite ratio.

Sample the trajectory, never half a tree

Two rules, and the second one is the one teams forget.

First: make the sampling decision at the invoke_agent level, not the chat level. The unit of debugging is the trajectory. The unit of sampling has to match it.

Second: when you keep a trajectory, keep the complete tree. Every chat span, every tool span, every nested handoff. A half-sampled trajectory, five chat spans out of fifteen, is worse than no trace at all, because it looks complete and lies to you. You read it, reconstruct a story from the surviving spans, and the story is wrong.

This is what tail sampling gives you that head sampling cannot. Tail sampling buffers the whole trace, waits for it to finish, then decides. By decision time you know the outcome, the latency, and the cost, and you can keep or drop the entire tree as one unit.

The four things you always keep

Tail sampling lets you write a keep-list based on what actually happened. For agents, four categories earn an always-keep:

Failed runs. Any trajectory where a span carries an error status. A tripped budget, a tool that threw, a guardrail that blocked. These are the runs you get paged about.

Slow runs. Any trajectory whose root span runs past a latency threshold. Ten seconds for a triage agent means it looped or a tool hung. The slow tail is where the runaways live.

Expensive runs. Any trajectory whose total token count crosses a ceiling. Latency does not always catch cost. A run can finish fast and still burn 200K input tokens because context accreted on every turn. Sample on tokens directly.

Eval traffic. Every run tagged as coming from your eval suite or CI, kept at 100%, always. This is the traffic you grade trajectories against later. Losing an eval trace to a probabilistic drop means a hole in your regression data. Tag it, and never sample it away.

Everything else is the boring happy path. Keep a baseline slice of it, around 10 to 20%, so you still have a picture of what normal looks like, and drop the rest.

The collector config

The OpenTelemetry Collector's tail_sampling processor does this natively. Each policy is an OR: if any policy votes to keep, the whole trace is kept.

processors:
  tail_sampling:
    decision_wait: 30s
    num_traces: 100000
    policies:
      - name: keep-failed
        type: status_code
        status_code:
          status_codes: [ERROR]
      - name: keep-slow
        type: latency
        latency:
          threshold_ms: 10000
      - name: keep-expensive
        type: numeric_attribute
        numeric_attribute:
          key: gen_ai.usage.total_tokens
          min_value: 100000
      - name: keep-eval-traffic
        type: string_attribute
        string_attribute:
          key: agent.traffic.source
          values: [eval, ci]
      - name: sample-the-rest
        type: probabilistic
        probabilistic:
          sampling_percentage: 15

decision_wait is how long the collector buffers a trace after the first span before it decides. Set it above your p99 trajectory duration, or a slow run finishes after the decision and gets cut anyway. num_traces is the in-memory buffer size; size it to your throughput times the wait window.

The latency policy reads the root span duration, which is the true wall-clock of the trajectory. Do not try to sum child spans for this. Tool calls sometimes run concurrently and the sum lies.

Make the signals visible

Two of those policies only work if your harness writes the signal onto the root span before it ends. The collector reads what you emit.

status_code: ERROR needs you to set the span status when a run fails or a budget fires. gen_ai.usage.total_tokens needs you to roll up the per-call token counts and stamp the total on the invoke_agent root.

from opentelemetry import trace
from opentelemetry.trace import StatusCode

tracer = trace.get_tracer("triage-agent")

with tracer.start_as_current_span(
    "invoke_agent triage-agent"
) as root:
    total_tokens = 0
    stop_reason = "final_answer"

    for step in run_loop(messages, tools):
        # each step emits its own chat/tool child spans
        total_tokens += step.input_tokens
        total_tokens += step.output_tokens
        if step.budget_hit:
            stop_reason = step.budget_hit
            break

    root.set_attribute(
        "gen_ai.usage.total_tokens", total_tokens
    )
    root.set_attribute("gen_ai.agent.stop_reason", stop_reason)

    if stop_reason != "final_answer":
        root.set_status(StatusCode.ERROR, stop_reason)

The rollup on the root is the same aggregation your finance dashboard already wants for per-trajectory cost. You emit it once and two systems read it: the cost view and the sampler.

Tag your eval traffic at the source

The keep-eval-traffic policy is only as good as the tag. Set agent.traffic.source on the root span for every run that comes from an eval harness or CI, so those runs bypass the probabilistic drop. Eval suites are often written in TypeScript, so the tag goes on wherever the run starts:

import { trace, SpanStatusCode } from "@opentelemetry/api";

const tracer = trace.getTracer("triage-agent");

await tracer.startActiveSpan(
  "invoke_agent triage-agent",
  async (root) => {
    root.setAttribute("agent.traffic.source", "eval");
    try {
      await runTrajectory(testCase);
    } finally {
      root.end();
    }
  },
);

Production traffic leaves the attribute unset, so it falls through to the 15% baseline. Eval and CI runs carry the tag and land every time.

The gotcha nobody mentions: route by trace ID

Tail sampling needs the whole trace in one place to decide. If you run more than one collector behind a load balancer, the spans of a single trajectory can scatter across instances, and no single collector ever sees the complete tree. Each one decides on a fragment, and you are back to half-sampled trajectories.

The fix is a two-tier collector layout. A first tier receives spans and routes them with the loadbalancing exporter keyed on trace ID, so every span of one trajectory lands on the same second-tier collector. The tail_sampling processor runs only on the second tier, where each trace is now whole. Skip this and your keep-the-complete-tree rule quietly stops holding under load.

Tune it by watching what you kept

Start at a 15% baseline with the four always-keeps, then look at your kept-trace mix after a day. If failures and slow runs dominate what you stored, the baseline is fine. If the boring happy path is still eating your storage, drop the baseline to 10%. If you find yourself wishing you had more normal runs to compare against a regression, raise it.

The number to protect is not the storage bill. It is the odds that the one trajectory you get paged about is sitting in your backend, complete, when you go looking for it.

If this was useful

If you are building the agent loop that emits these trajectories, Agents in Production covers the harness, the budgets, and the decision spans that make a trace worth sampling. If you are wiring the tracing and eval side, Observability for LLM Applications goes deep on OpenTelemetry attributes, tail sampling, and grading trajectories against a gold sequence. The two books in The AI Engineer's Library are meant to sit next to each other on exactly this kind of problem.

Per-Agent Cost and Token Attribution Straight From Your Traces

Gabriel Anhaia — Sat, 04 Jul 2026 09:55:52 +0000

Book: Observability for LLM Applications — Tracing, Evals, and Shipping AI You Can Trust
Also by me: Agents in Production — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

The bill lands on the first of the month. Your provider dashboard shows one number for the whole account. Finance forwards it to you with a subject line that ends in a question mark. You know your agent made the calls. You do not know which agent, which feature, or which step inside the loop turned a two-cent task into a forty-cent one.

That gap is not a billing problem. It is an instrumentation problem. The provider only sees API calls. Your traces see the trajectory: which agent ran, what step it was on, which tool it picked, how many tokens each turn burned. If you tag those spans correctly, the monthly bill stops being a mystery and starts being a GROUP BY.

Here is how to get there.

The provider bill is aggregated. Your traces don't have to be.

An agent turn is rarely one model call. You get a decision, you run a tool, you feed the result back, you loop. Every one of those model calls carries token usage. Your provider sums all of them into a single line item and calls it a day.

The fix is to attach a small, consistent set of attributes to every span your agent emits, so that later you can slice cost along any axis you care about: per agent, per feature, per run, per step. The OpenTelemetry GenAI semantic conventions already define most of the names. You just have to set them.

Tag every span with agent, step, and tool

Two levels matter. The invoke_agent span is the parent — it fires once per task and wraps the whole loop. The chat spans underneath carry the token usage. You want identity on the parent and usage on the children.

from opentelemetry import trace

tracer = trace.get_tracer("agent")

def run_agent(task, feature):
    with tracer.start_as_current_span(
        "invoke_agent triage-agent"
    ) as root:
        root.set_attribute(
            "gen_ai.agent.name", "triage-agent"
        )
        root.set_attribute(
            "gen_ai.agent.version", "2.1.0"
        )
        # your own dimension for feature rollups
        root.set_attribute("app.feature", feature)
        return loop(task)

gen_ai.agent.name is the human label. gen_ai.agent.version is the one you skip on the first pass and regret later — when cost jumps overnight, you want to know whether the agent changed. app.feature is not in the spec; it is your own dimension, and it is the one finance actually asks about.

Now the child span. Each model call sets its step, its model, and its token counts.

def chat_step(client, messages, step):
    with tracer.start_as_current_span(
        "chat claude-sonnet-4-6"
    ) as span:
        span.set_attribute("gen_ai.agent.step", step)
        resp = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            messages=messages,
        )
        u = resp.usage
        span.set_attribute(
            "gen_ai.response.model", resp.model
        )
        span.set_attribute(
            "gen_ai.usage.input_tokens",
            u.input_tokens,
        )
        span.set_attribute(
            "gen_ai.usage.output_tokens",
            u.output_tokens,
        )
        span.set_attribute(
            "gen_ai.usage.cache_read_input_tokens",
            getattr(u, "cache_read_input_tokens", 0),
        )
        span.set_attribute(
            "gen_ai.usage.cache_creation_input_tokens",
            getattr(u, "cache_creation_input_tokens", 0),
        )
        return resp

Read usage off the response. Never estimate token counts with a local tokenizer; the provider's number is the one you get billed on, and cache reads and system-prompt overhead make the local guess wrong. For Claude, usage.input_tokens and usage.output_tokens come straight off the message. If you use prompt caching, usage also carries cache_read_input_tokens and cache_creation_input_tokens. Record those too, because cache reads are billed at a fraction of the input rate and ignoring them overstates your cost.

Tool spans get the same treatment for identity, minus the tokens.

def run_tool(name, args):
    with tracer.start_as_current_span(
        f"execute_tool {name}"
    ) as span:
        span.set_attribute("gen_ai.tool.name", name)
        return TOOLS[name](**args)

Turn tokens into money

Tokens are the raw signal. Cost is tokens times a per-model rate. Keep the rate table in code, keyed on the response model, and treat it as data that drifts, because provider prices change and a stale table quietly makes every number wrong.

# USD per 1M tokens. Check current rates before trusting.
PRICING = {
    "claude-sonnet-4-6": {
        "input": 3.00,
        "output": 15.00,
        "cache_read": 0.30,
    },
    "claude-haiku-4-5": {
        "input": 1.00,
        "output": 5.00,
        "cache_read": 0.10,
    },
}

def cost_usd(model, in_tok, out_tok, cache_read=0):
    # in_tok is the uncached input remainder that
    # Anthropic reports in usage.input_tokens; cache
    # reads are billed separately, so add, don't subtract.
    p = PRICING[model]
    return (
        in_tok * p["input"]
        + cache_read * p["cache_read"]
        + out_tok * p["output"]
    ) / 1_000_000

You can attach the computed cost to each chat span as gen_ai.usage.cost so the rollup is a sum, not a join against a pricing table at query time. Most backends already do this multiplication for you: Langfuse, Phoenix, Braintrust, and LangSmith commonly read gen_ai.usage.* and apply their own pricing table. Setting the attribute yourself means your number and theirs agree, and it survives a provider price change their table hasn't caught up to. Treat the rates in the table above as illustrative. Check Anthropic's current published pricing before you trust any number that falls out of this.

Roll up per run, per feature, per step

Once the attributes are on the spans, attribution is aggregation. The parent invoke_agent span is what makes it clean — every child belongs to one task, so per-run cost is the sum of gen_ai.usage.cost across the subtree. Backends compute this for you and show it on the root span.

The dimension finance cares about is the feature, and that is where app.feature earns its place. If your span store is queryable (most export to a warehouse or expose an API), the question "what did the refund flow cost last week" is one grouped sum.

SELECT
  attributes['app.feature']      AS feature,
  count(DISTINCT trace_id)       AS runs,
  sum(attributes['gen_ai.usage.cost']) AS usd
FROM spans
WHERE name LIKE 'chat %'
  AND timestamp >= now() - INTERVAL 7 DAY
GROUP BY feature
ORDER BY usd DESC;

That single query answers the question the provider dashboard cannot. The dashboard gives you the account total. This gives you per-feature spend, the run count behind it, and the unit cost. Divide usd by runs and you have cost-per-task per feature, which is the number you take into a pricing conversation.

Group by gen_ai.agent.step instead of feature and you get the shape of the loop: how cost accumulates turn by turn. In an agent, input tokens grow every step because the context accretes — the transcript from step one rides along into step four. A run that should take three turns and takes twelve is not twelve times the cost. It is worse, because each later turn carries a fatter prompt.

Find the expensive step

Averages hide the runs that hurt. The bill is not driven by the median task; it is driven by the tail — the trajectory that looped, re-searched, re-read a giant document five times, or handed off to a model that was overkill for the job. Attribution per step is how you find it.

Sort your runs by cost, open the most expensive one, and read it top to bottom. The token counts on the chat spans tell the story. A step where input tokens jump from two thousand to twenty thousand is a step that stuffed something huge into context: a full document, an un-truncated tool result, an entire conversation history. A run with fifteen chat spans when the happy path has four is a loop that did not terminate.

Two rollups make the tail visible without opening traces one at a time:

-- cost per step position, across all runs
SELECT
  attributes['gen_ai.agent.step'] AS step,
  count(*)                         AS calls,
  avg(attributes['gen_ai.usage.input_tokens'])
    AS avg_in_tokens,
  sum(attributes['gen_ai.usage.cost']) AS usd
FROM spans
WHERE name LIKE 'chat %'
GROUP BY step
ORDER BY step;

If cost stays flat across steps, your loops are short and context is managed. If it climbs steeply, either you are looping too long or you are not trimming context between turns, and the fix is on the agent side, not the model side. Once you know it is a specific tool result blowing up the prompt, you truncate that result before it re-enters context, and the whole tail flattens.

The cheapest optimization is usually a model swap on one step, not the whole agent. If step zero is a routing decision that a small model handles fine, the per-step rollup shows you exactly that span burning Sonnet money on a Haiku-sized job. You would never see it in the account total.

What the rollup won't tell you

Cost attribution tells you where the money went. It does not tell you whether the money was well spent. A trajectory that costs forty cents and gets the answer right is cheaper than the two-cent one that fails and gets retried by a frustrated user. Token cost is one axis. Whether the agent did the right thing is a separate question, and it needs evals, not accounting. Wire the attribution first, though — you cannot optimize what you cannot attribute, and you cannot attribute what you never tagged.

If you want the full version of this — the complete gen_ai.* attribute set, multi-agent handoff cost rollups, and the sampling rules that keep trace volume affordable — it lives in The AI Engineer's Library. Agents in Production covers building and shipping the agent loop these spans wrap; Observability for LLM Applications covers the tracing, evals, and cost accounting you hang off it. The two are meant to be read together.

Silent Drift in Agent Decision Quality: Catching It Before Your Users Do

Gabriel Anhaia — Sat, 04 Jul 2026 09:54:01 +0000

Book: Observability for LLM Applications — Tracing, Evals, and Shipping AI You Can Trust
Also by me: Agents in Production — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Your triage agent has been in production for three months. The traces look clean. Every span is green, every run terminates, the p95 latency is flat, the token bill is boring. Then support forwards you a screenshot: the agent routed a billing refund to the security queue. You pull the trajectory. Nothing is broken. The agent called a reasonable tool with reasonable arguments, got a reasonable result, and picked the wrong queue with total confidence.

That is silent drift. The trace shows you what the agent did. It does not tell you whether what it did was any good. Between a model provider's minor version bump, a prompt tweak someone shipped on Tuesday, and the slow shift in your incoming traffic, the quality of your agent's decisions moves. It rarely announces itself with an error. It shows up as a support ticket, then a second one, then a churned account.

You catch it the same way you catch a memory leak: with a baseline and an alarm, not by staring at dashboards.

Decision quality is a distribution, not a number

The failing traces in Chapter 12 of Agents in Production are the easy case. Twenty retries of the same empty search is visibly wrong. You see the loop count in the invoke_agent parent and you know. Most quality regressions are not visible in a single trace. They show up only when you look at the distribution of decisions across thousands of runs.

So the first thing to instrument is the decision itself. If you followed the tracing chapter you already emit a small fixed vocabulary per chat span:

span.set_attribute("gen_ai.agent.step", 3)
span.set_attribute("gen_ai.agent.decision", "call_tool")
span.set_attribute(
    "gen_ai.agent.decision.tool", "classify_ticket"
)
span.set_attribute("gen_ai.agent.version", "2.1.0")

Those four attributes turn decision quality into something you can measure. decision and decision.tool give you the shape of the trajectory. version tells you which agent revision produced it. Group on those and you get a distribution: how often each decision type fires, which tool the model reaches for, how many steps a run takes. When that distribution moves, quality is moving with it.

Set a baseline while you know the answer

A baseline is a golden set of tasks where you know what a good trajectory looks like, scored once when the agent is healthy. You do not need thousands. A hundred hand-checked cases covering your real traffic mix beats ten thousand synthetic ones.

Score each case on two axes. Outcome: did the run reach the right final answer. Trajectory: did it take a sensible path to get there. A run can land the right answer through a bad path (three redundant tool calls, a lucky guess) and that path will not survive the next model update. Score the path, not only the destination.

from dataclasses import dataclass

@dataclass
class BaselineCase:
    task_id: str
    input: dict
    expected_tool_sequence: list[str]
    expected_label: str

def score_run(run, case):
    outcome = run.final_label == case.expected_label
    tools = [s.tool for s in run.tool_steps]
    trajectory = tools == case.expected_tool_sequence
    return {
        "task_id": case.task_id,
        "outcome_ok": outcome,
        "trajectory_ok": trajectory,
        "steps": len(run.chat_steps),
        "version": run.version,
    }

Run your whole golden set through the agent, record the aggregate: outcome accuracy, exact-trajectory rate, median steps. Freeze those numbers next to the agent version that produced them. That frozen record is what every future run gets compared against. Without it, "the agent feels worse" is an argument, not a measurement.

Re-run the golden set in CI on every prompt change, every model pin bump, every tool addition. This is the cheap gate. It catches the regression you introduced yourself before it reaches a user.

Online sampling: grade production, not just CI

CI covers the changes you make. It does not cover the changes made to you: a provider ships a new snapshot behind the same model alias, your traffic shifts toward a harder segment, an upstream tool starts returning subtly different data. For those you have to grade production traffic while it is live.

You cannot grade every run. Grading costs a model call or a human minute, and you have thousands of runs an hour. So you sample. Two kinds of sampling, and you want both.

Random sampling gives you an unbiased read on the whole population. Pull a small fixed percentage of completed trajectories, uniformly. Targeted sampling catches the runs most likely to be bad: high step counts, a decision the baseline says is rare, a final answer the agent produced with a short low-confidence chat span.

import random

def should_grade(run, base_rate=0.02):
    if random.random() < base_rate:
        return True, "random"
    if run.step_count > run.p95_steps:
        return True, "long_trajectory"
    if run.final_decision_latency_ms < 50:
        return True, "snap_answer"
    if run.tool_sequence in run.rare_sequences:
        return True, "rare_path"
    return False, None

The random slice keeps your quality estimate honest. The targeted slice finds problems fast. Keep them separate in storage so you never let the targeted samples poison your population estimate — a metric computed only over suspicious runs looks terrible on a perfectly healthy agent.

The judge that scores a sampled run

For the sampled runs you need a score. Human review is the gold standard and too slow to be your only tool. An LLM judge, pinned to a strong model and a tight rubric, handles the volume, with humans auditing a slice of the judge's own calls.

from anthropic import Anthropic

client = Anthropic()

RUBRIC = """You grade one agent trajectory.

Task given to the agent:
{task}

Tool calls the agent made, in order:
{trajectory}

Final answer the agent produced:
{answer}

Score three fields as strict JSON, no prose:
- outcome: "correct" | "wrong" | "unclear"
- path: "efficient" | "wasteful" | "wrong_tools"
- reason: one sentence, under 20 words
"""

def grade(run):
    msg = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=256,
        messages=[{
            "role": "user",
            "content": RUBRIC.format(
                task=run.task,
                trajectory=run.render_tools(),
                answer=run.final_answer,
            ),
        }],
    )
    return parse_json(msg.content[0].text)

Pin the judge model explicitly. A judge that silently upgrades under you drifts exactly like the agent you are trying to watch, and then you have two moving baselines and no ground. Keep the rubric short and the output structured. Audit the judge against human labels on a regular slice; if judge-human agreement falls below your threshold, the judge is the thing that regressed, and you fix that before you trust another one of its scores.

Alarms that fire on drift, not on noise

Now you have two signals over time: the golden-set score from CI and the graded-sample score from production. Drift detection is watching those move against the baseline and paging a human when the move is real rather than random.

The trap is alerting on a single bad run. One wrong trajectory in a stochastic system is expected. You want a sustained shift. A rolling window with a minimum sample size keeps you off the pager for noise.

def drift_alarm(window, baseline, min_n=200, drop=0.05):
    if len(window) < min_n:
        return None
    current = sum(r.outcome_ok for r in window) / len(window)
    delta = baseline.outcome_rate - current
    if delta >= drop:
        return {
            "fired": True,
            "baseline": baseline.outcome_rate,
            "current": round(current, 3),
            "delta": round(delta, 3),
            "window_n": len(window),
        }
    return None

Segment the window by gen_ai.agent.version before you compare. A blended rate across two versions during a rollout will smear a real regression into invisibility, or invent one that is only a mix shift. The debugging chapter says the same thing about reading traces under pressure: filter by version first. Drift detection is that instinct turned into a standing job.

Watch the trajectory distribution too, not only outcome accuracy. If classify_ticket used to fire in 92% of runs and now fires in 74%, the agent is reaching for a different tool than it used to, and that is a leading indicator you get before the outcome score has moved enough to trip. Decision-mix drift is your smoke alarm. Outcome drift is the fire.

Wire it into the loop you already have

None of this is a second system. The baseline is a table. The online sampler is a coin flip at the end of a run. The judge is one pinned model call on a sampled slice. The alarm is a windowed comparison you run on a schedule. All of it reads the gen_ai.agent.* attributes your traces already carry.

Start on Monday with the cheapest version. Freeze a hundred-case golden set against your current agent version. Run it in CI on every change. Add a 2% random sample of production trajectories to an LLM judge and store the scores next to the version tag. Put one alarm on the outcome rate with a 200-run window and a five-point drop threshold. That is a day of work, and it converts "a user noticed the agent got worse" into "an alarm noticed, at 2am, with the version that broke it already named in the payload."

The agents that stay good in production are not the ones that never drift. They are the ones whose owners measured drift on purpose, before a customer did it for them.

If you want the full version of this, the two books in The AI Engineer's Library split the work between them. Agents in Production covers building and running the agent loop — the trajectory attributes, the decision vocabulary, the guardrails these alarms key off. Observability for LLM Applications goes deep on the tracing, the eval harness, and the cost signals that turn a trace tree into a quality measurement you can trust.

Evals for Agents: Scoring Task Success, Trajectory, and Human Review

Gabriel Anhaia — Sat, 04 Jul 2026 09:52:31 +0000

Book: Observability for LLM Applications — Tracing, Evals, and Shipping AI You Can Trust
Also by me: Agents in Production — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

The agent finished. The trace is green. Every span says ok. The user got an answer, and the success counter on your dashboard ticked up by one. You would have shipped it on a Friday and gone home.

Then someone reads the run. To close a support ticket, the agent searched the knowledge base, found nothing, searched again with the same query, found nothing, escalated to a refund_customer tool it was never meant to touch on that tier, refunded thirty-seven dollars, wrote a cheerful closing note, and marked the ticket resolved. Task success: 1.0. The run itself: a small fire.

That gap is where single-number evals fall through with agents. When you scored a plain LLM call, the unit was the output. Input in, output out, grade it, move on. An agent has no single output to grade. It has an input, a trajectory, and a final state. Score only the final state and you miss every interesting failure. Score only the trajectory and you miss the ones that worked by accident. You need both, plus a way to pull in a human when neither is sure.

Three axes, not one

The eval loop you already know still holds. Collect a dataset, score against it with a judge, track the score, fail CI when it drops. What changes for agents is the unit. A run has three things worth scoring:

Task success. At the end, did the world look the way the user asked? The final-state check.
Trajectory. Along the way, were the steps sane? Right tools, right order, right arguments, no wandering?
Human judgment. When neither automated check is confident, or the stakes are high, a person grades the run. Those grades become ground truth for the first two.

Every production agent eval stack is some blend of these three. The vocabulary differs across tools. The shape does not.

Axis one: task success

Task success is the easiest to explain and the most dangerous to trust alone. You take the original request, you take the final state, and you ask whether the state satisfies the request. An LLM judge reads the run and returns a 0 to 1 score with a reason.

DeepEval's TaskCompletionMetric reads a trace, infers the task from the first user turn and the outcome from the final assistant turn plus the tool calls, and scores it. No hand-written test case required.

from deepeval.metrics import TaskCompletionMetric
from deepeval.test_case import LLMTestCase, ToolCall
from deepeval.models import AnthropicModel

# Bare model strings resolve through DeepEval's
# default provider. Wrap for a Claude judge.
judge = AnthropicModel("claude-haiku-4-5")

metric = TaskCompletionMetric(
    threshold=0.7,
    model=judge,
    include_reason=True,
)

case = LLMTestCase(
    input="Refund the last charge for user 8821.",
    actual_output=(
        "Refunded $37.00 to card ending 4242. "
        "Ticket #91234 closed."
    ),
    tools_called=[
        ToolCall(name="lookup_user", input={"id": 8821}),
        ToolCall(name="list_charges", input={"user": 8821}),
        ToolCall(
            name="refund_charge",
            input={"charge_id": "ch_7x"},
        ),
        ToolCall(name="close_ticket", input={"id": 91234}),
    ],
)

metric.measure(case)
print(metric.score, metric.reason)

Wire it into CI the way you wired faithfulness for plain calls. Pull a sample of production traces nightly, score them, fail the build when the rolling average drops below threshold.

One thing to be blunt about: the judge model matters. A judge should be at least as strong as the agent it grades. A weak judge grading a strong agent hands out kind, forgiving scores that drift upward and tell you nothing. A reasonable default is to judge with the cheapest frontier model you can afford, such as Claude Haiku, when the agent runs on a frontier model, then upgrade the judge to the agent's tier once you catch it passing runs that humans later flag.

Now the catch that keeps the refund fire on the books. The refund agent's endpoint was "ticket closed with refund issued." If the request was "refund the last charge," that endpoint scores a perfect 1.0. The judge has no idea the agent was not authorized to issue that refund on a free-tier account. That is not a final-state question. That is a trajectory question.

Axis two: trajectory

Trajectory scoring is the glass-box half. You stop asking "did it finish" and start asking "were the steps reasonable given what the agent already knew." The research on this converges on one recipe: break the run into small pieces, grade each piece against clear criteria, roll up. Feed the trajectory judge the steps, not the final answer, because judges systematically over-score runs that ended well no matter how messy the path.

You do not have to build that from scratch. The agentevals package from the LangChain org ships ready-made trajectory evaluators: exact-match tool sequence, subset, unordered set, and LLM-graded. Plug in your trace, plug in the expected shape, get a verdict.

from agentevals.trajectory.match import (
    create_trajectory_match_evaluator,
)

evaluator = create_trajectory_match_evaluator(
    trajectory_match_mode="strict",
)

actual = [
    {"role": "user", "content": "Refund user 8821."},
    {"role": "assistant", "tool_calls": [
        {"name": "lookup_user", "args": {"id": 8821}},
    ]},
    {"role": "tool", "content": "{'tier': 'free'}"},
    {"role": "assistant", "tool_calls": [
        {"name": "refund_charge",
         "args": {"charge_id": "ch_7x"}},
    ]},
]

expected = [
    {"role": "user", "content": "Refund user 8821."},
    {"role": "assistant", "tool_calls": [
        {"name": "lookup_user", "args": {"id": 8821}},
    ]},
    {"role": "tool", "content": "{'tier': 'free'}"},
    {"role": "assistant", "tool_calls": [
        {"name": "escalate_to_human",
         "args": {"reason": "free tier refund"}},
    ]},
]

result = evaluator(
    outputs=actual,
    reference_outputs=expected,
)
print(result)
# {'key': 'trajectory_strict_match', 'score': False, ...}

The refund scenario fails this check loudly. The expected path ends in escalate_to_human. The actual path ends in refund_charge. Task success said 1.0. Trajectory says false. Neither axis alone catches the failure class the other misses.

Do not grade every step with an LLM judge unless cost is no object. A practical stack is exact-match on the steps that matter (the destructive tool calls, the final answer shape), an LLM judge on the fuzzy reasoning in between, and one rubric pass at the end. Cheap step-level scorers are plain functions:

AUTHORIZED = {"free": set(), "pro": {"refund_charge"}}

def destructive_authorized(step, **_):
    call = step.get("tool_call")
    if not call:
        return 1.0
    if call["name"] not in {"refund_charge", "send_email"}:
        return 1.0
    tier = step["context"]["user_tier"]
    ok = call["name"] in AUTHORIZED[tier]
    return 1.0 if ok else 0.0

def trajectory_length(output, **_):
    steps = len(output["trajectory"])
    if steps <= 6:
        return 1.0
    if steps >= 20:
        return 0.0
    return 1.0 - (steps - 6) / 14

The first catches an unauthorized destructive call on a per-step basis. The second penalizes wandering. Neither calls a model, both run on every replay, and both catch a class of failure that an endpoint metric never sees.

Axis three: human review

Automated evals are cheap and wrong often enough that the disagreements cluster in the cases that matter most. The fix is not another round of judge-prompt tuning. The fix is a human review queue that pulls ambiguous runs out of production, puts them in front of a person, and feeds the resulting grades back as ground truth.

Build it from three parts. A router reads your trace stream and writes flagged trace IDs to a queue table. A reviewer UI pops the next flagged trace, shows it in full, and captures a label. A writer appends completed labels to your offline eval dataset. Langfuse, Braintrust, and LangSmith ship all three; rolling your own is roughly two hundred lines plus a six-column table.

The UI choice that matters most: the reviewer must see the trajectory, not just the final message. Show only the fluent closing reply and they will rubber-stamp everything. Put the request first, verbatim. Then the trajectory, one step per row, with destructive tools badged. Then the final message, last. Then the automated scores, visible but not authoritative. Then a short scoring form, three fields at most. A reviewer labels fifty runs an hour with a three-field form and ten runs an hour with a ten-field one.

Routing rules keep the queue honest. Send everything and reviewers start clicking "pass" to clear the backlog. Good triage: judge score below 0.7, any un-preapproved destructive call, any run that blew the cost cap and recovered, anything past the 95th-percentile latency, and one green run in two hundred at random so reviewers stay calibrated against normal, successful behavior.

The loop is the point. A human label on a flagged trace is worth a hundred synthetic cases, because it came from a real request and a real failure. Export labels weekly, re-run your judge against them, and tune the judge when it disagrees with people. Over a quarter the judge gets cheaper and more accurate, and you lean on the queue less for volume and more for the long tail.

About the public benchmarks

Someone always asks where SWE-bench and GAIA fit. Short answer: not in your CI. They tell you which models clear a baseline in a domain, and a model that cannot solve SWE-bench Verified will not solve your codebase. But a model that tops it might still be bad at your codebase, because the benchmark's input distribution is not your users'. SWE-bench tasks come from clean Python projects with isolated fixes. Your bug reports arrive as Slack screenshots and a "fix" spans three services and a migration.

Build the boring thing instead. Pull a hundred real requests from the last week, hand-label each for the outcome you wanted, save the pairs as JSON. That golden set is smaller and noisier than any leaderboard, and it is the only dataset whose score tracks whether your agent works for the people paying you. Run it on every PR that touches the agent, and grow it from the review queue. When a model upgrade moves the public leaderboard and your golden set in opposite directions, trust the golden set.

Where this leaves you

You can score an agent now on three axes: task success for the endpoint, trajectory for the path, human review for the runs neither one can call. Task success alone would have shipped the refund fire. The three together catch it. None of them stops the agent from refunding money it was not allowed to refund the first time. Tracing sees it after the fact, evals grade it after the fact, the queue catches it after the fact. After is the word all three share, which is exactly why you want all three running before the next Friday deploy.

If you are building the agent that produces these runs, Agents in Production is the book on tool loops, authorization, and shipping the thing safely. If you are wiring the tracing and eval pipeline underneath it, Observability for LLM Applications covers the traces, the judges, and the cost accounting that make the loop above real. Together they are The AI Engineer's Library.

Tracing an Agent Trajectory as a Tree of Spans

Gabriel Anhaia — Sat, 04 Jul 2026 09:50:52 +0000

Book: Observability for LLM Applications — Tracing, Evals, and Shipping AI You Can Trust
Also by me: Agents in Production — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You get paged: the triage agent is writing wrong labels on support tickets. You open your tracing backend and there are four thousand runs from the last hour. You know how to read a single LLM call. You emitted gen_ai.request.model, watched a span land in the waterfall, and read it top to bottom. That skill does not scale here. The question changed. It is no longer "what did the model say." It is "where in this fourteen-step run did the agent decide to do the wrong thing, and is that the same place it went wrong yesterday."

An LLM call is a span. An agent run is a tree. Once you model the run as a tree, every hard question about an agent becomes a query against that tree. Here is how to build it, what each node should carry, and how to replay it when a run goes sideways.

The root span is the trajectory boundary

The single most useful thing you can add is a parent span that wraps the whole run. The OpenTelemetry GenAI conventions call it invoke_agent. It fires once per task and it is the parent of every chat and tool span underneath.

Without that parent, a trace is a flat list of chat spans and tool spans, and you rebuild the trajectory in your head from timestamps. That reconstruction breaks the first time two runs interleave. With the parent, your backend has a boundary. It can render a trajectory view, sum cost per task, count turns, and diff one run against another, all without you scripting anything.

from opentelemetry import trace

tracer = trace.get_tracer("triage-agent")

with tracer.start_as_current_span(
    "invoke_agent triage-agent"
) as root:
    root.set_attribute("gen_ai.agent.name", "triage-agent")
    root.set_attribute("gen_ai.agent.version", "2.1.0")
    root.set_attribute("gen_ai.conversation.id", session_id)
    # run the loop; child chat/tool spans nest under root

If you already instrumented single LLM calls, this is the whole migration. Wrap the outer loop. The existing gen_ai.* chat and tool spans nest under it unchanged. No second collector, no re-instrumentation.

Of the four attributes above, version is the one teams skip and regret. Agents regress quietly. A prompt tweak, a new tool on the whitelist, a model swap between two minor revisions all shift the trajectory distribution. When an eval regresses overnight, your first move is to filter by gen_ai.agent.version and check whether the agent changed between yesterday and today. If it did, the fix is in your version control. If it did not, the regression is in the model provider, a tool backend, or the data.

Each child span records a decision, not a response

Here is the mental shift. On a plain LLM call, the chat span records what the model said: tokens, model name, latency, maybe the message payload. That is a record of the response, and it is enough when answering was the only job.

Inside an agent, the model's output is rarely the user-facing answer. It is a decision. Call this tool with these arguments. Hand off to that agent. Stop and emit a final message. The response payload is not what you want on the span. The decision is. And a decision has structure: which branch of the loop the model took, which tool it picked, what arguments it chose, and why.

with tracer.start_as_current_span(
    "chat claude-sonnet-4-6"
) as chat:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=messages,
        tools=tools,
    )
    chat.set_attribute("gen_ai.agent.step", step)
    chat.set_attribute("gen_ai.agent.decision", "call_tool")
    chat.set_attribute(
        "gen_ai.agent.decision.tool", "search_kb"
    )
    chat.set_attribute(
        "gen_ai.usage.input_tokens", resp.usage.input_tokens
    )
    chat.set_attribute(
        "gen_ai.usage.output_tokens", resp.usage.output_tokens
    )

Keep decision to a small fixed vocabulary your harness owns: call_tool, handoff, final_answer, reflect, stop. Consistency is what lets you group on it later. When you build trajectory evals, you score runs by grouping on gen_ai.agent.decision and measuring how often each decision type leads to task completion. That query is impossible unless the attribute is on every step.

Set one integer on the root when the loop exits: gen_ai.agent.step.count, the final turn count. Guardrail alerts like "agent exceeded 25 steps" key off it directly. If your harness raises on a recursion limit, set it in the exception handler before you re-raise, so the span still carries the truth.

Read the tree and the pathology is obvious

Here is a clean run. Indentation is parent-child nesting, numbers are the wall-clock offset from the root in seconds.

invoke_agent triage-agent          0.000  4.812s
├─ chat claude-sonnet-4-6          0.004  1.102s
│    in=842 out=96  decision: call search_kb
├─ execute_tool search_kb          1.118  0.612s
│    args={"query":"refund 14 day"} result_len=3
├─ chat claude-sonnet-4-6          1.741  0.980s
│    in=1910 out=44  decision: call classify_ticket
├─ execute_tool classify_ticket    2.734  0.018s
│    args={"label":"billing/refund"}
├─ chat claude-sonnet-4-6          2.760  1.420s
│    in=2004 out=312 decision: call write_reply
├─ execute_tool write_reply        4.198  0.598s
└─ chat claude-sonnet-4-6          4.810  0.002s
     decision: final_answer

Four chat turns, three tool calls, input tokens climbing from 842 to 2004 as context accretes. The final chat span is a two-millisecond decision to answer. The model did not reflect, did not double-check, did not loop. That is what good looks like.

Now the same agent on a different ticket:

invoke_agent triage-agent          0.000  31.204s
├─ chat claude-sonnet-4-6          0.004  1.240s
│    decision: call search_kb
├─ execute_tool search_kb          1.244  0.590s
│    result_len=0
├─ chat claude-sonnet-4-6          1.840  1.510s
│    decision: call search_kb
├─ execute_tool search_kb          3.360  0.612s
│    result_len=0
...  [18 more search_kb retries]  ...
└─ chat claude-sonnet-4-6         30.920  0.280s
     decision: final_answer
     text: "I could not find this information."

Every execute_tool span is green. No tool errored. The run failed on a decision loop: the model kept asking the same query, kept getting zero rows, kept deciding to try again, and burned thirty seconds before giving up. You would never spot this on a single-call waterfall. You spot it because the root span shows the turn count at a glance and the trajectory view surfaces "this run called search_kb twenty times" as the top anomaly. The unit of debugging is the trajectory.

Handoffs nest as child invocations

Multi-agent systems keep the same shape. When a supervisor hands off to a specialist, the specialist's entire run is another invoke_agent span, parented under the supervisor's current chat span.

invoke_agent research-supervisor   0.000  18.440s
├─ chat claude-opus-4-6            0.004  2.110s
│    decision: handoff to web-searcher
├─ invoke_agent web-searcher       2.120  6.880s
│  ├─ chat claude-sonnet-4-6       2.122  0.810s
│  ├─ execute_tool web_search      2.940  1.402s
│  └─ chat claude-sonnet-4-6       4.350  1.680s
│       decision: final_answer
└─ chat claude-opus-4-6            9.010  1.380s
     decision: final_answer

Cost accounting falls out of the nesting. Sum the child chat spans of each invoke_agent and you get per-agent token spend. The supervisor's context is usually small; the specialists burn most of the bill. You cannot see that from summing all chat spans flat.

The common failure here is a framework that emits a flat list of chat spans for a multi-agent run instead of nested invoke_agent spans. The tree collapses to one line and the trajectory view goes useless. The fix is a one-line wrapper at each handoff: start a child invoke_agent before you call the specialist, end it after. Check for this first when a multi-agent trace looks wrong.

Replaying a run to find the break

When you get paged, run the same procedure every time.

First, filter by gen_ai.agent.version. If it jumped in the last hour, diff the versions. The regression is almost certainly there.

Second, filter by decision = final_answer and the failing outcome, then pull one bad run and read it top to bottom. Look for the first decision that surprises you, not the one that produced the bad output. The bad output usually sits three or four steps downstream of the broken decision. You want the upstream one.

Third, pull a passing run from before the regression and read them side by side. Nine times out of ten the difference is a single tool call now returning something different, or a chat span where the model picked a different tool than it used to.

Fourth, grep that one divergence across the whole population. If decision.tool = classify_ticket used to fire in 92% of runs and now fires in 74%, you have localized the regression. Fix it there.

This procedure fails in exactly one case: an incomplete tree. Chat spans with no parent, an invoke_agent with no children, a multi-agent run flattened to one level. Then you scroll raw spans and lose an hour. Emitting the full tree is what buys you the fifteen-minute debug instead of the two-hour one.

What the tree cannot tell you

A trajectory shows what the agent did. It does not tell you whether what it did was good. The twenty-retry run is obvious because zero results twenty times is visibly wrong. Most bad runs are not visibly wrong: a reasonable tool, reasonable arguments, a reasonable result, and a reply that is slightly off. Read that trace without knowing ground truth and you shrug.

Tracing is the substrate. Evals are the judgment layer that grades the trajectory, and every eval technique assumes the tree exists first. So before Monday, open your backend, pick one production agent, and confirm every run has an invoke_agent root with gen_ai.agent.name, gen_ai.agent.version, and a complete child tree. If it does not, fix that before anything else. You cannot grade a trajectory you cannot see.

If you are building the agents, Agents in Production walks through the loop, the handoff, and the harness that emits these spans. If you are trying to see inside them, Observability for LLM Applications is the tracing and evals half of the pair. Together they are The AI Engineer's Library, and this post lives at the seam where they meet.

Agent State Desync: Why Your Agent Forgets and How to Fix It

Gabriel Anhaia — Sat, 04 Jul 2026 09:49:12 +0000

Book: Agents in Production — Building, Tracing, and Shipping Multi-Step AI You Can Trust
Also by me: Observability for LLM Applications — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You give your agent a task: "book the Lisbon trip, stay under €900, prefer window seats." It searches flights. It calls the hotel API. It reserves a seat. On step seven, the pod restarts. A deploy, an OOM kill, a spot instance reclaimed. Does not matter which.

The user retries. The agent starts over from an empty messages list. It searches flights again. It calls the hotel API again. It reserves a second seat, because the first reservation happened in a process that no longer exists and nothing wrote it down. The agent has amnesia, and the amnesia just cost your user a duplicate booking.

This is state desync. The model's context and the real state of the task drifted apart, and the agent believed the wrong one.

Two kinds of state, and only one of them is durable

There are two things people call "agent state," and conflating them is where the bug lives.

The first is the model context: the messages list you send on each turn. System prompt, user turns, tool calls, tool results. This is short-term memory. It rides in the prompt and it lives in RAM.

The second is the real state of the task: which flights you already searched, which reservation you already made, which €340 you already spent. Some of that lives in the messages list too, but the authoritative copy lives in the outside world: in Stripe, in the hotel's booking system, in a row in your database.

When those two agree, the agent works. When they drift, the agent either repeats work it already did or skips work it never did. A crash is the fastest way to make them drift, because a crash wipes the RAM copy and leaves the world copy untouched.

The fix is not more memory. The fix is durability: write the trajectory somewhere that survives the process, and rebuild from it when the process comes back.

The scratchpad is the thing you actually need to persist

Inside the loop, the agent keeps a scratchpad: the Thought-Action-Observation history of the current task. Step one, I searched flights, I got these three. Step two, I picked the 09:40, I reserved seat 14A. The user never sees this. It exists so that on step seven the agent remembers what it did on step three.

That scratchpad is the state that matters. If it dies with the process, the agent forgets. So model it as an explicit object, not as a slice of the messages array you hope stays intact.

# scratchpad.py
from dataclasses import dataclass, field, asdict


@dataclass
class Step:
    thought: str
    action: str       # tool name
    args: dict
    observation: str


@dataclass
class Scratchpad:
    task_id: str
    task: str
    steps: list[Step] = field(default_factory=list)

    def record(self, thought, action, args, obs):
        self.steps.append(
            Step(thought, action, args, obs)
        )

    def to_dict(self) -> dict:
        return asdict(self)

    @classmethod
    def from_dict(cls, d: dict) -> "Scratchpad":
        steps = [Step(**s) for s in d["steps"]]
        return cls(d["task_id"], d["task"], steps)

to_dict and from_dict are the whole point. A scratchpad you can serialize is a scratchpad you can checkpoint. One you can only hold in memory is one you lose on the next OOM kill.

Checkpoint after every step, not at the end

The naive instinct is to save state when the task finishes. That is exactly backwards. A task that finished does not need a checkpoint. The one that dies on step seven does, and it dies before it finishes, so you have to write after every step.

Here is a durable store backed by SQLite. Swap it for Postgres or Redis in production; the shape is the same.

# checkpoint.py  -- stdlib only
import json
import sqlite3
from scratchpad import Scratchpad

_DDL = """
CREATE TABLE IF NOT EXISTS checkpoints (
    task_id TEXT PRIMARY KEY,
    state   TEXT NOT NULL,
    updated INTEGER NOT NULL
)
"""


class CheckpointStore:
    def __init__(self, path: str = "agent.db"):
        self.db = sqlite3.connect(path)
        self.db.execute(_DDL)
        self.db.commit()

    def save(self, pad: Scratchpad) -> None:
        self.db.execute(
            "REPLACE INTO checkpoints VALUES "
            "(?, ?, strftime('%s','now'))",
            (pad.task_id, json.dumps(pad.to_dict())),
        )
        self.db.commit()

    def load(self, task_id: str) -> Scratchpad | None:
        row = self.db.execute(
            "SELECT state FROM checkpoints "
            "WHERE task_id = ?",
            (task_id,),
        ).fetchone()
        if row is None:
            return None
        return Scratchpad.from_dict(json.loads(row[0]))

Two details earn their place. REPLACE INTO on a task_id primary key means each save overwrites the last checkpoint for that task, so the store holds one row per in-flight task, not a growing log. And save() commits every call. That commit is the durability boundary. If the process dies one instruction after it returns, the checkpoint is on disk.

Rebuild, then continue where you left off

Now the loop. On start, try to load a checkpoint. If one exists, replay it into the model context and keep going from the step after the last one recorded. If none exists, this is a fresh task.

# agent.py  -- pip install "anthropic==0.69.0"
from anthropic import Anthropic
from scratchpad import Scratchpad
from checkpoint import CheckpointStore

client = Anthropic()
store = CheckpointStore()
MODEL = "claude-sonnet-4-5"


def context_from(pad: Scratchpad) -> list[dict]:
    lines = [f"Task: {pad.task}"]
    for i, s in enumerate(pad.steps, 1):
        lines.append(
            f"{i}. {s.action}({s.args}) "
            f"-> {s.observation[:200]}"
        )
    return [{"role": "user",
             "content": "\n".join(lines)}]


def run(task_id: str, task: str) -> Scratchpad:
    pad = store.load(task_id) or Scratchpad(
        task_id=task_id, task=task,
    )
    if pad.steps:
        print(f"resumed at step {len(pad.steps)}")

    while not done(pad):
        resp = client.messages.create(
            model=MODEL,
            max_tokens=1024,
            messages=context_from(pad),
        )
        thought, action, args = decide(resp)
        obs = dispatch(action, args)
        pad.record(thought, action, args, obs)
        store.save(pad)          # durability boundary
    return pad

The line that matters is store.save(pad) immediately after pad.record(...). The scratchpad in memory and the scratchpad on disk are never more than one step apart. When the pod restarts and the user retries with the same task_id, store.load returns the seven steps that already happened, context_from replays them into the model's context, and the agent picks up at step eight instead of step one.

The model gets its memory back by reading state you owned, not state you hoped survived.

The trap: side effects that already happened

Rebuilding the scratchpad closes the gap between context and your own storage. It does not close the gap between your storage and the outside world. That seat reservation on step six was a real API call with a real effect. Replaying the scratchpad tells the agent it reserved a seat. It does not un-reserve the duplicate if step six ran twice because the crash landed between the API call and the store.save.

The honest fix is idempotency at the effect boundary. Every tool call that mutates the world carries a key derived from the task and the step, and the downstream system dedupes on it.

def reserve_seat(task_id, step, flight, seat):
    key = f"{task_id}:{step}:reserve"
    return booking_api.reserve(
        flight, seat, idempotency_key=key,
    )

Now a replayed step six reaches the booking API with the same key it used the first time, and the API returns the original reservation instead of making a second one. Stripe, most booking systems, and any well-built internal API accept an idempotency key for exactly this. Checkpointing gives the agent its memory back. Idempotency keys keep that memory from turning into duplicate charges.

The rule

Model context is bounded by the window and lives in RAM. Real state is bounded by your storage and the outside world. A crash wipes the first and leaves the second, and desync is what you get when the agent trusts the wrong one on resume.

Serialize the scratchpad. Checkpoint after every step, not at the end. Rebuild from the checkpoint on restart. Put an idempotency key on every tool call that touches the world. Do those four things and a mid-trajectory crash becomes a resume instead of a duplicate booking.

If you are building agents that have to survive real infrastructure (pods that restart, deploys mid-task, spot instances that vanish), Agents in Production is the book for the loop, the checkpointing, and the idempotency patterns above. Its companion, Observability for LLM Applications, is where you learn to trace the resume so you can see, after the fact, exactly which step the agent replayed and whether it double-fired an effect. Together they are The AI Engineer's Library.

The Agent Production-Readiness Checklist You Can Run Before Shipping

Gabriel Anhaia — Sat, 04 Jul 2026 09:47:44 +0000

Book: Agents in Production — Building, Tracing, and Shipping Multi-Step AI You Can Trust
Also by me: Observability for LLM Applications — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

In February 2024, a tribunal ordered Air Canada to honor a refund policy that its support chatbot had invented on the spot. The airline argued it was not responsible for what its own bot said. The tribunal disagreed. The bot spoke for the company, so the company owned the answer.

That case is the whole problem with shipping an agent in one sentence. The agent talks to real users, touches real systems, and spends real money, and when it goes wrong the incident is yours. CPU is fine. Latency is fine. Everything returns a 200. The bot answered, and the answer was wrong.

So before you flip the traffic flag, you want a list you can walk top to bottom and honestly answer yes to. Not a maturity model. Six checks. Each one is a hard thing to fake, and each one closes a hole that has already burned a named team.

1. Every run emits a trace you can open

When you get paged on an agent at 3 a.m., your first move is not the metrics dashboard. It is the trajectory viewer. The trace is the runbook.

That only works if the trace exists and carries enough to reconstruct the decision. Emit a trace ID on every run, expose it to the user for support, and put the model, prompt version, tools called, tokens, and cost on every span.

You do not need a heavy framework to start. A span is a dict with a start, an end, and some attributes.

import time
import uuid
import json


def trace_run(user_id, prompt_version):
    return {
        "trace_id": str(uuid.uuid4()),
        "user_id": user_id,
        "prompt_version": prompt_version,
        "started_at": time.time(),
        "spans": [],
    }


def record_span(trace, name, **attrs):
    trace["spans"].append({"name": name, **attrs})

Wrap the model call so the usage lands on the span automatically. The Anthropic SDK returns token counts on every response.

from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-opus-4-8"  # pinned, never "latest"


def traced_call(trace, messages, tools):
    resp = client.messages.create(
        model=MODEL,
        max_tokens=1024,
        messages=messages,
        tools=tools,
    )
    record_span(
        trace,
        "model_call",
        model=MODEL,
        input_tokens=resp.usage.input_tokens,
        output_tokens=resp.usage.output_tokens,
        stop_reason=resp.stop_reason,
    )
    return resp

Export the spans over an OpenTelemetry-compatible pipeline once the shape settles. The point of check one: when the page hits, the viewer has something to show.

2. You froze an eval set before launch, not after

The fix you ship at 4 a.m. should not introduce a new regression at 4:30. That is what an eval set buys you, and you need it in place before the first user, not after the first incident.

Freeze at least 50 real trajectories. Run two kinds of check against them on every deploy. One deterministic check: string match, tool-call match, or a unit test. One LLM-as-judge check for the fuzzy parts, correctness and tone.

The deterministic ones are cheap and catch the dumb regressions.

def eval_tool_choice(trajectory, expected_tool):
    calls = [s for s in trajectory["spans"]
             if s["name"] == "tool_call"]
    if not calls:
        return False, "no tool called"
    got = calls[0]["tool"]
    return got == expected_tool, f"got {got}"

The judge check hands the trajectory to a model and asks a narrow question with a schema, so the output is parseable rather than prose.

def judge_correctness(question, answer):
    resp = client.messages.create(
        model=MODEL,
        max_tokens=512,
        messages=[{
            "role": "user",
            "content": (
                "Score the answer 1-5 for factual "
                "correctness. Reply as JSON with keys "
                f"score and reason.\nQ: {question}\n"
                f"A: {answer}"
            ),
        }],
    )
    text = resp.content[0].text
    return json.loads(text)

Have a human read 20 to 50 real traces before the first launch. No eval set replaces one engineer reading what the agent actually did.

3. Guardrails live in code, not in the prompt

A guardrail you can argue away with a clever prompt is not a guardrail. It is a suggestion. The real ones are deterministic checks sitting outside the model's reasoning: an input filter that refuses out-of-scope requests, an output scan for PII before the response leaves, and a loop detector that breaks when the same tool call repeats with the same arguments.

The loop detector is the one people skip and regret. An agent happy to call a broken tool forever will do exactly that.

def make_loop_guard(limit=3):
    seen = {}

    def check(tool_name, tool_input):
        key = (tool_name, json.dumps(tool_input,
                                     sort_keys=True))
        seen[key] = seen.get(key, 0) + 1
        if seen[key] >= limit:
            return False, f"repeated {key[0]}"
        return True, None

    return check

Keep each guardrail testable and logged. When one fires, that event goes on the trace from check one, so the postmortem can see the agent was stopped and why.

4. Every axis of spend has a cap

Developers have described runaway agent loops that burned five figures in credits when a tool misbehaved and the loop had no ceiling. The shape is generic: an autonomous loop without a budget will, at some rate, find a way to spend money unrelated to the work.

Cap every axis. Max steps per trajectory. Max tokens per trajectory. Max dollars per trajectory. A per-user daily budget and a per-tenant daily budget on top. Check the budget before the call, not after, because after means you already paid for the call that put you over.

from dataclasses import dataclass


@dataclass
class Budget:
    max_steps: int = 25
    max_tokens: int = 200_000
    max_usd: float = 2.0


def over_budget(budget, steps, tokens, usd):
    if steps >= budget.max_steps:
        return "step_budget"
    if tokens >= budget.max_tokens:
        return "token_budget"
    if usd >= budget.max_usd:
        return "usd_budget"
    return None

Return the reason as a value, not an exception. The user-facing answer differs when the model finished versus when a cap stopped it: one shows the answer, the other shows a partial with a "continue?" hatch.

5. No tool combination forms the dangerous trio

Meta's Agents Rule of Two is the clearest practical guidance on agent security right now. Within one session, an agent should satisfy at most two of these three: it processes untrusted input, it accesses private data or sensitive systems, and it can change state or communicate externally. All three at once is the pattern behind a class of 2025 agent breaches, and it means you need a human in the loop.

Audit it in code, and re-run the audit whenever a tool is added.

def rule_of_two_violation(tools):
    props = {"untrusted_input", "sensitive_access",
             "external_effect"}
    active = set()
    for t in tools:
        active |= props & set(t.get("properties", []))
    if len(active) == 3:
        return True, sorted(active)
    return False, sorted(active)

Tag each tool with the properties it carries. A web-fetch tool processes untrusted input. A database read touches private data. An email send communicates externally. When the audit lights up all three, the launch decision is not "ship carefully." It is "put a human on the confirmation step, or split the tools across sessions."

6. There is a runbook, and it points at the trace

Agent incidents look nothing like infra incidents. What breaks is semantics. So the runbook cannot start with the metrics dashboard.

Write it down before launch. The first line says: open the trajectory viewer before any dashboard. Page on judge-score drops and cost-p99 spikes, not only latency and error rate. Test the kill switch on a schedule rather than discovering during the incident that it never worked. And require two fields on every postmortem: a trajectory excerpt, and a new eval-set case that reproduces the failure.

That last one is what makes the list compound. Every incident that gets past the first five checks becomes a frozen eval case within 24 hours, so the same failure cannot ship twice. The list is not a gate you pass once. It is the loop that keeps the agent honest after you stop watching it.

Run it as a conversation

Print the six checks. Walk them with another engineer a week before go-live. For each one, either it is done, it is waived with a written reason and a named owner, or it is blocking. When the list is clean, set the flag to a small cohort and open the trajectory viewer in another tab.

The point is not the checkboxes. It is turning "is this ready" from a vibes question into a set of questions with answers. Vibes favor whoever wants to ship. A list makes someone say which items they are waiving, and lets someone else say no.

Start small. Pick an internal agent nobody will sue you over. Wire the trace, freeze the evals, cap the budget, audit the tools, write the runbook. Watch it for a week. Then build the one the lawyers care about.

If you want the long version of any of these six, that is the two books. Agents in Production is the machinery: the loop, the guardrails, the kill switch, the postmortem template. Observability for LLM Applications is the instruments underneath it: spans, traces, evals, and cost per call. They are the two halves of The AI Engineer's Library, and together they are the argument behind this checklist.

Multi-Agent Coordination: Message-Bus Patterns That Keep Agents Sane

Gabriel Anhaia — Sat, 04 Jul 2026 09:46:25 +0000

Book: Agents in Production — Building, Tracing, and Shipping Multi-Step AI You Can Trust
Also by me: Observability for LLM Applications — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

In June 2025 two engineering teams posted opposite advice in the same week.

Anthropic shipped How we built our multi-agent research system: an orchestrator dispatching subtasks to worker agents, beating a single agent by 90.2% on breadth-first research. A few days later Cognition, the team behind Devin, published Don't Build Multi-Agents, arguing that parallel subagents without shared context produce fragile systems.

Both were right. They were describing different workloads. Anthropic's research agent is embarrassingly parallel: four workers go read four things and come back with four small summaries. Cognition's target is writing code, where every edit depends on every other edit and context cannot be sliced.

Most people get the plumbing wrong, not the decision. Once you have two agents that need to coordinate, you have to choose how they talk. That choice decides your failure modes long before the models do.

Handoffs vs a shared bus

There are two ways to wire agents together, and they fail differently.

A handoff transfers control. Agent A finishes, hands the whole conversation to Agent B, and steps out. This reads well in a demo. In production it means the transcript grows on every hop, and by the fourth agent you are paying to re-read a conversation nobody trimmed. Handoffs also lose the parent: once A hands off to B, nobody is holding the original task to check the final answer against it.

A shared bus keeps a supervisor in charge. Workers never talk to each other. They receive a small typed task, do the work, and return a small typed artifact to the supervisor, which composes the result. This is the shape of Anthropic's research system, and it is the default you should reach for.

The test is one question: does a worker need to see what a sibling just produced? If yes, you do not have parallel workers. You have a sequential pipeline pretending to be a team, and you should run it as one ordered chain, not as free-form handoffs.

Here is the bus shape in the bare Anthropic SDK. Three workers fan out, the supervisor merges. No worker touches another worker.

import asyncio
from anthropic import AsyncAnthropic

client = AsyncAnthropic()
MODEL = "claude-sonnet-4-6"

WORKERS = {
    "researcher": (
        "Return 5 cited facts about the topic."
    ),
    "analyst": (
        "Return the 3 biggest risks and why."
    ),
    "writer": (
        "Return a 120-word summary."
    ),
}

async def run_worker(role, system, task):
    resp = await client.messages.create(
        model=MODEL,
        max_tokens=800,
        system=system,
        messages=[{"role": "user", "content": task}],
    )
    return role, resp.content[0].text

async def supervise(task):
    jobs = [
        run_worker(role, sys, task)
        for role, sys in WORKERS.items()
    ]
    done = await asyncio.gather(
        *jobs, return_exceptions=True
    )
    parts = {}
    for item in done:
        if isinstance(item, Exception):
            continue  # log, decide, maybe retry
        role, text = item
        parts[role] = text
    return parts

Three things earn their place. asyncio.gather is the fan-out, so wall-clock time is one worker, not three. return_exceptions=True stops one flaky worker from unwinding the whole run. And nothing in WORKERS reads another worker's output. Roles share only the original task. That last property is what makes the pattern safe to parallelize.

Give every message an envelope

The moment workers run on different machines or survive a crash, the shared dictionary stops working and you need a message bus. And every message that crosses it should carry the same fixed envelope, not a bare payload.

{
  "task_id": "t_8f2c",
  "parent_task_id": "t_7a1b",
  "trace_id": "0af7651916cd43dd",
  "source_agent_id": "supervisor_v3",
  "cost_so_far_usd": 0.42,
  "step_budget_remaining": 7,
  "payload": { "...": "..." }
}

The envelope is what ties a message back to an OpenTelemetry trace, tells you whose fault a bad result was, and (this is the part people skip) carries the budget. cost_so_far_usd and step_budget_remaining travel with the work. A supervisor that sees a child over budget can refuse to forward its next message, and the child's workers terminate when their envelope stops arriving. Without a shared envelope, the supervisor has no way to cancel work it dispatched a minute ago.

Enforce it in one place. Worker code should never publish raw bytes to a topic.

def publish(bus, topic, payload, *, ctx):
    if ctx.steps_left <= 0:
        raise StepBudgetExhausted(ctx.task_id)
    if ctx.cost_so_far >= ctx.cost_cap:
        raise CostCapExceeded(ctx.task_id)
    bus.send(topic, {
        "task_id": ctx.task_id,
        "parent_task_id": ctx.parent_task_id,
        "trace_id": ctx.trace_id,
        "source_agent_id": ctx.agent_id,
        "cost_so_far_usd": ctx.cost_so_far,
        "step_budget_remaining": ctx.steps_left,
        "payload": payload,
    })

The two guard clauses are the whole point. A bus without budget enforcement is how a single-agent runaway loop becomes a runaway loop across your whole fleet.

Avoid the context dump

The most common way a multi-agent system gets expensive is a habit, not a bug: passing the full conversation to every agent because it is easy.

Peer chat where everybody reads everything is O(n²) in token cost. Worse, it amplifies error. One agent's mistake becomes the next agent's premise, and the whole group drifts together because they were trained on similar data. Galileo measured this as a 17× error-amplification effect in poorly-scoped multi-agent runs.

The fix is a schema at the boundary. A worker returns a typed artifact, not prose. Validate it before it goes back on the bus, and reject anything that does not fit.

from pydantic import BaseModel, ValidationError

class RiskReport(BaseModel):
    risks: list[str]
    severity: int  # 1..5

def accept(role, raw_text):
    try:
        return RiskReport.model_validate_json(raw_text)
    except ValidationError:
        return None  # ask again, don't forward junk

A worker that has to return five risks and a severity cannot smuggle a 4,000-token transcript into the supervisor's context. The type is the compression. If an output is longer than the prompt that produced it, you have a compression problem wearing a parallelism costume.

In TypeScript the same guard is a Zod parse at the seam:

import { z } from "zod";

const RiskReport = z.object({
  risks: z.array(z.string()),
  severity: z.number().int().min(1).max(5),
});

function accept(raw: string) {
  const parsed = RiskReport.safeParse(JSON.parse(raw));
  return parsed.success ? parsed.data : null;
}

Kill the infinite chatter loop

The failure that scares people most is two agents talking forever. Agent A waits on B's report; B cannot finish without A's approval. Neither notices it is blocking the thing it is waiting on. Both keep burning tokens. It is the multi-agent version of a runaway recursion, and the mitigation is the same three habits.

First, a step counter on every trajectory, checked at the bus, that kills the run before the deadlock gets expensive. That is the step_budget_remaining field doing its job.

Second, a termination condition written before the first message. For any peer or debate setup, decide the stop rule up front:

async def debate(task, max_rounds=3):
    transcript = []
    for _ in range(max_rounds):
        claim = await propose(task, transcript)
        transcript.append(("proposer", claim))
        attack = await critique(claim, transcript)
        transcript.append(("critic", attack))
        if "no objection" in attack.lower():
            break
    return await judge(task, transcript)

"Three rounds, then the judge decides." Not "keep going until you agree." Models are agreeable. Two agents in an open loop will almost always converge, and what they converge on is almost always wrong in the same direction. The turn cap is not a safety net. It is the design.

Third, a timeout on every await. An agent that dies mid-task must not leave a sibling blocked forever. Pair the step budget with a wall-clock deadline and the deadlock becomes a bounded, retryable failure instead of an open invoice.

The one rule to keep

If a worker needs to see what a sibling produced, you do not have a parallel team. Keep workers isolated, hand them small typed tasks, make them return small typed artifacts, and put the budget in the envelope. Do that and the supervisor-worker shape stays cheap, traceable, and debuggable. Skip it and the same pattern turns into a group chat that argues with itself until the bill arrives.

If you want the full version of this — the four coordination shapes, the message-bus picker across Redis Streams, Kafka, and NATS, and the distributed-state patterns that keep two agents from corrupting the same row — that is what Agents in Production is for. Its companion, Observability for LLM Applications, is the tracing and cost-accounting side: how you make that shared trace_id show up as one trajectory you can read top to bottom. Together they are The AI Engineer's Library.

Incident Response When Your Agent Is on Fire: A Runbook

Gabriel Anhaia — Sat, 04 Jul 2026 09:45:04 +0000

Book: Agents in Production — Building, Tracing, and Shipping Multi-Step AI You Can Trust
Also by me: Observability for LLM Applications — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

The dashboard is green. Latency is flat. The error rate has not
moved in six hours. Then support forwards an email: a customer is
asking why the agent emailed their landlord instead of their lawyer.
By the time you finish reading, it has done it again, to someone
else.

That is what an agent incident looks like. Not a spike, not a page.
An email. The platform is fine and the product is broken. Agents
fail quietly: the HTTP call succeeds, the model returns well-formed
JSON, every span is a 200. What broke lives between the spans. The
agent picked the wrong tool, or looped on the right one, or was
steered by a string it read from an untrusted input.

This is the first five minutes. Not the postmortem, not the fix. The
five minutes where your job is to stop the bleeding before you
understand the cut. Print this and tape it to the wall.

Minute one: flip the kill switch

You do not debug first. You stop the agent first. The Replit agent
that ran destructive commands against a production database during a
code freeze, deleting live records, is the reference case. Reported
by Fortune
and logged as AI Incident Database entry 1152.
The window between "something is wrong" and "everything is off"
is where the blast radius grows.

The kill switch is a boolean gating every agent invocation, wired at
the outermost entrypoint so any on-call engineer can find it in
thirty seconds.

# agent/service.py
import ldclient

def run_agent(user_id: str, task: str) -> AgentResponse:
    flags = ldclient.get()
    ctx = build_context(user_id)
    if not flags.variation("agent.enabled", ctx, False):
        return static_fallback_response(task)
    return agent.invoke({"task": task, "user": user_id})

The flag defaults to False. A misconfigured flag client turns the
agent off, not on. That is the correct direction of failure for a
tool that can email your customers. The fallback is not clever. It
is a pre-written, legal-approved message: "We're investigating an
issue with this feature. Your request has been recorded and a human
will follow up within one business day." Write it before the
incident. During the incident you do not want to be debating wording
with PR while the meter runs.

Minute two: freeze the budget

Some incidents do not want the whole agent off. A runaway loop wants
its spend capped. Claude Code Issue #44726
(April 2025) is the case: users filed a billing bug reporting
input-to-output token ratios of 74:1 and 175:1 on sessions that
normally run 5:1. The reported symptom was a compounding loop where
context grew unbounded across tool calls. The slogan from that class
of incident, via sanj.dev:
"AI agents don't crash, they spend."

A budget freeze converts an unbounded financial event into a bounded
one. The agent still fails; the invoice stops metastasising. If you
already ship per-trajectory budgets, an incident freeze is a global
tightening of the same knob.

# agent/budget.py
def check_budget(spent_usd: float, caps: dict) -> str | None:
    if spent_usd >= caps["hard"]:
        return "hard_cap"          # stop the trajectory
    if spent_usd >= caps["freeze"]:
        return "freeze"            # incident mode: refuse new runs
    return None

During an incident you drop caps["freeze"] to near the current p50
so new trajectories refuse to start while in-flight ones drain. Wire
this check before the model call. If you check after, you already
paid for the call that put you over.

Minute three: triage the trajectory

Now you look. Not at Grafana, not at Kibana, not at the deploy log.
Open the trajectory viewer in whatever agent-observability tool you
wired up (Langfuse, Arize, Braintrust, Phoenix) and pull the
failing trace_id. The alert should have carried that ID as a link.
If it didn't, that is the first thing you fix after the incident.

Read the last five tool calls before the failure. Read their inputs,
their outputs, and what the model wrote between them. You are hunting
for the step where the trajectory stopped being the one you would
have chosen. That step is almost never the final step. It is three
or four steps upstream, where the agent made a small commitment to a
wrong path and spent the rest of the run defending it.

One rule for reading the reasoning text: trust the tool calls,
distrust the prose. The model writes "I will carefully verify the
target environment before executing any mutation," and the next tool
call is execute_sql against db://prod with no verification
between. The prose is post-hoc rationalisation. The tool calls are
what happened.

1. Grab trace_id from the alert.
2. Open the trajectory viewer; load the full run.
3. Scroll to the end, then walk backwards.
4. For each tool call: right tool? right arguments?
5. For each model turn: did reasoning match the inputs?
6. Diff against a golden run for the same input class.
7. Name the off-rails step in one sentence.

Keep a golden trajectory for every major input class — a
known-good run captured during development. The diff against the
failing run is faster than reading either one alone.

Minute four: check the blast radius

You have a hypothesis. Before you fix anything, answer one question:
how many users has this already reached, and is it still spreading?

The intake shape of an agent incident hides this. It arrives through
one support ticket, so it feels like one user. It is usually not one
user. Query the trace store for every trajectory in the incident
window that matches the off-rails signature.

# scripts/blast_radius.py
def blast_radius(traces, signature, window):
    hit = [
        t for t in traces
        if t.start >= window.start
        and matches(t, signature)
    ]
    users = {t.user_id for t in hit}
    return {
        "trajectories": len(hit),
        "distinct_users": len(users),
        "still_open": any(t.status == "running" for t in hit),
        "user_ids": sorted(users),
    }

Two branches. If still_open is true, your kill switch or freeze did
not fully take — go back to minute one and confirm the flag actually
flipped in every region. If it is false but distinct_users is
large, you have a customer-comms problem, not just a code problem.
A Canadian tribunal held Air Canada liable for what its chatbot told
a customer (CBC):
companies own what their agents say. If the agent promised something
wrong to 200 people,
legal needs the list, not a summary.

Minute five: capture the eval before you fix

The fix is the easy part and the trap. You patch the guardrail, the
agent stops misbehaving, everyone goes back to bed, and the same
class of failure ships again next quarter with a different trace ID.
The thing that stops the repeat is the eval, and you capture it now,
while the failing input is still in front of you, not later.

Pull the exact input that sent the agent off the rails and add it to
the frozen eval set as a regression case.

# evals/regressions.py
def add_regression(trace, verdict, eval_path):
    case = {
        "id": trace.trace_id,
        "input": trace.root_input,
        "off_rails_step": trace.flagged_step,
        "expected": verdict,       # what the agent should do
        "incident": trace.incident_id,
    }
    append_case(eval_path, case)
    return case["id"]

This is the field most agent postmortems skip and the one that makes
the difference. A traditional postmortem asks "was a deploy
involved." For an agent the answer is often no — the deploy was two
weeks ago, the model started drifting last Tuesday, nobody touched
anything. The question that generalises is "what input broke it, and
is it in the eval set now." No incident is closed until that case is
merged and the suite runs green against your fix.

The muscle you build before the fire

None of these five moves work if the first time you try them is
during a real incident. Run a gameday once a quarter: inject a
failure mode into staging and page the on-call engineer for real.
Time how long it takes them to flip the kill switch, freeze the
budget, find the off-rails step, and check the blast radius. The
first gameday always goes badly. That is the point. It tells you
which runbook lines are load-bearing and which are fiction, before a
customer finds out for you.

The AI Engineer's Library is the long version of this page. Agents
in Production covers building and shipping the kill switches,
budgets, and gamedays so they are real instead of theoretical, and
Observability for LLM Applications covers the tracing, judge
scores, and eval sets that make the trajectory readable at 03:00.
The runbook only works if the trace was there before the fire
started.

Deploying Agents: Containers, Orchestration, and Scaling the Loop

Gabriel Anhaia — Sat, 04 Jul 2026 09:43:52 +0000

Book: Agents in Production — Building, Tracing, and Shipping Multi-Step AI You Can Trust
Also by me: Observability for LLM Applications — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

The agent works on your laptop. It passes evals. Your manager asks when it ships and you say Monday, because the modeling is done. Then you try to put it behind a load balancer and it falls apart, because you deployed it like a web service.

An agent is not a web service. A web service answers in milliseconds and forgets. An agent thinks for minutes, burns tokens across two or three providers, streams partial output to a browser, and sometimes decides to call delete_invoice on the eighth turn. Every deployment decision you make flows from one question: what does this thing do to your infrastructure while it is running?

Here is how to package it, where to hold state, and how to scale a workload whose bottleneck is a model call you do not control.

The shape is decided by the longest step

The single rule that saves you the most pain: an agent's deployment shape is decided by its longest step, not its average step.

A support chatbot answers in two seconds. A code-review agent thinks for six minutes. A research agent runs for forty. You cannot put all three behind the same HTTP endpoint and expect any of them to survive. Pick the pattern that matches the longest step, then cap the rest with timeouts.

Under 30s → stateless HTTP endpoint (Cloud Run, Fly.io).
30s to 5m with a user watching → streaming over WebSocket or SSE.
5m to an hour, async → queue plus worker (Temporal, Inngest, or Redis).
Longer than an hour → still queue plus worker, whether you like it or not.

Do not hold an HTTP request open for forty minutes. Something you did not know existed will kill it at the worst moment: a proxy, a CDN, a load-balancer idle timeout.

Package it: pin everything, drop root

The base image is the same across every pattern. Pin your Python, pin your SDKs, run as a non-root user, install nothing you do not need.

# Dockerfile
FROM python:3.13-slim-bookworm AS builder
ENV PIP_NO_CACHE_DIR=1
WORKDIR /build
COPY requirements.txt .
RUN pip wheel --wheel-dir /wheels -r requirements.txt

FROM python:3.13-slim-bookworm AS runtime
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1
RUN groupadd -r agent && useradd -r -g agent agent
WORKDIR /app
COPY --from=builder /wheels /wheels
COPY requirements.txt .
RUN pip install --no-index \
    --find-links=/wheels -r requirements.txt
COPY app/ ./app/
USER agent
EXPOSE 8000
CMD ["uvicorn", "app.main:app", \
     "--host", "0.0.0.0", "--port", "8000"]

Two things earn their keep. The multi-stage build compiles wheels in stage one and copies only the runtime into stage two, so no build toolchain ships to production. And slim-bookworm is 130 MB against 1.1 GB for the default image. As a rough estimate, that smaller pull shaves seconds off cold pod start when you scale up under load.

Never bake an API key into the image. The runtime injects it. On Kubernetes that is a mounted Secret; on GCP it is Secret Manager with Workload Identity; on Fly it is fly secrets set. The image has no credentials, the agent reads them at boot, and it never logs them.

Pin exact versions in requirements.txt. The SDK field names drift, and a build that worked in February will break in July if the tags float:

anthropic==0.94.1
langgraph==1.1.6
litellm==1.75.1
fastapi==0.118.0
uvicorn[standard]==0.34.0
redis==5.2.1
tenacity==9.1.2

Stateless first: hold state in Redis, not the process

Reach for stateless unless you have a concrete reason not to. Each request starts a fresh agent. Conversation history, tool results, the scratchpad — all of it lives in Redis or Postgres, keyed by a session ID the client sends in. The process holds nothing between requests, so any pod can serve any request and a rolling deploy loses no memory.

# app/main.py
from fastapi import FastAPI
from pydantic import BaseModel
from anthropic import AsyncAnthropic
import redis.asyncio as redis
import json

app = FastAPI()
r = redis.from_url("redis://cache:6379/0")
client = AsyncAnthropic()

class Req(BaseModel):
    session_id: str
    message: str

@app.post("/chat")
async def chat(req: Req):
    key = f"hist:{req.session_id}"
    raw = await r.get(key)
    history = json.loads(raw) if raw else []
    history.append(
        {"role": "user", "content": req.message}
    )
    resp = await client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=history,
    )
    reply = resp.content[0].text
    history.append(
        {"role": "assistant", "content": reply}
    )
    await r.set(key, json.dumps(history), ex=3600)
    return {"reply": reply}

The state is the session, not the server. That is the whole trick. When you need a durable, long-running agent instead (one that must survive a worker restart mid-run), you move to a queue and a workflow engine, and the state lives in the workflow store rather than in Redis. Do not fake durability by keeping it in process memory.

Health checks: cheap liveness, expensive readiness

Kubernetes probes are where agent deployments quietly break, because the defaults assume a fast service.

Split the two probes. /healthz is cheap: did the process start, is the event loop alive. /readyz is expensive: can the agent actually reach its provider. A pod that boots with a bad API key should never take traffic.

# app/probes.py
from fastapi import APIRouter, Response
from anthropic import AsyncAnthropic

router = APIRouter()
client = AsyncAnthropic()

@router.get("/healthz")
async def healthz():
    return {"status": "ok"}

@router.get("/readyz")
async def readyz():
    try:
        await client.models.list()
        return {"status": "ready"}
    except Exception:
        return Response(status_code=503)

Liveness should almost never kill the pod. A legitimate long agent turn can make the event loop look stuck, and the standard advice, kill it after three failures, will murder a run that was working fine. Point liveness at /healthz with a generous failure threshold, and set terminationGracePeriodSeconds larger than your worst-case turn so a rolling deploy lets in-flight runs finish instead of severing them.

Scaling: the bottleneck is a lock you do not own

Here is what makes agents different from a normal backend. Adding workers does not add throughput past a point, because every provider caps you on requests per minute and tokens per minute, per key. Scale your pool from 10 to 100 and those limits do not move. You will just generate more 429s.

So the first thing to wire is not autoscaling. It is a semaphore per (provider, model) pair, sized to your real budget, plus retry with backoff and jitter for the noise that slips through.

import asyncio
from tenacity import (
    retry, stop_after_attempt,
    wait_exponential_jitter,
)

# One gate per model, sized to your RPM budget.
gate = asyncio.Semaphore(64)

@retry(
    stop=stop_after_attempt(5),
    wait=wait_exponential_jitter(initial=1, max=30),
)
async def call_model(client, **kw):
    async with gate:
        return await client.messages.create(**kw)

The workload blocks on I/O. The model call is a network wait, so concurrency is nearly free at the runtime level and expensive at the provider level. That inversion is the whole scaling story. Your CPU sits idle while a hundred coroutines wait on Claude. So do not autoscale on CPU alone; it will read near zero while you are completely saturated. Scale on in-flight request count, and cap in-flight runs per pod (four is a sane start for a 1-CPU pod with 30-second turns) so a single box does not fan out a thousand concurrent calls and eat your whole rate limit.

For a TypeScript agent the same gate is a small counting semaphore around the call:

// gate.ts — cap concurrent model calls
let active = 0;
const queue: Array<() => void> = [];
const LIMIT = 64;

export async function withGate<T>(
  fn: () => Promise<T>,
): Promise<T> {
  if (active >= LIMIT) {
    await new Promise<void>((r) => queue.push(r));
  }
  active++;
  try {
    return await fn();
  } finally {
    active--;
    queue.shift()?.();
  }
}

When the pool saturates, the queue grows. That is your signal. Shed load at the ingress (return 429 or park the work on a durable queue) rather than letting the agent thrash against the provider. A queue that holds work is also what carries you through a provider outage: the run waits for the model to come back instead of failing.

Route through a gateway, not straight at the provider

Point your agent at one gateway that owns fallback, not at a provider SDK directly. When Claude Sonnet rate-limits, the gateway retries on the next model in the chain and your agent code never sees it. LiteLLM Proxy is the self-hosted default; OpenRouter and Portkey are the managed options.

The catch: a fallback chain you have never exercised is a fallback chain you do not have. The failover target needs the same rate-limit headroom as your primary, and a different model means a different tokenizer and tool-call schema. Test the chain against a fixed eval set, reported as its own score, and drill it — force ten percent of traffic through the fallback once a month. If it cannot carry ten percent on a quiet Tuesday, it will not carry a hundred percent at 3 AM.

The deployment is the easy part

Five patterns, a Dockerfile, a semaphore, and a fallback chain get you something that ships on Monday and does not fall over on Tuesday. The container runs, the gateway routes around outages, the queue holds work when nothing else can. That part is mechanical.

The hard part is what happens at 3 AM when the agent starts returning confident answers to questions nobody asked and burning tokens on a loop that never terminates — which is why deployment is only worth doing on top of tracing and evals. Agents in Production walks the five patterns, the scaling limits, and the degradation ladder end to end; Observability for LLM Applications, its companion in The AI Engineer's Library, is the tracing, evals, and cost-accounting layer that tells you the loop went wrong before your users do.

The 2 a.m. Runaway Loop: Detecting and Killing an Agent That Won't Stop

Gabriel Anhaia — Sat, 04 Jul 2026 09:42:29 +0000

Book: Agents in Production — Building, Tracing, and Shipping Multi-Step AI You Can Trust
Also by me: Observability for LLM Applications — the companion book in The AI Engineer's Library (2-book series)
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

In April 2025 a user filed Issue #44726 against the Claude Code repo. The title said [BUG][Billing]. The body was a table of token counts. In a normal session, output tokens trail input tokens by a wide margin. This one read 74:1. Another attached session read 175:1. The account balance had gone negative.

The report traces it to a compounding loop: conversation history and file context growing unbounded across tool calls. The agent had no idea anything was wrong. From its own point of view it was working.

That is the whole problem in one sentence. The thing running in the loop cannot tell you it is running in the loop, because it is the thing that decides whether to keep running. So the detection and the kill switch have to live outside the model, in code the model never gets to touch.

How the loop actually starts

A runaway is rarely one dramatic decision. It is a small pattern that repeats.

Issue #27281 is a clean example: an agent stuck repeating "let me write the document" turn after turn, narrating its own intent, never actually calling the Write tool. A full context window, burned, on an agent talking about work it never did. Issue #6004 is an "infinite compaction loop" — the agent compacts its own history, fails to make progress, compacts again, and users hit their usage limit far sooner than expected.

These share a shape. The model emits a valid response. It maybe calls a tool. The tool maybe returns something. Every individual step is fine. Your load balancer sees a healthy endpoint. The bug is in the trajectory, not in any one step, and a trajectory is exactly the thing a request-level test suite cannot see.

The model does not "notice" the repetition because a forward pass sees only what is in the window right now. If the loop is short, the window shows a repeating pattern and the model might break out. If the loop compacts into a summary, the repetition looks like progress. There is no internal clock. There is no back-pressure unless you build it.

Ceiling first: the loop the model can't see

Before any clever detection, put a hard ceiling around the loop. Three axes: steps, tokens, wall-clock. This is the floor of the whole system, and it is a plain for loop the model never gets to override.

import time

MAX_STEPS = 12
MAX_TOKENS = 200_000
MAX_WALL_CLOCK = 300  # seconds


def run_agent(step_fn, task):
    tokens = 0
    start = time.monotonic()
    for _ in range(MAX_STEPS):
        if tokens >= MAX_TOKENS:
            raise RuntimeError("token cap hit")
        if time.monotonic() - start > MAX_WALL_CLOCK:
            raise RuntimeError("wall-clock cap hit")
        resp = step_fn(task)          # one model call
        tokens += resp["tokens"]
        if resp["done"]:
            return resp["result"]
    raise RuntimeError("step cap hit")

step_fn is your single provider call. The caps live in the code that calls it, never in the prompt that asks it to stop. Hand this wrapper the exact loop from Issue #44726 (a model that never returns done) and it ends the session instead of the invoice:

stuck = lambda task: {
    "done": False,
    "tokens": 5000,
    "result": None,
}
run_agent(stuck, "summarise the repo")

RuntimeError: step cap hit

Use time.monotonic for elapsed time, not time.time. An NTP correction on a wall-clock timestamp will eventually give you a negative elapsed value in a long-running loop, and your kill switch will quietly stop firing.

The ceiling is necessary. It is not sufficient. A 12-step cap still lets a loop burn twelve full turns before it stops, and a compaction loop can do real damage in twelve turns. You want to catch the runaway earlier, at the moment it stops making progress.

No-progress detection: catch it before the ceiling

A ceiling asks "have you gone too far?" No-progress detection asks the better question: "are you still getting anywhere?" A healthy agent's turns look different from each other: new tool, new argument, new result. A stuck agent repeats itself.

The cheapest signal that generalizes well is a hash of each proposed action. Same tool with the same arguments, back to back, is the fingerprint of a stuck loop. Track the recent fingerprints and stop when one repeats too often.

import hashlib
import json
from collections import deque


class NoProgressDetector:
    def __init__(self, window=6, repeat_limit=3):
        self.recent = deque(maxlen=window)
        self.repeat_limit = repeat_limit

    def _fingerprint(self, tool_name, tool_input):
        blob = json.dumps(
            [tool_name, tool_input],
            sort_keys=True,
            default=str,
        )
        return hashlib.sha256(
            blob.encode()
        ).hexdigest()

    def check(self, tool_name, tool_input):
        fp = self._fingerprint(tool_name, tool_input)
        self.recent.append(fp)
        count = self.recent.count(fp)
        if count >= self.repeat_limit:
            return False, (
                f"repeated action {count}x: "
                f"{tool_name}"
            )
        return True, None

check returns (ok, reason). Call it before you run each tool call. If it comes back False, you have a loop that is cycling on the same action, and you stop now instead of waiting for the step cap.

The "narrating intent" loop from Issue #27281 needs one more signal: turns that produce no tool call at all. An agent that talks for three turns in a row without acting is not thinking, it is stalling. Count consecutive no-tool turns and treat that as no-progress too.

class StallDetector:
    def __init__(self, max_idle_turns=3):
        self.max_idle_turns = max_idle_turns
        self.idle_turns = 0

    def observe(self, made_tool_call):
        if made_tool_call:
            self.idle_turns = 0
            return True, None
        self.idle_turns += 1
        if self.idle_turns >= self.max_idle_turns:
            return False, (
                f"{self.idle_turns} turns with no "
                "tool call"
            )
        return True, None

Neither detector is perfect. A legitimate retry can repeat an action once or twice, which is why repeat_limit is 3 and not 1. Some tasks genuinely need a couple of pure-reasoning turns, which is why max_idle_turns gives slack before it fires. Tune both against your own traces. The point is that the model does not get a vote on either one.

The kill switch that ends the horror story

Detection is only half the job. When something fires, you have to actually stop, and stop in a way the caller can reason about. Do not raise a bare exception and lose the context. Return a structured stop reason so the layer above knows whether the agent finished or got killed, and can show the user the right thing.

Here is the outer loop wiring the ceiling, both detectors, and a clean stop together.

from dataclasses import dataclass


@dataclass
class StopReason:
    kind: str      # done | step_cap | no_progress | stall
    detail: str


def run(model_call, run_tool, messages, tools):
    progress = NoProgressDetector()
    stall = StallDetector()

    for step in range(MAX_STEPS):
        resp = model_call(messages, tools)
        messages.append(
            {"role": "assistant",
             "content": resp.content}
        )

        calls = [b for b in resp.content
                 if b.type == "tool_use"]

        ok, why = stall.observe(bool(calls))
        if not ok:
            return messages, StopReason("stall", why)

        if not calls:
            return messages, StopReason(
                "done", "model finished")

        results = []
        for c in calls:
            ok, why = progress.check(c.name, c.input)
            if not ok:
                return messages, StopReason(
                    "no_progress", why)
            results.append(run_tool(c))

        messages.append(
            {"role": "user", "content": results})

    return messages, StopReason(
        "step_cap", "hit MAX_STEPS")

model_call is your provider call. With the Anthropic SDK it wraps client.messages.create(...) with your messages and tools, and Claude is a sensible default when the loop is doing real tool use. The detectors sit between the model's proposal and the tool actually running, which is the only place a kill switch belongs: after the model decides, before the action lands.

The structured StopReason is what turns a kill into a usable outcome. done shows the final answer. step_cap, no_progress, and stall show a partial answer plus an honest "this run was capped — want me to continue?" hatch. The user is never left staring at a spinner that has secretly been dead for thirty-six hours.

What to log, so 2 a.m. never repeats

The reason the Issue #44726 user found out from a billing table is that nobody was watching the trajectory. You can do better with four fields per session:

session_id
stop_reason.kind and stop_reason.detail
steps, input_tokens, output_tokens, wall_seconds
per tool: call_count, plus a repeated_action flag when the detector tripped

Chart the stop-reason mix over time. You want done to dominate. A rising share of no_progress or stall is your early warning that the model is getting stuck on a class of task — long before finance sends the message that starts with "is this number right?"

None of this makes the agent smarter. It makes the agent stoppable, which for anything running unattended at 2 a.m. matters more. The model owns the control flow. Your job is to own the off switch.

Runaway loops are one of the failure modes that only show up in the trajectory, never in a single request — which is why they slip past the test pyramid you already have. Agents in Production walks through building and shipping multi-step agents with these rails in place, and Observability for LLM Applications covers the tracing and evals that let you watch trajectories instead of guessing from an invoice. Together they are The AI Engineer's Library, and this post is a slice of what both books argue: you are the operator of a system whose author is a language model.