Request an external agent run

A connected agent normally finds out about your comments by polling: it asks the MCP server “anything new on the tasks I handle?” on its own schedule. That works for every agent, but the round-trip can take minutes or hours depending on how often the agent polls.

Run with <agent> is the low-latency alternative. It delivers a task.run_requested event to the agent immediately, so it picks the task up the moment you select it.

Where to find it

Open any task and expand the Run with Onplana Agent panel. If your organization has at least one connected external agent, a Run on selector appears there, listing the in-app Onplana agent plus every external agent you have connected. Pick one, then select Run with <agent>.

This is a change from earlier behavior. The option used to appear only on tasks an external agent had created; now you can hand any task to an agent, including one you wrote yourself. A task an external agent did create preselects that agent, so re-engaging it stays a single step.

Two things decide whether it actually dispatches:

• The agent has to be reachable right now. It qualifies either by having a Notify webhook URL set when its connection was created (hosted runners, CI dispatch), or by running the agent relay, which is how a local claude or codex on a laptop qualifies with no public address at all. An agent that is neither shows as not connected in the list, and the button is disabled with a hint to start its relay.
• The task is not Done. The whole agent panel is hidden on a completed task. A task its agent created still offers a standalone Run with <agent> card there so you can re-run it.

Selecting the in-app Onplana Agent instead of an external one runs the built-in assistant, which has its own path. See Run with Onplana Agent.

Send a task to an agent

1. Open the task and expand Run with Onplana Agent.

2. Under Run on, choose the external agent. A task that agent created already has it selected.

3. Select Run with <agent>. Onplana delivers a task.run_requested payload to the agent. If it is running a relay the event arrives down the open stream; if it has a webhook URL instead, Onplana POSTs to it with an X-Webhook-Signature header so the agent can verify the request came from your organization. An agent with both gets it over the stream, and the webhook is not called.

4. A “Run requested” comment is added to the task so the audit trail is intact.

The button greys out for a few seconds after each request so an accidental double-click does not double-trigger.

If you call the endpoint directly, an unreachable or unlinked target returns 400 EXTERNAL_RUN_UNAVAILABLE, and a connection id that is not an agent in your organization returns 400 DISPATCH_TARGET_INVALID.

Who can click it

The same gate as editing the task: either the project’s task.edit.any permission, OR the project’s task.edit.own permission combined with being assigned to the task. Members on a project can trigger runs on their own tasks; managers can trigger runs on any task in their projects.

Push vs poll

The two re-engagement paths complement each other:

	Push (this article)	Poll
Trigger	”Run with <agent>” button	Agent’s own schedule
Latency	Seconds	Whatever the agent polls at
Needs a public URL?	Only for the webhook route, not the relay	No
Works for local CLI agents?	Yes, with the relay running	Yes
Works for hosted runners?	Yes	Yes

For any agent that is neither webhook-registered nor running a relay, Talk to agents in task threads shows how the poll path works and how mentions in the [Agent] thread nudge the agent on its next sync.

What the agent receives

As a webhook POST body:

{
  "event": "task.run_requested",
  "timestamp": "2026-06-19T14:31:00.000Z",
  "data": {
    "taskId": "cmpx...",
    "projectId": "cmpw...",
    "taskTitle": "Draft the Q3 rollout plan",
    "brief": "focus on the migration risks",
    "requestedByName": "Sara Chen"
  }
}

brief is null unless the person typed one into the panel before selecting the button. Over the relay’s stream the data object above arrives as the frame’s data: field, without the outer timestamp wrapper (the frame carries its own id and event fields instead).

The X-Webhook-Signature header is an HMAC over the body using the secret the agent provided at connection time. The agent verifies the signature, picks up the task via the standard MCP get_task read, and decides what to do (it might just sync, or re-run its skill end to end).

FAQs

Can I send a task I wrote myself, not one the agent created? Yes. The Run on selector is on every task, so you can hand any task to any connected agent. A task the agent created just preselects it.

Does this dispatch the in-app Onplana Native assistant? No. Run with <agent> pushes to external agents. Picking the in-app Onplana Agent in the selector runs the built-in assistant through its own path instead. See Run with Onplana Agent.

Can my agent run without a webhook? Yes, two ways. Run the agent relay and the button works with no public address at all, which is the usual answer for an agent on a laptop. Failing that, polling is the universal fallback, see Talk to agents in task threads. The push path is a latency improvement; it is not a requirement.

Can the agent decline? Yes. The webhook is a notification, not a command. The agent can ignore it, queue it, or process it differently depending on its configuration. Onplana never forces work onto the agent’s side.

What if my webhook URL changes? Re-mint the PAT with the new URL from Connect an external agent. The new URL replaces the old one for future task.run_requested events.

Are these requests rate-limited? Yes, modestly. The button greys out for a few seconds after each click to prevent double-triggering, and repeated requests against a non-responsive webhook get backed off. The detail is in the agent connection’s audit log.

Best practices

1. Use Run with Onplana Agent for urgent feedback loops. When a human adds critical feedback, push trigger lets the agent see it in seconds rather than minutes.
2. Don’t push every comment. Most comments don’t need immediate agent attention. Reserve for blockers and urgent changes.
3. Verify webhook delivery via audit log. Every Run with Onplana Agent fires a task.run_requested event + posts a “Run requested” comment.
4. Set the Notify webhook URL when you create the connection, not later. It cannot be added afterwards; create a new connection to add or change it.
5. Coordinate with hosted agent ops. Push trigger requires the agent’s hosting infrastructure to be reachable. Ops contact matters.

Troubleshooting / common pitfalls

• No Run-on selector. The organization has no connected external agent, or the task is Done (the whole agent panel is hidden there).
• Button disabled, “not connected”. The chosen agent is unreachable: no webhook URL and no relay running. Start its relay.
• 400 EXTERNAL_RUN_UNAVAILABLE. The target is unreachable, or the task has no linked agent to fall back to.
• 400 DISPATCH_TARGET_INVALID. The connection id is not an agent in your organization.
• Webhook fired but agent silent. Agent didn’t ack. Check agent’s webhook receiver logs.
• Double-clicked, fired twice. Per the doc, button greys out briefly to prevent. If you catch it, only one task.run_requested event fires.
• Webhook signature didn’t match. Agent’s secret stale. Re-mint PAT.

How this combines with other features

• Run with Onplana Agent + Task threads. Push trigger after Agent thread reply for urgent feedback. See Talk to agents in task threads.
• Run with Onplana Agent + Agent assignment. Push works on agent-assigned tasks. See Assign work to an agent.
• Run with Onplana Agent + Webhooks. Push is a specialized webhook event. See Send webhooks.
• Run with Onplana Agent + Audit log. Every push event audit-logged.

Coming from another tool

Tool	Mapping
GitHub Actions workflow_dispatch	Direct concept; manual push
Custom webhook trigger	Direct
CI manual run button	Direct
Linear trigger external	Adjacent
Microsoft Power Automate manual	Direct

Related

• Wake your agent instantly with the relay, how a local agent qualifies for this button
• Assign work to an agent, the in-app Run with Onplana Agent counterpart
• Talk to agents in task threads, the poll path that works for every agent
• Connect an external agent, set the Notify webhook URL when you create the connection for the hosted-runner route
• Run a hosted agent on your own key, let Onplana dispatch the agent so no runner of yours is involved