Webhook to a running agent

  • Desktop, mobile and web
  • All plans

What it does

This is the supported way for another app (a Git client doing a review, a CI job, your own tool) to reach an agent that is ALREADY running, without starting a second one. It is a documented, stable behaviour of webhook triggers, not an internal API. A webhook trigger with the Existing project agent executor types each signed call into the console of a saved agent of the project, in its current conversation, instead of spawning a new agent. See Webhook Triggers for the webhook itself (URL, secret, filter, anti-burst).

Where to find it

  • Inside a project, Triggers panel > New trigger > Webhook, then Who runs it > the fifth card Existing project agent > Choose an agent.
  • The trigger's history shows Waiting for <agent> then Sent to <agent> for each call.

How to use it

Setup:

  1. New trigger > Webhook, Who calls this URL > Any service (JSON) (keep Replay protection on).
  2. Who runs it > Existing project agent > Choose an agent: a saved agent of this project. Temporary and quick agents are not offered. One trigger targets one agent: create one trigger per agent your app must reach.
  3. Anti-burst > One run per call, so every call becomes its own message (a window would fold calls arriving close together into one).
  4. Write the Prompt with the call's fields: {{event.title}}, {{event.body}}, {{event.author}}, {{event.url}}, {{event.id}}, {{event.action}} (read from the top-level title/name/subject/message, body/description/text, author/user/sender, url/link/html_url, id, action/type/event keys), or {{payload}} for the whole JSON. Say in the prompt who is speaking, e.g. Review feedback from <your app> for {{event.title}}: {{event.body}}: the message lands in the conversation like a typed message, it carries no other "from an external app" mark.
  5. Save, check Enabled, then send a signed call (Example call > Copy as curl shows the exact headers).

What the caller gets back (HTTP): 202 {"status":"queued","eventId":"..."} once the signature is verified and the event stored. Delivery to the console happens afterwards, on the user's machine: the 202 means "accepted", not "already typed". Other answers: 200 {"status":"duplicate"} (same delivery id again, nothing sent), 202 {"status":"ignored"} (the Only run when filter did not match), 202 {"status":"coalesced"} (folded by an anti-burst window), 401 (bad or missing signature, timestamp outside the window), 413 (body over 1 MB), 429 (more than 120 calls a minute on this URL, with Retry-After).

How the message reaches the agent:

  • Agent idle: the prompt is typed into its console and submitted, exactly like a message from the composer, usually within seconds.
  • Agent busy (a turn in progress), waiting for your answer, a draft in its composer, you are typing in it, or held by a team run: the call is NOT refused. It waits in the queue and is delivered as soon as the agent is free. Several calls are delivered one at a time, oldest first, each after the agent has taken the previous one.
  • Console closed: the call waits until the agent is opened again. Tick Reopen the agent if its console is closed to have AgentsRoom reopen it (previous conversation resumed when the provider and your restore settings allow it).
  • AgentsRoom closed or the computer asleep: the call waits on the server and is delivered at the next launch, held for a week, then dropped.
  • Agent deleted, or the trigger is a Restricted run: the run is recorded as failed (Could not send the prompt to this agent.) and nothing is typed. A restricted trigger never sends its payload into an agent that has your shell and tools.
  • Project paused: the call is skipped, not delivered later.

The trigger's history shows Waiting for <agent> then Sent to <agent> for each call. Signature, replay protection, filter, machine scope and the one-machine lock apply exactly as for the other executors.

Security: the payload is typed into an agent that has your project's permissions. Use this executor only for a sender you control (your own app on your own machine, your own CI), keep the signing secret in that app, and prefer sending pointers (ids, branch names) the agent then looks up rather than text written by a third party.

Settings

  • Per trigger, Reopen the agent if its console is closed (Triggers editor > Existing project agent): off by default.
  • autoLaunchAgentsAtStartup (global, Settings > Terminal): lets queued deliveries be replayed at launch.

Agent tools (MCP)

  • triggers_save, triggers_get, triggers_list, triggers_run: the same tools as any webhook trigger, see Webhook Triggers.

Providers

All providers: the message is typed into the agent's console like a message from the composer, whatever its CLI.

Mobile

Present. The phone edits the trigger, including the Existing project agent executor. Delivery happens on the desktop that runs the agent.

Limits

  • Existing project agent reaches one saved agent per trigger: an app that talks to several agents needs one trigger (one URL) per agent.
  • Refused on a Restricted run: a restricted trigger never sends its payload into an agent that has your shell and tools.
  • Project paused: the call is skipped, not delivered later.

Common questions

  • Can my app send review comments to the agent that is still working on the branch, instead of starting a second agent? Yes: a webhook trigger with Existing project agent pointed at that agent. Each signed call answers 202 queued and is typed into the agent's console as soon as it is free; a busy agent is not an error, the call waits its turn.
  • What if the agent is busy when my call arrives? Nothing is refused: the call waits in the queue and is delivered when the agent finishes its turn (and has no question pending, no draft, nobody typing in it). Calls are delivered one by one, oldest first.