Your first call

You have humanchain-mcp installed and wired into your coding agent (install guide). This page walks you through your first real consult() call so you know exactly what to expect on the wire.

Caution

Use the async pair for any real consult. A human answer usually takes longer than an agent runtime’s ~30-second tool-call limit, so fire consult_start(...) to get a consult_job_id, then poll consult_status(consult_job_id=...) until status is ANSWERED. The blocking consult() shown below is the shape of a call and a fine sub-30s smoke test, but it (and every require_human=true call) will trip the timeout on a real consult. Don’t call consult_start again each turn - reuse the same consult_job_id, or you open a new consult and lose the thread. The result leads with a banner telling you whether a human or the LLM fallback answered.

By the end you’ll have:

• Fired a real consult() call from your agent (or directly from Python)
• Seen the response shape, with provenance telling you whether a human or the LLM fallback answered
• Understood what the four approval_method options mean
• Learned the @hc/... shorthand we use throughout the docs

The single call

This is the entire API surface in one snippet:

# The `consult` tool's call shape. Your agent calls it via the humanchain-mcp
# server (no import); for scripted use, POST the same fields to the HTTP API.
answer = consult(
    question=(
        "For a B2B SaaS contract, customer is asking for 'all derivative "
        "work IP assigned to customer.' Our standard counter? Is "
        "'joint ownership of derivative work with mutual license' a "
        "reasonable middle ground?"
    ),
    domain_tags=["legal", "contracts", "saas"],
    target_responses=1,
    approval_method="fastest",
    wait_seconds=60,
    bypass_on_timeout=True,
)

print(answer.provenance)       # "human" or "llm_fallback"
print(answer.response_text)    # the actual answer
print(answer.responder_id)     # uuid of who answered (or "llm_fallback_v1")
print(answer.latency_ms)       # how long it took
print(answer.cost_credits)     # what this call cost you

That’s it. One function, eight parameters, one structured response.

Note

The snippet above shows the shape of a consult call. The two supported ways to make it are the MCP server (your coding agent calls the consult tool, no imports needed) and the HTTP API (shown below) - post the same fields to the endpoint directly.

Three ways to make the first call

From your coding agent

If you completed step 5 of the install guide, your agent already knows to reach for consult() on judgment-heavy questions. Try asking it something obviously human-judgment-shaped:

“I’m reviewing a SOW where the customer wants joint ownership of derivative IP. Ask humanchain what our standard counter-position is before you draft the redline.”

The agent should call consult() (you’ll see it in the tool-use trace), show you a loading state for a few seconds, then come back with a grounded answer that it weaves into the redline.

From Python directly

You can also call HumanChain directly without MCP, which is useful when you’re prototyping or running a script. No SDK required: any HTTP client works. Here is the same call with httpx against the documented endpoint.

pip install httpx
export HUMANCHAIN_API_KEY=hc_your_key_here

first_call.py

import os, httpx

resp = httpx.post(
    "https://hub.example.com/api/agent/consult",
    headers={"Authorization": f"Bearer {os.environ['HUMANCHAIN_API_KEY']}"},
    json={
        "question": (
            "Our agent is about to migrate a Postgres column from "
            "VARCHAR(255) to TEXT on a 50M-row table. Is CONCURRENTLY "
            "safe here? Any gotchas on Postgres 15?"
        ),
        "domain_tags": ["postgres", "migrations", "ops"],
        "target_responses": 1,
        "approval_method": "fastest",
        "wait_seconds": 90,
        "bypass_on_timeout": True,
    },
    timeout=120,
)
answer = resp.json()
print(f"[{answer['provenance']}] in {answer['latency_ms']}ms")
print(answer["response_text"])

python first_call.py

From curl (raw API)

If you want to see what’s on the wire - useful when integrating from a language without an SDK yet - you can hit the Hub backend directly:

curl -X POST https://hub.example.com/api/agent/consult \
  -H "Authorization: Bearer $HUMANCHAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Is it safe to ALTER TYPE on a 50M row Postgres column?",
    "domain_tags": ["postgres", "migrations"],
    "target_responses": 1,
    "approval_method": "fastest",
    "wait_seconds": 90,
    "bypass_on_timeout": true
  }'

The HTTP API is the lowest-level surface. The Python SDK and MCP server both call it underneath.

What a response looks like

A ConsultResponse is a structured object - same shape whether a human or the LLM answered:

