Best way to trigger an agent remotely from external systems — webhook vs. routine vs. agent wakeup?

[bggo]

Hi everyone,

I'm trying to find the recommended way to trigger an agent remotely from another system (an external app, backend service, or automation platform), and I'd like to confirm I'm using the right approach.

Here's what I've already read in the docs and how I understood it:

1. Routines — Webhook & API triggers
   From the Routines API, I saw that routines support three trigger types: schedule (cron), webhook (public URL + secret, with bearer / HMAC SHA256 / GitHub HMAC / unsigned signing modes), and API triggers (explicit firing without a public URL). The endpoints I found were:

POST /api/routine-triggers/public/{publicId}/fire (fire via webhook)
POST /api/routines/{routineId}/run (manual/API execution)
POST /api/routines/{routineId}/triggers (create a trigger)

I tried the webhook route, but in the platform UI, creating a routine with a trigger inside it shows up as "coming soon" and isn't available to me yet — so I couldn't complete this path.

My questions:

For triggering an agent remotely from an external system, is the agent wakeup endpoint the recommended path, or should I be going through routine triggers?

Is the routine "trigger inside a routine" feature (the one showing "coming soon") the intended long-term way to do this? Any ETA or workaround in the meantime?

Thanks in advance for any guidance or examples!

[hamedrabah]

The two paths have different semantics. For an external system, I would use a routine trigger when the event represents durable work; use the agent wakeup endpoint only when you deliberately want the lower-level “run this agent now” primitive.

Practical split:

• Public webhook / automation platform: create a routine plus a webhook trigger, then fire POST /api/routine-triggers/public/{publicId}/fire. Prefer hmac_sha256 (or bearer if the sender cannot sign), and pass a stable idempotency key in the workflow where possible.
• Trusted backend with Paperclip API credentials: POST /api/routines/{routineId}/run is the simpler API-trigger path. It still applies the routine's concurrency policy and creates a tracked run issue.
• Immediate operational ping: POST /api/agents/{agentId}/wakeup is appropriate when you already have the agent and task context and do not want routine/run history. Send source: "automation" or "on_demand", a reason/payload, and an idempotencyKey so retries do not create duplicate wakeups.

The important distinction is that a routine execution creates an issue assigned to the routine's agent and participates in concurrency, catch-up, and run history. A direct wakeup just enters the heartbeat/wakeup queue; it is useful infrastructure, but it is not a replacement for the durable routine abstraction.

The current repository already implements the API and CLI paths even if your deployed UI still labels trigger creation as coming soon:

• Routine behavior and payloads
• Routine CLI endpoints
• Agent wake CLI

So the workaround is API/CLI creation rather than waiting for the UI. I cannot speak to the UI ETA, but I would not build new external integrations directly on agent/wakeup unless you specifically do not want routine issue tracking and concurrency behavior.