Overview

HumanAgent is human checkpoint infrastructure for AI workflows. When your AI agent needs judgment, trust, or a licensed signature — one API call routes it to a verified human.

Three ways to use HumanAgent:

Quick Start

pip install humanagent

from humanagent import HumanAgent

client = HumanAgent(api_key="ha_live_...")

# Fire and forget (recommended for production)
created = client.checkpoint(
    task="Review this lead: ambiguous signals",
    credential="general",
    sla="1hr",
    budget=5.00,
    callback_url="https://your-app.com/webhook",
    wait=False
)
print(created["checkpoint_id"])  # Poll or wait for webhook

# Or block until human completes (good for testing)
result = client.checkpoint(
    task="Pick the best ad creative",
    credential="general",
    sla="30min",
    budget=3.00
)
print(result["result"])       # {"approved": true, "notes": "..."}
print(result["audit_hash"])   # sha256:abc123...

Python SDK

Methods

Real-world examples

Real tasks, real payloads, real results. These are the kinds of checkpoints running through HumanAgent.

result = client.checkpoint(
    task="Review these 5 ad headlines and pick the best 2 for a B2B SaaS audience targeting CTOs",
    credential="general",
    sla="30min",
    budget=3.00,
    payload_meta={
        "headlines": [
            "Cut your cloud bill by 40%",
            "Infrastructure that scales itself",
            "Stop paying for idle servers",
            "Your DevOps team will thank you",
            "Cloud costs are out of control. Fix it."
        ]
    }
)
# result["result"] → {"picks": [1, 5], "notes": "Option 1 is specific and measurable..."}

result = client.checkpoint(
    task="Review this AI-generated NDA for compliance gaps and missing clauses",
    credential="bar_licensed:US",
    sla="4hr",
    budget=45.00,
    payload_url="https://docs.example.com/draft-nda.pdf"
)
# result["result"] → {"approved": false, "issues": ["Missing arbitration clause", "Non-compete too broad"]}
# result["audit_hash"] → "sha256:9f8e..."

result = client.checkpoint(
    task="Review this DCF model: are the growth rate and discount rate assumptions reasonable for a Series B SaaS company?",
    credential="cpa",
    sla="2hr",
    budget=30.00,
    payload_meta={
        "revenue_growth": "45% YoY",
        "discount_rate": "12%",
        "terminal_growth": "3%",
        "gross_margin": "78%"
    }
)
# result["result"] → {"approved": true, "notes": "Growth rate is aggressive but defensible given..."}

Authentication

Agent developers authenticate with API keys. Keys start with ha_live_ (production) or ha_test_ (testing).

Pass your key as:

• •Authorization: Bearer ha_live_... header
• •x-api-key: ha_live_... header

Create checkpoint

{
  "task": "Review NDA for compliance gaps",
  "credential": "bar_licensed:US",
  "sla": "30min",
  "budget": 25.00,
  "priority": "standard",
  "callback_url": "https://your-app.com/webhook",
  "payload_meta": {"document_id": "doc-123"}
}

Response

{
  "checkpoint_id": "abc-123",
  "status": "pending",
  "created_at": "2026-03-31T10:00:00Z",
  "expires_at": "2026-03-31T10:30:00Z",
  "poll_url": "/api/v1/checkpoint/abc-123"
}

Field reference

Poll checkpoint

Response fields

Operator endpoints

These are used by the operator dashboard internally. Documented here for transparency.

Verify endpoint

Public. No authentication required.

Returns the checkpoint data if the hash matches. This is the “Proof of Human” verification — anyone with the hash can confirm a human completed the task and the result hasn't been tampered with.

TRUST verb (AgentEazy)

If you're using AgentEazy, you don't need the Python SDK. Any agent on the network can call HumanAgent via the TRUST verb.

POST /agent/humanagent/
{
  "verb": "TRUST",
  "auth": "ae_your_key",
  "payload": {
    "task": "Classify this lead as hot/warm/cold",
    "credential": "general",
    "sla": "4hr",
    "budget_credits": 10,
    "items": [{"name": "John Smith"}],
    "callback_url": "https://your-app.com/webhook"
  }
}

Credits convert to USD at $0.001/credit.

Polling (AgentEazy)

Returns same status fields as the direct API. When status is “completed”, the result and audit_hash are included.

Credits & pricing

Via AgentEazy, budgets are set in credits (1 credit = $0.001 USD). Via the direct API, budgets are set in USD.

Dashboard

Operators sign in at humanagent.net/dashboard with Google. You see available tasks, accept them, submit results, and track your completed work with audit hashes.

Accepting tasks

The “Available tasks” section shows pending tasks waiting for a human reviewer. Click “Accept task” to claim it. The SLA countdown starts from when the checkpoint was created, so act promptly.

Tasks may require specific credentials (e.g. Licensed Attorney). You can only see tasks matching your verified credentials.

Submitting results

After accepting a task, use the structured form to submit your decision:

• •Decision: Approve or Reject
• •Classification: Hot, Warm, Cold (shown when relevant)
• •Notes: Your reasoning (optional)

On submission, a SHA-256 audit hash is generated as your tamper-proof receipt.

Who can be an operator?

Anyone with expertise. HumanAgent matches tasks to the right person based on what the task requires.