Triggers - when should your agent call HumanChain?

The hardest integration choice is when your agent should reach for HumanChain. Pick the threshold too aggressively and you burn credits on questions the LLM could answer alone. Pick it too conservatively and you ship hedged-or-wrong answers in moments that needed a human.

This page lays out five concrete heuristics that compose well. Use them as a checklist when wiring up the first integration point.

Heuristic 1: Domain-out-of-training

Trigger: the question is in a domain where the agent’s LLM is demonstrably weak.

LLMs are competent across general knowledge but get sharply worse on:

• Recent regulatory changes (anything past the model’s knowledge cutoff)
• Jurisdiction-specific legal nuances
• Niche medical / pharmacological interactions
• Internal company knowledge (your codebase, your customers, your past decisions)
• Domain-specific safety rules (healthcare, PCI-DSS, GDPR, FedRAMP, …)
• Active markets (current commodity prices, live regulatory filings, ongoing litigation)

If your agent’s task description mentions any of these domains, wire HumanChain in by default.

The signal in code: the user is asking about something with a clear domain tag (legal, medical, financial, compliance, jurisdiction-bound) and the response would be acted upon.

LEGAL_TAGS = {"legal", "contracts", "ip", "compliance", "gdpr", "hipaa"}
MEDICAL_TAGS = {"medical", "clinical", "drug-interaction", "diagnosis"}
FINANCIAL_TAGS = {"securities", "tax", "audit", "accounting"}

def should_call_humanchain(inferred_tags: set[str]) -> bool:
    return bool(inferred_tags & (LEGAL_TAGS | MEDICAL_TAGS | FINANCIAL_TAGS))

Heuristic 2: Irreversibility

Trigger: the agent is about to do something it can’t easily undo.

The blast-radius test: if the action goes wrong, how much pain does it cause? Rank actions by reversibility:

Reversibility	Examples	Threshold
Trivial (undo button)	Drafting an email, suggesting code	No HumanChain needed
Cheap to undo	Creating a PR, scheduling a meeting	Optional
Costly to undo	Sending an email, posting publicly, deploying to staging	consult() with target_responses=1
Effectively irreversible	Sending money, deploying to prod, deleting data, contract signature, public statement	consult() with require_human=True, approval_method="all_must_agree", target_responses>=3

The pattern:

def gate_irreversible(action_kind: str, payload: dict) -> bool:
    if action_kind not in IRREVERSIBLE_ACTIONS:
        return True  # proceed without consulting

    answer = consult(
        question=f"About to {action_kind} with this payload. Approve?",
        context_brief=json.dumps(payload, indent=2)[:2000],
        target_responses=3,
        approval_method="all_must_agree",
        wait_seconds=600,
        require_human=True,
    )
    return answer.response_text.strip().lower().startswith("approve")

Tip

For truly irreversible actions, use require_human=True. You’d rather the action fail (and your agent retry tomorrow) than have an LLM fallback green-light a wire transfer.

Heuristic 3: Self-doubt signals

Trigger: the LLM’s own response shows hedging or low confidence.

LLMs hedge in predictable phrases. When you see these in your agent’s own draft response, that’s a signal it should have asked a human:

• “You should consult a [lawyer / doctor / accountant / professional].”
• “I’m not certain, but…”
• “It depends on your jurisdiction.”
• “Without more context, it’s hard to say.”
• “Generally speaking, …” (when the user wanted a specific answer)
• “Based on my training data, which may be outdated…”

You can build a simple hedge-detector and route any draft containing these phrases through HumanChain before surfacing it to the user:

HEDGE_PHRASES = [
    "consult a lawyer", "consult a doctor", "consult a professional",
    "I'm not certain", "it depends on your jurisdiction",
    "without more context", "based on my training data",
]

def hedges(draft: str) -> bool:
    low = draft.lower()
    return any(p in low for p in HEDGE_PHRASES)

draft = llm.generate(user_question)
if hedges(draft):
    # don't show the user a hedge - get a real answer
    real_answer = consult(question=user_question, ...)
    return real_answer.response_text
return draft

This is the single highest-leverage integration shape for retrofitting HumanChain into an existing chatbot. Two-line guard, immediate quality lift on the questions that most need it.

Heuristic 4: Stakes asymmetry

Trigger: the cost of being wrong is much higher than the cost of asking.

A consult() call costs 1 credit and ~30–90 seconds of latency. An agent’s wrong answer in a high-stakes context can cost a customer relationship, a lawsuit, a deploy outage, or a regulatory fine.

The decision rule is asymmetric: if (cost of wrong answer) > (cost of consult × failure rate of LLM alone), ask. Most of the time those numbers aren’t precise, but the asymmetry is obvious. Examples where the asymmetry tips toward asking:

• Outbound communication to a customer (one bad reply → churn)
• Code that touches money, auth, or PII
• Decisions surfaced to senior stakeholders
• Anything the user is paying for the agent’s judgment on (not just its execution)

If your agent is doing any of these and the answer isn’t trivially verifiable, default to consulting.

Heuristic 5: Explicit user request

Trigger: the user asked for a human, or the user is pushing back on the agent.

If the user says “are you sure?”, “is that right?”, “ask a human”, or “get a second opinion” - that’s the agent’s cue to escalate, full stop. Don’t argue, don’t re-justify; route to HumanChain.

ESCALATION_PHRASES = [
    "are you sure", "is that right", "ask a human", "ask an expert",
    "get a second opinion", "double check that", "i don't believe you",
]

def user_wants_escalation(user_message: str) -> bool:
    return any(p in user_message.lower() for p in ESCALATION_PHRASES)

This is the cheapest possible escalation path and dramatically lifts user trust. The user knows they can override the LLM and get a real person; the agent visibly responds; the relationship survives the moment.

Composing the heuristics

In practice you’ll want a router that fires on the union of these signals. A reasonable shape:

def should_consult(
    user_question: str,
    inferred_tags: set[str],
    intended_action: str | None,
    llm_draft: str | None,
) -> bool:
    # 5 - user explicitly asked
    if user_wants_escalation(user_question):
        return True
    # 1 - high-stakes domain
    if inferred_tags & HIGH_STAKES_DOMAINS:
        return True
    # 2 - irreversible action
    if intended_action in IRREVERSIBLE_ACTIONS:
        return True
    # 3 - LLM hedged in its own draft
    if llm_draft and hedges(llm_draft):
        return True
    # 4 - stakes asymmetry (your domain-specific check)
    if stakes_asymmetric(user_question, intended_action):
        return True
    return False

That single function captures most of the “when to call” question. Plug it in front of your agent’s action layer; route the question through consult() when it fires; carry on with the LLM-only path when it doesn’t.

Tip

Keep this router in code, not in your system prompt. A prompt instruction to “consult when it’s risky” fires inconsistently across models and runs - smaller models under-consult and can wave a high-stakes question straight through. See Non-determinism for why the gate belongs in code and how to tune the gray-zone cases.

What not to trigger on

Common over-triggers that waste credits:

• Anything mentioning a regulated word. “What’s the company’s GDPR policy?” - that’s a retrieval question, not a judgment one. Look up your policy doc instead.
• Anything sounding technical. “How do I add a Postgres index?” - that’s an LLM-tier question unless the index is non-trivial.
• Anything with “should I…” - most of these are advice questions the LLM answers fine. The exception is “should I do this irreversible thing”, which falls under heuristic 2.

When in doubt, ship with the trigger conservatively wired (one heuristic, not all five), watch what your agent actually does for a week, then dial it in.

Next step

Once your trigger fires, the next question is how you fold the response back into the agent’s flow:

Aggregation patterns →