# Awaithumans Human In The Loop Ai Agents > Pause your AI agent. Ask a human. Resume with their answer. Open source human-in-the-loop (HITL) library for production LLM agents: Slack, email, and web dashboard. Typed Pydantic and Zod responses. Durable Temporal and LangGraph adapters. AI verifier. Audit trail. Self-hosted, Apache 2.0. Python and TypeScript. - **Type:** MCP server - **Install:** `agentstack add mcp-awaithumans-awaithumans-human-in-the-loop-ai-agents` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [awaithumans](https://agentstack.voostack.com/s/awaithumans) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [awaithumans](https://github.com/awaithumans) - **Source:** https://github.com/awaithumans/awaithumans-human-in-the-loop-ai-agents - **Website:** https://awaithumans.dev ## Install ```sh agentstack add mcp-awaithumans-awaithumans-human-in-the-loop-ai-agents ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # awaithumans — HITL infrastructure for AI agents **Your agents already await promises. Now they can await humans.** [](https://pepy.tech/project/awaithumans) [](https://www.npmjs.com/package/awaithumans) [](https://github.com/awaithumans/awaithumans-human-in-the-loop-ai-agents) [](https://pypi.org/project/awaithumans/) [](https://www.npmjs.com/package/awaithumans) [](https://github.com/awaithumans/awaithumans-human-in-the-loop-ai-agents/actions/workflows/test.yml) [](https://github.com/awaithumans/awaithumans-human-in-the-loop-ai-agents/blob/main/LICENSE) [](https://www.python.org/downloads/) [](https://discord.gg/Kewdh7vjdc) [**Docs**](https://docs.awaithumans.dev) · [**Quickstart**](https://docs.awaithumans.dev/quickstart) · [**Examples**](./examples) · [**Discord**](https://discord.gg/Kewdh7vjdc) **HITL infrastructure for AI agents — open source.** A single primitive (`await_human()` / `awaitHuman()`) your agent calls when it needs a human. A real person reviews via Slack / email / a built-in dashboard, submits a typed response, and your agent resumes — like awaiting any other promise. ```python from awaithumans import await_human from pydantic import BaseModel class Decision(BaseModel): approved: bool note: str | None = None decision = await await_human( task="Approve refund request", payload_schema=RefundRequest, payload=RefundRequest(order_id="A-4721", amount_usd=180), response_schema=Decision, timeout_seconds=900, ) if decision.approved: process_refund(...) ``` The agent waits on `decision` like it waits on any other Promise or Future. A human gets notified ([Slack](https://slack.com), email, dashboard), reviews the request, and submits a typed response. The agent resumes with the typed answer. --- ## The problem Every production agent hits a wall where the model can't or shouldn't proceed alone. Three distinct walls, each permanent: - **Judgment.** The agent has the information but can't be trusted to decide. High liability, regulation, or consequence — KYC approvals, refund sign-offs, content moderation escalations. A human carries the accountability. - **System-uncertainty.** The agent doesn't know the state of the world. The source of truth is in a bank dashboard, a partner system, a manual file. No model can close this gap. A human investigates and tells the agent what's true. - **Embodiment.** The task requires a real person — signing, calling, picking something up, passing a CAPTCHA. Not a model problem. Better models don't solve walls 2 and 3. `awaithumans` makes the call to a human a first-class primitive instead of a pile of bespoke glue per project. --- ## Why awaithumans | | **awaithumans** | humanlayer | DIY glue code | |---|---|---|---| | **Maintained** | ✅ Active development | ❌ Abandoned | — | | **Setup time** | One command (`awaithumans dev`) | Per-customer rebuild | Weeks | | **Channels** | Slack + email + built-in dashboard | Slack only | Build each yourself | | **Typed responses** | ✅ [Pydantic](https://pydantic.dev) (Python) / [Zod](https://zod.dev) (TS) — schema-validated end to end | Partial | Build each yourself | | **Restart-safe** | ✅ Stripe-style idempotency — agent resumes across restarts | ❌ | Build each yourself | | **AI pre-verification** | ✅ [Claude](https://www.anthropic.com/claude) / [OpenAI](https://openai.com) / [Gemini](https://gemini.google.com) / [Azure](https://azure.microsoft.com/en-us/products/ai-services/openai-service) — pre-check the human's answer before the agent trusts it | ❌ | Build each yourself | | **Workflow engines** | ✅ [Temporal](https://temporal.io) + [LangGraph](https://langchain-ai.github.io/langgraph/) adapters — hand the wait to the engine | ❌ | Build each yourself | | **Self-hostable** | ✅ Docker + Postgres in one command | SaaS-only | — | | **License** | Apache 2.0 (patent grant) | — | — | Built by engineers who hit the HITL wall three times in production fintech and ScaleBrick agent systems — and watched the only OSS alternative get abandoned by its founder over per-customer-fork creep. The architecture has exactly four extension points (channels, verifiers, routers, task-type handlers) so no single customer can push the core into the same trap. --- ## Quick start **60 seconds. Two terminals.** First-time setup needs a browser click; everything else is paste-and-run. **Terminal 1** — server + dashboard: ```bash pip install "awaithumans[server]" && awaithumans dev ``` Click the setup URL it prints, create your operator account. The dashboard is now at `http://localhost:3001`. **Terminal 2** — paste this whole block: ```bash pip install awaithumans pydantic && cat > /tmp/refund.py **Note on the image name.** The canonical image is > `ghcr.io/awaithumans/awaithumans-human-in-the-loop-ai-agents`. The > shorter `ghcr.io/awaithumans/awaithumans` from earlier release notes > is **deprecated** and frozen at a pre-rename build — older docs and > blog posts pointing there pull a stale image. Update any pipelines > or compose files referencing the short name. Or `docker compose up` with the included `docker-compose.yml` (optional Postgres block inside). Backs everything — API, dashboard, channels — from one image. --- ## Managed: AwaitVerify If your use case is **document verification** and you would rather not run the infrastructure or recruit reviewers yourself, [**AwaitVerify**](https://awaithumans.dev/awaitverify) is the managed service we sell on top of this primitive. We provide the humans, the ops, and the SLA. You keep the same one-function-call integration. ```python from awaithumans import verify_document # also aliased as awaitVerify from pydantic import BaseModel class LineItem(BaseModel): sku: str qty: int unit_price_cents: int class Invoice(BaseModel): invoice_number: str total_cents: int line_items: list[LineItem] result = await verify_document( document_path="./invoice.pdf", prior_extraction={ "invoice_number": "INV-4471", "total_cents": 12000, "line_items": [...], }, response_schema=Invoice, priority="standard", # or "high" for the Express queue api_key=os.environ["AWAITHUMANS_API_KEY"], ) ``` **$0.80 per page** standard. **$0.60** at 1,000+ pages/month. **Custom** at 10,000+. The Express SLA (30-minute target during Mon-Fri 8am-8pm ET, best-effort outside) runs at 2x the rate and is triggered by `priority="high"`. The SDK fragments the document **client-side** into five masked views before any upload. The full unfragmented document never leaves your environment. Fragments are encrypted in transit (TLS 1.2+) and at rest (AES-256-GCM with per-task data keys destroyed on reviewer submit). [**Sign up at app.awaithumans.dev**](https://app.awaithumans.dev) · [**Pricing**](https://awaithumans.dev/awaitverify#pricing) · [**Security**](https://awaithumans.dev/awaitverify/security) --- ## Architecture - **Core primitive:** one function, `await_human()` / `awaitHuman()`, typed-in-typed-out. - **Task store:** SQLite in dev, Postgres in prod. Idempotency keys, atomic state transitions, audit trail. - **Channels:** Slack + email today. Plug in your own by implementing a small interface (`server/channels/`). - **Verifiers:** [Claude](https://www.anthropic.com/claude) today, [OpenAI](https://openai.com), [Gemini](https://gemini.google.com), and [Azure OpenAI](https://azure.microsoft.com/en-us/products/ai-services/openai-service) shipped; any provider is a one-file adapter. - **Router:** least-recently-assigned over a user directory with free-form `role`/`access_level`/`pool` labels. - **Task-type handlers:** forms auto-generated from your [Pydantic](https://pydantic.dev) / [Zod](https://zod.dev) schema, rendered per channel (Slack Block Kit, email, web form). Every customization flows through one of these four buckets. That's the entire extension surface. --- ## Documentation - **Quickstart:** [`examples/quickstart/`](./examples/quickstart/) - **Full docs:** [docs.awaithumans.dev](https://docs.awaithumans.dev) - **Contributing:** [`CONTRIBUTING.md`](./CONTRIBUTING.md) - **Security policy:** [`SECURITY.md`](./SECURITY.md) --- ## Built with awaithumans? Drop this badge in your project's README so folks know where the HITL primitive came from: [](https://github.com/awaithumans/awaithumans-human-in-the-loop-ai-agents) ```markdown [](https://github.com/awaithumans/awaithumans-human-in-the-loop-ai-agents) ``` Or generate a generic variant via [shields.io](https://shields.io): ```markdown [](https://github.com/awaithumans/awaithumans-human-in-the-loop-ai-agents) ``` --- ## Troubleshooting If something isn't working, run the pre-flight check first: ```bash awaithumans doctor ``` It scans your environment for the most common misconfigurations — missing or malformed `PAYLOAD_KEY`, Slack token issues, unreachable database, Docker bind-mount gotchas — and prints a clear report with actionable fixes. Catches ~80% of first-run issues in under 2 seconds. --- ## Packages | Package | Registry | License | |---|---|---| | `awaithumans` (Python SDK + server + CLI + dashboard) | PyPI | Apache 2.0 | | `awaithumans` (TypeScript SDK) | npm | Apache 2.0 | | `ghcr.io/awaithumans/awaithumans-human-in-the-loop-ai-agents` (container) | GHCR | Apache 2.0 | **License:** [Apache License 2.0](LICENSE). Permissive, OSI-approved, with an explicit patent grant. Use it in proprietary stacks, fork it, ship it inside paid products — no fee, no contact required. The only thing the license asks is that you preserve the notice and don't use the project's trademarks without permission. --- ## Status **v0.1.0 — public preview.** Released 2026-05-11. The full primitive, all three channels (dashboard / Slack / email), both durable adapters (Temporal / LangGraph), AI verification across four providers, and one-command self-hosting are all live in this release. This is a young project — APIs are stable for v0.x, but expect rough edges in the long tail. File issues, open PRs, drop questions in [Discussions](https://github.com/awaithumans/awaithumans-human-in-the-loop-ai-agents/discussions) or [Discord](https://discord.gg/Kewdh7vjdc). Every reproducible bug report shipped with a fix in v0.2. For the post-launch roadmap — local task book for runtimes without an orchestrator, custom router strategies, post-launch hardening — see [Roadmap & help wanted](https://docs.awaithumans.dev/community/roadmap). --- ## Contributors awaithumans is built by the maintainers and these brilliant community contributors. Hiren Gajjar awaithumans doctor #150 Want to be on this list? Pick a [`good first issue`](https://github.com/awaithumans/awaithumans-human-in-the-loop-ai-agents/labels/good%20first%20issue), drop a comment on it to claim, and we'll review your PR within ~24h. As we grow, this gallery shrinks each avatar back down to a tight grid — same shape, more faces. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [awaithumans](https://github.com/awaithumans) - **Source:** [awaithumans/awaithumans-human-in-the-loop-ai-agents](https://github.com/awaithumans/awaithumans-human-in-the-loop-ai-agents) - **License:** Apache-2.0 - **Homepage:** https://awaithumans.dev Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-awaithumans-awaithumans-human-in-the-loop-ai-agents - Seller: https://agentstack.voostack.com/s/awaithumans - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.