# ElevenLabs ConvAI — Full-Duplex Voice Agent Platform

> ElevenLabs ConvAI bundles STT, LLM, TTS, VAD, barge-in into one managed voice agent. Define prompt, attach tools, point at Twilio number.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

1. Create agent at elevenlabs.io/app/conversational-ai (or via API)
2. Set prompt, voice, optional tools schema
3. Embed via `<elevenlabs-convai>` widget or connect to Twilio Stream

---

## Intro

ElevenLabs Conversational AI is a managed voice agent platform — bring an agent prompt and an optional function-call schema, ElevenLabs handles STT, LLM routing, ElevenLabs TTS, VAD, and barge-in. Drop it into a web widget, a Twilio phone number, or any custom WebRTC client. Best for: customer support bots, lead qualification calls, voice characters in mobile apps, anyone who wants sub-1-second voice without wiring four providers. Works with: Web JS SDK, Python SDK, Twilio Voice integration. Setup time: 15 minutes.

---

### Create an agent (dashboard or API)

```python
import requests

agent = requests.post(
    "https://api.elevenlabs.io/v1/convai/agents/create",
    headers={"xi-api-key": API_KEY},
    json={
        "name": "Refund Triage",
        "conversation_config": {
            "agent": {
                "prompt": {
                    "prompt": "You triage refund requests. Confirm order ID, reason, then offer to escalate to a human if amount > $500.",
                    "llm": "gpt-4o-mini",
                },
                "first_message": "Hi, I can help with refunds. What's your order ID?",
                "language": "en",
            },
            "tts": {"voice_id": "21m00Tcm4TlvDq8ikWAM", "model_id": "eleven_turbo_v2_5"},
            "asr": {"provider": "elevenlabs", "language": "en"},
        },
    },
).json()
print(agent["agent_id"])
```

### Attach a tool (function call)

```python
tools = [{
    "type": "client",
    "name": "lookup_order",
    "description": "Look up order status by ID",
    "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
    },
}]

requests.patch(
    f"https://api.elevenlabs.io/v1/convai/agents/{agent_id}",
    headers={"xi-api-key": API_KEY},
    json={"conversation_config": {"agent": {"tools": tools}}},
)
```

### Embed in a web app

```html
<!-- One-line embed via official widget -->
<elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>
<script src="https://elevenlabs.io/convai-widget/index.js" async type="text/javascript"></script>
```

### Wire to Twilio (phone agent)

```python
# In Twilio Voice webhook
from twilio.twiml.voice_response import VoiceResponse, Connect

response = VoiceResponse()
connect = Connect()
connect.stream(url="wss://api.elevenlabs.io/v1/convai/conversation?agent_id=YOUR_AGENT_ID")
response.append(connect)
return str(response)
```

### Pricing tiers (May 2026)

| Plan | Minutes/month | Per extra min |
|---|---|---|
| Starter ($5) | 60 | $0.30 |
| Creator ($22) | 250 | $0.20 |
| Pro ($99) | 1,100 | $0.18 |
| Scale ($330) | 3,800 | $0.15 |
| Business ($1,320) | 13,500 | $0.12 |

---

### FAQ

**Q: ConvAI vs LiveKit Agents?**
A: ConvAI is managed and opinionated — one bill, ElevenLabs TTS, fast to ship. LiveKit Agents is self-assembled — you pick STT/LLM/TTS, run on your infra, cheaper at scale, more control. Use ConvAI for fast launch, LiveKit when scale or vendor diversity matters.

**Q: Can I use a non-ElevenLabs LLM?**
A: Yes — set `llm` to a custom endpoint with OpenAI-compatible schema. Or use Anthropic / Gemini through the supported list. ElevenLabs handles the orchestration regardless of which LLM serves tokens.

**Q: Latency in practice?**
A: Typical round-trip 600-900ms on Pro tier with Turbo v2.5 TTS. Long agents with verbose tool calls slip into 1.2-1.8s. Use `first_message` and avoid huge system prompts to keep TTFR (time-to-first-response) tight.

---

## Source & Thanks

