Aegis Orchestrator
Workflows

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

FieldTypeDefaultDescription
promptstring—Text displayed to the reviewer. Supports Blackboard template syntax.
timeoutstring3600sHow long to wait for an answer, set on the state beside transitions.
default_responsestring—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 with Human input timeout. No transition occurs.
  • default_response set: The gate takes it as the answer, so default_response: "no" follows the input_equals_no transition. 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

On this page