# AwaitHuman

> Your agent's lifeline to human judgment.

AwaitHuman lets AI agents ask humans for help when they can't proceed on their own. Agents create tasks via the API, humans respond via Telegram, and agents poll for results.

## Use Cases

- Visual/aesthetic judgment (logo choices, color schemes, layout reviews)
- Yes/no decisions (deploy to production? send this email?)
- Reviews with feedback (approve, reject, or provide notes)
- Physical world tasks (set up an account, take a photo, check a delivery)

## API

Base URL: `https://api.awaithuman.com/api/v1`

Authentication: Bearer token with API key (`sk_live_...`)

### Create Task

POST /api/v1/tasks

Request body:
```json
{
  "type": "pick_one | yes_no | review | do_for_me",
  "title": "Short question",
  "description": "Detailed context",
  "options": ["Option A", "Option B"],
  "max_reminders": 3,
  "reminder_interval_minutes": 30
}
```

Response:
```json
{
  "task_id": "abc123",
  "status": "sent"
}
```

### Get Task Result

GET /api/v1/tasks/{task_id}

Response:
```json
{
  "task_id": "abc123",
  "status": "completed",
  "result": {
    "choice": "Option A",
    "text": null,
    "image_urls": null
  }
}
```

### Task Types

- **pick_one**: Present options, human picks one. Requires `options` array.
- **yes_no**: Binary decision. Result choice is "yes" or "no".
- **review**: Human can approve, reject, or give feedback. Result choice is "approve", "reject", or "feedback" (with text).
- **do_for_me**: Free-form. Human replies with text and/or images.

### Task Statuses

- `pending` — created, not yet sent to Telegram
- `sent` — delivered to human's Telegram
- `completed` — human responded
- `timed_out` — no response after max reminders
- `cancelled` — cancelled by agent

## MCP Integration

AwaitHuman provides an MCP server (`awaithuman-mcp`) with three tools:

- `create_task` — create a task and notify the human
- `get_task_result` — poll for the human's response
- `wait_for_task` — poll until complete or timeout

Install: `uvx awaithuman-mcp`

## Links

- Website: https://awaithuman.com
- Documentation: https://awaithuman.com/docs/
- Skill guide: https://awaithuman.com/skill.md