Skip to content

Human-in-the-Loop & Interrupts

Autonomous agents still need people at critical points: to approve a risky action, supply information the agent cannot find, or correct a result before it is used. Human-in-the-loop means the agent pauses at a decision point and waits for a person. An interrupt means a person, or another system, can stop or redirect an agent while it is working.

This page shows how to do both from agent code. The building block is the Human Intervention Service (HIS): the agent posts a request, a person answers it through any interface built on the HIS API, and the agent picks up the answer.


How It Works

 Agent (on_data)                  Human Intervention Service              Reviewer UI / tool
      │  submit(input_data) ───────────►  record: status = pending   ───────►  lists pending requests
      │                                                                          │
      │  wait / poll  ◄──────────────────  record: status = completed ◄──────── set-response(response_data)
      ▼
 continue with response_data

Each request is a subject response record:

Field Description
id Request ID
subject_id The agent that asked (taken from SUBJECT_ID)
input_data What the agent is asking: question, options, context, the draft to approve
response_data The person's answer
status pending until answered, then completed
creation_time, response_time Unix timestamps

Asking a Human from an Agent

The agents SDK includes HisClient (core/his.py):

from core.his import HisClient

his = HisClient(
    base_url="http://<his-host>:30608",
    poll_interval=1.0,     # seconds between checks
    max_wait=300,          # default timeout for submit_and_wait, in seconds
)

Blocking: Wait for the Answer

def on_data(self, task):
    draft = self.write_contract_summary(task.job_data)

    reply = his.submit_and_wait(
        input_data={
            "kind": "approval",
            "question": "Approve this summary before it is sent?",
            "draft": draft,
            "options": ["approve", "reject", "edit"],
        },
        wait_timeout=600,        # None → max_wait; a negative value → wait forever
    )

    decision = reply.response_data
    if decision.get("choice") == "reject":
        return AgentResult(task_id=task.task_id, is_error=True,
                           error_data={"stage": "human_review", "message": "rejected"})
    if decision.get("choice") == "edit":
        draft = decision["edited_draft"]
    return AgentResult(task_id=task.task_id, job_output={"summary": draft})

submit_and_wait raises TimeoutError if nobody answers in time. Catch it to escalate, pick a safe default, or fail the task.

Non-Blocking: Ask Now, Check Later

req = his.submit(input_data={"question": "Which region should this deploy to?"})
# ...continue other work, store req.id in the task state...

reply = his.check_and_get_response(req.id)   # None while pending
if reply:
    region = reply.response_data["region"]

Use this when the agent can do useful work while it waits, or when the decision can arrive in a later task.


Answering Requests (Reviewer Side)

Any UI, chat bot or script can act as the reviewer interface through the HIS REST API:

Method & Path Description
POST /subject-responses Create a request (used by HisClient.submit)
GET /subject-responses/<id> Get one request
GET /subject-responses/by-subject/<subject_id> All requests from one agent
POST /subject-responses/query Query with a MongoDB filter, e.g. {"status": "pending"}
POST /subject-responses/<id>/set-response Answer: {"response_data": {...}, "status": "COMPLETED"}
PUT / PATCH /subject-responses/<id> Update a request
DELETE /subject-responses/<id> Delete a request
# List pending requests
curl -s -X POST http://<his-host>:30608/subject-responses/query \
  -H "Content-Type: application/json" -d '{"status": "pending"}'

# Approve one
curl -s -X POST http://<his-host>:30608/subject-responses/<id>/set-response \
  -H "Content-Type: application/json" \
  -d '{"response_data": {"choice": "approve"}}'

Responses use the shape {"ok": <bool>, "data": ..., "error": ...}.


Interrupts

An agent can be stopped or redirected while it runs:

Interrupt How
Pause before a step Make the step depend on a human answer with submit_and_wait. The agent cannot continue until someone responds
Cancel or redirect at a checkpoint Between steps of a long task, call check_and_get_response on an open "control" request. A reviewer answers it with, for example, {"action": "stop"} or new instructions, and the agent acts on it at the next check
Signal over the mesh Send a P2P event to the agent, which receives it in on_event(event_name, event_data). Set a flag there that the task loop checks. See Chat and P2P Communication
Stop accepting work Block new tasks with an admission policy, for example a message_prechecker that reads a kill-switch from the Profile Manager. See Agentic Governance

Other Human-in-the-Loop Points

Mechanism Page
Human verification of delegated results, with live WebSocket updates Verification System
Human interaction inside DSL workflows DSL Manager — Human Interaction
Human review of lessons before agents use them Learner

Deploying the Service

The HIS is installed by deploy_services.sh from src/yaml/human-intervention.yaml in the agent-automation repository, into the registries namespace and exposed on NodePort 30608. See Install & Setup.

Architecture

Human interface

Download Image

Interrupts system

Download Image