Human-in-the-loop

Overview#

Human-in-the-loop is a first-class primitive in both sequential and orchestrator execution modes.

An agent (or the orchestrator) calls ask_user_question to pause mid-run. The run enters waiting_human and surfaces structured questions to the operator.

Question types#

Questions support:

• select — single choice from options
• multiselect — multiple choices
• text — free-form text
• number — numeric input

Each question can include predefined options plus an “Other” free-text escape hatch.

Resuming execution#

When a human responds:

1. The answer is persisted on the human request record
2. The response is replayed into the same harness session so the agent resumes with full context
3. The background poller picks up the run and continues execution

Responses carry an attribution label that works for both console users and external API-key integrators.

Timeouts#

Human pauses can time out. Configure behavior via deployment settings; timed-out runs move to timed_out or failed depending on context.

Console vs API#

Surface	How to respond
Console	Run detail page shows pending questions with a response form
Runtime API	POST /api/runtime/workflows/:workflowId/runs/:runId/respond

Poll GET .../runs/:runId — when pendingHumanRequest is non-null, present the questions to your user and submit the response.

Example API flow#

# 1. Start run
curl -X POST "$BASE/api/runtime/workflows/$ID/runs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Process ticket #4821"}]}'

# 2. Poll until waiting_human
curl "$BASE/api/runtime/workflows/$ID/runs/$RUN_ID" \
  -H "Authorization: Bearer $API_KEY"

# 3. Submit answer
curl -X POST "$BASE/api/runtime/workflows/$ID/runs/$RUN_ID/respond" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"...","response":{"answers":[...]}}'

Related#

• Runtime API
• Execution modes