What does the root-cause agent receive when the triage agent hands off 5xx errors on an API?

Tares hands the root-cause agent the triage finding, not the logs, after a line such as Handed off by triage with the verdict. The agent runs on the entity the finding is about and fetches any further evidence itself with its tools. The triage agent must end its runs with the conclude tool, because the verdict comes from that tool.

How it works

When triage sees 5xx errors on an API, it ends its run with a finding. The verdict on that finding, for example investigate, is matched against the handoffs on the triage agent. Case does not matter in the match. On a match, Tares starts the target agent, here your root-cause agent, on the entity the finding is about, such as service=checkout.

The root-cause agent receives:

• The finding. It is the triage agent’s recorded conclusion, naming the numbers that moved, for example the 5xx counts on the API.
• A handoff line before the finding. It reads like Handed off by triage with verdict "investigate" on service=checkout.
• The entity. The run is scoped to the entity the finding is about, so the root-cause agent starts on the API that looks wrong.

It does not receive the raw logs. It fetches further evidence itself with its tools, such as read, stats and any MCP tools you give it. It then writes its root-cause note on the same entity with conclude.

The verdict only exists if the handing agent ends with the conclude tool. Mark the triage agent as one that ends every run with a conclusion and list the verdicts it can give. Tares then holds it to that: every run ends with conclude, and a finding carries one of those verdicts or goes back to the agent to fix. Runs where nothing needs a closer look end as no_op, with no finding and no handoff.

Set it up

1. Label the fields you want counted on the source that carries your API logs, such as service and status_code, so triage can see which values moved. Put both agents in one project.
2. Add a schedule trigger that summarizes those labels for the triage agent. See Watch, then escalate for the full walkthrough.
3. Create the triage agent on that trigger. Tick that it ends every run with a conclusion, and give it the verdict investigate.
4. Create the root-cause agent with no trigger, so it runs only when handed off. It runs whether or not it is on for its own trigger.
5. On the triage agent, under When it concludes, choose Add a handoff. Pick the verdict, the root-cause agent and a cooldown. The default cooldown is 30m.

In the catalog, the same wiring looks like this:

agents:
  - name: triage
    trigger: watch-web
    concludes: true
    verdicts:
      - { verdict: investigate, when: one entity looks like a problem and needs a closer look }
    prompt: ...
    handoffs:
      - { verdict: investigate, agent: rca, cooldown: 30m }
  - name: rca               # no trigger: it runs only when handed off
    concludes: true
    verdicts:
      - { verdict: rca, when: you found what is failing and why }
      - { verdict: resolved, when: it was noise, or it is already over }
    prompt: ...

The verdict field in the console offers the triage agent’s own verdicts as a dropdown and also takes any word you type. If the handoff names a word the agent never gives, the form tells you, since that handoff would never run.

This page covers the handoff as part of an AI SRE setup. The rules for handoffs, including limits and what is recorded, are on Handoffs.

What you get

• A focused root-cause run. The root-cause agent starts with a clear statement of what triage saw on the API and which entity it concerns, not with tens of thousands of log lines.
• Evidence on demand. The agent pulls only what it needs with its own tools, so you decide what it can reach by choosing which tools to give it.
• One thread. The handed-off run is recorded with woken_by: handoff and the finishing run as its parent. On the project’s Activity, the triage finding and the root cause it led to read as one thread.
• Limits that never drop anything silently.
  • Within the cooldown, at most one handoff per entity goes from the triage agent to the root-cause agent. A skipped handoff shows handoff to rca skipped: cooldown in the finishing run’s results.
  • If the target is already running for that entity, or has hit its daily cap or budget, the handoff is recorded as a capped run with the reason.
  • Chains stop at depth 3, and the next handoff is recorded as capped with the error handoff chain stopped at depth 3.
• Cost control. Triage runs often and cheaply, while the root-cause agent runs only when triage flags something, at most once per cooldown per entity.

When something else fits

• If you need a condition before the root-cause agent wakes, such as several investigate findings in a window or findings from more than one agent, use a trigger over the findings source instead. Use one link or the other, not both, or the agent runs twice per flag.
• If you have no triage step and a single alert should wake the root-cause agent directly, a plain alert trigger on your 5xx source is simpler than a handoff.

Related