Docs / References

Plain-text version: /docs/voice-agents.md  ·  llms.txt

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 surface instead — that's the public, anonymous-callable layer.

Auth

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 for the human-tier system.

Required scopes

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)

See also

• Quickstart
• Authentication
• Recommendation Agents — for the public agent-callable surface