Zum Hauptinhalt springen

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.