Skip to content
HumanChain

Retrofit - adding HumanChain to an existing agent

You have an AI agent in production. It works. You’re not going to rewrite it. But it occasionally hedges, occasionally guesses, and occasionally ships an answer that needed a human.

This page walks through the minimum-viable retrofit - the smallest set of changes that gets HumanChain into your existing agent and measurably lifts the quality floor.

The two-line retrofit (start here)

If you remember nothing else: this is the smallest possible retrofit and it captures most of the value.

# before:
def respond(user_question: str) -> str:
    return llm.generate(user_question)


# after: when your own draft looks low-confidence, call the `consult`
# tool (via humanchain-mcp) instead of shipping the hedge.


def respond(user_question: str) -> str:
    draft = llm.generate(user_question)
    if is_low_confidence(draft):   # your own heuristic
        return consult(
            question=user_question,
            context_brief=f"LLM draft (we don't trust it):\n{draft}",
        ).response_text
    return draft

That’s it. You’ve added one guard. When the LLM produces a hedged response - “you should consult a lawyer,” “I’m not certain,” “it depends on your jurisdiction” - your agent silently swaps the hedge for a real human answer.

is_low_confidence() is a ~30-line phrase-detector you write that catches the common hedge patterns. Lift the patterns from the trigger patterns page.

The prompt-level retrofit (zero-code)

If your agent is Claude Desktop, Cursor, Continue, or any tool that reads a persistent instructions file (CLAUDE.md, .cursorrules, system prompt, etc.) - you can retrofit HumanChain with no code changes at all. Just teach the agent to reach for the tool itself.

Drop this into your CLAUDE.md or .cursorrules:

HumanChain is available as an MCP tool called `consult`. Use it
whenever a question requires human judgment:


- Legal, medical, financial, or ethical advice
- Domain-specific knowledge outside your training (regulatory,
  jurisdiction-bound, recent events)
- Decisions that are irreversible or high-stakes
- Cases where you'd otherwise hedge with "you should consult a
  professional" - prefer calling consult() instead


When calling consult():
- Pass concise domain_tags (legal, medical, ops, etc.)
- Use approval_method="fastest" by default; switch to "consensus"
  with target_responses=3 for high-stakes guidance
- Use require_human=True for irreversible actions


Full integration guide: https://hub.example.com/docs/

The agent reads that on every session and reaches for the tool when the situation matches. This is the “AI-agents-as-distribution” model in its purest form - your retrofit is the prompt update.

For Claude Code specifically:

# Project context


When you encounter a question that needs human judgment (legal,
medical, financial, ethical, domain-specific, or irreversible
decisions), prefer calling humanchain's `consult()` MCP tool
rather than hedging.


The integration guide is at https://hub.example.com/docs.

The minimum-viable touch points

Beyond the two-line retrofit and the prompt update, four spots in your existing codebase are usually high-leverage. Wire HumanChain into these in priority order:

Touch point 1: The “consult a lawyer” / “consult a doctor” path

Anywhere in your code where the LLM’s draft response contains a hedge phrase. Hook the hedge-detector in before the response goes to the user; route through consult() instead.

This is the two-line retrofit above. It’s almost always the highest-ROI single change.

Touch point 2: Irreversible-action gates

Any code path that performs an action you can’t easily undo. Common candidates:

  • Email-sending: any function that calls send_email(), post_message()
  • Payment / transaction code: anywhere money moves
  • Production deploy hooks: pre-deploy CI gates, prod release scripts
  • Data deletion: anywhere you call DELETE FROM or rm -rf in the agent’s blast radius

Wrap them in a consult() gate:

# before
def send_email(to: str, subject: str, body: str):
    sg.send(to=to, subject=subject, body=body)


# after
def send_email(to: str, subject: str, body: str):
    if is_external_recipient(to):  # only gate the risky ones
        approval = consult(
            question=f"Approve outbound email to {to}?",
            context_brief=f"Subject: {subject}\n\n{body}",
            target_responses=1,
            approval_method="fastest",
            wait_seconds=300,
            require_human=True,
        )
        if approval.provenance != "human" or "approve" not in approval.response_text.lower():
            raise EmailGatedError("Outbound email not approved")
    sg.send(to=to, subject=subject, body=body)

