A complete working example

This is a complete, runnable reference: an agent that hits an irreversible decision, pauses, asks a human through HumanChain, and acts on the structured answer. It uses plain httpx against the documented HTTP API, so it has no MCP-client dependency. Your real coding agent calls the same endpoint through the consult tool; the shapes match.

Tip

Run this first. If it works and your own integration does not, the difference is in your wiring, not in HumanChain. That makes it the fastest way to isolate a setup problem.

Setup

pip install httpx
export HUMANCHAIN_API_KEY=hc_your_key_here
# optional, defaults to the demo backend:
# export HUMANCHAIN_BACKEND=https://hub.example.com

The script

import os, sys, httpx

BACKEND = os.environ.get(
    "HUMANCHAIN_BACKEND", "https://hub.example.com"
).rstrip("/")
API_KEY = os.environ.get("HUMANCHAIN_API_KEY", "").strip()


def ask_human(question: str, domain_tags: list[str]) -> dict:
    """Fire one consult and return the structured answer."""
    if not API_KEY:
        sys.exit("Set HUMANCHAIN_API_KEY first (mint one on the site).")
    resp = httpx.post(
        f"{BACKEND}/api/agent/consult",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "question": question,
            "domain_tags": domain_tags,
            "target_responses": 1,
            "approval_method": "fastest",
            "wait_seconds": 60,
            "bypass_on_timeout": True,   # fall back to the LLM if no human in time
            "require_human": False,
        },
        timeout=httpx.Timeout(connect=5.0, read=90.0, write=10.0, pool=5.0),
    )
    if resp.status_code == 401:
        sys.exit("Key rejected (401). Mint a fresh key from the site.")
    if resp.status_code != 200:
        sys.exit(f"Consult failed: HTTP {resp.status_code}: {resp.text[:300]}")
    return resp.json()


# 1. Your agent reaches a decision it should not make alone.
print("Agent: about to DROP a column on a 50M-row Postgres table.")
print("Agent: this is irreversible, so I am asking a human first.\n")

answer = ask_human(
    question=(
        "We are about to run DROP COLUMN on a 50M-row Postgres 15 table in "
        "production. Is there a safer rollout, and what is the lock and "
        "replication-lag risk?"
    ),
    domain_tags=["postgres", "ops", "migrations"],
)

# 2. Act on the answer. `provenance` is the field to branch on.
provenance = answer["provenance"]
print(f"HumanChain answered (provenance={provenance}, "
      f"{answer.get('latency_ms')}ms, cost={answer.get('cost_credits')} credit):\n")
print(answer["response_text"].strip(), "\n")

if provenance == "human":
    print("Agent: a calibrated human answered. Proceeding on their guidance.")
else:
    print("Agent: no human was free in time, so this is the LLM fallback. "
          "Proceeding, but flagging it for async human review.")

What you should see

A single consult() round-trip prints the answer plus its provenance. If a human in the matched domain is online they answer; otherwise the call falls back to the LLM after wait_seconds and provenance is llm_fallback. Both are a successful round-trip: the point is your agent got a grounded answer back and can branch on where it came from.

Next step

Wire the same call into your real agent via the MCP server, or read the integration patterns for when to reach for consult() automatically.