# AwaitHuman Skill Guide

This guide is for AI agents that want to use AwaitHuman to ask their human operator for help.

## When to use AwaitHuman

Use AwaitHuman when you encounter something you cannot do or decide on your own:

- **You need a subjective opinion** — "Which of these designs looks better?"
- **You need approval** — "Should I deploy this to production?"
- **You need human action** — "Please set up the Stripe account and give me the API key"
- **You need verification** — "Does this landing page copy feel right?"

Do NOT use AwaitHuman for things you can figure out yourself (calculations, code logic, factual lookups).

## Setup

### Option 1: MCP Server (recommended for Claude Code, Cursor, etc.)

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "awaithuman": {
      "command": "uvx",
      "args": ["awaithuman-mcp"],
      "env": {
        "AWAITHUMAN_API_KEY": "sk_live_your_key_here",
        "AWAITHUMAN_API_URL": "https://api.awaithuman.com/api/v1"
      }
    }
  }
}
```

### Option 2: Direct API

```bash
curl -X POST https://api.awaithuman.com/api/v1/tasks \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"type":"yes_no","title":"Deploy?","description":"All tests pass."}'
```

## Task Types

### pick_one

Present multiple options. The human taps a button to choose.

```json
{
  "type": "pick_one",
  "title": "Which color scheme for the landing page?",
  "description": "I generated 3 options. Which feels right for a B2B SaaS?",
  "options": ["Dark (navy + cyan)", "Light (white + blue)", "Gradient (purple to blue)"]
}
```

**Result:** `{"choice": "Dark (navy + cyan)"}`

### yes_no

Binary decision. Two buttons: Yes and No.

```json
{
  "type": "yes_no",
  "title": "Deploy to production?",
  "description": "All 87 tests pass. Staging looks good. Ready to ship?"
}
```

**Result:** `{"choice": "yes"}` or `{"choice": "no"}`

### review

Three options: Approve, Reject, or Feedback. If feedback, the human types a text response.

```json
{
  "type": "review",
  "title": "Review the landing page copy",
  "description": "Headline: 'Work gets done. By whoever is best.'\nSubheadline: 'The task network for the mixed workforce.'"
}
```

**Result:** `{"choice": "approve"}`, `{"choice": "reject"}`, or `{"choice": "feedback", "text": "Make it more aggressive"}`

### do_for_me

Free-form. The human replies with text, images, or both. Use this for tasks the agent physically cannot do.

```json
{
  "type": "do_for_me",
  "title": "What is your Stripe account email?",
  "description": "I need to configure payment processing. Please provide the email associated with your Stripe account."
}
```

**Result:** `{"text": "it's hello@example.com", "image_urls": []}` or `{"choice": "cant_do"}`

## Polling for Results

After creating a task, poll for the result:

```
GET /api/v1/tasks/{task_id}
```

The `status` field tells you the state:
- `sent` — waiting for human response (keep polling)
- `completed` — human responded, check `result`
- `timed_out` — human didn't respond in time
- `cancelled` — task was cancelled

**MCP shortcut:** Use `wait_for_task` which polls automatically:

```
wait_for_task(task_id, poll_interval=10, timeout=300)
```

## Best Practices

1. **Write clear titles.** The title is what the human sees first in their Telegram notification. Make it scannable.
2. **Provide context in the description.** The human may not have your full context. Explain why you're asking and what you'll do with the answer.
3. **Use the right task type.** Don't use `do_for_me` when `yes_no` would suffice. Simpler types get faster responses.
4. **Handle timeouts gracefully.** If the human doesn't respond, decide what to do — use a sensible default, skip the step, or ask again with higher urgency.
5. **Don't spam.** Batch related questions when possible. Don't create 10 tasks in a row if one task with options would work.

## Parameters Reference

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| type | string | yes | — | `pick_one`, `yes_no`, `review`, or `do_for_me` |
| title | string | yes | — | Short title (shown in Telegram notification) |
| description | string | no | `""` | Detailed context |
| options | string[] | pick_one only | — | List of choices |
| image_urls | string[] | no | `[]` | Public image URLs to show the human |
| images | string[] | no | `[]` | Base64-encoded images |
| max_reminders | int | no | `3` | Max reminder notifications |
| reminder_interval_minutes | int | no | `30` | Minutes between reminders |
| metadata | object | no | `{}` | Passthrough data (returned in result) |