Workflow human questions
Use an ask_question step to ask a person to choose the next part of a workflow. The step
creates a question in the ordinary Task backlog and waits durably for its
answer. Each configured answer selects its own path; expired handles no answer in time.
These paths can perform another action or finish successfully using an end step.
The editor's Approval preset creates an ordinary question with editable Approve and Reject choices.
Author a fixed-choice questionβ
{
"id": "00000000-0000-4000-8000-000000000002",
"type": "ask_question",
"title": [{"type": "literal", "text": "What should happen next?"}],
"question": {
"options": [
{"id": "prepare", "label": "Prepare delivery"},
{"id": "contact", "label": "Contact the customer"}
],
"timeout_seconds": 604800
}
}
Publication requires 2β50 distinct options. An ID uses 1β64 letters, digits, underscores or hyphens; its nonblank label has at most 128 characters. Retain the ID when renaming or reordering options. The timeout accepts 1β2592000 seconds and defaults to seven days. Incomplete questions can be saved as drafts; publication requires all choices and paths to be configured.
Connect each choice with an edge containing option_id, for example
{"source":"00000000-0000-4000-8000-000000000002","target":"00000000-0000-4000-8000-000000000003","option_id":"prepare"}.
Also connect one expiry edge with branch: "expired". An edge cannot contain both selectors.
Choice IDs and system branches are distinct, including when a choice happens to be named expired.
Paths that converge must use an explicit Join.
ask_question declares output.interaction_id, output.task_id, output.status and
output.option_id for downstream mappings. Status is answered or expired; the option ID is
nullable because expiry has no answer. Private comments are excluded. Use a nullable destination
for the option ID; the editor does not assume a choice was made simply because a path is connected.
Preview marks the question output_unknown and, unless an assumed answer is supplied, stops before dependent actions.
Author an approvalβ
Approval is an authoring preset using the same question configuration, title tokens, optional assignee and trigger-record links:
{
"id": "00000000-0000-4000-8000-000000000002",
"type": "ask_question",
"title": [{"type": "literal", "text": "Approve the customer follow-up?"}],
"link_trigger_record": true,
"question": {
"options": [
{"id": "approved", "label": "Approve"},
{"id": "rejected", "label": "Reject"}
],
"timeout_seconds": 604800
}
}
The title must resolve to nonblank text of at most 255 characters. Mapped values come from the run's captured inputs or supported preceding outputs. Workflow publication pins the question configuration and timeout. Renaming or reordering choices preserves their IDs and paths; removing a choice in the editor preserves downstream steps, which must be reconnected or removed explicitly.
Connect option_id: "approved" to a follow-up Task, option_id: "rejected" to an End step,
and branch: "expired" to a reminder or another End step. Paths that converge use a join node.
The editor shows the deadline as βWait up toβ¦β and the expiry path as βNo answer in timeβ.
The editor's POST /frontend/v2/workflows/editor/preview accepts an optional answers map keyed
by human-step UUID. Values are option:<configured option ID> or expired; option:expired selects a customer choice and is
separate from system expiry. Unknown steps, non-human steps, and invalid answers return 422
with a pointer under #/answers/<step UUID>.
An assumed answer selects that path and marks other paths skipped. It does not manufacture Task
IDs or execution outputs: steps that need those outputs remain output_unknown. Omitted answers
leave human steps unanswered. Preview never creates Tasks, runs, timers, or other persisted effects.
Allow an Agent to ask for clarificationβ
An Agent step can enable bounded human questions alongside its output configuration:
{
"clarification": {
"allowed_types": ["single_choice", "free_text"],
"max_questions": 3,
"timeout_seconds": 604800,
"max_text_length": 2000
}
}
Set this under the Agent action's config in the editable workflow version. Replacing the action
replaces its configuration: omitted or null clarification disables it; {} enables the defaults
shown above. Allow one or both distinct types, 1β10 questions, an answer timeout of 1β2592000
seconds, and 1β16384 text characters. Publishing the workflow freezes the configuration together
with all other steps.
Set optional assignee_user_id on the Agent action when clarification is enabled. Existing runs
retain the settings captured from their workflow publication.
The model generates a prompt and, for a choice, 2β50 stable options. It cannot choose assignment,
change the deadline or text limit, or gain general Task write access. One model turn can request
one question and cannot mix that request with ordinary tools. The Agent must have another model
call available to process the response.
Each question creates a Task and pauses the same Agent execution. Human waiting is excluded from its active duration; model/tool call counts, tokens and cost remain cumulative. An accepted answer returns to the Agent; expiry returns an explicit unavailable result. Cancellation closes pending questions and does not resume the Agent. A question answer does not itself complete the Agent step.
Inspect and answerβ
Read the Task through GET /api/v2/tasks/{task_id}. Its optional interaction contains the
frozen prompt, choices, deadline and accepted response. The interaction has its own UUID, distinct
from the Task ID. Workflow provenance is separate from the interaction's question content.
Answer with POST /api/v2/tasks/{task_id}/interaction/answer:
{
"interaction_id": "fbab0b62-fbbb-4731-86cf-dba29b4ab985",
"option_id": "approved",
"comment": "The customer confirmed the details.",
"lock_version": 0
}
The Approval preset initially uses option IDs approved and rejected; always send the configured
choice ID. The optional comment must
be nonblank and at most 2000 characters. Include the latest Task lock_version to detect
reassignment or another change before answering; omitted or null skips that optional precondition.
Reading requires tasks:read. Answering requires an active human user with tasks:write.
Service accounts and API-only users cannot answer. Assignment organizes the backlog; it does not
grant access or restrict answering to that assignee. Workflow authoring permission is not needed.
The response is 200 with the updated Task and interaction status answered; its response records
the selected option and any comment, or the bounded free-text answer. pending, expired and cancelled remain distinct interaction
states. The answer, Task completion and durable delivery intent commit atomically. Workflow
continuation happens asynchronously: fixed choices select their configured edge, while an Agent receives
the answer and continues its pinned execution.
Retrying the same answer and comment as the same currently authorized user returns the committed
result, even with the original lock version. A conflicting answer, wrong interaction ID, stale
supplied version on a pending question, expiry or closed execution returns 409. Invalid field
values return 422. Tenant boundaries apply to reads and answers.
See Task interactions for the complete Task contract.
Task lifecycle and run historyβ
Question Tasks cannot be marked done, reopened or deleted through ordinary Task writes. Their question text and record context cannot be edited; assignment may change. Deleting a linked record still removes its Task link through normal record cleanup. Completing a question emits the existing Task update lifecycle event.
While waiting, the run remains running and the question step has waiting status with its
ordered interactions list. For static question steps, a committed answer or expiry completes the
step and selects its path. Agent questions accumulate in that list; the Agent completes only when
its final output is accepted. Its code_execution.deadline_at is omitted while human waiting pauses
the active execution timer, then reflects the effective deadline after resuming.
Task creation alone does not complete the question step.
To cancel a run, use POST /api/v2/workflows/{workflow_id}/runs/{run_id}/cancel with workflows:manage and no body.
It immediately prevents new effects and closes unanswered questions and their Tasks, then delivers
cancellation asynchronously. The response is 202 with cancellation_requested_at; repeat requests
are idempotent. An already observed terminal run returns 200 unchanged. Check the actual run
status: a concurrent completion can win. Previously committed effects and decision history remain.
Other verified engine closure also closes pending questions.
See Workflow Runs for nested run/step identities, retained question outcomes and history freshness.