> Built by [ElevenLabs](https://github.com/elevenlabs). ConvAI docs at [elevenlabs.io/docs/conversational-ai](https://elevenlabs.io/docs/conversational-ai).
>
> [elevenlabs/elevenlabs-python](https://github.com/elevenlabs/elevenlabs-python) — official SDK

---

<!-- ZH -->

## 快速使用

1. 在 elevenlabs.io/app/conversational-ai 建 agent（或用 API）
2. 设 prompt、嗓音、可选 tools schema
3. 用 `<elevenlabs-convai>` widget 嵌入或接 Twilio Stream

---

## 简介

ElevenLabs Conversational AI 是托管语音 agent 平台 —— 给一段 agent prompt 加可选 function-call schema，ElevenLabs 负责 STT、LLM 路由、ElevenLabs TTS、VAD、打断处理。嵌网页 widget、绑 Twilio 电话号码、或接任何自定义 WebRTC 客户端。适合客服 bot、销售线索资格 call、移动应用里的语音角色，任何想要 <1 秒延迟但不想接 4 家 provider 的人。兼容 Web JS SDK、Python SDK、Twilio Voice 集成。装机时间 15 分钟。

---

### 创建 agent（仪表盘或 API）

```python
import requests

agent = requests.post(
    "https://api.elevenlabs.io/v1/convai/agents/create",
    headers={"xi-api-key": API_KEY},
    json={
        "name": "退款分流",
        "conversation_config": {
            "agent": {
                "prompt": {
                    "prompt": "你处理退款请求。确认订单号、原因，金额 >500 美元时主动升级到人工。",
                    "llm": "gpt-4o-mini",
                },
                "first_message": "你好，我可以帮你处理退款。订单号是多少？",
                "language": "zh",
            },
            "tts": {"voice_id": "21m00Tcm4TlvDq8ikWAM", "model_id": "eleven_turbo_v2_5"},
            "asr": {"provider": "elevenlabs", "language": "zh"},
        },
    },
).json()
print(agent["agent_id"])
```

### 挂工具（function call）

```python
tools = [{
    "type": "client",
    "name": "lookup_order",
    "description": "按订单号查状态",
    "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
    },
}]

requests.patch(
    f"https://api.elevenlabs.io/v1/convai/agents/{agent_id}",
    headers={"xi-api-key": API_KEY},
    json={"conversation_config": {"agent": {"tools": tools}}},
)
```

### 嵌入网页

```html
<!-- 官方 widget 一行嵌入 -->
<elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>
<script src="https://elevenlabs.io/convai-widget/index.js" async type="text/javascript"></script>
```

### 接 Twilio（电话 agent）

```python
# Twilio Voice webhook 里
from twilio.twiml.voice_response import VoiceResponse, Connect

response = VoiceResponse()
connect = Connect()
connect.stream(url="wss://api.elevenlabs.io/v1/convai/conversation?agent_id=YOUR_AGENT_ID")
response.append(connect)
return str(response)
```

### 价格档（2026 年 5 月）

| 套餐 | 每月分钟 | 超出价 |
|---|---|---|
| Starter（$5）| 60 | $0.30/分钟 |
| Creator（$22）| 250 | $0.20/分钟 |
| Pro（$99）| 1,100 | $0.18/分钟 |
| Scale（$330）| 3,800 | $0.15/分钟 |
| Business（$1,320）| 13,500 | $0.12/分钟 |

---

### FAQ

**Q: ConvAI vs LiveKit Agents？**
A: ConvAI 托管、固定栈 —— 一张账单、ElevenLabs TTS、上线快。LiveKit Agents 自组装 —— 自选 STT/LLM/TTS、自有基建、规模更便宜、控制更强。快速上线用 ConvAI，规模或多厂商用 LiveKit。

**Q: 能用非 ElevenLabs 的 LLM 吗？**
A: 能 —— `llm` 设为带 OpenAI 兼容 schema 的自定义 endpoint。或在支持列表里用 Anthropic / Gemini。无论 LLM 谁出 token，ElevenLabs 都负责编排。

**Q: 实际延迟？**
A: Pro 档 Turbo v2.5 TTS 典型往返 600-900ms。带啰嗦 tool 调用的长 agent 滑到 1.2-1.8 秒。用 `first_message` 同时避免巨长 system prompt 保 TTFR（首响时间）紧。

---

## 来源与感谢

> Built by [ElevenLabs](https://github.com/elevenlabs). ConvAI docs at [elevenlabs.io/docs/conversational-ai](https://elevenlabs.io/docs/conversational-ai).
>
> [elevenlabs/elevenlabs-python](https://github.com/elevenlabs/elevenlabs-python) — official SDK


---
Source: https://tokrepo.com/en/workflows/elevenlabs-convai-full-duplex-voice-agent-platform
Author: ElevenLabs