What happens to handoffs when I update an agent through the API or delete the agent they point to?

Tares keeps an agent’s handoffs when an update leaves handoffs out, and clears them when the update sends an empty list. Deleting a target agent removes every handoff that points to it, and the delete response lists the affected agents under handoffs_removed_from. Each agent can have at most 10 handoffs, and each verdict and agent pair can appear once.

How it works

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 the target agent on the entity the finding is about. The handoffs page covers the full behavior. This page covers what happens when you change handoffs through the API or delete a target. It is part of the wider AI SRE workflow.

On the API, handoffs is a list on POST and PUT /api/agents/builtin. Three rules decide what happens to it:

• Update with handoffs left out. The agent keeps the handoffs it already has.
• Update with an empty list. The agent’s handoffs are cleared.
• Delete a target agent. Tares removes the handoffs that point to it. The delete response lists the agents the handoffs were removed from under handoffs_removed_from.

Two limits apply to the list you send:

• At most 10 handoffs per agent.
• Each verdict and agent pair appears once.

The target can be any other agent on the instance. The run belongs to the project whose wiring holds the handoff, so the same agent can hand off differently in two projects.

Set it up

1. Define handoffs on the handing agent. Each entry has a verdict, the target agent and a cooldown. The target agent has no trigger here, so it runs only when handed off.

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

2. Update the agent without touching its handoffs. Send your update with handoffs left out and the existing handoffs stay in place. Use this when you change only the prompt or other fields.

3. Clear all handoffs on purpose. Send the update with an empty list:

handoffs: []

4. Keep the list within the limits. Send no more than 10 handoffs for one agent, and list each verdict and agent pair once. If you need two different follow-ups, use two different verdicts or two different target agents.

5. Delete a target agent when you no longer need it. Read handoffs_removed_from in the delete response to see which agents lost a handoff. If one of those agents should now hand off elsewhere, send an update with the new handoffs list for that agent.

6. Check the console. The agent form has a When it concludes section with Add a handoff, a verdict, the agent that takes over and a cooldown (30m by default). The project’s page shows each agent’s handoffs in both directions.

What you get

• Safe partial updates. Changing an agent without sending handoffs never wipes its wiring.
• An explicit way to clear. An empty list removes every handoff on that agent in one update.
• No dangling handoffs. Deleting a target removes the handoffs that point to it, so no agent keeps a handoff to an agent that no longer exists.
• A record of the cleanup. handoffs_removed_from names every agent that lost a handoff, so you know which agents to rewire.
• Bounded wiring. The cap of 10 handoffs per agent and the one-time verdict and agent pair keep each agent’s handoff list small and unambiguous.

Handoffs that remain keep their usual behavior. The cooldown allows at most one handoff from this agent to that agent per entity within the cooldown. A handoff inside the cooldown starts no run, and the finishing run’s results say handoff to rca skipped: cooldown. Chains stop at depth 3, and the next handoff is recorded as a capped run with the error handoff chain stopped at depth 3. 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.

When something else fits

• If you want to chain agents through a trigger instead, a trigger over the findings source still wakes an agent as before. Handoffs are the simpler way to chain two agents.
• If one agent should keep its handoffs while you change other fields, leave handoffs out of the update rather than sending a partial list.

Related