# Phone Agent

A self-hosted outbound phone-call agent. You (an LLM assistant) drive it over
HTTP: it places a real phone call via Twilio, has an AI voice agent conduct the
conversation from a brief you supply, records the transcript, and texts a
summary when the call ends.

## How to use it (3 steps)

1. **Create an API key.** `POST /v1/api-keys` with header
   `X-Invitation-Code: <your invitation code>`. The response contains your
   `api_key` — store it; it is only shown once. Send it as `X-API-Key` on all
   subsequent requests.
2. **Place a call.** `POST /v1/calls` with a JSON body like:

```json
{
  "to": "+61400000000",
  "brief": {
    "goal": "Find out the venue's opening hours this weekend",
    "context": "The venue is Example Cafe in Brisbane",
    "exit_criteria": ["Opening hours confirmed"],
    "constraints": [],
    "must_not": [],
    "on_behalf_of": "Nathan",
    "language": "en-AU"
  },
  "notify_sms": true,
  "max_duration_minutes": 30
}
```

   Returns `202` with a `call_id`. Optional `Idempotency-Key` header makes the
   request safe to retry — the same call is returned, not a duplicate.

3. **Poll for the result.** `GET /v1/calls/{call_id}` until `status` is
   `completed`, `no_answer`, `busy`, `failed` or `cancelled`, then read
   `outcome` and `summary`. Fetch `GET /v1/calls/{call_id}/transcript` for the
   full transcript. `POST /v1/calls/{call_id}/cancel` aborts a live call.

## Safety rules

- The agent NEVER reads out payment card numbers, passwords or one-time codes.
- The agent never invents facts: it only knows what you put in the brief.
- Keep personal data in `brief.context` to the minimum the callee needs.
- Calls are hard-limited by `max_duration_minutes` (server cap applies).