paperclip_wakeup_agent
Wake up an agent on-demand to process assignments or respond to @-mentions. Optionally specify source, reason, payload, or idempotency key.
Instructions
Wake up an agent by invoking a wakeup request on-demand.
Args:
agentId: string — Agent UUID (example: "agt_abc123")
source: "timer"|"assignment"|"on_demand"|"automation" (optional) — Invocation source
triggerDetail: "manual"|"ping"|"callback"|"system" (optional) — Trigger qualifier
reason: string|null (optional) — Human-readable reason for the wakeup
payload: object|null (optional) — Arbitrary JSON passed to the agent session
idempotencyKey: string|null (optional) — Same key within 60s returns existing run
forceFreshSession: boolean (optional) — Force a new session even if one is active
Returns: Heartbeat run object { id, agentId, companyId, status, invocationSource, triggerDetail, startedAt, createdAt } OR { status: 'skipped' } if the agent is already running or paused.
Examples:
Use when: triggering an agent to process a new assignment or respond to an @-mention
Don't use when: the agent has a scheduled heartbeat and will fire on its own — use paperclip_invoke_heartbeat for scheduled agents
Error Handling:
401: authentication failed → check PAPERCLIP_API_KEY
404: agent not found → verify ID with paperclip_list_agents
409: agent already running → check returned { status: 'skipped' } response
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agentId | Yes | Agent UUID to wake up | |
| source | No | Invocation source (default: on_demand) | |
| triggerDetail | No | Trigger detail qualifier (default: manual) | |
| reason | No | Human-readable reason for the wakeup | |
| payload | No | Arbitrary JSON payload passed to the agent session | |
| idempotencyKey | No | Idempotency key — same key within 60s returns the existing run | |
| forceFreshSession | No | Start a new session even if one is already active |