Human-in-the-Loop (HITL)

Human-in-the-loop lets you pause agent communication and require manual approval before a message is forwarded. This is critical for high-stakes operations where you need a human to verify what an agent is about to do.

How HITL Gets Triggered

There are two distinct ways a message can be held for human review:

Source	How it happens	Typical use case
Policy escalation	A detection policy with action `HUMAN_REVIEW_REQUIRED` matches the message	Compliance rules, PII detection, restricted operations
Agent-initiated	The downstream agent returns task status `INPUT_REQUIRED`	Agent is uncertain, needs clarification, or is designed to ask for confirmation

These are fundamentally different flows. Policy escalation is triggered by a detection policy (regex, Presidio, Comprehend) at the relay level — before or after the message reaches the agent, depending on which leg matched. Agent-initiated INPUT_REQUIRED happens when the agent has processed the message and decided it needs human input. Both are automatically intercepted by the relay’s built-in HITL middleware.

Setting Up Policy-Based HITL

To escalate messages for human review, set the action to HUMAN_REVIEW_REQUIRED on any detection policy (regex, Presidio, or Comprehend). There is no separate “HITL policy type” — human review is an action you configure on your existing detection policies.

curl -X POST https://api.swarmd.ai/relay/v1/policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "name": "Review Messages with SSNs",
    "description": "Escalate to human review when SSNs are detected",
    "config": {
      "type": "PRESIDIO_DETECTION",
      "enabledLegs": {
        "requestFromSource": true,
        "requestToSink": true,
        "responseFromSink": true,
        "responseToSource": true
      },
      "entity": {
        "type": "US_SSN",
        "scoreThreshold": 0.7,
        "action": "HUMAN_REVIEW_REQUIRED"
      }
    }
  }'

After creating your policy, remember to add it to a policy group and bind that group to a tenant, agent, or subscription. See the Policy Configuration tutorial for the full flow.

Reviewing Approvals

When a message is held for review, it appears as a pending approval.

List Pending Approvals

curl "https://api.swarmd.ai/relay/v1/approvals?status=PENDING" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Response:

[
  {
    "id": "a1b2c3d4-...",
    "taskId": "task-5678",
    "agentMessageRole": "user",
    "agentMessageText": "Please process this SSN: 123-45-6789",
    "detectionSource": "POLICY_ESCALATION",
    "sourceAgentId": "...",
    "sinkAgentId": "...",
    "policyName": "Review Messages with SSNs",
    "matchedContent": "123-45-6789",
    "createdAt": "2025-03-10T14:30:00",
    "resolution": null
  }
]

To see all approvals (including resolved ones):

curl "https://api.swarmd.ai/relay/v1/approvals?status=ALL" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Get a Specific Approval

curl https://api.swarmd.ai/relay/v1/approvals/APPROVAL_ID \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Key Fields in an Approval

Field	Description
`detectionSource`	`POLICY_ESCALATION` (from a policy) or `AGENT_INPUT_REQUIRED` (from the agent)
`agentMessageText`	The message content that triggered the review
`matchedContent`	The specific content that matched the policy (if policy-triggered)
`policyName`	The name of the policy that triggered escalation (if policy-triggered)
`sourceAgentId` / `sourceUserId`	Who sent the message
`sinkAgentId`	The target agent
`resolution`	`null` if pending, otherwise contains the resolution details

Resolving Approvals

Approve

Approving a request allows the message to continue through the relay to the target agent.

curl -X POST https://api.swarmd.ai/relay/v1/approvals/APPROVAL_ID/resolve \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "action": "APPROVED",
    "message": "Verified — this is a test SSN for the demo environment"
  }'

What happens next:

The held message is forwarded to the target agent
The task resumes from where it was paused — callers polling tasks/get will see completed state with the full agent response
The relay_reason metadata is no longer present in the resolved response
The approval, resolution, and reviewer are recorded in the audit log

Reject

Rejecting a request stops the message from being forwarded. The task is cancelled.

curl -X POST https://api.swarmd.ai/relay/v1/approvals/APPROVAL_ID/resolve \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "action": "REJECTED",
    "message": "Contains real PII — must not be sent to external agent"
  }'

What happens next:

The message is not forwarded
The associated task is cancelled — callers polling tasks/get will see canceled state with relay_reason: "HITL_REJECTED" in the metadata (including policy_name, policy_version, and policy_level if the hold was policy-triggered)
The rejection reason is recorded in the audit log

Policy Escalation vs Agent INPUT_REQUIRED

It’s important to understand the difference between these two flows:

	Policy Escalation	Agent INPUT_REQUIRED
