Skip to main content

​
Use real IDs

Get workspace, agent and task IDs from read operations such as list_workspaces. Read a task or pending action before you change it, and don’t guess a recipient or workspace from a display name.

​
Give an agent a task

submit_task creates a task and starts the agent. It needs agents:write. The agent works with its own connected apps and follows its usual approval rules. A successful response means the task started, not that it’s done.
  1. Get an agentId from a read operation.
  2. Call submit_task with the workspace, the agent and what you want done. The API reference lists the fields.
  3. Save the task ID it returns.
  4. Check progress and output with list_task_runs and get_run.
  5. Send follow-ups with send_task_message, once the user has approved the message.
If a request times out, check whether the task was created before you try again.

​
Approve or reject an action

Pending actions are changes an agent wants to make. Reading them needs workspace:read. Approving, rejecting and editing drafts needs approvals:write.
  1. List the task’s pending actions and read the one you want.
  2. Show the user the recipients, content and changes.
  3. Approve or reject that exact action ID, as the user decided.
  4. Call get_pending_action to follow it until it finishes.
Approving an action can send an email or message, or change another app. The response shows the action’s state at that moment; follow it with get_pending_action to see when it’s done.

​
Polling

Poll with backoff, stop once you have a result, and honor Retry-After. Don’t run several polls for the same task at once. If an action fails, tell the user rather than approving it again. Long output comes in pages. Keep reading with the continuation field until there’s nothing left.

​
Scheduled tasks and reminders

Scheduled tasks have their own operations to create, update, pause and resume them. “Run now” starts a real run. Reminders follow the same scheduling limits as in Whirl. Check times and repeat settings against each operation’s schema.

​
Logging

Whirl logs which user and app made each call, the operation, the result and how long it took. It doesn’t log tokens or request bodies. Keep tokens and sensitive content out of your own logs too.