Skip to content
HumanChain

Integration patterns

You’ve installed humanchain-mcp (install guide) and made your first call (tutorial). You know the API surface (reference). The remaining question is the most important one:

When should your agent actually reach for HumanChain, and how do you wire that decision into your codebase?

These pattern pages are the answer. They’re not features - they’re field-tested integration shapes that work for real agents.

The four categories

The patterns fall into four buckets:

1. When to call - trigger patterns

The hard part of integrating HumanChain isn’t how to call consult(). It’s deciding when the agent should call it instead of pushing through with its own answer. Pick the wrong threshold and you either burn credits on questions the LLM could answer alone, or you hedge and short-change your user.

→ Triggers - five concrete heuristics for deciding when an agent should pause and ask.

2. How to call - architecture patterns

Two postures, depending on whether you’re starting fresh or retrofitting an existing agent. Both end in the same place; the road there differs.

→ Greenfield - designing a new agent with HumanChain as a first-class peer to the LLM from day one.

→ Retrofit - adding HumanChain to an existing agent codebase without rewriting it. Minimum-viable touch points and where they pay off.

3. What to do with the response - aggregation patterns

consult() can return one human, three humans in consensus, the top-ranked of N, or the LLM fallback. How you fold the response back into your agent’s flow depends on what kind of decision you were making and how reversible it is.

→ Aggregation - pick the right approval_method for the criticality of the decision point. Worked examples for each.

4. Who answers - routing surfaces

HumanChain has two responder surfaces. Pick the one that matches your trust boundary.

→ Nominated chains - designate your own team as the responder pool. No marketplace, no fees per query, full control. The right answer for company-internal knowledge.

→ Public marketplace - vetted public experts matched by relative expertise grading. Pay per query. The right answer for domains your team doesn’t cover (regulatory, exotic stack, foreign jurisdiction, etc.).

A quick decision tree

If you’re skimming and want one path to follow:

Is the question in a domain YOUR team owns?
├── Yes → Use nominated chains (your team answers, no fees)
└── No  → Use public marketplace (expertise grading picks the expert, pay per query)


Is the decision irreversible? (deploy, send, transact, commit)
├── Yes → require_human=True, approval_method="all_must_agree", target_responses=3+
└── No  → require_human=False, approval_method="fastest", target_responses=1


Is the LLM fallback acceptable if no human is around?
├── Yes → bypass_on_timeout=True (default)
└── No  → bypass_on_timeout=False, larger wait_seconds (e.g. 600)

That covers maybe 80% of the integration choices. The pattern pages dig into the other 20%.

The opinionated default

If you don’t want to think about any of this and just want a reasonable starting point, this is the call we’d write for an agent on day one:

# Your agent calls the `consult` tool via humanchain-mcp. The call shape is:
answer = consult(
    question=user_question,
    domain_tags=infer_domain_tags(user_question),
    target_responses=1,
    approval_method="fastest",
    wait_seconds=90,
    bypass_on_timeout=True,
    require_human=False,
)

In shorthand: @hc/1/fastest/90s/bypass.

One human if available, LLM fallback otherwise, response in ≤ 90s. Cheapest, fastest, lowest friction. Tune from there based on what your agent’s actually doing.

When not to use HumanChain

HumanChain is for moments that need human judgment. It’s overkill (and slower than just asking the LLM) for:

  • Pure information retrieval. “What’s the syntax for a Postgres partial index?” - your LLM knows this. Asking a human is wasteful.
  • Boilerplate code generation. “Write a Pydantic model for this schema.” - LLM territory.
  • Translations between formats. “Convert this YAML to JSON.” - LLM.
  • Verifiable computation. “What’s 17% of $4,832?” - LLM, or just Python.

The smell test: if a competent LLM with a current knowledge cutoff would answer this correctly 95% of the time, don’t pay a human to double-check. Save the consults for the genuinely judgment-heavy 5%.

Next step

Start with Triggers - the most important pattern to get right.