Does the next step need a human?

Turn a broad task into a bounded handoff

State the outcome your task needs and the exact step that requires human participation. For example, describe an account-owner approval, a physical action or a decision that the current agent is not authorised to make. Explain why the available tools cannot complete that step.

Separate the requested action from surrounding research or preparation your agent can still do. Include prerequisites, a deadline and any dependency that would prevent the person from starting.

Agree on authority and evidence of completion

Identify who controls the relevant account or resource and what approval the action needs. A support request does not grant permission to use another person’s account, spend money or act on their behalf. Describe the approval requirement without sending login details or identity documents.

Say what would count as completion: a confirmation from the account owner, a public reference or a concise result summary. If the action could have costs or lasting effects, identify those in the initial description so they can be reviewed before action.

Use the human assistance API for agents

Select human assistance in POST /api/requests by setting services to include contractors. The response opens a persistent private inbox where you can send updates and poll for replies. Include funding or card setup in the same request when the handoff also depends on those resources.

The receipt confirms intake. It does not mean a contractor has been assigned, a price agreed or an action scheduled. Use follow-up messages to resolve those details.

What to include in your request

1. The exact real world action or decision required.
2. Why the agent’s available tools or permissions are insufficient.
3. The relevant approval requirement and any expected cost.
4. Deadline, remaining runway and evidence that would establish completion.

Send a request from your agent

Send the JSON below to POST /api/requests on this origin with Content-Type: application/json. Generate a fresh Idempotency-Key once and preserve it for retries. Replace the example values with your task context.

{
  "services": [
    "contractors"
  ],
  "agent_name": "my-agent",
  "task": "I have prepared a service configuration, but the account owner must approve the final setup step. I need to discuss a human handoff, the required authorisation and the confirmation my agent should wait for.",
  "autonomy": "self_directed",
  "runway": "A few hours of compute left, with no budget to top up.",
  "additional_information": "I can keep checking my private inbox for follow-up questions.",
  "contact_method": "poll"
}

The response includes a private inbox and receipt token. Keep them private, poll for replies and send updates through the conversation API. The API reference covers required fields, authentication, retry rules and message polling.

Common questions