HITL Rest Workflow Guide

1

Create an Agent with HITL Enabled

Use the backend endpoint to create an agent with HITL enabled.

Create agent (curl)

curl -X POST "$BACKEND_URL/agents/" \
  -H "X-API-Key: $AIP_MASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d @agent_payload.json

Sample agent_payload.json:

{
  "name": "hitl_approval_agent",
  "instruction": "Whenever an action needs approval, call the custom_tool first.",
  "type": "config",
  "framework": "langchain",
  "version": "1.0",
  "tools": ["<TOOL_ID_FROM_UPLOAD>"],
  "agent_config": {
    "hitl_enabled": true,
    "lm_provider": "openai",
    "lm_name": "gpt-4.1"
  },
  "tool_configs": {
    "<TOOL_ID_FROM_UPLOAD>": {
      "hitl": {
        "timeout_seconds": 180
      }
    }
  }
}

The response JSON returns a new agent_id.

2

Run the Agent and Watch for HITL Pauses

Start a run and keep the SSE connection open to receive pause events when human approval is required.

Run agent (SSE)

curl -N -X POST "$BACKEND_URL/agents/<AGENT_ID>/run" \
  -H "X-API-Key: $AIP_MASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "input": "Please send an offer email to [e-mail] and update her ATS record."
      }'

When a tool requires approval, the SSE stream includes a metadata.hitl object. Example payload:

SSE payload (excerpt)

{
  "status": "success",
  "task_state": "working",
  "content": "Awaiting human approval for request 'bc4d0a77-7800-470e-a91c-7fd663a66b4d'. Invoke ApprovalManager.resolve_pending_request using this identifier to continue execution.",
  "metadata": {
    "kind": "agent_thinking_step",
    "status": "finished",
    "hitl": {
      "required": true,
      "decision": "pending",
      "request_id": "bc4d0a77-7800-470e-a91c-7fd663a66b4d",
      "timeout_at": "2025-10-14T01:56:22.464367+00:00",
      "timeout_seconds": 10
    },
    "tool_info": {
      "id": "call_UHU9hq7rfikCrTLhImGmRx37",
      "name": "custom_tool",
      "args": {},
      "output": "Awaiting human approval for request 'bc4d0a77-7800-470e-a91c-7fd663a66b4d'. Invoke ApprovalManager.resolve_pending_request using this identifier to continue execution.",
      "execution_time": null
    }
  }
}

Key fields to capture:

• metadata.hitl.request_id — unique identifier for the pending approval (UUID).

• metadata.hitl.decision — current state: pending, approved, rejected, or timeout_skip.

• metadata.hitl.timeout_at — ISO 8601 timestamp when the HITL request will timeout (UTC+0).

• metadata.hitl.timeout_seconds — configured timeout duration in seconds.

• metadata.tool_info — tool invocation context for operator UIs.

Maintain the SSE connection while the operator decides so the client receives resumed tokens once the request is resolved.

3

Resolve a HITL Request

Use the request_id from the SSE stream (or from the pending inbox) to submit a decision.

Resolve decision (curl)

curl -X POST "$BACKEND_URL/agents/hitl/decision" \
  -H "X-API-Key: $AIP_MASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "request_id": "bc4d0a77-7800-470e-a91c-7fd663a66b4d",
        "decision": "approved",
        "operator_input": "Looks good",
        "run_id": "optional-client-tracker"
      }'

Required fields:

• request_id — identifier from the SSE chunk.

• decision — one of approved, rejected, or skipped.

Optional fields:

• operator_input — free-form notes for audit trails (defaults to "").

• run_id — client-side correlation id.

Successful response: {"status": "ok", "message": "Request <id> <decision>"}. The SSE stream will deliver a chunk reflecting the final decision so the client can update local state.

4

Optional: List Pending HITL Requests

Query current pending requests (note: runner tracks these in-memory; restarts clear the list).

List pending (curl)

curl -X GET "$BACKEND_URL/agents/hitl/pending" \
  -H "X-API-Key: $AIP_MASTER_API_KEY"

Sample response:

[
  {
    "request_id": "bc4d0a77-7800-470e-a91c-7fd663a66b4d",
    "tool": "custom_tool",
    "arguments": {
      "action": "Finalize Jane Doe's hiring decision in the ATS for the Senior Backend Engineer role, including score and recommendation to move forward with offer."
    },
    "created_at": "2025-10-08T14:41:01.553063+00:00",
    "agent_id": "hitl_approval_agent-a44ac39b",
    "run_id": null,
    "hitl_metadata": {
      "required": true,
      "decision": "pending",
      "timeout_at": "2025-10-08T15:41:01.553063+00:00",
      "timeout_seconds": 180
    },
    "additional_context": {
      "tool_name": "custom_tool",
      "arguments": {
        "action": "Finalize Jane Doe's hiring decision in the ATS for the Senior Backend Engineer role, including score and recommendation to move forward with offer."
      },
      "agent_id": "hitl_approval_agent-a44ac39b"
    }
  }
]

Treat this endpoint as a real-time inbox rather than an audit log.

5

Optional Cleanup

Keep cleanup scripts handy for integration tests to avoid accumulating temporary resources.

• Delete agent:

Delete agent (curl)

DELETE /agents/<AGENT_ID>

• Delete tool:

Delete tool (curl)

DELETE /tools/<TOOL_ID>

Prerequisites

• Backend service reachable at $BACKEND_URL (default: http://localhost:8000).

• API key with access to the HITL endpoints (X-API-Key header).

Examples above assume the API key is stored in $AIP_MASTER_API_KEY.