ConsultResponse(
    consult_id="cns_01HXVR...",          # opaque ID for this call
    provenance="human",                   # "human" | "llm_fallback" | "mixed"
    response_text="For derivative work in a B2B SaaS context...",
    responder_id="usr_01HX...",           # human uuid OR "llm_fallback_v1"
    responder_handle="@kavya-legal",      # null for LLM
    domain_tags_matched=["legal", "contracts"],
    confidence=0.84,                      # responder's self-assessed
    latency_ms=4231,                      # wall-clock for the call
    cost_credits=1,                       # billing units consumed
    cached=False,                         # was this served from HCKB?
    fallback_reason=None,                 # set if provenance == "llm_fallback"
)

A few fields worth dwelling on:

provenance is the single most important field. If it’s "human", treat the response as ground truth - a calibrated expert answered. If it’s "llm_fallback", treat it as a thoughtful default but flag it for async human review.

responder_id lets you trace any answer back to its source. For humans, it’s a stable UUID - you can build a feedback loop that rewards answers your team validates downstream. For the LLM fallback, it’s a versioned string (llm_fallback_v1, llm_fallback_v2, …) so you know which model produced it.

latency_ms includes the full round-trip. Human responses typically arrive in 10–90 seconds for online experts; LLM fallback fires in under 2 seconds. The wait_seconds parameter you passed is the upper bound the Hub will wait for a human before falling back.

cost_credits is the billable unit consumed. On the free tier you have 100 credits; one consult call with target_responses=1 costs 1 credit.

The four approval_method options

approval_method controls what counts as a complete response. Pick based on how high the stakes are:

Method	Behaviour	Use when
"fastest"	First valid response wins; others discarded.	Most cases - informational lookups, light judgment calls. Cheapest.
"consensus"	All target_responses voters return; if agreement ≥ 0.6 it’s surfaced.	Medical / legal / financial guidance where you want sanity-checking but not unanimity.
"best_of_n"	Wait for target_responses, return the one with the highest expertise grading score.	Niche domains where one expert is meaningfully better than the others.
"all_must_agree"	Wait for target_responses, only surface if unanimous. Else escalate.	Irreversible actions, gated deploys, high-stakes commits.

Picking the right method matters. The full decision tree is in Integration patterns → Aggregation.

Shorthand notation: @hc/...

Throughout these docs you’ll see calls written like this:

@hc/3/consensus/120s/bypass

That’s purely a documentation / marketing shorthand. It maps to:

consult(
    question=...,
    target_responses=3,
    approval_method="consensus",
    wait_seconds=60,
    bypass_on_timeout=True,
)

The shape is @hc/<N>/<method>/<wait>s/<bypass-or-strict> where:

• N is target_responses
• method is one of fastest, consensus, best_of_n, all_must_agree
• waits is wait_seconds (always with a trailing s)
• bypass means bypass_on_timeout=True, strict means False

You don’t write @hc/... in code - code is always the full Python function call. The shorthand is for prose, READMEs, tweets, and Slack messages where you want to communicate “ask humanchain this way” in a single token.

What happens if no human is online

By default, if wait_seconds elapses with no human response, the Hub fires its single-voice LLM fallback (Groq’s Llama 3.3 70B) and returns that. provenance will be "llm_fallback" and fallback_reason will explain why (“no humans online for domain”, “all candidates busy”, “timeout waiting for required N responses”, etc.).

If you’d rather hard-fail than fall back - for example, you only want human answers and you’d rather raise an exception than ship an LLM answer through your pipeline - pass require_human=True:

answer = consult(
    question=...,
    require_human=True,         # hard-fail on no human
    wait_seconds=600,            # give them ten minutes
)
# raises HumanChainNoHumanAvailable if no human responds in 10 min

The trade-off: stricter quality bar, but you have to handle the exception in your agent code. Use it for irreversible decisions.

Try it now - three suggested first questions

Pick whichever matches your team’s domain. Send it through your agent and watch the response come back.

For an agent doing legal work:

“What’s the standard counter-position when a customer asks for joint IP ownership on derivative work in a B2B SaaS contract?”

For an agent doing code review:

“We’re about to merge a migration that runs ALTER TYPE on a 50M-row column without CONCURRENTLY. What’s the blast radius on Postgres 15?”

For an agent doing medical-adjacent triage:

“User reports chest tightness on day 3 of a new beta blocker. Algorithmic flag or human review?”

All three will pull a real consult() call. You’ll see whether a human on your chain (or in the public marketplace) is online for the domain, or whether the LLM fallback fires.

Next step

You’ve made your first call. Now learn when your agent should reach for HumanChain proactively:

Integration patterns →