Content
# Humand
**English** · [English](README.en.md)
[](https://github.com/dubeno/Humand/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/downloads/)
Humand is an **Human-in-the-Loop** infrastructure for **AI Agent and Python workflow**: pause sensitive operations, wait for human approval, and then continue.
Humand is decoupled from specific Agent frameworks - LangGraph, LangChain, CrewAI, AutoGen, **MCP (Cursor)**, or self-developed HTTP services all use the same REST API. The core is **Humand Service + SDK**; Feishu/Web/local simulated inbox are responsible for waking up humans.
## Core Features
### Approval Lifecycle
| Capability | Description |
|------|------|
| Create and Wait | SDK / REST / MCP initiate approval; MCP defaults to **create and block** until human decision |
| Approve / Reject | Structured results returned to Agent, with approval opinions |
| Request Changes | `changes_requested` status + modification requirements; Agent can `revise` and resubmit |
| Multi-Round Approval | Revised versions automatically associate history, supporting version chain queries |
| Specify Approvers | Match by email/username; support timeout and cancellation |
| Progress and Acceptance | Approve and `send_progress` report stage progress; details page timeline + acceptance loop |
| Webhook Notification | Active push of status changes to Agent, reducing polling |
### Access Methods
| Method | Applicable Scenarios |
|------|----------|
| **Python SDK** | `@require_approval` decorator, `HumandClient` |
| **REST API** | Any language / microservices / self-developed Agent |
| **MCP** | Cursor, Claude Desktop, and other IDE Agents (`pip install -e ".[mcp]"`) |
| **LangGraph** | Optional package `humand_langgraph` approval node |
### Notification Channels
| Channel | Description |
|------|------|
| **Web UI** | Inbox, audit history, activity monitoring, detailed decision-making |
| **Simulator** | Local simulated inbox, zero-external key experience (`make demo`) |
| **Feishu** | Interactive card + callback (optional for production) |
| **Enterprise WeChat / DingTalk** | Webhook notification (optional) |
### Production Capabilities
- **Redis**: Approval storage, session (multi-instance), rate limiting, Webhook retry queue
- **PostgreSQL** (optional): Audit logs, long-term retention
- **Authentication**: Local account; optional LDAP / OIDC
- **Security**: Production API Key, approver verification, readiness probe `/ready`
## One-Minute Experience
```bash
make demo
```
Open after startup:
| Address | Purpose |
|------|------|
| http://localhost:5500 | Local simulated inbox (approve/reject) |
| http://localhost:8808 | Web audit platform (`admin` / `humand-demo`) |
| http://localhost:8808/docs | OpenAPI |
Complete the approval loop without Feishu key. Default ports **8808** / **5500** (see `env.example`).
## Quick Start
```bash
cp env.example .env # Windows: copy env.example .env
pip install -r requirements.txt
pip install -e .
py -3 scripts/run_server.py # or python scripts/run_server.py
```
```python
from humand_sdk import require_approval
@require_approval(
title="Delete Customer Workspace",
approvers=["owner@company.com"],
timeout_seconds=1800,
)
def delete_workspace(workspace_id: str):
return {"deleted": workspace_id}
```
Detailed steps: [docs/GETTING_STARTED.en.md](docs/GETTING_STARTED.en.md)
## Cursor MCP
```bash
pip install -e ".[mcp]"
```
Copy `examples/cursor-mcp.json` to Cursor MCP configuration (or merge into global `mcp.json`). Description: [docs/CURSOR_MCP.en.md](docs/CURSOR_MCP.en.md)
| Tool | Function |
|------|------|
| `humand_request_approval` | Initiate approval and default block waiting |
| `humand_get_approval` | Query single approval status |
| `humand_wait_for_approval` | Asynchronously create and then wait |
| `humand_send_progress` | Report execution progress after approval |
| `humand_revise_approval` | Resubmit after "requesting changes" |
| `humand_list_approvals` | List / filter approvals |
| `humand_cancel_approval` | Cancel pending approvals |
| `humand_get_approval_history` | View multi-round version chain |
## Architecture Overview
```text
Arbitrary Agent Runtime Humand (framework-agnostic)
───────────────── ────────────────────
LangGraph / MCP / Self-developed REST API ←→ SDK / MCP
Approval Lifecycle
│
┌───────────────┼───────────────┐
▼ ▼ ▼
Rate Limiting / Session Webhook Retry Notification (Web / Feishu / Simulator)
```
1. Sensitive actions → Create approval
2. Human decision on Web / Feishu / simulated inbox
3. Approve → Agent continues; reject / request changes → stop or revise
## Documentation
| Document | Description |
|------|------|
| [Quick Start](docs/GETTING_STARTED.en.md) | Installation, ports, verification |
| [Cursor MCP](docs/CURSOR_MCP.en.md) | IDE Agent integration |
| [API Reference](docs/API_REFERENCE.md) | SDK and HTTP usage |
| [OpenAPI](docs/openapi.yaml) | Machine-readable contract |
| [Scope](docs/SCOPE.en.md) | Functional boundary (read before contributing) |
| [Contribution Guide](CONTRIBUTING.md) | Development and PR |
| [Security Note](SECURITY.md) | Vulnerability reporting and production hardening |
See [README.en.md](README.en.md) for English documentation (including integration instructions, Feishu configuration, etc.).
## Open Source
- MIT License
- Set `HUMAND_API_KEY` and `HUMAND_BOOTSTRAP_ADMIN_PASSWORD` in production environment
## License
MIT
