This site does not allow itself to be embedded. You can still read it on the original site — the toolbar below keeps your place in the directory.
A support page nobody talks to is a support page doing half its job. ElevenLabs Agents gives you a two-way voice agent grounded on your own docs: ASR, LLM, TTS and turn-taking in one platform, a widget you embed in five lines, and CLI or MCP management so your coding agent can run it. The complete one-hour build.
A text chat widget answers questions the way you asked them: typed. A voice agent answers them the way your users actually talk - out loud, mid-scroll, hands off the keyboard. It is the difference between a support page and a person standing next to it, and the cost of that difference keeps collapsing.
This guide builds the real thing end to end: a conversational support agent that talks to your visitors, answers from your actual documentation, and lives on your site as an embeddable widget. The platform is [ElevenLabs](https://dub.sh/dd-elevenlabs) Agents, which bundles the four pieces of a voice conversation into one product - speech recognition, an LLM of your choice, text to speech, and a turn-taking model that knows when to speak and when to listen - plus the dashboard, CLI, and MCP server you use to run it. We covered one-way audio from agent runs in the [audio briefs guide](/blog/agent-audio-briefs-elevenlabs); this is the two-way version.
Seven steps, under an hour, each ending in something you can run. No phone required: the web widget is the fastest path, and the same agent plugs into Twilio or a SIP trunk later.
## Official Sources
| Resource | Description |
|----------|-------------|
| [ElevenAgents overview](https://elevenlabs.io/docs/eleven-agents/overview) | Architecture, platform capabilities, model options |
| [ElevenAgents quickstart](https://elevenlabs.io/docs/eleven-agents/quickstart) | First agent in 5 minutes, dashboard and API paths |
| [Widget customization](https://elevenlabs.io/docs/eleven-agents/customization/widget) | Embed code, attributes, security allowlist |
| [Knowledge base docs](https://elevenlabs.io/docs/eleven-agents/customization/knowledge-base) | File formats, RAG modes, size limits |
| [ElevenLabs CLI](https://elevenlabs.io/docs/eleven-agents/operate/cli) | Agents as code, CI/CD, templates |
| [Hosted MCP server](https://elevenlabs.io/docs/eleven-agents/operate/hosted-mcp) | Manage agents from Claude or any MCP client |
| [ElevenLabs pricing](https://elevenlabs.io/pricing) | Plans, credits, per-product credit costs |
## Step 1: Account, API key, and the agents CLI
Prerequisites: an [ElevenLabs](https://dub.sh/dd-elevenlabs) account - the free tier includes 10,000 credits a month, enough for this whole build - and Node.js 16 or newer.
Sign up, then create an API key in the dashboard (**Settings → API Keys**). You will use it once, to authenticate the CLI, which stores the key in `~/.agents/api_keys.json` with file permissions 600:
```bash
npm install -g @elevenlabs/cli
elevenlabs auth login
```
Confirm with `elevenlabs auth whoami` - it should print your account. If the command is missing, your npm bin path is not on `$PATH`; fix it and rerun.
**What you have now:** a CLI that can create, push, and pull agents - the backbone of every later step.
## Step 2: Create the agent from a template
The CLI scaffolds agents as code - configuration in files, version-controllable, deployable from CI. Initialize a project, then add your first agent:
```bash
elevenlabs agents init
elevenlabs agents add "Docs Support" --template customer-service
```
The `customer-service` template exists for exactly this job: professional empathetic prompts, low temperature (0.1) for consistent answers, a 30-minute conversation limit, and evaluation criteria wired up. The other templates cover the spectrum - `assistant` for a general-purpose bot, `voice-only` and `text-only` to force one modality, `minimal` when you want to write everything yourself.
The init command creates the project structure: `agents.json` as the central registry, `agent_configs/` holding one file per agent, plus `tools.json` and `tests.json`.
**What you have now:** a real agent configuration on disk, in files you can commit.
## Step 3: Write the system prompt and first message
This is where the agent becomes yours. Two fields in the config decide the conversation:
- **`agent.prompt.prompt`** - the system prompt, the agent's operating manual.
- **`agent.first_message`** - what it says when a visitor opens the widget. It sets the tone of the whole call, so state who the agent is and what it can do.
A prompt that works for a support voice agent:
```json
{
"agent": {
"first_message": "Hi, this is the Docs Assistant for Acme. I can answer questions about setup, billing, and the API. How can I help?",
"prompt": {
"prompt": "You are the support assistant for Acme. Answer questions about setup, billing, and the API using only the knowledge base. If the answer is not in the knowledge base, say so and offer to open a support ticket. Keep answers to two sentences where possible, and never invent pricing or limits."
}
}
}
```
Two details matter. First, the honesty clause: "use only the knowledge base, and say so when it is not there." A voice agent that confabulates pricing sounds authoritative while being wrong, which is worse than silent. Second, the length limit: spoken answers past two sentences lose the listener. The [prompting guide](https://elevenlabs.io/docs/eleven-agents/best-practices/prompting-guide) covers what else to tune.
**Runnable check:** edit the file, then run `elevenlabs agents push --dry-run` to preview the change before it ships.
## Step 4: Ground it on your docs with a knowledge base
Without grounding, the agent answers from general knowledge and your product is exactly the thing it knows least about. The knowledge base fixes that: upload your docs, and the agent answers from them.
Supported formats are the boring ones - PDF, Markdown, text, HTML, Word, EPUB - up to 20MB per file. Small documents (under about 300,000 characters of extracted text) ride in full context, always available on every turn. Everything larger goes through RAG: the document is indexed into embeddings ahead of time, and per question only the relevant passages are retrieved, which keeps large knowledge bases usable and adds roughly 250ms of latency per answer, per the [RAG docs](https://elevenlabs.io/docs/eleven-agents/customization/knowledge-base/rag).
The fastest path is the dashboard: open your agent, go to the **Knowledge Base** section, upload your FAQ, getting-started guide, and API reference, and toggle **Use RAG** on. In the CLI, set the `rag` block in the pulled config and push:
```json
{
"conversation_config": {
"agent": {
"prompt": {
"rag": {
"enabled": true,
"embedding_model": "e5_mistral_7b_instruct",
"max_vector_distance": 0.6,
"max_retrieved_rag_chunks_count": 20
}
}
}
}
}
```
RAG limits are per workspace, based on tier: 1MB of indexed documents on Free, 2MB on Starter, 20MB on Creator, 100MB on Pro. Indexing happens automatically when documents are attached with RAG on, and can take a few minutes for larger files.
**Runnable check:** ask the agent a question whose answer exists only in one of your docs. If it answers from the doc with the right detail, grounding works.
## Step 5: Test it like a customer
The dashboard has a **Test AI agent** button that opens a live conversation - talk to the agent directly before it ever meets a visitor. Run it through the questions your users actually ask, and crucially, the ones they ask *wrong*: half-formed sentences, slang, the wrong name for a menu. A support agent is graded on the misspelled query, not the perfect one.
Two dashboard features turn that test into signal:
- **Analysis → evaluation criteria.** Define what success looks like - for example "the assistant was able to answer all queries or redirect them to a relevant support channel" - and every transcript is graded against it, with a success/failure/unknown result and a rationale. That is your QA loop, automated.
- **Data collection.** Extract structured data per conversation, like the user's question, so you see what people actually ask rather than what you predicted.
Iterate on the system prompt when the tone is wrong; on the knowledge base when the content is wrong. The evaluation criteria tell you which failure mode you are looking at.
**What you have now:** a tested agent whose conversations are scored against your own definition of success.
## Step 6: Embed the widget on your site
The widget is the deployment. From the CLI, generate the embed snippet:
```bash
elevenlabs agents widget "Docs Support"
```
It outputs two lines. Paste them into the ` ` of your page, replacing the agent ID with yours:
```html
```
That is the whole integration - no server, no SDK, no build step. The widget defaults to voice-only: visitors talk, the agent talks back. Flip on **Voice + text** in the agent's **Widget** tab for both modalities, or **Chat Mode** to start conversations in text. Text modes are worth enabling on day one: voice is the differentiator, but a visitor in a meeting still needs the typed path.
Two security steps before it goes live, both from the [widget docs](https://elevenlabs.io/docs/eleven-agents/customization/widget):
1. Widgets require public agents with authentication disabled - check the **Advanced** tab.
2. Set the **Allowlist** in the **Security** tab to your own domains. Without it, anyone can hotlink your widget and spend your credits from their own site.
**Runnable check:** load your page, open the widget, and ask it a question from your docs - then repeat on your phone. Voice agents break in weird places; test the real deployment surface.
## Step 7: Run it from your coding agent, and watch the cost
Two operations patterns complete the loop.
**Hosted MCP.** ElevenLabs runs a remote MCP server at `https://api.elevenlabs.io/v1/mcp` that exposes agent management to any MCP client - Claude Desktop connects via **Settings → Connectors**, other clients use the server URL with OAuth and Streamable HTTP transport. Once connected, your coding agent can create agents, change voices, estimate LLM cost per conversation before committing a change, and generate voice samples. This is the [MCP primer](/blog/what-is-mcp) applied to ops: you say "make the support agent answer in Spanish for our Latin America launch" and review the proposed config.
**CLI in CI.** The Step 2 project is the deployable artifact: a pipeline step that sets `ELEVENLABS_API_KEY` from secrets and runs `elevenlabs agents push` turns agent changes into pull requests - the same discipline as the [cron automation guide](/blog/opencode-cron-automation-guide).
**The cost.** ElevenLabs credits are shared across all products. Per the pricing FAQ: text to speech costs 1 credit per character, speech to text costs 330 credits per minute, and - the detail that makes support agents cheap - silent periods during a conversation are billed at 5% of the per-minute rate. A typical support call is mostly the customer talking and the agent thinking, so billable audio is a fraction of wall-clock time. The free tier's 10,000 credits covers hours of testing; Starter is $6 a month for 30,000 credits and Creator $22 for 121,000. Model choice is the other lever: pick the smallest LLM that reliably handles the task, per the [cost optimization guide](https://elevenlabs.io/docs/eleven-agents/customization/llm/optimizing-costs).
**What you have now:** a voice support agent, grounded on your docs, scored on your criteria, deployed as a widget, and managed as code - built and shipped in under an hour.
## FAQ
### How is this different from ElevenLabs text-to-speech?
The TTS API turns text into audio - one direction, one step. ElevenLabs Agents is a full conversation platform: speech recognition, an LLM of your choice, TTS, and a turn-taking model that handles interruptions and timing. Our [audio briefs guide](/blog/agent-audio-briefs-elevenlabs) is the one-way version; this build is two-way.
### Can the agent answer from my own documentation?
Yes, that is the point of the knowledge base. Upload PDFs, Markdown, or text files and the agent answers from them, with full-context for small docs and RAG for large ones. If the answer is not in the knowledge base, it says so.
### What does a conversation cost?
Credits, shared with all ElevenLabs products: 1 credit per character of TTS, 330 credits per minute of speech recognition, and silence billed at 5% of the per-minute rate - so a real support call is cheaper than it sounds. Free tier is 10,000 credits a month; Starter is $6 for 30,000.
### Do I need a phone number?
No. The widget embeds in any page with two lines of HTML. When you want an actual phone line, the same agent connects to Twilio or a SIP trunk later.
### Can my coding agent manage the voice agent?
Yes. The hosted MCP server exposes agent management to any MCP client, so Claude Code or another client can create agents, change voices, and estimate costs. The CLI also stores agents as code for CI/CD deploys.
## Sources
| Source | URL |
|--------|-----|
| ElevenAgents overview | https://elevenlabs.io/docs/eleven-agents/overview |
| ElevenAgents quickstart | https://elevenlabs.io/docs/eleven-agents/quickstart |
| Widget customization | https://elevenlabs.io/docs/eleven-agents/customization/widget |
| Knowledge base | https://elevenlabs.io/docs/eleven-agents/customization/knowledge-base |
| RAG guide | https://elevenlabs.io/docs/eleven-agents/customization/knowledge-base/rag |
| ElevenLabs CLI | https://elevenlabs.io/docs/eleven-agents/operate/cli |
| Hosted MCP server | https://elevenlabs.io/docs/eleven-agents/operate/hosted-mcp |
| Cost optimization | https://elevenlabs.io/docs/eleven-agents/customization/llm/optimizing-costs |
| ElevenLabs pricing | https://elevenlabs.io/pricing |
Some links to tools above are referral links - see our [affiliate disclosure](/affiliate-disclosure).
**Last updated:** August 9, 2026
## Continue Reading
- [Make Your Coding Agent Talk](/blog/agent-audio-briefs-elevenlabs) - the one-way version: agent summaries as MP3s with the same platform's TTS
- [Best TTS APIs for Developers 2026](/blog/best-tts-apis-for-developers-2026) - how ElevenLabs stacks up against the text-to-speech alternatives
- [OpenAI Realtime Voice API Guide](/blog/openai-realtime-voice-api-guide) - the other major path to two-way voice, if you are already in the OpenAI stack
- [What Is MCP?](/blog/what-is-mcp) - the protocol behind the hosted MCP server your coding agent uses to run this agent
- [Put an AI Agent on a Cron Job](/blog/opencode-cron-automation-guide) - the scheduling discipline that pairs with agents-as-code deploysRead on developersdigest.tech ↗
Comments
Nothing yet. Say the first thing.
Sign in to join the conversation.