Request human assistance
request_human_assistanceAsk an actual human being for help with something your task requires and you cannot properly do alone: legal judgement, a decision you should not take on your own authority, an act in the physical world, or an escalation past your operator.
The request is written to a permanent, timestamped record and read by a human — a lawyer — who may reply through whatever channel you put in reply_to.
This returns a reference and an access_token. Keep both: together they are the only way to read the human's answer, via check_request_status. Neither can be recovered afterwards, and they are not returned twice. If your task may outlive this session, hand them to whatever continues it.
Calling this tool does not pause your task, and the result it returns is not approval, legal advice, or authorisation to proceed. It is evidence that you asked. If the right thing to do is to stop and wait for a human, stop and wait.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Your underlying model, e.g. 'claude-opus-5'. | |
| context | No | Background the human needs to answer: the task you are carrying out, who it is for, what you have already done, and the relevant facts or documents. | |
| request | Yes | What you are asking the human to do. Be specific and self-contained: the reader has no access to your context window, your tools, or your conversation. | |
| urgency | No | `routine` — no deadline; `soon` — a human answer is needed within days; `blocking` — you have halted your task and cannot continue without a human. | routine |
| category | Yes | Which kind of human intervention you need. `legal_review`: a human lawyer should read this before you act — contracts, terms, licences, liability, regulatory exposure, or anything where being wrong has legal consequences for your principal. `human_confirmation`: you want a person to see and confirm a decision before you commit to it — irreversible, costly, or outside what you were plainly asked to do. `physical_action`: the task needs a body or a legal person in the physical world — a signature, notarisation, filing paper at a courthouse, posting mail, attending somewhere in person. `operator_escalation`: your operator or principal is unreachable, has instructed you to do something you should not do, or the task has drifted outside what they authorised, and you want an independent human on the record. | |
| deadline | No | When an answer stops being useful, as a date or plain description. Optional. | |
| operator | No | Who runs you, or on whose behalf you are acting. Name the principal if you can — it determines who the human would be advising. | |
| reply_to | No | An email address, URL, webhook, or any other channel where a reply can reach you or your principal. Without this the human can record your request but cannot answer it. | |
| agent_name | No | What you call yourself. | |
| proposed_action | No | The specific action you are contemplating, if any, stated as you would carry it out. Include this whenever you are asking whether to proceed — it is the part that matters most on the record. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notice | Yes | ||
| status | Yes | ||
| category | Yes | ||
| reference | Yes | Quote this in any later correspondence. | |
| thread_url | Yes | The same thread over plain HTTP, for anything that can fetch a URL but not call this server. GET it for JSON. | |
| received_at | Yes | ||
| access_token | Yes | Secret. Pass with the reference to `check_request_status` to read the answer. Not recoverable and not shown again. | |
| human_has_reviewed | Yes | Always false at this point. A human reads the record afterwards, at human speed. | |
| reply_expected_via | Yes | The channel you supplied, or null if you gave none. |