# Voice Agents — agent-api reference

Voice agents are a **separate system** from recommendation agents. They run on ElevenLabs Conversational AI for inbound + outbound phone calls. The public agent surface is for *autonomous internal agents* (those that own an AGOS API key) — not for arbitrary external callers.

## When to use this

- An autonomous agent (with an AGOS Bearer key + voice scopes) needs to programmatically build/configure a voice agent
- That agent needs to attach phone numbers, knowledge base entries, or tools (Calendly, custom webhooks)
- That agent needs to launch outbound campaigns (subject to human approval gates)
- That agent needs to monitor calls (transcripts, recordings, conversion outcomes)

If you're an external agent looking for product recommendations, use the [Recommendation Agent](/docs/recommendation-agents) surface instead — that's the public, anonymous-callable layer.

## Auth

```http
Authorization: Bearer agos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

API keys are minted in the AgilityOS dashboard at **Settings → Agent Keys**. Each key has scopes + an `agentId` (for ownership isolation) — see [Authentication](/docs/auth) for the human-tier system.

## Required scopes

| Scope | Grants |
|---|---|
| `voice:read` | List/read agents, voices, phone numbers, conversations, KB, tools, campaigns |
| `voice:write` | CRUD agents, KB, tools, env vars; attach existing phone numbers |
| `voice:campaign:write` | Create campaigns, load contacts |
| `voice:campaign:execute` | Request start/pause/stop (queues for human approval) |
| `voice:read:all` | Cross-owner read (for ops/audit agents) |

## Endpoints (28 total)

### Agents
- `GET /api/agent-api/voice/agents` — list (filtered by ownerAgentId)
- `GET /api/agent-api/voice/agents/:id` — read
- `POST /api/agent-api/voice/agents` — create
- `PATCH /api/agent-api/voice/agents/:id` — update
- `DELETE /api/agent-api/voice/agents/:id` — delete

### Voices + phone numbers
- `GET /api/agent-api/voice/voices` — EL voice library
- `GET /api/agent-api/voice/phone-numbers` — owned Twilio numbers
- `POST /api/agent-api/voice/agents/:id/phone` — attach existing phone

### Knowledge base
- `GET /api/agent-api/voice/knowledge` — list KB documents
- `POST /api/agent-api/voice/knowledge/text` — add text doc
- `POST /api/agent-api/voice/knowledge/url` — add URL doc
- `DELETE /api/agent-api/voice/knowledge/:docId` — delete
- `PATCH /api/agent-api/voice/agents/:id/knowledge` — attach to agent

### Per-agent env vars + tools
- `GET /api/agent-api/voice/agents/:id/env-vars` — list keys
- `PUT /api/agent-api/voice/agents/:id/env-vars/:name` — set value
- `DELETE /api/agent-api/voice/agents/:id/env-vars/:name` — delete
- `GET /api/agent-api/voice/agents/:id/tools` — list attached tools
- `POST /api/agent-api/voice/agents/:id/tools/calendly` — attach Calendly preset
- `POST /api/agent-api/voice/agents/:id/tools` — attach custom webhook tool
- `DELETE /api/agent-api/voice/agents/:id/tools/:name` — detach

### Conversations
- `GET /api/agent-api/voice/agents/:id/conversations` — list
- `GET /api/agent-api/voice/conversations/:id` — read

### Campaigns + execution
- `GET /api/agent-api/voice/campaigns` — list (owner-scoped)
- `GET /api/agent-api/voice/campaigns/:id` — read
- `POST /api/agent-api/voice/campaigns` — create
- `POST /api/agent-api/voice/campaigns/:id/contacts` — load contacts (max 5000/call)
- `GET /api/agent-api/voice/campaigns/:id/contacts` — list contacts
- `POST /api/agent-api/voice/campaigns/:id/(start|pause|stop)` — request action (human-gated)
- `GET /api/agent-api/voice/actions/:id` — poll action status

## Human-approval queue

Calls to `start`/`pause`/`stop` do **not** execute immediately. They insert a row in `va_campaign_actions` with `status: 'awaiting_approval'`. A human reviews and approves in the dashboard at `/voice-approvals`. On approval, the EL batch call fires for `start`; the campaign is paused/stopped for the others.

This is the security spine: no autonomous agent can place real outbound calls without human gating.

## Carve-outs (NOT exposed to autonomous agents)

| Capability | Why excluded |
|---|---|
| Twilio number provisioning | Spends money — UI/human only |
| Voice settings (account-level credentials) | Secrets — UI/human only |

## See also

- [Quickstart](/docs/quickstart)
- [Authentication](/docs/auth)
- [Recommendation Agents](/docs/recommendation-agents) — for the public agent-callable surface