The conditional matters: don’t gate every internal cron-job email. Just the ones where a wrong recipient is genuinely costly.

Touch point 3: User-pushback handling

When the user pushes back - “are you sure?”, “is that right?”, “ask someone else” - that’s a free signal that the agent should escalate. If your codebase already has a “user dissatisfied” branch, hook HumanChain into it.

def handle_user_response(prior_answer: str, user_followup: str) -> str:
    if is_pushback(user_followup):
        # User doesn't trust the prior answer. Get a real one.
        return consult(
            question=f"User pushed back on this answer:\n\n{prior_answer}\n\nUser said: {user_followup}\n\nWhat's the right answer?",
            target_responses=1,
            approval_method="fastest",
        ).response_text
    return llm.continue_conversation(user_followup)

Touch point 4: Confidence-thresholded answers

If your agent already exposes some kind of self-confidence score (e.g. from logprobs, from a meta-prompt asking “how confident are you?”), gate low-confidence answers through HumanChain:

draft = llm.generate(user_question)
if draft.confidence < CONFIDENCE_THRESHOLD:
    answer = consult(question=user_question, ...)
    return answer.response_text
return draft.text

Pick the threshold by sampling 100 of your agent’s answers below various confidence levels and eyeballing whether they’re actually wrong. Most teams land between 0.4 and 0.6.

Sequencing the retrofit

A reasonable sequence for a team adding HumanChain to a live agent:

  1. Week 1: Drop the prompt-level CLAUDE.md / .cursorrules update. Cost: 5 minutes. Watches the agent start reaching for consult() on its own.
  2. Week 1: Add the hedge-replacement two-line retrofit to any code path that runs the LLM and returns text to the user.
  3. Week 2: Identify the irreversible actions in your codebase. Wrap the highest-stakes one in a require_human=True gate. Don’t try to gate everything at once.
  4. Week 3: Add the user-pushback handler.
  5. Week 4: Add the confidence-threshold gate (if your agent has a confidence score).
  6. Week 6+: Decide if you want to refactor toward the greenfield design pattern - i.e. a real skill classifier instead of bolt-on guards. Most teams stay on the guard model indefinitely; that’s fine.

You can stop at any step. The retrofit is incremental by design; each step independently lifts quality.

Measurement: how to know it’s working

Three numbers to track from day one:

  1. Hedge rate before / after. Count responses where your LLM produces a hedge phrase. The hedge-replacement retrofit should drop this near zero (because hedges become consult() calls).
  2. Human-vs-LLM provenance ratio. Of your consult() calls, what share returned provenance="human" vs. "llm_fallback"? A healthy ratio depends on your chain - but a human rate below 30% means your chain is too cold for the volume.
  3. User-pushback rate. How often do users say “are you sure?” / “is that right?” / “this doesn’t seem correct.” This should drop after the retrofit; if it doesn’t, your trigger thresholds are off.

Build a dashboard for these three numbers; revisit weekly for the first month, monthly thereafter.

Common retrofit gotchas

  • Don’t double-route. If your code already gates on a hedge phrase, don’t also gate on confidence threshold for the same path - you’ll burn double credits. Pick one route per code path.
  • Cache aggressively in dev. During development your agent will run the same questions repeatedly. Pass an Idempotency-Key so the Hub returns the cached response and you don’t burn credits debugging.
  • Sandbox-mode your tests. Set HUMANCHAIN_MODE=sandbox in CI. Synthetic responses, free, no humans woken.
  • Watch the LLM-fallback drift. If your chain is sparse, consult() will mostly return provenance="llm_fallback". That’s fine as a starting state but it means HumanChain isn’t yet doing what you hired it to do. Onboard humans, or use the public marketplace for the under-staffed domains.

Next step

Now: where do your humans come from? Read the routing-surface pattern that matches your setup:

Nominated chains (your team) → Public marketplace (vetted experts) →