How-to

How do I add a human approval step to a LangGraph or CrewAI agent?

Wrap the risky tool call: register the action type once, escalate with the action’s context before executing, wait for the human’s decision, and only run the action on approval. With the Avowex SDK (pip install avowex) that’s about ten lines, and it works the same in LangGraph, CrewAI, or any Python agent — the gate lives server-side, so the agent can’t skip it.

1. Get a key and register the action

# pip install avowex
from avowex import Avowex

client = Avowex(api_key="avx_...")  # free key: create an org at avowex.com/console

client.register_action_type(
    "issue_refund",
    description="Refund a customer",
    timeout_seconds=3600,     # if no human acts in time...
    fallback_approve=False,   # ...reject by default (fail safe)
)

2. Gate the tool your agent calls

In LangGraph or CrewAI, tools are plain Python functions — gate inside the tool, and every path through the graph inherits the checkpoint:

def issue_refund(amount: float, customer_id: str) -> str:
    """Refund a customer. Requires human approval."""
    esc = client.escalate(
        action_type="issue_refund",
        context={"amount": amount, "customer": customer_id},
        idempotency_key=f"refund-{customer_id}-{amount}",  # retries never double-act
    )
    decision = client.wait_for_decision(esc.id)
    if not decision.approved:
        return f"Refund rejected by reviewer: {decision.reason}"
    payload = decision.payload or {"amount": amount}       # reviewer may edit amount
    result = do_the_refund(payload["amount"], customer_id) # your real logic
    client.resume(esc.id)
    return result

Register the function as a tool exactly as you normally would — @tool in LangChain/LangGraph, a Tool in CrewAI. Nothing else in the graph changes.

3. Handle the three verdicts

A decision is approve, reject, or edit. Treat edit as approval of a modified payload (e.g., the reviewer lowered the refund amount) — use decision.payload. On reject, return the reason to the agent so it can explain or try another path. Timeouts follow your policy’s fail-safe; keep fallback_approve=False for anything irreversible.

Also available

TypeScript agents: npm install @avowex/sdk (with a withApproval() wrapper). Claude and other MCP-capable agents: npx @avowex/mcp exposes escalate/decision/resume as MCP tools. Full SDK and REST reference: the AI integration guide — it’s written to be handed directly to your coding assistant.

Frequently asked questions

Which risky actions should I gate first?

Money movement (refunds, payments, purchases), destructive operations (deletes, overwrites), external communications (email, posts), and access grants. Benchmarks show these are where unapproved agent actions cluster; reads and drafts don't need gates.

Does this work with frameworks other than LangGraph and CrewAI?

Yes — the gate is inside the tool function, so any framework that calls Python or TypeScript tools works the same: OpenAI Agents SDK, LlamaIndex, AutoGen, Pydantic AI, smolagents, or hand-rolled loops. MCP-capable agents can use the Avowex MCP server instead.

What happens if no human responds?

Your policy's timeout applies. With fallback_approve=False the action is rejected when the timer expires — the safe default for irreversible actions. The escalation and the timeout are both recorded in the audit log.

Is there a free tier to test with?

Yes — 500 resolved actions per month, reviewer-pool mode, full SDK and audit log, no card required.