Human Approvals
Pause workflow execution for human review, approval, or rejection using the built-in approval gate.
Human Approvals
Workflows can pause at any point to wait for a human decision before proceeding. The run waits at a kind: Human state, posts the gate as a workflow event, and goes on along the transition the answer takes, with a configurable timeout. You answer a gate in Zaru Web, with aegis workflow signal, or over the REST API (Answering a Gate).
Defining an Approval Gate
Add a kind: Human state to your workflow manifest:
states:
GENERATE_DRAFT:
kind: Agent
agent: draft-agent
input: "{{input.topic}}"
transitions:
- condition: always
target: AWAIT_APPROVAL
AWAIT_APPROVAL:
kind: Human
prompt: "Review the draft in {{GENERATE_DRAFT.output}}. Answer yes to publish, no to discard."
timeout: 86400s # 24 hours; 3600s when omitted
default_response: "no" # optional; the answer taken if the timeout elapses
transitions:
- condition: input_equals_yes
target: PUBLISH
- condition: input_equals_no
target: DISCARD
PUBLISH:
kind: Agent
agent: publish-agent
input: "{{GENERATE_DRAFT.output}}"
transitions: []
DISCARD:
kind: System
command: "echo 'Draft discarded'"
transitions: []kind: Human Fields
| Field | Type | Default | Description |
|---|---|---|---|
prompt | string | — | Text displayed to the reviewer. Supports Blackboard template syntax. |
timeout | string | 3600s | How long to wait for an answer, set on the state beside transitions. |
default_response | string | — | The answer taken when timeout elapses with none. Without it, the workflow fails. |
A gate's answers come from its transitions: input_equals_yes takes yes (also y or 1), input_equals_no takes no (also n or 0), and input_equals takes its value. An answer no transition takes, such as approved at a yes-or-no gate, is refused and the gate is asked again.
Timeout Behaviour
When timeout elapses without an answer:
- No
default_response(default): The workflow execution fails withHuman input timeout. No transition occurs. default_responseset: The gate takes it as the answer, sodefault_response: "no"follows theinput_equals_notransition. Useful when a missing response should be treated as a "no".
Answering a Gate
When a run reaches a kind: Human state, the worker posts a HumanInputRequested workflow event for the gate. Besides the rendered prompt and the state's default_response, the event carries state_name, responses (the words the state's input_equals, input_equals_yes and input_equals_no transitions take, in their order: ["yes", "no"] for a yes-or-no gate, [] for a gate with no such transition, which takes any answer) and expires_at (one timeout after the gate's first post). A gate posted again after an answer it does not take carries the same three.
In Zaru Web, a gate of a run you started is one of your pending approvals: a card under the run in the conversation, an entry on the Approvals page and a card on the run's execution page, each with one button per word in responses (Human Gates of a Workflow Run). Zaru's companion is offered no tool that answers a gate, in any mode.
Once a gate is answered, or closes on its timeout, it stays listed: in Zaru Web under Recent on the Approvals page, with "You answered <word>." (or, for a gate that closed on its timeout, "Nobody answered; the run timed out.") and a link to the run, and the card under the run reads the same line.
From your own client, list the gates your runs wait at with GET /v1/workflow-gates?status=pending, the ones that closed with ?status=answered (each with the word chosen, the feedback, when it closed and what the run did then), or both with ?status=any, and answer one with POST /v1/workflows/executions/{id}/signal, or with aegis.workflow.signal, which Zaru's MCP server lists to external MCP clients such as Claude Code.
A gate is listed as pending while it is the latest event the workflow's worker posted for the run. Rows the orchestrator records for the run itself, such as its repository_prepared row, stay in the run's history and its logs route and never hide a pending gate, even when they follow it.
curl https://your-aegis-node/v1/workflow-gates?status=pending \
-H "Authorization: Bearer $KEYCLOAK_JWT"
curl -X POST https://your-aegis-node/v1/workflows/executions/exec-uuid/signal \
-H "Authorization: Bearer $KEYCLOAK_JWT" \
-H "Content-Type: application/json" \
-d '{ "response": "yes", "feedback": "Keep the flag name short." }'Building an Approval UI
A minimal polling loop for a custom approval interface, on the same two routes:
const ORCHESTRATOR = 'https://your-aegis-node';
const TOKEN = process.env.KEYCLOAK_JWT;
async function pollGates() {
const res = await fetch(`${ORCHESTRATOR}/v1/workflow-gates?status=pending`, {
headers: { Authorization: `Bearer ${TOKEN}` },
});
const { gates } = await res.json();
for (const gate of gates) {
console.log(`[${gate.execution_id}] ${gate.state_name}: ${gate.prompt}`);
console.log(` Answers: ${gate.responses.join(', ')} Expires: ${gate.expires_at}`);
}
}
async function answer(executionId: string, response: string, feedback?: string) {
await fetch(`${ORCHESTRATOR}/v1/workflows/executions/${executionId}/signal`, {
method: 'POST',
headers: {
Authorization: `Bearer ${TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ response, feedback }),
});
}response is one of the gate's responses (yes or no at a yes-or-no gate); any other word is refused and the gate is asked again.
Template Variables in Prompts
The prompt field in a kind: Human state supports Blackboard template syntax, giving reviewers access to outputs from earlier workflow states:
AWAIT_APPROVAL:
kind: Human
prompt: |
Agent produced the following output:
{{GENERATE_DRAFT.output}}
Score from quality check: {{QUALITY_CHECK.output.score}}
Answer yes or no.See the Template Syntax Reference for the full variable namespace.
See Also
- Building Workflows — full workflow authoring guide
- Workflow Manifest Reference — complete
kind: Humanfield spec - REST API — Workflow Gates