docs

Human-in-the-Loop

Require human approval before an agent executes specific tools. Essential for agents that write files, send emails, make API calls, or perform any irreversible action.

Configure approval gates

agentfile.yaml
governance:
  human_approval:
    enabled: true
    actions:
      - file_write        # any tool whose name contains "write"
      - send_email
      - github__create_issue
      - shell_exec

Tool names are matched as substrings — file_write matches any tool containing that string.

How it works

  1. Agent decides to call an approved tool
  2. Execution pauses — status is set to waiting_for_approval in the checkpoint
  3. You see the request in the dashboard or CLI
  4. Approve or reject — agent continues or receives a rejection message

Two modes

ModeWhenHow to approve
TerminalTelemetry not configured (AGENTFILE_API_URL unset)Prompted inline in the terminal [y/N]
AsyncTelemetry configured (AGENTFILE_API_URL + AGENTFILE_RUNNER_TOKEN set)Via dashboard or API — agent polls every 5s, times out after 1 hour

Approve via dashboard

Open http://localhost:8000/dashboard, go to Approvals, and click Approve or Reject on any pending request. The agent will resume within 5 seconds.

Approve via API

Bash
curl -X POST http://localhost:8000/approvals/{trace_id}/{step_index}/approve \
  -H "Authorization: Bearer ${AGENTFILE_RUNNER_TOKEN}"
Crash recovery
If the agent container crashes while waiting for approval, restarting it with the same --thread-id will resume from the waiting_for_approval checkpoint.
On this page