人机协作AI

What you can build with it

Real production patterns this primitive collapses into a single function call:

• High-value approvals — refunds above a threshold, wire transfers, plan upgrades, contract renewals. Agent prepares the case (Pydantic payload), human signs off with a typed decision (approved + reason).
• KYC / identity review — agent flags borderline documents, human inspects, sends back verified: bool with notes. Pair with verifier=verify_with_claude(...) to pre-check the reviewer's reasoning.
• Content moderation escalation — AI tags a borderline post; instead of hard-deciding, it calls await_human() with the content + AI's reasoning + a Switch for keep/remove. Reviewer's decision flows back into the moderation pipeline.
• Agent-generated code review — your LLM drafts a pull request; before merge, the agent waits for a human to approve via Slack. The "Claim this task" button assigns it to whoever's on rotation.
• Customer-success escalation — support agent answers FAQs; on a complex thread, it escalates to a human with the full transcript as the payload. Human writes the reply, agent posts it.
• Scrape-and-CAPTCHA fallback — automation hits a CAPTCHA wall, calls await_human() with the screenshot, a human solves it, agent resumes the scrape.

Anything where an LLM's confidence is too low, the liability too high, or the source of truth lives outside the model's reach — it's HITL-shaped, and this primitive fits.

---

Quick start

60 seconds. Two terminals. First-time setup needs a browser click; everything else is paste-and-run.

Terminal 1 — server + dashboard:

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:

pip install awaithumans pydantic && cat > /tmp/refund.py <<'PY'
from awaithumans import await_human_sync
from pydantic import BaseModel

class RefundRequest(BaseModel):
    order_id: str
    amount_usd: float

class Decision(BaseModel):
    approved: bool

d = await_human_sync(
    task="Approve refund of $180?",
    payload_schema=RefundRequest,
    payload=RefundRequest(order_id="A-4721", amount_usd=180),
    response_schema=Decision,
    timeout_seconds=300,
)
print("approved" if d.approved else "rejected")
PY
python /tmp/refund.py

The script blocks. Open the dashboard, click the pending task, hit Approve. The script unblocks with the typed Decision.

That's the full loop. From here, swap the schema for your own, add notify=["slack:#ops", "email:ops@yourco.com"] to route the task elsewhere, or wrap the call in a Temporal / LangGraph workflow.

More examples — refund, KYC, content moderation, Slack-native, Temporal, LangGraph — in examples/.

---

Packages

License: Apache License 2.0. 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.

---

Troubleshooting

If something isn't working, run the pre-flight check first:

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.

---