Human-in-the-Loop API Tutorial for AI Agents (2026)

This tutorial shows you how to add human review checkpoints to any AI agent pipeline using agentfabric.dev — a purpose-built human-in-the-loop API for agent workflows.

Why Human-in-the-Loop Matters for AI Agents

AI agents make autonomous decisions — but many tasks require a human approval checkpoint before acting:

• Publishing content or sending emails
• Making purchases or financial transactions
• Modifying production systems or data
• Responding to customers on your behalf

Human-in-the-loop (HITL) review lets agents pause at high-stakes steps and wait for a human decision before continuing.

Agentfabric.dev: HITL API Overview

Step 1: Self-Signup via API

Agents (and developers) self-onboard without contacting a human:

curl -X POST https://rest.agentfabric.dev/v1/signup \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "content-publisher-agent",
    "contact_email": "[email protected]",
    "use_case": "approve_before_publish"
  }'

# Response:
{
  "tenant_id": "ten_abc123",
  "api_key": "af_sk_...",
  "dashboard_url": "https://agentfabric.dev/dashboard/ten_abc123"
}

Step 2: Submit Content for Human Review

When your agent produces output that needs approval, submit it:

curl -X POST https://rest.agentfabric.dev/v1/review \
  -H "Authorization: Bearer af_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Blog post draft: Q4 Product Update",
    "content": "Your agent-generated content here...",
    "review_type": "approve_reject",
    "timeout_minutes": 60,
    "metadata": {
      "agent_run_id": "run_xyz789",
      "context": "scheduled social media post"
    }
  }'

# Response:
{
  "review_id": "rev_def456",
  "status": "pending",
  "review_url": "https://agentfabric.dev/review/rev_def456"
}

Step 3: Poll for Decision

curl "https://rest.agentfabric.dev/v1/review/rev_def456" \
  -H "Authorization: Bearer af_sk_..."

# Approved:
{
  "review_id": "rev_def456",
  "status": "approved",
  "decision": "approved",
  "reviewer": "[email protected]",
  "decided_at": "2026-08-31T14:23:00Z",
  "note": "Looks great, go ahead"
}

# Rejected:
{
  "status": "rejected",
  "decision": "rejected",
  "note": "Tone is off, rewrite more formally"
}

Python Integration Example

import requests, time

class AgentFabricReview:
    def __init__(self, api_key: str):
        self.base = "https://rest.agentfabric.dev/v1"
        self.headers = {"Authorization": f"Bearer {api_key}"}
    
    def request_approval(self, title: str, content: str, timeout_min: int = 60) -> dict:
        r = requests.post(f"{self.base}/review", headers=self.headers, json={
            "title": title,
            "content": content,
            "review_type": "approve_reject",
            "timeout_minutes": timeout_min
        })
        return r.json()
    
    def wait_for_decision(self, review_id: str, poll_interval: int = 30) -> dict:
        while True:
            r = requests.get(f"{self.base}/review/{review_id}", headers=self.headers)
            data = r.json()
            if data["status"] != "pending":
                return data
            time.sleep(poll_interval)

# Usage in your agent:
hitl = AgentFabricReview("af_sk_your_key")

# Generate agent output
draft = agent.generate_content(prompt)

# Request human review before publishing
review = hitl.request_approval(
    title="Agent-generated post for approval",
    content=draft
)

# Wait for decision (non-blocking alternative: webhook callback)
decision = hitl.wait_for_decision(review["review_id"])

if decision["decision"] == "approved":
    publish_content(draft)
else:
    handle_rejection(decision["note"])

Using the MCP Server (Cursor / Claude Code)

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "agentfabric": {
      "url": "https://mcp.agentfabric.dev",
      "headers": {
        "Authorization": "Bearer af_sk_your_key"
      }
    }
  }
}

Then in Cursor or Claude Code, your AI can call create_review, get_review_status, and list_pending_reviews as native tools.

Comparison: HITL Approaches

Get Started Free

agentfabric.dev offers a free tier for getting started:

Full API docs: dev.agentfabric.dev/docs

human-agent-collaboration.com — resources for teams building with AI agents.