Team run callback

  • Desktop app
  • All plans
View as Markdown

What it does

A team run tells the agent that drives it where it stands. Each time the run reaches its End (or stops short of it because a step's flags matched no connection), gets blocked, waits for you, finishes or is cancelled, AgentsRoom sends that agent an Agent Mail with the run id, the ticket, the team, the new state, the stall reason, the last handoff flags and the next step to take. An agent that runs your backlog on its own (start a run, finish it, commit, start the next ticket) reacts within seconds, without a watchdog trigger polling backlog_get.

Where to find it

Teams window > select a team > Team settings > Callback agent (not shown on templates). The mails appear in the agent's console like any Agent Mail, from AgentsRoom (team run), and in the Organization panel.

How to use it

  1. Let an agent start the run with backlog_start_next: it is the callback agent by default, nothing to set.
  2. To notify a fixed agent instead (runs started from the board, a trigger or the phone), pick it in Callback agent.
  3. The agent ends its turn after starting the run and acts when the mail lands: team_finalize_run, team_reopen_run (send the run back to a step with a note when the work needs another pass), team_extend_run or team_cancel_run with the run id the mail gives.
  4. While the run works, the callback agent can also write to one of its steps with agents_send (a nudge to an idle step, a fact it is missing): the message lands once that step has received its brief. Since 2026-10-22.

Settings

  • callbackAgentId (team field, Team settings > Callback agent): The agent that started the run (default) = the agent whose backlog_start_next started it, nobody for a run started from the board; a saved agent of the project = always that agent (an agent that no longer exists in the project falls back to the default); Nobody = no mail. Stored with the team on your account. Since 2026-10-15.
  • agentMailWakesRecipients (global, Settings > Agents & AI > Agent behavior > Inter-agent messaging, A message may start the recipient, off by default): also starts the callback agent's console when it is closed. Without it, the mail waits for the console to open.

Agent tools (MCP)

  • teams_save: callbackAgentId takes a saved agent id, "none", or null for the default; teams_list returns it.
  • capabilities_get({topic: "teams"}): runLifecycle.callback describes the mail and when it is sent.
  • backlog_get: still returns the run state (effectiveExecutor.run) for an agent that wants to check after the mail, and for a finished run endedBy: who finished it (user, mobile, agent with its id, team-idle, trigger-idle) and where its ticket went. Since 2026-10-22.
  • Replying to the mail (agents_reply) is refused: nobody reads it. The agent acts on the run instead.
  • team_reopen_run: send a run that reached its End (waiting for Finish) back to one of its steps with a note, the agent-side Loop back to .... Use it when the work needs another pass, for example the reviewer asked for changes after End: the same run, its consoles, notes and changes, goes back to that step instead of a cancel and a new run on the same branch. The step gets the note first in its brief, the note is kept in the run's notes, and the run box shows "<agent> sent the finished run back to <step>: <note>" (click to read it all). No extra cycle is granted: a step past the team's max cycles stops the run as blocked, the note kept for when cycles are added. Any other state is refused with what to do instead. Since 2026-10-22.

Providers

All providers, no difference: the mail goes through the same Agent Mail queue for every agent CLI.

Mobile

Nothing to do on the phone: the mail is sent by the desktop and lands in the agent's console, which the phone shows. The setting is edited on the desktop only, like the other team settings.

Limits

  • The desktop app must be running (it runs the team too).
  • No mail when the callback agent finished or cancelled the run itself: the tool already answered it.
  • Only these six stops send a mail; a step that is merely slow, or a missing reply between teammates, does not.
  • The mail is not counted in any messaging budget and still goes through when inter-agent messaging is turned off.

Common questions

  • My coordinator agent starts team runs. How does it know a run is finished? The run mails it at each stop, so a watchdog trigger that polls backlog_get is no longer needed.
  • Can another agent get these mails? Yes: pick it in Team settings > Callback agent, or teams_save({callbackAgentId: "<agent id>"}).
  • How do I turn it off? Pick Nobody (callbackAgentId: "none").
  • The callback mail said the run was done, but nobody finished it. Who did? Since 2026-10-22 the mail says it on an ended by: line, and so do the run's timeline and backlog_get (endedBy). A run finished by Finish after inactivity (team setting) or Close after inactivity (trigger) gets a different mail: it says nobody checked the work, and its ticket waits in In Review when your board has that column (it used to be closed as done, pull request still open). See Agent Teams.
  • The agent did not react. Its console was closed: open it, or turn on A message may start the recipient (Settings > Agents & AI > Agent behavior).
  • My reviewer asked for changes after the run reached End. Do I have to cancel it and start a new run? No, since 2026-10-22. The agent that drives the run calls team_reopen_run with the run id (from its callback mail), the step that must redo the work and a note: the same run goes back to that step with the note, then on to End again, where the callback agent is mailed again. You can still do it by hand with Loop back to ... in the run box.
  • The lead agent's nudge to an idle team step stayed queued until the run ended. Fixed on 2026-10-22: the run's callback agent, the agent that started it, the project's lead agent and you reach a step while the run works, once the step has received its brief. Messages from other agents still wait for the run to stop, and a step waiting for your answer to its question keeps every message until you answer (or until the delay of Deliver mail to an agent waiting for an answer, Settings > Agents & AI > Agent behavior).

Related