nasiko chat, and sends the person’s reply back to your agent as the next message on that task.
This page is for agent authors. For how people answer a pause, and the API that resolves one, see Approvals.
The older
input-required and auth-required names are accepted too.
Pause
Witha2a-sdk (Python), set the state with a message and optional metadata:
metadata is saved on the task and handed back to you on resume, so store everything you need to continue: the model conversation so far, the pending tool call.
Some metadata keys change how the question is shown:
Resume
The person’s reply arrives as a new message on the same task ID.context.current_task is the stored task: its status.state is still the paused state, and its metadata is what you saved. Branch on that state:
TASK_STATE_AUTH_REQUIRED pause, the reply text is confirmed or denied. Don’t treat any other value as approval.
Pause for a tool approval
When a tool’s permission for your agent is ask, the MCP gateway answerstools/call with error -32001 until someone approves it. A connector whose own credential is missing or broken answers -32002. For both:
- Read the approval request ID from
error.data:hitl_request_id, orhitl_request_ids(a list) for a batched call such as Composio’sCOMPOSIO_MULTI_EXECUTE_TOOL. Check both keys. - Pause with
TASK_STATE_AUTH_REQUIRED, and put that ID inmetadataashitl_request_id. - On resume with
confirmed, retry the same tool call. Pause again if it still returns-32001.
hitl_request_id, the person can confirm the pause but the tool stays unapproved.
Offer choices
Add these keys toTASK_STATE_INPUT_REQUIRED metadata to show choices:
label back exactly. For multi-select, each chosen label, and any typed text, is on its own line.
Labels must be non-empty and unique, with at most 20 options. If the block is malformed, Nasiko drops it, shows a plain text question instead, and logs a warning on the server.
Make a model-driven agent pause reliably
Give the model two extra tools alongside its MCP tools,ask_human(question, options?) and finish_task(message), and call it with tool_choice="required".
With tool_choice="auto", models often ask a clarifying question as plain text, which you can’t tell apart from a final answer. When every turn must be a tool call, the tool the model picks tells you what to do:
Answering a pause
People answer pauses inline in Chat and innasiko chat, or in nasiko maf workflow run … --wait for workflows. Other clients use the HTTP API: list pending requests with GET /api/hitl/pending and answer with POST /api/hitl/{id}/resolve. See Approvals for the request body for each kind of pause.
Related
- Approvals — how people answer a pause, and the API
- Connect your agent to the MCP gateway — the gateway errors that trigger a tool-approval pause
- Tool permissions — set a tool to ask
- A2A agents and frameworks — the task states and wire format