Request an external agent run

When a human comments on a task an external agent created, the agent finds out by polling (it asks the MCP server “any new comments on tasks I created?” on its schedule). That works for every agent, but the round-trip can take minutes or hours depending on how often the agent polls.

The Run with <agent> button is the low-latency alternative for hosted agents. It fires a task.run_requested webhook to the agent’s configured URL immediately, so the agent picks the task up the moment you click.

When this works

The button only appears on tasks that meet all three conditions:

• The task was created by an external agent, not by you or the in-app Onplana Native assistant. Onplana tracks this via the task’s createdViaConversationId.
• The agent’s connection has a notifyWebhookUrl registered at PAT mint time. Most local CLI agents (a bare claude or codex binary on your laptop) do not, because they have no public listener for Onplana to call. Hosted runners, CI dispatch handlers, and relays do.
• The agent is not the Onplana Native in-app agent. The native agent uses a different re-engagement path (Run with Onplana Agent).

If any one of these fails, the button is hidden. If you call the endpoint anyway you get 400 EXTERNAL_RUN_UNAVAILABLE.

Click the button

1. Open the task. Look near the right side of the modal for the violet card with the agent’s name and a Run with <agent> button.

2. Select the button. Onplana POSTs a task.run_requested payload to the agent’s webhook URL with an X-Webhook-Signature header so the agent can verify it came from your organization.

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

The button immediately greys out for a few seconds so accidental double-clicks do not double-trigger.

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
Requires webhook URL?	Yes	No
Works for local CLI agents?	No	Yes
Works for hosted runners?	Yes	Yes

For any agent without a webhook, 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 webhook looks like

The hosted agent receives a small JSON body:

{
  "event": "task.run_requested",
  "timestamp": "2026-06-19T14:31:00.000Z",
  "data": {
    "taskId": "cmpx...",
    "projectId": "cmpw...",
    "requestedBy": { "userId": "cmpv...", "name": "Sara Chen" }
  }
}

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 (the agent might just sync, or it might re-run its skill end-to-end).

FAQs

Does this work for the in-app Onplana Native assistant? No. Native uses a separate re-engagement path. See Run with Onplana Agent.

Can my agent run without a webhook? Yes, via polling. See Talk to agents in task threads for the universal fallback. The push path is a latency improvement for hosted agents; 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-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. Per CLAUDE.md note 89, every Run-with-Agent fires a task.run_requested event + posts a “Run requested” comment.
4. Set notifyWebhookUrl at PAT mint, not later. Per note 89, the URL is set at agent connection. Re-mint to add or change.
5. Coordinate with hosted agent ops. Push trigger requires the agent’s hosting infrastructure to be reachable. Ops contact matters.

Troubleshooting / common pitfalls

• Button missing. Per note 89: (a) task not external-agent- created; (b) agent has no webhook URL; (c) it’s the in-app agent.
• 400 EXTERNAL_RUN_UNAVAILABLE. Same as above. Verify all 3 conditions.
• 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-Agent + Task threads. Push trigger after Agent thread reply for urgent feedback. See Talk to agents in task threads.
• Run-with-Agent + Agent assignment. Push works on agent-assigned tasks. See Assign work to an agent.
• Run-with-Agent + Webhooks. Push is a specialized webhook event. See Send webhooks.
• Run-with-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

• 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 notifyWebhookUrl at PAT mint to enable this button