How to Use withHuman: The Beginner's Guide to Human Approval for AI Agents
CodexFuse Team · 2026-11-02T18:22:49.216Z · 11 min read min read
withHuman is an open-source approval layer for AI agents: it intercepts each tool call, checks it against your rules, and sends risky ones to a human. This beginner's guide covers install, Claude Code hooks, your first approval pipeline, and approving requests.
Give a coding agent shell access and it will eventually do something you did not expect: delete a file you meant to keep, refund the wrong customer, or push to production on a Friday afternoon. Learning how to use withHuman means those moments stop being accidents waiting to happen. withHuman is an open-source human approval layer for AI agents: it sits between your agents and the tools they call, and every risky action waits for a human's yes or no before it runs. This beginner's guide walks you through installing the withHuman adapter, connecting it to a coding agent (this Claude Code beginner guide covers the agent side if you are new to it), writing your first approval pipeline, and approving a real request from your phone. You do not need to be a security engineer. If you can run a terminal command and read a config file, you can use withHuman.
What Is withHuman, Exactly?
withHuman is an open-source approval layer for AI agents: it intercepts each tool call an agent wants to make, checks it against your rules, and either auto-approves it, denies it, or sends it to a human for a decision. Nothing about the agent changes; the safety net wraps around the tool calls themselves.
The project has two pieces. The first is the Agent Approval Protocol (AAP), an open spec hosted at agentapprovalprotocol.io that defines how agents ask for a decision and wait for one. The second is withHuman itself: the software that manages the rules, the approval pipelines, the escalation paths, and the audit trail. The code is open source, and the team also runs a hosted version for people who do not want to self-host. The team built Metoro, an AI SRE agent, first; their customers refused to let that agent apply infrastructure fixes without a human sign-off, and withHuman grew out of that demand. The two products are built alongside each other by the same team.
The team's own worked example shows the idea in miniature (reported here as the vendor presents it):
- A support agent decides to refund a $75 duplicate charge.
- Your policy says refunds over $20 need a human.
- The refund is held before it ever reaches Stripe.
- The Payments team is notified and Chris, who is on call, approves it.
- The refund runs.
One name warning, stated once: kyaprotocol.org also calls itself the "Agent Approval Protocol," but that is a payments-authorization protocol from a different company (AGSM LLC, published March 2026). withHuman's AAP governs agent tool-call approvals and lives at agentapprovalprotocol.io. They are different products with an identical acronym.
How Does withHuman Sit Between Your Agent and Its Tools?
The interception happens at the tool call: your agent calls its tool normally, and the adapter wrapping that tool (a hook, an SDK, or MCP) holds the call while a decision is made, then lets it run or makes it fail. The agent is transparent to this whole process, which is the point: the agent "can't forget to ask," as the launch blog puts it.
For coding agents there are prebuilt hooks for Claude Code and Codex. Framework agents get SDKs for Python and TypeScript plus drop-in integrations for Deep Agents, LangGraph, Pydantic AI, CrewAI, and Mastra, with documented AAP middleware for LangChain agents. There is also a built-in MCP Gateway that holds your credentials so the agents never see them, which matters for a specific reason the team states openly: an agent holding its own credentials, say a GITHUB_TOKEN, could bypass the approval layer entirely with a curl command. Holding the keys outside the agent's reach closes that hole. (If token hygiene in general feels new, this GitHub beginner guide is a good refresher on how tokens and repos work.)
The team is also honest about what is still open work: HTTP requests made through CLIs and scripts, and non-MCP tool calls, are not yet covered by the interception. Treat those as unprotected paths until the team closes them, and do not promise stakeholders coverage you do not have.
How Do You Install withHuman? Step by Step
Installation has two moves: install the AAP adapter binary on the machine running your agent, then pick an approval provider and follow the adapter's setup guide. The exact self-host steps are moving fast, so verify the current Quickstart at write time; what follows is the path that is verifiable today.
- Install the adapter binary. On the machine running your agent, run the install command published on the AAP spec site:
curl -fsSL https://downloads.agentapprovalprotocol.io/install.sh | sh(verified at agentapprovalprotocol.io, 2026-11-02). - Pick your provider. Self-host the open-source stack, or use the vendor's hosted version at app.withhuman.ai with a token stored in
WITHHUMAN_TOKEN. - Install the withHuman CLI. The vendor homepage's instruction is to install the CLI to connect every supported agent on your machine, so every agent on that box routes through one place.
- Connect your agent. Attach a prebuilt hook (Claude Code, Codex) or wire middleware into your framework. Metoro's sister-company walkthrough shows the LangGraph shape:
ApprovalMiddleware("https://app.withhuman.ai/api/aap", os.environ["WITHHUMAN_TOKEN"])(metoro.io, 2026-11-02). - Write your first approval pipeline (next section).
- Trigger a risky call and watch the approval arrive on your preferred platform, then approve it and watch the call run.
Run the agent inside a reproducible environment if you can. This Docker beginner guide shows the setup pattern for keeping agent runtimes isolated and repeatable, which pairs well with an approval layer.
How Do You Connect withHuman to Claude Code?
You use the prebuilt hook: once it is installed on the machine running Claude Code, every tool call your session makes passes through your approval pipeline before it executes. There is no agent-side configuration beyond attaching the hook, and the agent's behavior stays identical from its own point of view.
Codex gets the same treatment with its own prebuilt hook. If your agent runs inside a framework rather than a coding CLI, the SDK or middleware path applies instead. Either way, the mental model is the same: one interception point, owned by your pipeline, invisible to the agent.
How Do You Write Your First Approval Pipeline?
A pipeline is a list of blocks evaluated in order: the first block that makes a decision wins, and if no block decides, the call falls back to human review. You can also add an explicit final deny so nothing slips through by accident.
Each block can condition on the agent, the tool, the arguments, and the agent's context. The block types the vendor documents are:
| Block | What it does | Beginner example |
|---|---|---|
| Auto-approve rule | Lets matching calls through untouched | Read-only calls like listing a directory |
| Auto-deny rule | Fails matching calls immediately | Writes to the production database from a test agent |
| AI judge | Decides calls your rules cannot describe precisely | Calls whose safety depends on intent, not arguments |
| Webhook | Asks your own policy service for a verdict | Check against an internal risk score |
| Escalation | Routes the call to a person or team | Refunds over $20 go to the Payments team |
Build your first pipeline around the refund example: auto-approve reads and refunds under $20, escalate refunds of $20 or more to Payments, deny everything else from agents you do not fully trust yet. Keep the policy in version control like any other config. This Git beginner guide covers the workflow if you need it, and treat the policy file as production code: review changes, keep history, and never edit the live rules directly.
Where Does the Human Get Asked?
Reviewers get notified on the platform they prefer: Slack, Discord, iPhone and Android apps with push notifications, email, text message, or WhatsApp. The notification carries the tool call and the request context, so the reviewer decides from evidence rather than from a bare "approve?" prompt.
Routing rules decide which requests go to which team or person, based on the agent, the tool, the arguments, or the team. Teams set their own escalation order and on-call flows, and the pipeline escalates when nobody answers in time. The practical beginner move is one routing rule and one on-call person; add teams and escalation chains only after the simple path works.
What Happens After a Decision?
An approved call runs normally and a denied one fails. Every request, every decision, and every note is kept in an append-only audit history with the reviewer's identity attached to each decision, and the full request is stored with each verdict. That log is what you show an auditor, a manager, or yourself at 2 a.m.
The approval itself has a lifecycle worth knowing: approvals expire, an approval must be consumed before execution, and reusing one approval for different arguments is out of bounds (these semantics come from the sister-company walkthrough). And if withHuman itself goes down, the tool call fails rather than passing through: the vendor chose fail-closed deliberately, calling it a conservative choice for a security boundary, with rule caching planned for later.
withHuman vs Navige: What's the Difference?
They solve different problems, so they are never rivals: withHuman is the dedicated approval layer; Navige is a cost-control proxy. Navige's "Sufficiency Intelligence" routes agent requests to smaller models, caches repeated reads, and trims bulky tool results to cut spend; its approval holds are one cost feature inside that system. withHuman's whole product is interception, policies, escalation, and audit. If you are comparing the two, read this Navige beginner guide next; the lanes are adjacent, not competing.
7 Mistakes Beginners Make with withHuman
| Mistake | Why it hurts | What to do instead |
|---|---|---|
| Routing every call to a human | Reviewers get approval fatigue and start rubber-stamping | Auto-approve reads and routine calls; reserve humans for writes and money |
| No explicit final block | Unmatched calls fall back in ways you did not design | Add a final deny (or deliberate review) block at the end of every pipeline |
| One person approves everything | They become the bottleneck, or the single point of failure | Route by agent, tool, and team; set an escalation order |
| Ignoring approval expiry | A stale approval can green-light a call that no longer matches the context | Respect consumption and expiry semantics; never reuse approvals across arguments |
| Handing agents raw credentials | An agent with its own keys can bypass the layer with curl | Use the MCP Gateway so agents never see tokens |
| Skipping the audit history | You lose accountability and the evidence auditors ask for | Review the append-only history regularly, like any production log |
| Forgetting unprotected paths | HTTP-via-CLI and non-MCP calls bypass interception today | Name those paths in your runbook until the vendor closes them |
Sources
- withhuman.ai — product homepage: positioning, the refund flow, interception, pipeline blocks, escalation, notification destinations, framework list (fetched 2026-11-02).
- withHuman launch blog (published 2026-10-15) — the Metoro origin story, the two pieces (open AAP spec + open-source/hosted withHuman), hooks for Claude Code/Codex, Python/TypeScript SDKs, Deep Agents/LangGraph/Pydantic AI/CrewAI/Mastra, MCP Gateway, open problems (fetched 2026-11-02).
- Product Hunt: withHuman (published 2026-10-14, page updated 2026-11-01) — fail-closed vendor comment, Claude Code/Codex + LangGraph/Pydantic AI support, open source + hosted, launch promo terms (fetched 2026-11-02).
- agentapprovalprotocol.io — AAP spec homepage: the three-part model (Agent / Adapter / Approval provider), the adapter install command, spec v1 and OpenAPI contract (fetched 2026-11-02).
- Metoro: Designing an AI SRE from Scratch — sister-company walkthrough: pipeline pattern, fallback-to-human-review, LangGraph middleware code sample, hosted endpoint, approval lifecycle semantics (fetched 2026-11-02).
- Product Hunt: Navige — Navige facts used for the one-line distinction (cost proxy; approval holds as one feature) (fetched 2026-11-02).
- kyaprotocol.org — the colliding "Agent Approval Protocol" (payments authorization, AGSM LLC, March 2026), used only for the disambiguation (fetched 2026-11-02).
Frequently Asked Questions
Is withHuman free?
The code is open source and the vendor runs a hosted version; Product Hunt lists the price as $0. A launch promo (three months of Scale free with a launch code) was advertised as time-sensitive at launch, so do not assume it is still active. Verify current pricing on the vendor site before you commit a team to the hosted plan.
Do I need to rewrite my agent to use withHuman?
No. The hooks, SDKs, and middleware wrap the tool calls around the agent, and the agent's own code and behavior stay the same. The launch blog's framing is that the agent "can't forget to ask," because the asking happens outside the agent.
What happens if withHuman goes down?
The tool call fails instead of passing through. The vendor chose fail-closed on purpose, describing it as the conservative option for a security boundary, with rule caching at an intermediary layer planned for the future.
Is withHuman's AAP the same as KYA Protocol's AAP?
No. They share an acronym and nothing else. KYA Protocol (kyaprotocol.org) is an AI-driven payments-authorization protocol from AGSM LLC, published March 2026. withHuman's AAP (agentapprovalprotocol.io) is the open spec for how agents request and wait for tool-call approvals.
Which agents and frameworks does withHuman support?
Prebuilt hooks exist for Claude Code and Codex; SDKs cover Python and TypeScript; drop-in integrations cover Deep Agents, LangGraph, Pydantic AI, CrewAI, and Mastra; and there is documented AAP middleware for LangChain agents. The list is growing, so check the vendor homepage for the current roster.
