# Edit a Flow with AI
Source: https://docs.voiceblox.ai/ai-generation/edit-flow
Iterate on existing flows using natural language instructions.
# Edit a Flow with AI
You can ask the AI to modify your existing flow at any time. The AI receives the current graph state and generates targeted operations to apply your requested changes.
## How to edit
1. Open the AI panel
2. Describe what you want to change (you don't need to describe the whole flow)
3. The AI generates only the operations needed for your change
## What you can edit
* **Change node parameters** — update any parameter on any node (e.g., "Change the greeting to be more formal")
* **Add steps** — insert new conversation nodes into the chain
* **Remove steps** — delete nodes and their edges
* **Add branches** — turn a linear flow into a branching one
* **Add integrations** — connect MCP servers, Exa search, or webhooks
* **Swap providers** — change the LLM, TTS, or STT provider
## How operations are applied
When the AI returns operations, `applyOperations()` applies them to the React Flow state:
* `update_node` — merges new parameter values and reapplies template metadata
* `add_node` — creates a new node with defaults and marks the canvas for auto-arrange
* `remove_node` — deletes the node and cascades to remove all connected edges
* `add_edge` — creates a new animated edge between two nodes
* `remove_edge` — removes matching edges
All changes are added to the version history as a named snapshot.
## Iterating
If the result isn't what you expected:
1. Look at the canvas to understand what changed
2. Open the AI panel again
3. Describe what's wrong specifically: "The billing branch is missing a Burst node before the End"
The AI will apply corrective operations on top of the current state.
# Generate a Flow with AI
Source: https://docs.voiceblox.ai/ai-generation/generate-flow
Describe your voice agent in plain language and let AI build the flow for you.
# Generate a Flow with AI
The AI generator uses Claude (claude-sonnet-4-6) with an `edit_flow` tool to build or modify Voiceblox flows from natural language descriptions.
## How to use it
1. Click the **AI** button in the top toolbar
2. Describe the agent you want to build in plain language
3. The AI generates a set of operations and applies them to the canvas
## How it works
The system prompt is dynamically built from `nodeTemplates.ts` and `connectionRules.ts`, so the AI always has an up-to-date understanding of the available nodes and valid connections.
When you submit a message, the AI either:
* Calls `ask_user` to surface a clarifying question (response: `{ done: false, message }`)
* Calls `edit_flow` to produce a list of operations (response: `{ done: true, operations[], versionName }`)
The operations are validated against the graph's topology before being applied. If validation fails, the AI retries up to 3 times with the error feedback.
## Operation types
| Operation | What it does |
| ------------- | -------------------------------------- |
| `add_node` | Adds a new node with all parameters |
| `update_node` | Updates parameters on an existing node |
| `remove_node` | Deletes a node and all its edges |
| `add_edge` | Connects two nodes |
| `remove_edge` | Removes a connection |
## Example prompts
```
Build a customer support agent for a SaaS product with:
- A greeting
- A triage question (billing vs technical support)
- Two branches routing to different specialists
```
```
Add a web search tool to the existing flow so the agent can
look up real-time product pricing.
```
```
Change the opening message to be more friendly and casual.
```
## Requirements
* The builder LLM key for your `BUILDER_LLM_PROVIDER` (`BUILDER_LLM_ANTHROPIC_API_KEY` or `BUILDER_LLM_GEMINI_API_KEY`) must be set in `.env.local`
## Tips
* Be specific about the conversation structure (number of steps, branch conditions)
* You can ask the AI to modify only part of an existing flow
* If the result isn't right, describe what's wrong and ask it to fix it
See [Prompting Tips](/ai-generation/prompting-tips) for more examples.
# Prompting Tips
Source: https://docs.voiceblox.ai/ai-generation/prompting-tips
Best practices and example prompts for getting great results from the AI flow generator.
# Prompting Tips
## Be specific about conversation structure
The AI works best when you describe the flow structure explicitly.
**Too vague:**
> Make a customer support agent
**Better:**
> Build a customer support agent with: a greeting step, a single triage question (billing or technical), and two branches — billing goes to a Burst node for 3 exchanges then End, technical goes to Open Talk then End.
## Describe branches explicitly
When you want conditional logic, describe the condition and both outcomes.
```
Add an If/Else node after the first Burst step.
Condition: "Did the user say they want to upgrade?"
- If true: go to a new Burst node with command "Great! Let me walk you through our plans."
- If false: go to End with command "No problem, let me know if you need anything else."
```
## Reference existing nodes
When editing, you can refer to nodes by their role or command content.
```
Change the greeting in the Start node to: "Hi! Welcome to Acme Support. How can I help you today?"
```
```
Add a Webhook node after the End node that posts to https://example.com/webhook
```
## Use cases and example prompts
### Customer support triage
```
Build a voice agent for Acme SaaS support:
1. Greeting step (literal): "Thank you for calling Acme Support."
2. Burst (1 round): ask the customer for their account email
3. Categorize into: Billing, Technical, Cancel — each routing to a separate Burst
4. Each branch ends with an End node
Use OpenAI GPT-4 for LLM, ElevenLabs for TTS, Deepgram for STT.
```
### Sales qualification
```
Build a sales qualification agent:
1. Start: introduce the agent and ask what the prospect is looking for
2. Open Talk: let them describe their needs freely
3. If/Else: "Is the prospect a good fit for our enterprise plan?"
- Yes: Burst with 2 rounds to schedule a demo
- No: End with a polite message
```
### Appointment reminder
```
Build a short outbound reminder agent:
1. Start (literal): "Hi [name], this is a reminder about your appointment tomorrow at 2pm."
2. Burst (1 round): ask if they can make it
3. If/Else: "Did they confirm the appointment?"
- Yes: End with "Great, see you then!"
- No: Burst to reschedule, then End
```
## Common mistakes
* **Putting If/Else directly after Start** — not allowed. You need at least one Burst, Open Talk, or Timer between Start and a branching node.
* **Forgetting to specify a separate LLM for branching nodes** — If/Else and Categorize need their own LLM connection.
* **Not specifying `isLiteral`** — if you want the agent to speak exact words, say "speak this verbatim" or "set isLiteral to true".
# Managing Agents
Source: https://docs.voiceblox.ai/building-flows/agents
Save, load, rename, and delete agents using the Agent History sidebar.
# Managing Agents
Voiceblox stores each agent you build — including all its version snapshots, AI Builder conversations, and test sessions — in a local PostgreSQL database. You can manage multiple agents and switch between them without losing any work.
## Agent History sidebar
Click the **Agents** icon in the left toolbar to open the Agent History sidebar. It shows all saved agents, sorted by last modified date. Click any agent to load it onto the canvas.
## Auto-save
Your current agent is saved automatically:
* **Debounced save** — a short delay after each change triggers a background save
* **Manual save** — press `Cmd+S` (macOS) or `Ctrl+S` (Windows / Linux) at any time
* **Before unload** — a save is attempted when you close or navigate away from the page
The toolbar shows a save indicator while a save is in progress.
## Creating a new agent
Click **New Agent** in the toolbar or in the Agent History sidebar. This:
1. Saves your current agent (if any changes are pending)
2. Clears the canvas
3. Creates a fresh agent ready for you to build
## Renaming an agent
In the Agent History sidebar, hover over an agent name and click the **edit** (pencil) icon. Type the new name and press Enter to save.
## Deleting an agent
In the Agent History sidebar, hover over an agent and click the **delete** (trash) icon. Deleted agents are soft-archived — they are hidden from the list but not permanently removed from the database.
## Switching between agents
Click any agent in the sidebar to load it. The current agent is auto-saved before switching. The canvas, version history, and AI Builder conversation are all restored to the state of the selected agent.
# Canvas Basics
Source: https://docs.voiceblox.ai/building-flows/canvas-basics
Navigate the drag-and-drop canvas, place nodes, and use keyboard shortcuts.
# Canvas Basics
The Voiceblox canvas is built on [React Flow](https://reactflow.dev).
## Layout
* **Left sidebar** — Node palette organized by category. Drag any node onto the canvas.
* **Canvas** — The main working area. Pan and zoom freely.
* **Top toolbar** — Undo, redo, clear, AI generator, export, and test buttons.
* **Properties Panel** — Appears when you select a node. Configure its parameters on the right.
## Navigation
| Action | How |
| ------------ | ----------------------------------------------- |
| Pan | Click and drag on empty canvas area |
| Zoom | Scroll wheel / pinch on trackpad |
| Select node | Click it |
| Multi-select | Hold `Shift` and click, or drag a selection box |
| Deselect | Click on empty canvas |
## Placing nodes
Drag a node type from the left sidebar onto the canvas and release to place it.
## Connecting nodes
1. Hover over a node to reveal its **handles** (colored dots on the edges)
2. Click and drag from an output handle
3. Release on a compatible input handle
Voiceblox enforces [connection rules](/building-flows/connecting-nodes): only compatible handle types can connect.
## Keyboard shortcuts
| Shortcut | Action |
| ---------------------- | ------------------------------- |
| `Cmd/Ctrl + C` | Copy selected node(s) |
| `Cmd/Ctrl + V` | Paste node(s) |
| `Backspace` / `Delete` | Delete selected node(s) or edge |
| `Cmd/Ctrl + Z` | Undo |
| `Cmd/Ctrl + Shift + Z` | Redo |
| `Arrow keys` | Nudge selected node(s) |
## Moving and arranging nodes
Click and drag any node to reposition it. After AI generation, click **Auto-arrange** in the toolbar to tidy up the layout.
# Component Nodes
Source: https://docs.voiceblox.ai/building-flows/component-nodes
LLM, TTS, STT, Avatar, and Persona nodes — providers, parameters, and configuration.
# Component Nodes
Component nodes define the AI capabilities of your agent. Each connects to the Framework node via a dedicated typed handle.
***
## Persona
Defines the agent's identity. Connected to `persona_in` on the Framework node.
| Parameter | Type | Description |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `agentName` | string | Display name of the agent |
| `persona` | text | System prompt (supports markdown) |
| `language` | enum | Primary language: `en`, `es`, `fr`, `de`, `pt`, `ja`, `zh`, `ko`, `it`, `nl`, `hi`, `ar`, `pl`, `tr` |
***
## LLM
The language model that generates the agent's responses. Connected to `llm_in` on the Framework node.
| Parameter | Type | Description |
| ------------- | ------------ | ----------------------------------- |
| `model` | enum | Model identifier |
| `temperature` | slider (0–2) | Response creativity. Default: `0.7` |
| `max_tokens` | number | Max output tokens (advanced) |
### Providers
| Provider | Default model |
| -------------- | ----------------------------------------- |
| OpenAI | `gpt-4.1-mini` |
| Anthropic | `claude-sonnet-4-20250514` |
| Gemini | `gemini-2.5-pro` |
| Groq | `llama-3.3-70b-versatile` |
| Together AI | `meta-llama/Llama-3.3-70B-Instruct-Turbo` |
| DeepSeek | `deepseek-v3` |
| Moonshot | `moonshotai/kimi-k2-instruct` |
| Mistral AI | `ministral-8b-2410` |
| Cerebras | `llama3.1-8b` |
| Fireworks AI | `llama-v3p3-70b-instruct` |
| Perplexity | `llama-3.1-sonar-small-128k-chat` |
| xAI | `grok-4-1-fast` |
| OpenRouter | 500+ models |
| Amazon Bedrock | `amazon.nova-2-lite-v1:0` |
| OVHCloud | `gpt-oss-120b` |
| Ollama | Custom (local) |
| Azure OpenAI | Custom deployment |
IfElse and Categorize nodes also require their own LLM connection for condition evaluation. You can reuse the same LLM node or connect a separate one.
***
## TTS
Text-to-speech engine for voice output. Connected to `tts_in` on the Framework node.
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------- |
| `model` | enum | TTS model |
| `voiceId` | string | Voice identifier from the provider |
### Provider-specific parameters
| Provider | Extra parameters |
| ---------- | ------------------------------------------- |
| ElevenLabs | `stability` (0–1), `similarity_boost` (0–1) |
| Cartesia | `emotion` |
| OpenAI | `instructions` (style/tone prompt) |
### Providers
| Provider | Default model |
| ----------- | --------------------- |
| ElevenLabs | `eleven_flash_v2_5` |
| Cartesia | `sonic-3` |
| Deepgram | `aura-2` |
| OpenAI | `gpt-4o-mini-tts` |
| Rime | `arcana` |
| Inworld | `inworld-tts-1.5-max` |
| Neuphonic | — |
| Resemble AI | — |
| Groq | — |
***
## STT
Speech-to-text engine for voice input. Connected to `stt_in` on the Framework node.
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `model` | enum | STT model |
### Provider-specific parameters
| Provider | Extra parameters |
| ---------- | ------------------------------------------------------------------------- |
| Deepgram | `keyterms` (comma-separated domain terms), `enable_diarization` (boolean) |
| AssemblyAI | `keyterms_prompt`, `language_detection` (boolean) |
### Providers
| Provider | Default model |
| ---------- | ------------------------ |
| Deepgram | `nova-3` |
| ElevenLabs | `scribe_v2_realtime` |
| Cartesia | `ink-whisper` |
| AssemblyAI | `u3-rt-pro` |
| OpenAI | `gpt-4o-transcribe` |
| Groq | `whisper-large-v3-turbo` |
| OVHCloud | `whisper-large-v3-turbo` |
***
## Avatar
Renders a visual avatar during the call. Connected to `avatar_in` on the Framework node (optional).
| Parameter | Type | Description |
| ---------- | ------ | ----------------------------------- |
| `avatarId` | string | Avatar identifier from the provider |
**Providers:** Anam, Avatario, Beyond Presence, bitHuman, Hedra, LemonSlice, LiveAvatar, Simli, Tavus, TruGen.
Avatar nodes are optional and only supported on the LiveKit framework.
# Connecting Nodes
Source: https://docs.voiceblox.ai/building-flows/connecting-nodes
Handle types, connection validation rules, and auto-routing behavior.
# Connecting Nodes
Voiceblox enforces typed connections — not every node can connect to every other node. The rules are defined in `connectionRules.ts` and validated both in the UI and at runtime.
## Handle types
| Type | Color | Used for |
| ----------- | ------ | ---------------------------------- |
| `control` | Purple | Conversation step chain |
| `framework` | Blue | Start → Framework link |
| `context` | Green | Tools/context injection (MCP, Exa) |
| `llm` | Gray | LLM component wiring |
| `tts` | Gray | TTS component wiring |
| `stt` | Gray | STT component wiring |
| `persona` | Gray | Persona component wiring |
| `avatar` | Gray | Avatar component wiring |
## Connection rules
### Component → Framework
| Source node | Connects to | Handle |
| ----------- | ----------- | ------------ |
| Persona | Framework | `persona_in` |
| LLM | Framework | `llm_in` |
| TTS | Framework | `tts_in` |
| STT | Framework | `stt_in` |
| Avatar | Framework | `avatar_in` |
### Conversation chain
| Source node | Target handle | Notes |
| ----------- | ---------------------------------------- | ------------------------------------------- |
| Framework | Start `framework_in` | Starts the step chain |
| Start | Any step `in` | One outgoing connection |
| Burst | Any step `in` or Framework `transfer_in` | One outgoing connection |
| Open Talk | Any step `in` or Framework `transfer_in` | One outgoing connection |
| Timer | Any step `in` or Framework `transfer_in` | One outgoing connection |
| If/Else | Two targets: `true` and `false` handles | Cannot target Start, If/Else, or Categorize |
| Categorize | One target per category | Cannot target Start, If/Else, or Categorize |
| End | Webhook `in` | Optional, fires webhook before disconnect |
| Transfer | Framework `transfer_in` | One outgoing connection |
### Integration → Framework
| Source node | Connects to | Handle |
| ----------- | ----------- | ---------------------- |
| MCP | Framework | `tools_in` (unlimited) |
| Exa | Framework | `tools_in` (unlimited) |
## Auto-routing
When you drag an edge from an output handle and release it on a target node (not a specific handle), Voiceblox automatically routes the connection to the correct handle using `findTargetRule()`. This works for all component nodes wiring into the Framework node.
## Validation
Invalid connections are rejected visually during drag. If a connection would violate the rules (wrong handle type, wrong source category, max connections exceeded), the edge snaps back and the connection is not created.
IfElse and Categorize nodes cannot immediately follow a Start node. You need at least one Burst, Open Talk, or Timer step between Start and a branching node.
# Conversation Nodes
Source: https://docs.voiceblox.ai/building-flows/conversation-nodes
Step nodes that define the conversation flow: Start, Timer, Burst, IfElse, End, and more.
# Conversation Nodes
Conversation nodes form the **step chain** — the ordered sequence of actions your agent takes during a call. They connect left-to-right via `control` handles.
## Start
The entry point of every conversation. The Agent node connects to Start, and Start connects to the first step.
}>
| Parameter | Type | Description |
| ----------- | ------- | -------------------------------------------------------------------------- |
| `command` | text | The agent's opening message |
| `isLiteral` | boolean | If true, speaks the command verbatim instead of using it as an instruction |
**Connections:** Agent `output` → Start → next step `in`
***
## Burst
A fixed number of back-and-forth exchanges on a topic. Use it for structured Q\&A, data collection, or focused discussions.
}>
| Parameter | Type | Description |
| --------- | -------------- | -------------------------------------------- |
| `rounds` | stepper (1–10) | Number of user/agent exchanges. Default: `1` |
| `command` | text | Topic instruction for the LLM |
***
## Open Talk
Unlimited free-form conversation on a topic. Use it when you don't know how many turns the user needs.
}>
| Parameter | Type | Description |
| --------- | ---- | ----------------------------- |
| `command` | text | Topic instruction for the LLM |
Open Talk continues until the StepWatcher decides to advance — typically after the user signals they are done. Connect an If/Else or Categorize node after Open Talk to decide where to go next.
***
## Timer
Conversation on a topic for a fixed duration. Advances automatically when the timer expires.
}>
| Parameter | Type | Description |
| ---------- | ------------------ | ---------------------------------- |
| `duration` | stepper (30–1800s) | Duration in seconds. Default: `30` |
| `command` | text | Topic instruction for the LLM |
***
## If/Else
Binary branch based on an LLM-evaluated condition. Requires its own LLM node connected to `llm_in`.
}>
| Parameter | Type | Description |
| --------------- | ---- | -------------------------------------------------------------------- |
| `conditionText` | text | Condition to evaluate (e.g., "Is the user interested in upgrading?") |
**Outputs:** `true` handle and `false` handle — connect each to a different next step.
**Allowed sources:** Timer, Burst, Open Talk only (not Start).
***
## Categorize
Multi-way branch by semantic classification. Requires its own LLM node connected to `llm_in`. Dynamically generates one output handle per category.
| Parameter | Type | Description |
| ------------ | ---------------- | ----------------------------------------------------------------------------------------- |
| `command` | text | Classification instruction |
| `categories` | categories array | Category names (e.g., `["Sales", "Support", "Billing"]`). Default: `["Sales", "Support"]` |
**Outputs:** One `control` handle per category — connect each to a different next step.
***
## End
Terminates the conversation. The agent speaks its closing message and disconnects.
}>
| Parameter | Type | Description |
| ----------- | ------- | ------------------------------------ |
| `command` | text | Closing message |
| `isLiteral` | boolean | If true, speaks the command verbatim |
**Note:** End nodes can also connect to Webhook nodes to fire an HTTP POST before disconnecting.
***
## Transfer
Hands off to another agent or phone number. Connects to `transfer_in` on the Agent node.
| Parameter | Type | Description |
| ----------- | ------- | ------------------------------------ |
| `command` | text | Spoken message before the transfer |
| `isLiteral` | boolean | If true, speaks the command verbatim |
***
## Typical flow patterns
**Simple linear:**
```
Start → Burst → End
```
**With branching:**
```
Start → Open Talk → If/Else → [true] Burst → End
→ [false] End
```
**With triage:**
```
Start → Burst → Categorize → [Sales] Burst → End
→ [Support] Open Talk → End
→ [Billing] Transfer
```
# Framework Node
Source: https://docs.voiceblox.ai/building-flows/framework-node
The central orchestrator that connects all components and drives the conversation.
# Framework Node
The Framework node is the heart of every Voiceblox flow. It receives all component connections, acts as the entry point for the conversation step chain, and determines the runtime.
Every flow must have **exactly one** Framework node.
## Providers
| Provider | Status |
| --------- | -------------- |
| `livekit` | ✅ Stable |
| `pipecat` | 🔜 Coming soon |
## Parameters
| Parameter | Type | Default | Description |
| ------------------- | ---- | --------- | -------------------------------------------------------------------------------------------------- |
| `provider` | enum | `livekit` | Runtime framework (`livekit`) |
| `interruption_mode` | enum | `off` | Interruption: `off` (disabled) or `on` (adaptive ML-based detection for cascade, VAD for realtime) |
## Input handles
| Handle | Type | Max connections | Description |
| ------------- | --------- | --------------- | -------------------------------------- |
| `persona_in` | persona | 1 | Agent identity and system prompt |
| `llm_in` | llm | 1 | Language model |
| `tts_in` | tts | 1 | Text-to-speech engine |
| `stt_in` | stt | 1 | Speech-to-text engine |
| `avatar_in` | avatar | 1 | Visual avatar (optional) |
| `transfer_in` | framework | unlimited | Incoming transfers from Transfer nodes |
| `tools_in` | context | unlimited | MCP servers and Exa search tools |
## Output handle
| Handle | Type | Description |
| -------- | ------- | -------------------------- |
| `output` | control | Connects to the Start node |
## Interruption behavior
The `interruption_mode` parameter controls how the agent handles user speech while it is speaking:
* **Off** — The agent cannot be interrupted. Useful for scripted announcements or compliance-sensitive flows.
* **On** — The agent can be interrupted by the user. For cascade agents, this uses adaptive ML-based interruption handling that distinguishes true interruptions from conversational backchanneling (e.g. "uh-huh", "okay"). For realtime agents, this uses VAD-based interruption detection.
A flow without a Persona, LLM, TTS, and STT connected to the Framework node will fail to run.
# Node Overview
Source: https://docs.voiceblox.ai/building-flows/node-overview
The five categories of nodes: Agent, Component, Conversation, Tools, and Post-Processing.
# Node Overview
Every element on the Voiceblox canvas is a **node**. Nodes are grouped into five categories.
## Agent
The **Agent** node is the central orchestrator. There is exactly one per flow.
| Node | Description |
| ------- | ------------------------------------------------------------------------------------------------------------ |
| `Agent` | Configures the agent's name, persona (system prompt), and language; connects to all component and tool nodes |
## Component
Component nodes define the AI capabilities of your agent.
| Node | Handle | Description |
| -------- | ----------- | --------------------------------------- |
| `LLM` | `llm_in` | Language model for generating responses |
| `TTS` | `tts_in` | Text-to-speech for voice output |
| `STT` | `stt_in` | Speech-to-text for voice input |
| `Avatar` | `avatar_in` | Visual avatar rendering (optional) |
## Conversation
Conversation nodes form the **step chain** — the sequence of actions during a call.
| Node | Description |
| ------------ | -------------------------------------------------- |
| `Start` | Entry point. Agent speaks its opening line. |
| `Burst` | A fixed number of back-and-forth exchanges. |
| `Open Talk` | Unlimited free-form conversation on a topic. |
| `Timer` | Conversation capped at a time duration. |
| `If/Else` | Binary branch based on an LLM-evaluated condition. |
| `Categorize` | Multi-way branch by semantic classification. |
| `Transfer` | Hand off to another agent or phone number. |
| `End` | Terminates the conversation. |
## Tools
Tool nodes connect to the Agent's `tools_in` handle and give the LLM access to external capabilities during a conversation.
| Node | Description |
| -------------- | ---------------------------------------------------- |
| `MCP` | Exposes tools from an MCP server to the LLM |
| `Exa` | Gives the LLM real-time web search via Exa.ai |
| `SIP Transfer` | Lets the LLM transfer a call to a human phone number |
## Post-Processing
Post-processing nodes run after the conversation ends. Chain them after an **End** node.
| Node | Description |
| ------------------- | ----------------------------------------------------------------- |
| `Structured Output` | Extracts structured data from the conversation using an LLM |
| `Webhook` | Fires an HTTP POST with conversation data to an external endpoint |
## Connection diagram
```
[LLM] ──llm──▶ [Agent] ◀──tools── [MCP / Exa / SIP Transfer]
[TTS] ──tts──▶ │
[STT] ──stt──▶ ▼
[Start] ──▶ [Burst] ──▶ [End]
│
[Structured Output] ──▶ [Webhook]
```
# Properties Panel
Source: https://docs.voiceblox.ai/building-flows/properties-panel
Configure node parameters using the properties panel.
# Properties Panel
The Properties Panel lets you configure any node's parameters. Select a node on the canvas to open it on the right side, or right-click a node and choose **Edit**.
## Parameter types
| Type | Input | Description |
| --------------- | ------------ | ----------------------------------------------------------- |
| `string` | Text input | Single-line text. Supports placeholders. |
| `text` | Textarea | Multi-line text. Used for system prompts and commands. |
| `enum` | Dropdown | Pick from a predefined list of options. |
| `number` | Number input | Numeric value with optional min/max/step constraints. |
| `slider` | Range slider | Numeric value with visual range. Shows min/max labels. |
| `boolean` | Toggle | On/off switch. |
| `stepper` | +/− stepper | Integer value with unit display (e.g., `30s`). |
| `categories` | Tag input | Array of string labels. Used for Categorize node outputs. |
| `tool_selector` | Checklist | Select which tools from an MCP server to expose to the LLM. |
## Advanced parameters
Some parameters are collapsed under an **Advanced** section by default (e.g., `max_tokens` on LLM nodes). Click to expand.
## Saving changes
Parameter changes are applied immediately and reflected on the canvas. No save button needed — changes are part of the flow's current state and included in the next undo snapshot.
# Version History
Source: https://docs.voiceblox.ai/building-flows/version-history
Undo, redo, and restore previous versions of your flow using snapshots.
# Version History
Voiceblox keeps up to **50 snapshots** per agent. Each significant change (node addition, deletion, parameter edit, edge change) creates a new snapshot.
## Undo / Redo
| Action | Shortcut |
| ------ | ---------------------- |
| Undo | `Cmd/Ctrl + Z` |
| Redo | `Cmd/Ctrl + Shift + Z` |
Undo and redo are also available in the top toolbar.
## Version snapshots
When the AI generator applies operations to your flow, it creates a named snapshot with the description of the change (e.g., "Added billing branch"). You can view and restore named snapshots from the **Version History** panel in the toolbar.
## Persistence
Version snapshots are saved to the PostgreSQL database automatically — they persist across page reloads and browser restarts. There is no need to export your flow to preserve version history.
* Up to **50 snapshots** stored per agent
* **Content-hash deduplication** — identical consecutive states do not create duplicate entries
* Snapshots are tied to the current agent; switching agents loads that agent's own version history
## Exporting
To share or back up a flow externally, you can still export it as JSON at any time:
1. Click **Export** in the toolbar
2. Download the JSON file
3. Re-import it later via **Import** to restore the flow
See [Export as JSON](/deployment/export-json) for the full format.
# Agent Runtime
Source: https://docs.voiceblox.ai/deployment/agent-runtimes
How the Voiceblox Python agent worker runs alongside the Next.js app.
# Agent Runtime
The Voiceblox agent runs as a standalone **Python worker process** using the [LiveKit Agents Python SDK](https://github.com/livekit/agents). When you click **Test** in the builder or call `/api/agent-session`, the app dispatches a job to the worker.
## How it works
1. The app creates a LiveKit room with the `AgentConfig` JSON in the room metadata
2. It calls `AgentDispatchClient.createDispatch()` to dispatch the job to the registered Python worker
3. The browser receives a JWT and joins the room
4. The worker picks up the job, reads the config from metadata, builds the LLM/TTS/STT instances, and starts the session
## Running the worker
Start the Next.js app and the Python worker in separate terminals:
```bash theme={null}
# Terminal 1 — Next.js app
pnpm dev
# Terminal 2 — Python agent server (spawns workers on demand)
pnpm agent:server
```
See [Python Worker](/deployment/python-worker) for full setup instructions and supported providers.
## Deploying with Docker
See [Docker Compose](/deployment/docker) for running the worker alongside the web app in a container.
# Docker Compose
Source: https://docs.voiceblox.ai/deployment/docker
Deploy the full Voiceblox stack (app + agent) using Docker Compose.
# Docker Compose
Voiceblox ships with a `docker-compose.yml` that starts both the web app and the agent worker.
## Prerequisites
Make sure Docker is installed and running:
```bash theme={null}
# Check if Docker is installed
docker --version
# Check if Docker is running
docker info
```
If `docker --version` returns `command not found`, install Docker from [docker.com/get-started](https://www.docker.com/get-started/). If `docker info` shows `Cannot connect to the Docker daemon`, open **Docker Desktop** (macOS/Windows) or run `sudo systemctl start docker` (Linux).
## Quick start
```bash theme={null}
# Build and start both services
docker compose up --build
# Stop both services
docker compose down
```
## Services
### `app` — Next.js web application
* Port: `3000`
* Loads `.env.local` from the host
* Runs: `pnpm start`
### `agent` — Python agent server
* No published ports (connects outbound to LiveKit)
* Loads `.env.agent` from the host
* Runs: `pnpm agent:server`
## Environment variables
API keys are configured inside the app (Settings dialog). The agent worker reads keys at startup, so after adding keys for a new provider restart the agent service:
```bash theme={null}
docker compose restart agent
```
## Logs
```bash theme={null}
# View logs for both services
docker compose logs -f
# View logs for just the agent
docker compose logs -f agent
```
# Environment Variables
Source: https://docs.voiceblox.ai/deployment/environment-variables
Complete reference for all required and optional environment variables.
# Environment Variables
All environment variables go in `.env.local` at the project root. Restart the dev server after changes.
## Framework
| Variable | Required | Description |
| -------------------- | -------- | ------------------------------------------ |
| `LIVEKIT_URL` | ✅ | LiveKit server WebSocket URL (`wss://...`) |
| `LIVEKIT_API_KEY` | ✅ | LiveKit API key |
| `LIVEKIT_API_SECRET` | ✅ | LiveKit API secret |
## Core
| Variable | Required | Description |
| ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------- |
| `BUILDER_LLM_PROVIDER` | ❌ | LLM provider for the AI flow generator: `anthropic` (default) or `gemini` |
| `BUILDER_LLM_ANTHROPIC_API_KEY` | ✅ when `BUILDER_LLM_PROVIDER=anthropic` | AI flow generator (Anthropic) |
| `BUILDER_LLM_GEMINI_API_KEY` | ✅ when `BUILDER_LLM_PROVIDER=gemini` | AI flow generator (Gemini) |
| `BUILDER_STT_PROVIDER` | ❌ | STT provider for voice dictation: `deepgram` (default) or `gemini` |
| `BUILDER_STT_DEEPGRAM_API_KEY` | ✅ when `BUILDER_STT_PROVIDER=deepgram` | Voice dictation in builder (Deepgram) |
| `BUILDER_STT_GEMINI_API_KEY` | ✅ when `BUILDER_STT_PROVIDER=gemini` | Voice dictation in builder (Gemini) |
## LLM
| Variable | Provider |
| -------------------- | -------------- |
| `OPENAI_API_KEY` | OpenAI |
| `GEMINI_API_KEY` | Google Gemini |
| `GROQ_API_KEY` | Groq |
| `TOGETHER_API_KEY` | Together AI |
| `MOONSHOT_API_KEY` | Moonshot AI |
| `DEEPSEEK_API_KEY` | DeepSeek |
| `MISTRALAI_API_KEY` | Mistral AI |
| `CEREBRAS_API_KEY` | Cerebras |
| `FIREWORKS_API_KEY` | Fireworks AI |
| `PERPLEXITY_API_KEY` | Perplexity |
| `XAI_API_KEY` | xAI |
| `OPENROUTER_API_KEY` | OpenRouter |
| `OVHCLOUD_API_KEY` | OVHCloud |
| `BEDROCK_API_KEY` | Amazon Bedrock |
| `LETTA_API_KEY` | Letta |
| `OLLAMA_API_KEY` | Ollama (local) |
| `TELNYX_API_KEY` | Telnyx |
## TTS
| Variable | Provider |
| -------------------- | ----------- |
| `ELEVENLABS_API_KEY` | ElevenLabs |
| `CARTESIA_API_KEY` | Cartesia |
| `NEUPHONIC_API_KEY` | Neuphonic |
| `RESEMBLE_API_KEY` | Resemble AI |
| `RIME_API_KEY` | Rime |
| `INWORLD_API_KEY` | Inworld |
## STT
| Variable | Provider |
| ---------------------- | ------------ |
| `ASSEMBLYAI_API_KEY` | AssemblyAI |
| `FAL_API_KEY` | fal.ai |
| `GLADIA_API_KEY` | Gladia |
| `SONIOX_API_KEY` | Soniox |
| `SPEECHMATICS_API_KEY` | Speechmatics |
## Integrations
| Variable | Description |
| ------------- | ----------------- |
| `EXA_API_KEY` | Exa.ai web search |
## Sharing
| Variable | Required | Description |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LIVEKIT_SANDBOX_ID` | ❌ | LiveKit Sandbox Token Server ID — needed for public share links. Enable at [LiveKit Cloud Settings](https://cloud.livekit.io/projects/p_/settings/project). |
## Database
| Variable | Required | Description |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | ✅ | PostgreSQL connection string (e.g. `postgresql://voiceblox:voiceblox@localhost:5432/voiceblox`) |
| `ENCRYPTION_KEY` | ✅ | 64-char hex key for AES-256-GCM encryption of stored provider credentials. Generate with: `openssl rand -hex 32` |
## Notes
* `OPENAI_API_KEY` is shared across LLM, TTS (gpt-4o-mini-tts), and STT (Whisper)
* `BUILDER_STT_DEEPGRAM_API_KEY` is for voice dictation in the builder only; use `DEEPGRAM_API_KEY` for Deepgram STT/TTS nodes in your flow
* `GROQ_API_KEY` is shared across LLM and TTS
* `BUILDER_LLM_ANTHROPIC_API_KEY` is for the AI flow generator only; use `ANTHROPIC_API_KEY` for Anthropic LLM nodes in your flow
* `BUILDER_LLM_GEMINI_API_KEY` and `BUILDER_STT_GEMINI_API_KEY` can hold the same Google API key value if you use a single Google project
# Export as JSON
Source: https://docs.voiceblox.ai/deployment/export-json
Export your flow as an AgentConfig JSON file ready for deployment.
# Export as JSON
Every Voiceblox flow can be exported as a JSON file containing the full `AgentConfig` — a framework-agnostic representation of your agent.
## How to export
1. Click **Export** in the top toolbar
2. Download the `.json` file
## File format
```json theme={null}
{
"version": "1.0",
"name": "My Agent",
"exportedAt": "2025-01-01T12:00:00.000Z",
"nodes": [
{
"id": "node_1",
"nodeType": "framework",
"provider": "livekit",
"position": { "x": 100, "y": 200 }
},
{
"id": "node_2",
"nodeType": "llm",
"provider": "openai",
"model": "gpt-4.1-mini",
"temperature": 0.7,
"position": { "x": 300, "y": 100 }
}
],
"edges": [
{
"source": "node_2",
"sourceHandle": "output",
"target": "node_1",
"targetHandle": "llm_in"
}
]
}
```
## Importing a flow
1. Click **Import** in the top toolbar
2. Select your `.json` file
3. The flow is loaded onto the canvas
## Using the exported config
The exported JSON contains the full node/edge graph. To use it with the LiveKit agent worker:
1. Export the flow
2. Set the JSON as the room metadata when creating a LiveKit room
3. The agent worker reads the metadata, converts it to `AgentConfig` via `graphToConfig()`, and starts the session
See [Python Worker](/deployment/python-worker) for the full deployment flow.
# Deploy to LiveKit Cloud
Source: https://docs.voiceblox.ai/deployment/livekit-cloud
One-click deployment of your Voiceblox agent to LiveKit Cloud.
# Deploy to LiveKit Cloud
Voiceblox includes a built-in deploy flow that packages your agent and publishes it to LiveKit Cloud in a single click. Once deployed, the agent runs persistently in the cloud — no local process required.
## Prerequisites
Before deploying, you need three things in place:
### 1. Install the lk CLI
```bash macOS theme={null}
brew install livekit-cli
```
```bash Linux theme={null}
curl -sSL https://get.livekit.io/cli | bash
```
```bash Windows theme={null}
winget install LiveKit.LiveKitCLI
```
### 2. Authenticate with LiveKit Cloud
```bash theme={null}
lk cloud auth
```
This opens a browser window to sign in. After authenticating, the CLI stores credentials locally.
### 3. Set LIVEKIT\_URL
Add your project URL to `.env.local`:
```env theme={null}
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxxxx
LIVEKIT_API_SECRET=your-secret
```
You can find these values in the [LiveKit Cloud dashboard](https://cloud.livekit.io).
***
## Deploying your agent
1. Open the Voiceblox builder and click **Deploy** in the toolbar.
2. The dialog checks your setup automatically. All three requirements must show a green checkmark.
3. Select a **region** (US East, EU Central, or AP South).
4. Click **Deploy to LiveKit Cloud**.
The deploy log streams in real time. When it finishes, you'll see the success screen with a link to the agent in the LiveKit Cloud dashboard.
***
## How it works
When you click Deploy, Voiceblox:
1. Packages the Python agent source files into a temporary directory
2. Serializes your current flow as `VOICEBLOX_CONFIG` (a JSON string)
3. Runs `lk agent create` (first deploy) or `lk agent deploy` (subsequent deploys)
4. The `lk` CLI uploads the agent to LiveKit Cloud and sets the secrets
The deployed agent registers with `agent_name="voiceblox"`. LiveKit Cloud dispatches jobs to it when new rooms are created.
### API keys as secrets
Any provider API keys you've entered in the builder (OpenAI, ElevenLabs, Deepgram, etc.) are uploaded as LiveKit Cloud secrets during deployment. The running agent reads them from environment variables — they are never stored in plaintext in the agent code.
### Agent config
Your flow configuration is stored as the `VOICEBLOX_CONFIG` secret. The agent reads it on startup and builds the LLM, TTS, and STT pipeline from it.
***
## Testing the deployed agent
After deploying, you can test the live cloud agent directly from the builder:
1. Open the **Test Panel** (microphone icon in the toolbar).
2. Switch to the **Production** tab.
3. Click **Start**.
This creates a real LiveKit room and dispatches it to your deployed agent. You're talking to the actual cloud-hosted agent, not a local process.
***
## Redeploying after changes
After modifying your flow, click **Deploy** again. Voiceblox automatically detects that the agent already exists and runs `lk agent deploy` to update it in place. If the agent was deleted from LiveKit Cloud, the deploy falls back to `lk agent create` automatically.
***
## Sharing your deployed agent
Once deployed, you can generate shareable links so anyone can talk to your agent — no setup required on their end. See [Sharing Agents](/deployment/sharing-agents) for details.
***
## Troubleshooting
| Issue | Fix |
| --------------------------------------- | ----------------------------------------------------------------------------------------------- |
| "lk CLI not installed" | Run the install command for your platform (see above) |
| "Not authenticated" | Run `lk cloud auth` |
| "LIVEKIT\_URL not configured" | Add `LIVEKIT_URL=wss://...` to `.env.local` |
| Deploy fails with "failed to get agent" | The dialog retries automatically with `lk agent create` |
| Production test shows no activity | Ensure the deploy completed successfully and the agent is listed in the LiveKit Cloud dashboard |
***
## Related
* [Python Worker](/deployment/python-worker) — run the agent locally as a standalone worker
* [Docker Compose](/deployment/docker) — self-host the full stack with Docker
* [Environment Variables](/deployment/environment-variables) — full list of supported env vars
# Python Worker
Source: https://docs.voiceblox.ai/deployment/python-worker
Run the Voiceblox agent as a standalone Python worker process using the LiveKit Agents Python SDK.
# Python Worker
The Python worker runs the Voiceblox agent using the [LiveKit Agents Python SDK](https://github.com/livekit/agents) (v1.4+).
## Prerequisites
* Python 3.12+
* [uv](https://docs.astral.sh/uv/) (Python package manager)
## Setup
```bash theme={null}
cd agent
uv sync
```
Download required ML models (run once after setup):
```bash theme={null}
pnpm agent:download-files
```
## Running
### Starting the agent server
```bash theme={null}
pnpm agent:server
```
The agent server spawns workers on demand via `/ensure-worker`. It auto-reloads on file changes in development.
## Connecting to the playground
Start both the app and the agent server:
```bash theme={null}
# Terminal 1 — Next.js app
pnpm dev
# Terminal 2 — Python agent server
pnpm agent:server
```
Ensure `AGENT_SERVER_URL=http://localhost:8080` is set in `.env.local`.
When you click **Test** in the builder, the app creates a LiveKit room with the `AgentConfig` in metadata and dispatches the job to this worker.
## Required environment variables
The worker loads environment variables from the project root `.env.local`.
```env theme={null}
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxxxx
LIVEKIT_API_SECRET=your-secret
```
Plus provider keys for whichever LLM, TTS, and STT your flow uses. Keys not set fall back to the **LiveKit inference gateway**.
## Supported providers
### LLM
OpenAI, Gemini, Groq, Together, Azure, Cerebras, xAI, Fireworks, Perplexity, DeepSeek, Moonshot, Telnyx, Ollama, OVHcloud
### TTS
ElevenLabs, Deepgram, OpenAI, Cartesia, Rime, Neuphonic, Resemble
### STT
Deepgram, OpenAI, Groq, OVHcloud
### Tools
* **MCP servers** — native `MCPServerHTTP` support with bearer/API key auth
* **Exa web search** — configurable search type and result count
## Project structure
```
agent/
├── src/
│ ├── main.py # Worker entry point
│ ├── agent.py # VoicebloxAgent + build helpers
│ ├── models.py # AgentConfig dataclasses
│ └── step_watcher.py # Conversation step state machine
└── pyproject.toml # Dependencies (managed by uv)
```
## Deploying with Docker
See [Docker Compose](/deployment/docker) for running the Python worker alongside the web app in a container.
# Sharing Agents
Source: https://docs.voiceblox.ai/deployment/sharing-agents
Share your deployed voice agent via link, embed, or phone number.
# Sharing Agents
After deploying your agent to LiveKit Cloud, you can share it in three ways: a **Private Link**, a **Public Link**, or a **Phone Number**. All options are in the **Share** tab of the Deploy dialog.
## Opening the Share tab
1. Open the **Deploy** dialog from the toolbar.
2. Switch to the **Share** tab.
3. Choose a sharing option: **Private Link**, **Public Link**, or **Phone**.
***
## Private Link
Best for sharing with a specific person — a colleague, a client, or a tester.
* Generates a **one-time use** link with a configurable expiration (1 hour, 24 hours, or 7 days).
* The link contains a LiveKit JWT token that auto-creates a room and dispatches your deployed agent when opened.
* After the TTL expires, the link stops working.
### Security
The JWT token embedded in the URL is **signed** with your LiveKit API secret but **does not contain** the secret itself. If someone decodes the URL, they can only see the room name, participant identity, permissions, and agent name — no credentials are exposed.
### How it works
```
1. Builder generates JWT with RoomAgentDispatch (agent name embedded in token)
2. Token + LiveKit server URL encoded as base64 in the share URL
3. End-user opens voiceblox.ai/talk/{encoded-config}
4. Browser connects to LiveKit using the JWT
5. LiveKit Cloud auto-creates the room and dispatches the agent
6. Voice conversation starts
```
***
## Public Link
Best for embedding on a website or sharing publicly. Each visitor gets their own independent session.
Public links require the **LiveKit Sandbox Token Server**, which is designed for development and testing. It is not recommended for high-volume production use.
### Setup
1. Open your project's [Settings](https://cloud.livekit.io/projects/p_/settings/project) page in LiveKit Cloud.
2. Find the **Token server** toggle and switch it on.
3. Copy the **sandboxId** displayed below the toggle.
4. Add it to `.env.local`:
```env theme={null}
LIVEKIT_SANDBOX_ID=your-sandbox-id
```
5. Restart the dev server.
### How it works
* Each time someone opens the link, the LiveKit Sandbox Token Server generates a fresh token and creates a new room.
* The deployed agent is automatically dispatched to the new room.
* Multiple people can use the same link simultaneously — each gets a separate conversation.
***
## Embed code
Public links also generate an embed code (iframe) you can paste into any website:
```html theme={null}
```
Embed code is only available for Public Links, since Private Links are single-use.
***
## Phone Number
Assign a real phone number to your agent so anyone can call it from their phone — no browser or link required.
### How it works
Voiceblox uses [LiveKit Phone Numbers](https://docs.livekit.io/agents/telephony/phone-numbers/) to purchase and assign a US number to your deployed agent. When someone calls the number, LiveKit creates a room and dispatches your agent automatically via a SIP dispatch rule.
Avatars are automatically disabled on phone calls to avoid unnecessary API cost.
### Assigning a phone number
1. Open the **Deploy** dialog and go to the **Share** tab → **Phone** section.
2. If you already own a number in LiveKit, it appears in the **Your Numbers** list — click **Assign** to connect it to this agent.
3. To get a new number, optionally enter an **area code** and click **Search**. Available US numbers are listed.
4. Click **Purchase** next to the number you want. Voiceblox purchases it and creates a SIP dispatch rule pointing to your agent.
5. The assigned number is displayed — anyone can now call it and be connected to your agent.
### Releasing a number
Click the **trash icon** next to the assigned number to unassign it and release it from your LiveKit project.
Releasing a number removes the SIP dispatch rule. Anyone who has the number saved will no longer be able to reach the agent via that number.
### Requirements
* The agent must be deployed to LiveKit Cloud first.
* Phone numbers are US-based only at this time.
* The `lk` CLI must be installed and available on the server running Voiceblox (used internally for number search and purchase).
***
## Troubleshooting
| Issue | Fix |
| ------------------------------------------ | --------------------------------------------------------------------------------- |
| "Share" tab says "Deploy your agent first" | Deploy the agent before generating links or assigning a phone number |
| Public Link shows setup warning | Add `LIVEKIT_SANDBOX_ID` to `.env.local` (see [Setup](#setup) above) |
| Private Link expired | Generate a new link with a longer TTL |
| Agent doesn't connect after opening link | Ensure the agent is still deployed in LiveKit Cloud |
| Phone number search returns no results | Try a different area code, or leave it blank to search all available US numbers |
| Caller hears silence or no agent joins | Verify the agent is deployed and the SIP dispatch rule is active in LiveKit Cloud |
***
## Related
* [Deploy to LiveKit Cloud](/deployment/livekit-cloud) — deploy your agent first
* [Environment Variables](/deployment/environment-variables) — full list of env vars
* [Playground](/testing/playground) — test agents locally before deploying
# API Keys
Source: https://docs.voiceblox.ai/getting-started/api-keys
Configure API keys for LLM, TTS, STT, framework, and integration providers.
# API Keys
Voiceblox uses a `.env.local` file to store all provider API keys. Keys are loaded at server startup — restart the dev server after making changes.
## Core keys
These are required for full functionality:
| Key | Provider | Purpose |
| ------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- |
| `LIVEKIT_URL` | [LiveKit Cloud](https://cloud.livekit.io) | WebSocket URL for rooms |
| `LIVEKIT_API_KEY` | LiveKit Cloud | Room management auth |
| `LIVEKIT_API_SECRET` | LiveKit Cloud | Room management auth |
| `BUILDER_STT_DEEPGRAM_API_KEY` | [Deepgram](https://deepgram.com) | Voice input in builder (when `BUILDER_STT_PROVIDER=deepgram`) |
| `BUILDER_STT_GEMINI_API_KEY` | [Google AI Studio](https://aistudio.google.com) | Voice input in builder (when `BUILDER_STT_PROVIDER=gemini`) |
| `BUILDER_LLM_ANTHROPIC_API_KEY` | [Anthropic](https://console.anthropic.com) | AI flow generator (when `BUILDER_LLM_PROVIDER=anthropic`) |
| `BUILDER_LLM_GEMINI_API_KEY` | [Google AI Studio](https://aistudio.google.com) | AI flow generator (when `BUILDER_LLM_PROVIDER=gemini`) |
## LLM providers
| Key | Provider |
| -------------------- | ---------------------------------------------------- |
| `OPENAI_API_KEY` | [OpenAI](https://platform.openai.com) |
| `ANTHROPIC_API_KEY` | [Anthropic](https://console.anthropic.com) |
| `GEMINI_API_KEY` | [Google AI Studio](https://aistudio.google.com) |
| `GROQ_API_KEY` | [Groq](https://console.groq.com) |
| `TOGETHER_API_KEY` | [Together AI](https://api.together.xyz) |
| `MOONSHOT_API_KEY` | [Moonshot AI](https://platform.moonshot.cn) |
| `DEEPSEEK_API_KEY` | [DeepSeek](https://platform.deepseek.com) |
| `MISTRALAI_API_KEY` | [Mistral AI](https://console.mistral.ai) |
| `CEREBRAS_API_KEY` | [Cerebras](https://cloud.cerebras.ai) |
| `FIREWORKS_API_KEY` | [Fireworks AI](https://fireworks.ai) |
| `PERPLEXITY_API_KEY` | [Perplexity](https://www.perplexity.ai/settings/api) |
| `XAI_API_KEY` | [xAI](https://x.ai) |
| `OPENROUTER_API_KEY` | [OpenRouter](https://openrouter.ai) |
| `OVHCLOUD_API_KEY` | [OVHcloud](https://endpoints.ai.cloud.ovh.net) |
| `BEDROCK_API_KEY` | [Amazon Bedrock](https://aws.amazon.com/bedrock) |
| `LETTA_API_KEY` | [Letta](https://letta.ai) |
| `OLLAMA_API_KEY` | [Ollama](https://ollama.ai) (local) |
| `TELNYX_API_KEY` | [Telnyx](https://telnyx.com) |
## TTS providers
| Key | Provider |
| -------------------- | ----------------------------------- |
| `ELEVENLABS_API_KEY` | [ElevenLabs](https://elevenlabs.io) |
| `CARTESIA_API_KEY` | [Cartesia](https://cartesia.ai) |
| `DEEPGRAM_API_KEY` | [Deepgram](https://deepgram.com) |
| `OPENAI_API_KEY` | OpenAI (also used for TTS) |
| `NEUPHONIC_API_KEY` | [Neuphonic](https://neuphonic.com) |
| `RESEMBLE_API_KEY` | [Resemble AI](https://resemble.ai) |
| `RIME_API_KEY` | [Rime](https://rime.ai) |
| `INWORLD_API_KEY` | [Inworld](https://inworld.ai) |
| `GROQ_API_KEY` | Groq (also used for TTS) |
## STT providers
| Key | Provider |
| -------------------- | ---------------------------------------- |
| `DEEPGRAM_API_KEY` | [Deepgram](https://deepgram.com) |
| `OPENAI_API_KEY` | OpenAI Whisper |
| `GROQ_API_KEY` | Groq Whisper |
| `ASSEMBLYAI_API_KEY` | [AssemblyAI](https://www.assemblyai.com) |
| `CARTESIA_API_KEY` | Cartesia (also used for STT) |
| `ELEVENLABS_API_KEY` | ElevenLabs (also used for STT) |
| `OVHCLOUD_API_KEY` | OVHcloud (also used for STT) |
| `FAL_API_KEY` | [fal.ai](https://fal.ai) |
| `GLADIA_API_KEY` | [Gladia](https://gladia.io) |
| `SONIOX_API_KEY` | [Soniox](https://soniox.com) |
## Integration keys
| Key | Provider |
| ------------- | ------------------------------------- |
| `EXA_API_KEY` | [Exa.ai](https://exa.ai) (web search) |
## LiveKit inference gateway
If you don't have a direct API key for a provider, LiveKit's inference gateway can proxy requests for supported models. Set your LiveKit credentials and leave the provider API key blank — Voiceblox falls back to inference automatically.
## Managing keys in the UI
You can also set keys through the **Settings** panel in the builder (gear icon). Keys are written to `.env.local` on the server and take effect immediately without a restart.
# First Agent
Source: https://docs.voiceblox.ai/getting-started/first-agent
Build your first voice agent step by step — manually or with the AI generator.
# 🎨 Build Your First Agent
Once the app is running and your API keys are configured, here's how to build a simple voice agent.
## Manual build
Drag **Agent** from the sidebar onto the canvas. This is the central node that orchestrates your voice agent — configure the agent name, persona, and language here.
Drag an **LLM**, **TTS**, and **STT** node onto the canvas. Connect each one to the Agent node — they auto-route to the correct handle.
Click the Agent node and fill in the **Persona** (system prompt) field — e.g., "You are a friendly customer support agent."
Add a **Start** node and connect it to the Agent node's output. Then add a **Burst** node, then an **End** node. Chain them: Start → Burst → End.
Click the Start node and set the **Command** to your opening line (e.g., `Hello! How can I help you today?`). Enable **Is Literal** to speak it verbatim instead of generating it.
Click **Test** in the top bar, then **Start Session**. Allow microphone access when prompted and start talking to your agent.
## Or use the AI generator
Instead of building manually, describe your agent in plain language:
1. Click the **AI** button in the toolbar
2. Type something like: `Build a customer support agent with a greeting, a triage question, and two branches: billing and technical support`
3. The AI generates the full flow and applies it to the canvas automatically
***
## Next steps
Full reference for every supported provider key.
Learn about all available node types.
Generate flows from natural language.
Complete environment variable reference.
# Ingredients
Source: https://docs.voiceblox.ai/getting-started/ingredients
Gather all the API keys you'll need before installing Voiceblox.
# 🧾 Ingredients — Gather Your API Keys
Before installing anything, let's collect all the accounts and keys you'll need. Do this first so the installation flows smoothly without interruptions.
Powers the **AI Builder** — describe your agent in plain language and it builds the flow for you.
1. Go to [platform.claude.com/settings/keys](https://platform.claude.com/settings/keys)
2. Create an account (or sign in)
3. Click **Create Key** and copy it somewhere safe
> This is the only key required to start using the builder.
Required to **test and run** your voice agent. You'll need three values: **URL**, **API Key**, and **API Secret**.
1. Go to [cloud.livekit.io](https://cloud.livekit.io) and create a free account
2. Create a new project (any name works)
3. Go to **Settings → Keys** and copy these three values:
* `LIVEKIT_URL` — your server address (looks like `wss://your-project.livekit.cloud`)
* `LIVEKIT_API_KEY` — starts with `API...`
* `LIVEKIT_API_SECRET` — a long string of characters
Enables **voice dictation** in the builder — speak your prompts instead of typing.
1. Go to [console.deepgram.com](https://console.deepgram.com/) and create a free account
2. Go to **API Keys** and create a new key
3. Copy it somewhere safe
Save all your keys in a text file or note — you'll paste them into the app during setup. Don't worry about `.env` files or configuration; the app handles everything for you.
## Quick reference
| Key | What it's for | Required? |
| ---------------------- | -------------------------------------- | --------------------- |
| **Anthropic API Key** | AI Builder (generates flows from text) | ✅ Yes |
| **LiveKit URL** | Connects to the voice server | ✅ Yes, to test agents |
| **LiveKit API Key** | Authenticates with LiveKit | ✅ Yes, to test agents |
| **LiveKit API Secret** | Authenticates with LiveKit | ✅ Yes, to test agents |
| **Deepgram API Key** | Voice dictation in the builder | Optional |
These are the keys to get started. Once your agent is running, you can add more provider keys (OpenAI, ElevenLabs, etc.) through the **⚙️ Settings** button inside the app. See [API Keys](/getting-started/api-keys) for the full list.
***
Got all your keys? Let's move on to the installation.
Next step: install and run Voiceblox.
# Installation
Source: https://docs.voiceblox.ai/getting-started/installation
Install and run Voiceblox — choose between Docker (recommended) or a manual setup.
# 🍳 Installation
Now that you have your [ingredients](/getting-started/ingredients) ready, let's install Voiceblox.
***
## Step 1 — Open the Terminal
The terminal is a text window where you type commands. Here's how to open it on your operating system:
1. Press **Command (⌘) + Space** to open Spotlight Search.
2. Type **Terminal** and press **Enter**.
* **Ubuntu / Debian:** Press **Ctrl + Alt + T**.
* Or search for **Terminal** in your applications menu.
1. Press the **Windows key**, type **PowerShell**, and click **Windows PowerShell**.
2. Alternatively, press **Windows key + R**, type `powershell`, and press **Enter**.
Every command in this guide should be typed (or pasted) into the terminal and confirmed with the **Enter** key.
***
## Step 2 — Install Git
Git is the tool used to download the Voiceblox source code.
### Check if Git is already installed
```bash theme={null}
git --version
```
* If you see a version number — **skip to Step 3.**
* If you see `command not found` — install it:
```bash theme={null}
brew install git
```
> Don't have Homebrew? Install it first:
>
> ```bash theme={null}
> /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
> ```
```bash theme={null}
sudo apt-get install -y git
```
```powershell theme={null}
winget install Git.Git
```
> Or download the installer from [git-scm.com](https://git-scm.com/download/win). After installation, close and reopen your terminal.
***
## Step 3 — Download Voiceblox
In your terminal, run:
```bash theme={null}
git clone https://github.com/voiceblox-ai/voiceblox.git
cd voiceblox
```
This downloads the project into a folder called `voiceblox` and moves you into it.
***
## Step 4 — Choose how to run it
Docker is the easiest way to run Voiceblox — no need to install Node.js or any other dependencies.
### Check if Docker is already installed
```bash theme={null}
docker --version
```
* If you see a version number — **skip to [Check if Docker is running](#check-if-docker-is-running).**
* If you see `command not found` — install it below.
### Install Docker
```bash theme={null}
brew install --cask docker
```
> Don't have Homebrew? Install it first:
>
> ```bash theme={null}
> /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
> ```
After installation, open the **Docker** app from your Applications folder to start the Docker engine.
```bash theme={null}
sudo apt-get update
sudo apt-get install -y docker.io docker-compose-plugin
sudo usermod -aG docker $USER
```
> Log out and log back in for the group change to take effect. For other distributions, see [Docker's official install guide](https://docs.docker.com/engine/install/).
```powershell theme={null}
winget install Docker.DockerDesktop
```
> After installation, open **Docker Desktop** and wait until the Docker engine is running (you should see the Docker icon in your system tray).
### Check if Docker is running
Docker needs to be running before you can start the project. Check with:
```bash theme={null}
docker info
```
* If you see system information — **Docker is running, continue below.**
* If you see `Cannot connect to the Docker daemon` — open the **Docker Desktop** app (macOS/Windows) or start the service with `sudo systemctl start docker` (Linux), then try again.
### Start the project
Inside the `voiceblox` folder, run:
```bash theme={null}
docker compose up --build
```
This builds the Docker images and starts the project. Two services start at once:
* **The app** — open your browser at **[http://localhost:3000](http://localhost:3000)** to use the builder
* **The agent worker** — connects to your LiveKit server and handles voice sessions in the background
### Stop the project
To stop everything, go back to the terminal and press **Ctrl + C**, then run:
```bash theme={null}
docker compose down
```
If you prefer to run Voiceblox without Docker, you'll need Node.js and pnpm.
### Install Node.js
Node.js is the engine that runs Voiceblox. You need **version 20 or newer**.
#### Check if Node.js is already installed
```bash theme={null}
node --version
```
* If you see something like `v20.x.x` or higher — **you're all set, skip to [Install pnpm](#install-pnpm).**
* If you see `command not found` or a version below 20 — follow the instructions below.
```bash theme={null}
brew install node@20
```
> Don't have Homebrew? Install it first:
>
> ```bash theme={null}
> /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
> ```
Confirm it worked:
```bash theme={null}
node --version
```
Run the following commands one at a time:
```bash theme={null}
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```
Confirm the installation:
```bash theme={null}
node --version
```
> **Other Linux distributions:** See [NodeSource's guide](https://github.com/nodesource/distributions) for RPM-based systems (Fedora, CentOS, etc.).
Open **PowerShell** and run:
```powershell theme={null}
winget install OpenJS.NodeJS.LTS
```
> If `winget` is not available, download the installer directly from [nodejs.org](https://nodejs.org/en/download) and run the `.msi` file.
After installation, **close and reopen PowerShell**, then confirm:
```powershell theme={null}
node --version
```
### Install pnpm
`pnpm` is the package manager Voiceblox uses.
#### Check if pnpm is already installed
```bash theme={null}
pnpm --version
```
* If you see a version number — **you're all set, skip ahead.**
* If you see `command not found` — install it:
```bash theme={null}
npm install -g pnpm
```
Confirm it worked:
```bash theme={null}
pnpm --version
```
### Install dependencies
Inside the `voiceblox` folder, install all required packages:
```bash theme={null}
pnpm install
```
This may take a minute or two. Wait until it finishes before moving on.
### Start the app
Run the development server:
```bash theme={null}
pnpm dev
```
When you see a message like `Ready on http://localhost:3000`, open your web browser and go to:
**[http://localhost:3000](http://localhost:3000)**
To stop the server at any time, go back to the terminal and press **Ctrl + C**.
***
## Step 5 — Enter Your API Keys
When you open the app for the first time, it will ask you for your API keys — this is where you paste the [ingredients](/getting-started/ingredients) you collected earlier.
1. The setup dialog appears automatically on first launch
2. Paste your **Anthropic API Key** and **Deepgram API Key** (if you have one)
3. Click the **⚙️ Settings** button in the toolbar to add your **LiveKit credentials** (URL, API Key, API Secret)
The app saves everything automatically — **no need to edit any files manually**.
**Docker users:** The agent worker reads keys at startup. If you add keys for a new provider while the containers are running, restart the agent with `docker compose restart agent` for it to pick them up.
***
You're all set! Time to build your first agent.
Next step: create a voice agent on the canvas.
# What is Voiceblox?
Source: https://docs.voiceblox.ai/getting-started/introduction
A visual drag-and-drop builder for voice AI agents — design, test, and deploy without writing boilerplate.
# What is Voiceblox?
Voiceblox is an open-source visual builder for voice AI agents. Instead of wiring together SDKs by hand, you drag nodes onto a canvas, connect them, and get a fully working voice agent — backed by [LiveKit](https://livekit.io).
## Key concepts
The building blocks of your agent. Each node represents a component (LLM, TTS, STT) or a conversation step (Start, Burst, IfElse, End).
The directed graph of conversation steps that defines how your agent behaves — what it says, when it listens, and how it branches.
The runtime that executes your agent. Voiceblox runs on **LiveKit**'s real-time infrastructure.
The serialized JSON representation of your flow — framework-agnostic and ready for deployment.
## How it works
```
Canvas (drag & drop)
↓
React Flow graph (nodes + edges)
↓ serializeGraph()
SimpleNode[] + SimpleEdge[]
↓ graphToConfig()
AgentConfig (JSON)
↓
LiveKit agent runtime
```
## Who is it for?
* **Voice AI developers** who want to skip boilerplate and focus on conversation design
* **Teams** who need to iterate quickly on agent behavior without touching code
* **Engineers** deploying multi-step, branching voice workflows (triage, sales, support)
## What can you build?
* Customer support agents with branching triage logic
* Sales qualification flows with conditional routing
* Multilingual voice assistants with multiple TTS/STT providers
* Agents that call external APIs via webhooks or MCP servers
* Agents augmented with real-time web search
## Next steps
Get Voiceblox running locally in 5 minutes.
Configure your provider API keys.
# MCP Servers
Source: https://docs.voiceblox.ai/integrations/mcp-servers
Connect Model Context Protocol servers to give your agent access to external tools.
# MCP Servers
The MCP node connects your agent to a [Model Context Protocol](https://modelcontextprotocol.io) server, exposing its tools to the LLM. The agent can call these tools during a conversation to fetch data, run actions, or interact with external systems.
## Adding an MCP node
1. Drag the **MCP** node from the sidebar (Tools category) onto the canvas
2. Connect its output handle to the Agent node's `tools_in` handle
3. Configure the node parameters
## Parameters
| Parameter | Type | Required | Description |
| --------------- | -------------- | -------- | --------------------------------------------------- |
| `serverUrl` | string | ✅ | The MCP server's HTTP endpoint URL |
| `authType` | enum | — | Authentication type: `none`, `bearer`, or `api_key` |
| `authValue` | string | — | The token or API key value (if auth is enabled) |
| `selectedTools` | tool\_selector | — | Which tools from the server to expose to the LLM |
## Discovering tools
After entering a `serverUrl`, click **Load Tools** in the Properties Panel. Voiceblox calls `/api/mcp-tools` to fetch the tool list from the server. You'll see each tool's name and description. Check the tools you want to expose.
## How it works at runtime
When the agent is running and the LLM decides to call a tool:
1. The agent connects to the MCP server via `StreamableHTTPClientTransport`
2. It calls `callTool()` with the tool name and arguments
3. The result is streamed back to the LLM as tool output
4. The agent publishes a `tool_call` event (visible in step highlighting)
## Authentication
For servers that require authentication:
* **Bearer token:** Set `authType` to `bearer` and paste your token in `authValue`. The server receives `Authorization: Bearer {token}`.
* **API key:** Set `authType` to `api_key` and paste your key in `authValue`. The server receives `x-api-key: {key}`.
## Multiple MCP servers
You can connect multiple MCP nodes to the same Agent node via the `tools_in` handle (unlimited connections). The agent will have access to all selected tools from all connected servers.
# SIP Transfer
Source: https://docs.voiceblox.ai/integrations/sip-transfer
Let your agent transfer a live call to a human phone number.
# SIP Transfer
The SIP Transfer node gives your agent the ability to transfer an active call to a human phone number. The LLM decides when to initiate the transfer based on the conversation context — for example, when an issue is too complex or the user explicitly asks to speak with a person.
## Setup
1. Configure a SIP trunk in your LiveKit project (see [LiveKit SIP docs](https://docs.livekit.io/agents/telephony/sip/))
2. Drag the **SIP Transfer** node from the sidebar (Tools category) onto the canvas
3. Connect its output handle to the Agent node's `tools_in` handle
4. Add the phone numbers the agent can transfer to
## Parameters
| Parameter | Type | Required | Description |
| -------------- | ----------- | -------- | ------------------------------------------------------------------------------------------- |
| `phoneNumbers` | phone\_list | ✅ | List of phone numbers the agent can transfer to (international format, e.g. `+14155551234`) |
| `playDialtone` | boolean | — | Whether to play a dialtone sound during the transfer. Default: `true` |
## How it works
When the LLM determines a transfer is needed, it calls the `transfer_to_human` tool. The agent then initiates a SIP call to the selected phone number and bridges the active session.
The agent has access to all phone numbers you configure — the LLM chooses the most appropriate one based on context (or you can configure a single number for a dedicated transfer target).
## Typical pattern
```
[Agent] ◀──tools── [SIP Transfer]
│
[Start] ──▶ [Categorize] ──▶ [human branch] ──▶ [End]
```
SIP Transfer requires a configured SIP trunk in LiveKit Cloud. See [LiveKit SIP setup](https://docs.livekit.io/agents/telephony/sip/) for instructions.
## Use cases
* Escalate to a live agent when the issue is too complex
* Route to a specialist (billing, technical, sales) based on conversation outcome
* Let users opt out of the bot and speak to a human at any time
# Structured Output
Source: https://docs.voiceblox.ai/integrations/structured-output
Extract structured data from a conversation at the end of a session.
# Structured Output
The Structured Output node runs after the conversation ends. It uses an LLM to extract structured data from the full conversation transcript — returning a JSON object with the fields you define. You can then pipe the result to a Webhook.
## Adding a Structured Output node
1. Drag the **Structured Output** node from the sidebar (Post-Processing category) onto the canvas
2. Connect the **End** node's output to the Structured Output node's `end` handle
3. Connect an **LLM** node to its `llm_in` handle
4. Define the schema fields you want extracted
5. Optionally, connect the Structured Output node's output to a **Webhook** node
## Parameters
| Parameter | Type | Description |
| -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `command` | text | Instruction for extraction (e.g., "Extract the customer's name, issue type, and whether the issue was resolved") |
| `schemaFields` | schema\_fields | The fields to extract — each with a name, type, and optional description |
### Schema field types
| Type | Description |
| --------- | ---------------------------- |
| `string` | Free-form text |
| `int` | Integer number |
| `float` | Decimal number |
| `boolean` | True/false value |
| `list` | Array of strings |
| `enum` | One of a fixed set of values |
## Output
The extracted data is available as a JSON object matching your schema. When chained to a Webhook, it is sent as the `structuredOutput` field in the POST body:
```json theme={null}
{
"structuredOutput": {
"customerName": "Jane Smith",
"issueType": "billing",
"sentiment": "negative",
"resolved": false
}
}
```
## Typical pattern
```
[End] ──▶ [Structured Output] ──▶ [Webhook]
```
## Use cases
* Extract leads (name, email, interest level) from a sales call
* Classify support tickets and collect issue details at the end of the call
* Score call quality or customer sentiment
* Build a CRM record automatically from each conversation
# Web Search (Exa.ai)
Source: https://docs.voiceblox.ai/integrations/web-search
Enable real-time web search in your voice agent using the Exa node.
# Web Search (Exa.ai)
The Exa node gives your agent access to real-time web search via [Exa.ai](https://exa.ai). The LLM can call the `web_search` tool during a conversation to look up current information.
## Setup
1. Get an API key from [exa.ai](https://exa.ai)
2. Add it to `.env.local`:
```env theme={null}
EXA_API_KEY=your-exa-key
```
3. Drag the **Exa** node from the sidebar (Tools category) onto the canvas
4. Connect its output handle to the Agent node's `tools_in` handle
## Parameters
| Parameter | Type | Default | Description |
| ----------------- | ------------- | ------- | ------------------------------------------------ |
| `searchType` | enum | `auto` | Search strategy: `auto`, `neural`, or `keyword` |
| `numResults` | slider (1–10) | `5` | Number of search results to return |
| `includeContents` | boolean | `true` | Whether to include page text snippets in results |
## How it works
When the LLM decides it needs current information:
1. It calls the `web_search` tool with a query string
2. Exa searches the web and returns results (title, URL, snippet)
3. The results are injected into the LLM's context
4. The agent responds using the search results
The agent publishes `tool_call` and `tool_result` events (visible in step highlighting).
## Search types
* **auto** — Exa automatically selects the best search strategy
* **neural** — Semantic search, best for conceptual queries
* **keyword** — Traditional keyword search, best for specific terms or names
## Use cases
* Answering questions about current events, prices, or availability
* Looking up product documentation or specs in real time
* Fetching information that changes frequently
* Research-oriented voice agents
# Webhooks
Source: https://docs.voiceblox.ai/integrations/webhooks
Send conversation data to external HTTP endpoints at the end of a call.
# Webhooks
The Webhook node fires an HTTP POST to a URL when the conversation ends. Use it to send transcripts, trigger CRM updates, create support tickets, or notify external systems.
The Webhook node is a **post-processing node** — it runs after the conversation ends and receives the full conversation data. You can chain it after **Structured Output** to also send extracted fields.
## Adding a Webhook node
1. Drag the **Webhook** node from the sidebar (Post-Processing category) onto the canvas
2. Connect the End node's output to the Webhook node's `in` handle
3. Set the `transferTarget` URL
## Parameters
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | -------------------------------- |
| `transferTarget` | string | ✅ | The HTTP endpoint URL to POST to |
## Payload
The webhook receives a POST request with this JSON body:
```json theme={null}
{
"conversation": [
{
"type": "user",
"text": "I need help with my bill",
"timestamp": "2025-01-01T12:00:00.000Z"
},
{
"type": "assistant",
"text": "I'd be happy to help with your billing question.",
"timestamp": "2025-01-01T12:00:01.000Z"
}
]
}
```
When chained after a **Structured Output** node, the payload also includes the extracted fields:
```json theme={null}
{
"structuredOutput": {
"customerName": "Jane Smith",
"issueType": "billing",
"resolved": false
}
}
```
## Response handling
Voiceblox checks the HTTP response status. The call proceeds regardless of the webhook response — failures are logged but don't crash the session.
## Typical patterns
**Transcript only:**
```
[End] ──▶ [Webhook]
```
**Structured data + transcript:**
```
[End] ──▶ [Structured Output] ──▶ [Webhook]
```
## Common use cases
* **CRM update** — POST conversation summary to Salesforce or HubSpot
* **Support ticket** — Create a Zendesk ticket with the transcript
* **Analytics** — Send conversation data to your data warehouse
* **Notifications** — Alert your team via Slack or email webhook
# v0.1.0
Source: https://docs.voiceblox.ai/releases/v0-1-0
Initial release — visual drag-and-drop voice agent builder with AI flow generation.
# v0.1.0 — Initial Release 🎉
*Released March 11, 2026*
The first public release of Voiceblox — a visual drag-and-drop builder for voice AI agents. Design conversation flows on a canvas, connect components, and generate agents with natural language.
## ✨ What's New
### 🎨 Visual Builder Canvas
A full-screen React Flow canvas where you drag nodes from a sidebar, connect them with typed handles, and configure properties in a side panel. Includes auto-arrange for quick layout organization and graph import/export as JSON.
### 🧩 Node System
A complete set of building blocks for voice agents:
* **Component nodes** — LLM, TTS, STT, and Avatar nodes that wire into a framework node
* **Conversation nodes** — Start, Burst, OpenTalk, End, Transfer, IfElse, Timer, and Categorize nodes that define the conversation flow
* **Connection rules** — typed handles (`audio`, `text`, `context`, `control`, `agent`) with validation to prevent invalid wiring
### 🔌 Multi-Provider Support
Out-of-the-box support for major AI providers:
* **LLM** — OpenAI, Anthropic, Google Gemini
* **TTS** — OpenAI, ElevenLabs, Cartesia, Deepgram
* **STT** — Deepgram, Google, AssemblyAI
### 🤖 AI Flow Generation
Describe the voice agent you want in natural language and let Claude generate the entire flow — nodes, edges, and parameters. Edit existing flows by chatting with the AI builder.
### 💬 Agent Builder Panel
A chat-based interface for iterating on flows. Attach specific nodes to your message for targeted edits. The AI understands the full node catalog and connection rules.
# v0.2.0
Source: https://docs.voiceblox.ai/releases/v0-2-0
Python agent runtime, LiveKit Cloud deployment, SQLite persistence, and enhanced AI generation.
# v0.2.0 — Deploy & Persist 🚀
*Released March 16, 2026*
A major infrastructure release that makes Voiceblox agents runnable and deployable. Agents now persist locally, run on a Python worker, and can be deployed to LiveKit Cloud with one click.
## ✨ What's New
### 🐍 Python Agent Worker
A standalone Python worker process powered by LiveKit Agents SDK. The worker receives an `AgentConfig` via room metadata and dynamically builds the LLM, TTS, and STT pipeline at runtime. Run it locally with `pnpm agent-python:dev`.
### ☁️ Deploy to LiveKit Cloud
One-click deployment from the builder. The deploy dialog uploads your agent configuration and Python worker to LiveKit Cloud, where it runs as a hosted agent. Includes deploy history and version tracking.
### 💾 Local SQLite Persistence
All data now persists locally in a SQLite database (WAL mode, Drizzle ORM):
* **Agents** — save, rename, soft-delete, and list your agents
* **Version history** — automatic snapshots with content-hash deduplication (max 50 per agent)
* **AI Builder conversations** — chat history preserved across sessions
* **Test sessions** — playground messages saved per session
### 🔑 First-Launch Setup
A setup dialog appears on first visit to configure API keys. Keys are saved to `.env.local` automatically — works in both local and Docker environments.
### 🧠 Enhanced AI Flow Generation
The AI generator now supports:
* **Extended thinking** — Claude reasons step-by-step before generating operations
* **File upload** — attach reference documents to your prompt
* **Web search** — the AI can search the web for context while generating
### 🔧 MCP Server Integration
A new MCP (Model Context Protocol) node that connects external tool servers to your voice agent. The agent can call MCP tools during conversation, enabling integrations with databases, APIs, and custom services.
### 🔍 Exa.ai Web Search
A dedicated web search node powered by Exa.ai. Add real-time web search capabilities to your agent's conversation flow.
### 📋 Expanded Provider Support
Improved node UI with better model selection and provider management. Dynamic model lists fetched per provider with caching.
### 🛠️ Additional Improvements
* **🌙 Theme persistence** — dark/light mode preference saved across sessions
* **🪄 Node wand button** — quick-attach a node to the AI chat for targeted edits
* **🐳 Docker support** — `docker compose` setup for running the full stack
* **📖 Documentation site** — Mintlify-powered docs with guides, API reference, and architecture docs
* **♻️ Decomposed codebase** — page.tsx broken into focused hooks and components for maintainability
# v0.3.0
Source: https://docs.voiceblox.ai/releases/v0-3-0
Share your deployed agents with private JWT links and public sandbox links.
# v0.3.0 — Agent Sharing 🔗
*Released March 18, 2026 (includes v0.3.1 patch)*
After deploying to LiveKit Cloud, you can now generate share links so anyone can talk to your agent — no login required.
## ✨ What's New
### 🔗 Share Links
A new **Share** tab in the Deploy dialog with two link types:
* **🔒 Private Link** — generates a LiveKit JWT token with `RoomAgentDispatch` embedded. Each link creates a dedicated room for the visitor. Configurable expiration: 1 hour, 24 hours, or 7 days.
* **🌐 Public Link** — uses the LiveKit Sandbox Token Server so every visit gets a fresh room and token. Requires `LIVEKIT_SANDBOX_ID` configuration.
Share links open on `voiceblox.ai/talk/{encoded-config}` with a ready-to-use voice interface.
### 📋 Embed Code
Copy an HTML embed snippet to add your agent to any website as an iframe.
## 🐛 Bug Fixes
* **Agent name slugification** (v0.3.1) — agent names are now properly slugified for LiveKit dispatch compatibility, fixing issues where names with spaces or special characters would fail to dispatch.
# v0.4.0
Source: https://docs.voiceblox.ai/releases/v0-4-0
Unified agent node, inbound phone calls, structured output, LemonSlice avatar, and SIP transfer.
# v0.4.0 — Agents & Phone Calls 📞
\_*Released March 24, 2026*
A release focused on simplifying the agent model and adding telephony capabilities. The agent node is now the central orchestrator, and deployed agents can receive inbound phone calls.
## ✨ What's New
### 🤖 Unified Agent Node
The framework and persona nodes have been replaced by a single **Agent** node. Configure your agent's name, persona, language, and interruption settings in one place. LLM, TTS, STT, and Avatar nodes wire directly into it.
### 📞 Inbound Phone Calls
Deployed agents can now receive inbound phone calls via SIP. Configure a phone number in the deploy settings and callers will be connected to your voice agent automatically.
### 📲 SIP Transfer Node
A new **Transfer** tool node that hands the call over to a human agent via SIP. Define the transfer destination and conditions — the agent will transfer the call when the conversation flow reaches this node.
### 📊 Structured Output Node
A new node type that constrains the LLM's output to a specific JSON schema. Useful for extracting structured data from conversations (e.g., booking details, form fields, classifications).
### 🎭 LemonSlice Avatar Integration
Connect a visual avatar to your agent using LemonSlice. The avatar node accepts an API key and renders a real-time animated avatar that syncs with the agent's speech.
### 🔍 Tool Call Events in Test History
The test playground now displays tool call events (MCP tools, web search, etc.) inline in the conversation transcript, making it easier to debug agent behavior.
### 🔄 Post-End Pipeline
When a session ends (or the user disconnects), the agent now executes a post-end pipeline with an enriched webhook payload containing the full conversation summary and metadata.
## ⚡ Improvements
* **♻️ Python agent refactor** — unified tool system into a registry-based `tools/` package for cleaner extensibility
* **🗑️ Removed TypeScript agent** — the Python worker is now the sole agent runtime, simplifying the stack
* **🔌 MCP SSE transport fallback** — MCP server connections now fall back to SSE transport if the primary transport fails
* **🔗 Share link regeneration** — share links are regenerated when the modal opens or settings change, ensuring they're always fresh
## 🐛 Bug Fixes
* Fixed auto-scroll overriding manual scroll in the test transcript
* Fixed deploy mismatch detection to compare project URLs instead of names
* Fixed AI Builder panel not showing the last message instantly when opened
* Fixed page scroll when scrolling the version history panel
# v0.5.0
Source: https://docs.voiceblox.ai/releases/v0-5-0
Input variables, Zapier/Make nodes, canvas redesign, and multi-tenant public mode.
# v0.5.0 — Input Variables & Canvas Redesign
*Released March 25, 2026*
A release focused on making agents more dynamic and the builder experience more polished. Input variables let you parameterize agents at runtime, the canvas gets a full visual overhaul, and Zapier/Make integrations open up post-processing pipelines.
## ✨ What's New
### 🔤 Input Variables
Agents can now declare **input variables** — runtime parameters injected into the agent's prompt before a session starts. Variables are defined in the Agent node, automatically get kebab-case keys, and sync with the prompt as you type. A **tag picker and autocomplete** make it easy to reference variables inside any prompt field.
Share links and the Production playground use the deployed variable values, keeping staging and production consistent.
### ⚡ Zapier & Make Post-Processing Nodes
Two new integration nodes — **Zapier** and **Make** — let you trigger automation workflows at the end of a conversation. Use them to push call summaries, extracted data, or transcripts into your existing tools.
### 🎨 Canvas Redesign
The builder canvas has been redesigned with **floating panels**, an interactive dot background, and opaque nodes for better visual clarity.
### 🌈 Updated Node Color Palette
Node colors have been refreshed and categories expanded, making it easier to visually distinguish node types on the canvas.
### 🛠️ Setup Screen Redesign
The initial setup screen is now a two-column layout with a dot background for a more polished first impression.
### ⚙️ Collapsible Settings Sections
The Settings panel now uses collapsible sections, with LiveKit configuration shown first.
### 🌐 Multi-Tenant Public Mode
Added support for a public multi-tenant mode with on-demand Python worker management, enabling Voiceblox to serve multiple users from a shared infrastructure.
## ⚡ Improvements
* **📋 Webhook payload redesign** — cleaner, richer webhook payloads; structured output events are now shown inline in test history
* **📸 Updated app screenshot** — reflects the new canvas design
## 🐛 Bug Fixes
* Fixed MCP auth value field visibility when auth type is none
* Fixed deploy prompts by passing `--yes` to lk CLI commands to skip interactive confirmations
* Fixed nodes appearing transparent when inactive in the playground
* Fixed deploy log overflow and ANSI escape codes in deploy output
* Fixed deploy status using the DB as source of truth to prevent stale state
* Fixed TTS and LLM errors now surfaced to the frontend with a clean disconnect message
* Fixed Share and Deploy panels expanding when switching tabs
* Fixed deploy error display to show the last CLI output line instead of a raw command dump
* Fixed auto-arrange layout algorithm and version history scroll behavior
* Fixed wand button incorrectly opening the AI Builder panel
* Fixed AI Builder notification not re-showing when the same message is sent again
* Added LiveAvatar provider icon
# v0.6.0
Source: https://docs.voiceblox.ai/releases/v0-6-0
Realtime agents, 24 new providers, latency metrics, and adaptive interruption.
# v0.6.0 — Realtime Agents & Provider Expansion
*Released April 2, 2026*
A release focused on expanding what agents can do and how many ways you can build them. Realtime speech-to-speech agents are now supported as a first-class pipeline, 24 new providers cover nearly every major AI vendor, and the playground now shows per-turn latency so you can see exactly where time is spent.
## ✨ What's New
### ⚡ Realtime (Speech-to-Speech) Agents
Agents can now run as **Realtime agents** — a new pipeline mode where a single multimodal model handles speech input and output directly, skipping the cascade STT → LLM → TTS chain. Four realtime providers are supported: **OpenAI**, **Gemini**, **Azure OpenAI**, and **xAI**.
To use it, drop a Realtime Agent node on the canvas and connect one of the four realtime provider nodes. The existing pipeline is now called **Cascade Agent** for clarity. Both modes support input variables, the playground, and all conversation flow nodes.
### 🌐 24 New AI Providers
**LLM providers:** Anthropic (direct), Mistral, OpenRouter, AWS Bedrock
**TTS providers:** Groq TTS, Google Cloud TTS, Azure Speech, AWS Polly, Cartesia STT
**STT providers:** ElevenLabs STT, Cartesia STT, AssemblyAI STT, Mistral STT, Google Cloud STT, Azure Speech STT, AWS Transcribe
**Avatar providers:** Anam, Avatario, AvatarTalk, Hedra, Keyframe, LiveAvatar, Simli, Tavus, TruGen
The default TTS provider has been switched from ElevenLabs to **Cartesia**.
### 📊 Provider Latency Metrics
The playground and conversation history now show a **LatencyBar** beneath each agent turn, breaking down STT, LLM, and TTS latency in milliseconds. The session list also shows average latency per conversation so you can compare providers at a glance.
Metrics are collected from LiveKit SDK events, grouped by speech turn, and persisted to the database.
### 🎛️ Adaptive Interruption Handling
The boolean interruption toggle has been replaced with a **3-mode selector** on the Agent node:
* **Off** — interruptions disabled
* **VAD** — voice activity detection, interrupt on any speech
* **Adaptive** — LiveKit's TurnHandlingOptions, which learns from the conversation
## ⚡ Improvements
* **Model lists updated** to match the latest LiveKit documentation
* **agent-python dependencies** updated to latest versions
# v0.7.0
Source: https://docs.voiceblox.ai/releases/v0-7-0
Voice picker, LiveKit Inference, separated API keys, and Cloud Run stability.
# v0.7.0 — Voice Picker & Deployment Improvements
*Released April 9, 2026*
A release focused on making the builder more interactive and deployments more reliable. TTS nodes now let you preview voices directly on the canvas, LiveKit Inference is available as a managed deployment option, API keys are now split between builder and agent, and the Cloud Run worker received a round of stability fixes.
## ✨ What's New
### 🎙️ Dynamic Voice Picker with Preview
TTS nodes now include an interactive **voice picker** — browse available voices for your selected provider and click the play button to hear a preview before committing. The picker loads voices dynamically based on the provider and selected model, so you always see exactly what's available.
### ☁️ LiveKit Inference Deployment
When deploying to LiveKit Cloud, you can now choose **LiveKit Inference** as the compute backend. This offloads model execution to LiveKit's managed infrastructure instead of your own Python worker, reducing operational overhead for supported providers.
### 🔑 Separate Builder & Agent API Keys
API keys are now split into two independent sections:
* **Builder keys** — used by the AI assistant (flow generation and editing) inside the canvas
* **Agent keys** — used by the deployed agent at runtime for LLM, TTS, and STT providers
This makes it easier to use different credentials for development vs. production, and avoids accidentally mixing billing accounts.
### 🔌 SIP Transfer: Disconnect After Transfer
The SIP Transfer node has a new **disconnect after transfer** toggle. When enabled, the agent disconnects from the call immediately after the transfer is initiated, rather than staying connected until the transfer completes.
## ⚡ Improvements
### Simplified Interruption Mode
The 3-mode interruption selector (Off / VAD / Adaptive) has been simplified back to a plain **Off / On toggle**. The toggle maps to VAD-based interruption when enabled. Realtime agents no longer expose an interruption setting (it is controlled by the provider).
### Cloud Run Worker Stability
Several fixes were applied to the agent Python worker running on Cloud Run:
* **SSE keepalive** — an SSE ping is sent periodically to prevent Cloud Run from scaling to zero mid-session
* **HuggingFace offline mode** — the worker now forces HF offline mode so model files are loaded from the container image cache instead of attempting network downloads
* **Resource allocation** — memory increased to 4Gi and CPU to 2 cores to support the turn detector model reliably
* **gVisor compatibility** — model cache is now copied rather than symlinked, which is required for Cloud Run's gVisor sandbox
* **Startup reliability** — spawn and fetch timeouts increased to 60s; room metadata is retried on warm dispatches
# In-Browser Playground
Source: https://docs.voiceblox.ai/testing/playground
Test your voice agent live in the browser without any external setup.
# In-Browser Playground
The Test Panel lets you run a live voice session with your agent directly in the browser. No deployment needed.
## Requirements
* `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` in `.env.local`
* At least one LLM, TTS, and STT configured in your flow
* Microphone access in the browser
## Starting a session
1. Click **Test** in the top toolbar
2. The Test Panel opens on the right side of the canvas
3. Click **Start Session**
4. Allow microphone access when prompted
5. The agent speaks its opening line — start talking
## Agent runtime
The playground dispatches agent jobs via the Python agent server. You need to have `pnpm agent:server` running in a separate terminal and `AGENT_SERVER_URL=http://localhost:8080` set in `.env.local`. See [Agent Runtimes](/deployment/agent-runtimes).
## What happens under the hood
When you click Start Session:
1. The frontend POSTs to `/api/agent-session` with your current flow's nodes and edges
2. The server converts the graph to an `AgentConfig` via `graphToConfig()`
3. A LiveKit room is created with the config stored in room metadata
4. The job is dispatched to the Python agent worker via `AgentDispatchClient`
5. You receive a JWT token to join the room
6. The frontend joins the room using the LiveKit SDK
7. The agent publishes `voiceblox.agent.events` data messages that the frontend listens to
## During a session
* **Speak** into your microphone to interact with the agent
* **Watch** the active conversation step highlight on the canvas in real time
* **View** the conversation transcript in the Test Panel
* The session ends when the agent reaches an End node or you click **End Session**
## Ending a session
Click **End Session** in the Test Panel to disconnect from the LiveKit room.
## Session persistence
Test sessions and their conversation transcripts are automatically saved to the local SQLite database. After a session ends, you can review the full conversation history from the **History** tab in the Test Panel — including message timestamps, session duration, and the conversation step each message belonged to.
Previous sessions are listed per agent, so you can compare runs across different versions of your flow.
## Troubleshooting
See [Troubleshooting](/testing/troubleshooting) for common issues.
# Step Highlighting
Source: https://docs.voiceblox.ai/testing/step-highlighting
Watch the active conversation step highlight in real time during a live session.
# Step Highlighting
During a live test session, the canvas highlights the currently active conversation step node in real time.
## How it works
The agent publishes `voiceblox.agent.events` data channel messages to the LiveKit room. The frontend subscribes to these messages and updates the canvas accordingly.
### Event types
| Event | When it fires | Canvas effect |
| ------------- | ------------------------------------- | ------------------------------ |
| `step_change` | Agent advances to a new step | Highlights the new step node |
| `tool_call` | Agent calls an MCP tool or Exa search | Shows tool activity indicator |
| `tool_result` | Tool returns a result | Clears tool activity indicator |
### Event payload
```typescript theme={null}
{
type: "step_change",
stepId: string, // ID of the newly active step node
stepType: string // e.g., "burst", "ifelse", "end"
}
```
## What you see
* The active step node pulses with a colored highlight
* When branching (If/Else, Categorize), the selected branch's edge animates
* Tool calls show a spinner on MCP/Exa nodes
## Use cases
Step highlighting is especially useful for:
* **Debugging** — verify the agent follows the expected path through the flow
* **Demonstrations** — show stakeholders how the conversation flows visually
* **Validating branches** — confirm the correct branch is taken for given user input
# Troubleshooting
Source: https://docs.voiceblox.ai/testing/troubleshooting
Common issues and how to fix them.
# Troubleshooting
## The agent doesn't respond
**Check:**
* LLM API key is set in `.env.local`
* The LLM node is connected to the Framework node
* Restart the dev server after adding keys
## No voice output (silent agent)
**Check:**
* TTS API key is set
* TTS node is connected to the Framework node's `tts_in`
* Try a different TTS provider
## No voice input (agent can't hear me)
**Check:**
* Browser microphone permissions are granted
* STT API key is set
* STT node is connected to the Framework node's `stt_in`
* The builder STT key for the selected `BUILDER_STT_PROVIDER` is set (`BUILDER_STT_DEEPGRAM_API_KEY` for Deepgram, `BUILDER_STT_GEMINI_API_KEY` for Gemini)
## Session fails to start
**Check:**
* `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` are all set
* LiveKit credentials are valid (test in your LiveKit Cloud dashboard)
* No typos in the URL (must start with `wss://`)
## AI generator returns an error
**Check:**
* The builder LLM key for the selected `BUILDER_LLM_PROVIDER` is set (`BUILDER_LLM_ANTHROPIC_API_KEY` for Anthropic, `BUILDER_LLM_GEMINI_API_KEY` for Gemini)
* You have credits/quota with the selected provider
* The flow has the required nodes (framework, LLM, TTS, STT, start, end)
## Flow validation error
Voiceblox validates the graph before applying AI-generated operations. Common validation errors:
| Error | Fix |
| ---------------------------- | -------------------------------------------------- |
| Missing framework node | Add a LiveKit node |
| No start node | Add a Start node connected to the Framework |
| If/Else directly after Start | Add a Burst or Open Talk between Start and If/Else |
| Categorize has no categories | Add at least two categories to the Categorize node |
## Step highlighting not working
**Check:**
* The LiveKit SDK is connected to the room
* Check browser console for WebSocket errors
## Restarting the agent
If the agent gets into a bad state, click **End Session** and then **Start Session** again to restart with a fresh session.