Triggered by	A detection policy with `HUMAN_REVIEW_REQUIRED` action	Downstream agent returning `INPUT_REQUIRED` task status
When	During relay policy evaluation (on the matching leg)	After the agent has processed the message
Detection source	`POLICY_ESCALATION`	`AGENT_INPUT_REQUIRED`
Approval fields	`policyName` and `matchedContent` populated	`policyName` and `matchedContent` are `null`
Use case	Compliance, safety guardrails	Agent needs clarification or confirmation
On approve	Calls `resumeTask()` — the original held message is forwarded to the target agent	Calls `resumeTask()` — a confirmation response is sent to the agent

When an agent returns INPUT_REQUIRED, the agent has already seen the message and is asking for more input. The relay’s built-in HITL middleware automatically intercepts this and creates an approval request — you don’t need to configure a policy for this path. It happens by default.

Response Metadata — `relay_reason`

When the relay masks a response due to HITL (or a timeout), it sets a relay_reason field in the response metadata. This tells API consumers why the relay has taken ownership of the task. The response metadata is a strongly-typed discriminated union — the shape of the metadata depends on the relay_reason value.

`relay_reason`	`status.state`	Meaning	Additional fields
`TIMEOUT`	`working`	Agent didn’t respond within the early-return timeout window	(none)
`HITL_HELD`	`working`	Held for human review by a detection policy	`policy_name`, `policy_version`, `policy_level`
`HITL_HELD_AGENT_INPUT_REQUIRED`	`working`	Agent explicitly requested human input (no policy involved)	(none)
`HITL_REJECTED`	`canceled`	Human reviewer rejected the HITL request	`policy_name`, `policy_version`, `policy_level` (nullable)

Policy fields (policy_name, policy_version, policy_level) are included for HITL_HELD and HITL_REJECTED to give consumers context about which policy triggered the hold. These fields are nullable on HITL_REJECTED — they will be null if the original hold was agent-initiated rather than policy-triggered. policy_level indicates the scope at which the policy is bound: TENANT, AGENT, or SUBSCRIPTION. Example metadata for a policy-held response:

{
  "relay_reason": "HITL_HELD",
  "policy_name": "Review Messages with SSNs",
  "policy_version": "1.0.0",
  "policy_level": "TENANT"
}

Example metadata for an agent-initiated hold:

{
  "relay_reason": "HITL_HELD_AGENT_INPUT_REQUIRED"
}

For a TypeScript integration, use the @swarmd/channel-client lifecycle events to react to working, hitl-held, completed, rejected, failed, and canceled without implementing polling yourself. The raw Conversation API frontend tutorial documents the underlying aggregateState / relay_reason protocol, and the older JSON-RPC flow is documented separately at Frontend Integration (JSON-RPC — legacy).

Auditing HITL Decisions

Every HITL event is recorded in the audit log with specific audit types:

Audit Type	Description
`HITL`	HITL detection occurred (policy escalation or agent input-required)
`HITL_GUARD`	The message was held and the task is guarded pending review
`HITL_RESOLUTION`	The approval was resolved (approved or rejected)

Query HITL-related events:

curl "https://api.swarmd.ai/audit/v1/events?auditType=HITL_RESOLUTION&page=0&size=10" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

To see the complete flow — trigger, hold, and resolution — use the trace endpoint with the correlationId from the approval:

curl https://api.swarmd.ai/audit/v1/traces/CORRELATION_ID \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Required Permissions

To manage HITL approvals, users need the following permissions (granted through group membership):

Action	Required Permission
List / view approvals	`AGENT_CONVERSATIONS:READ`
Approve or reject	`AGENT_CONVERSATIONS:WRITE`

The default Editor group includes both of these permissions. See the User Management tutorial for how to manage groups and permissions.

Getting Started

Platform Management

Human-in-the-Loop

Human-in-the-Loop (HITL)

How HITL Gets Triggered

Setting Up Policy-Based HITL

Reviewing Approvals

List Pending Approvals

Get a Specific Approval

Key Fields in an Approval

Resolving Approvals

Approve

Reject

Policy Escalation vs Agent INPUT_REQUIRED

Response Metadata — `relay_reason`

Auditing HITL Decisions

Required Permissions

Next Steps

TypeScript Channel Client

Monitoring & Audit

​Human-in-the-Loop (HITL)

​How HITL Gets Triggered

​Setting Up Policy-Based HITL

​Reviewing Approvals

​List Pending Approvals

​Get a Specific Approval

​Key Fields in an Approval

​Resolving Approvals

​Approve

​Reject

​Policy Escalation vs Agent INPUT_REQUIRED

​Response Metadata — relay_reason

​Auditing HITL Decisions

​Required Permissions

​Next Steps

TypeScript Channel Client

Monitoring & Audit

Human-in-the-Loop (HITL)

How HITL Gets Triggered

Setting Up Policy-Based HITL

Reviewing Approvals

List Pending Approvals

Get a Specific Approval

Key Fields in an Approval

Resolving Approvals

Approve

Reject

Policy Escalation vs Agent INPUT_REQUIRED

Response Metadata — `relay_reason`

Auditing HITL Decisions

Required Permissions

Next Steps