Handoffs

An agent can pass its finding to another agent, by verdict. A cheap agent that watches often can hand the one entity that needs a closer look to a thorough agent, without a second trigger in between.

A handoff is three values: a verdict, the agent that takes over, and a cooldown. When a run ends with a finding whose verdict matches (case does not matter), Tares starts that agent on the entity the finding is about. The agent is handed the finding, after a line such as Handed off by triage with verdict "investigate" on service=checkout. It fetches any further evidence itself with its tools. A verdict comes from the conclude tool, so the handing agent must end its runs with a conclusion (see How a run ends).

In the console, the agent form has a When it concludes section: Add a handoff, then a verdict, the agent that takes over, and a cooldown (30m by default). The verdict field offers the agent’s own verdicts as a dropdown and also takes any word you type; when a handoff names a word the agent never gives, the form says so, since that handoff would never run. On the project’s page, each agent shows its handoffs in both directions. Handoffs are the project’s wiring: the same agent can hand off differently in two projects. In the catalog and on the API (POST and PUT /api/agents/builtin), handoffs is a list:

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
    prompt: |
      ...

The rules:

• Any other agent. The target is any other agent on the instance; the run belongs to the project whose wiring holds the handoff. At most 10 handoffs per agent, and each verdict and agent pair once.
• The target runs whether or not it is on for its own trigger. Give it no trigger when it should only run when handed off.
• Cooldown. At most one handoff from this agent to that agent per entity within the cooldown. A handoff inside the cooldown starts no run; the finishing run’s results say handoff to rca skipped: cooldown.
• Chains stop at depth 3. An agent that was handed off to can hand off in turn. After three handoffs in a row, the next is recorded as a capped run with the error handoff chain stopped at depth 3.
• Nothing is dropped silently. When 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.
• Deleting the target removes the handoffs that point to it. The delete response lists the agents it was removed from under handoffs_removed_from.
• An update that leaves handoffs out keeps them; an empty list clears them.

A handed-off run is recorded with woken_by: handoff and the finishing run as its parent. On the project’s Activity it sits under the run that handed off, so a triage finding and the root cause it led to read as one thread.

A trigger over the findings source still wakes an agent as before; handoffs are the simpler way to chain two agents.