Metadata-Version: 2.4
Name: vocal-bridge
Version: 0.25.0
Summary: CLI tools for Vocal Bridge voice agent development
License-Expression: Apache-2.0
Project-URL: Homepage, https://vocalbridgeai.com
Project-URL: Documentation, https://vocalbridgeai.com/docs/developer-guide
Keywords: voice,agent,ai,cli,vocal-bridge
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets>=16.0; python_version >= "3.10"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Vocal Bridge CLI

Developer tools for iterating on voice agents built with [Vocal Bridge](https://vocalbridgeai.com).

## Installation

```bash
pip install vocal-bridge
```

Requires Python 3.9+. Real-time debug streaming uses WebSockets on Python 3.10+
and automatically falls back to HTTP polling on Python 3.9.

## Quick Start

```bash
# Authenticate with your API key (get this from the Vocal Bridge dashboard)
vb auth login

# View your agent info
vb agent

# View recent call logs
vb logs

# View call statistics
vb stats

# Update your agent's prompt
vb prompt edit
```

## Authentication

### API Key Types

Vocal Bridge supports two types of API keys:

- **Agent API keys**: Tied to a specific agent. Get one from your agent's detail page.
- **Account API keys**: Work across all your agents. Create one from the dashboard's "API Keys" tab. After login, use `vb agent use` to select which agent to work with. When calling the API directly with an account key, include the `X-Agent-Id` header with the agent UUID.

### Login with API Key

```bash
# Interactive login
vb auth login

# Or provide key directly
vb auth login vb_your_api_key_here

# For account keys, select an agent after login
vb agent use
```

### Check Status

```bash
vb auth status
```

### Logout

```bash
vb auth logout
```

### Environment Variables

You can also set credentials via environment variables:

```bash
export VOCAL_BRIDGE_API_KEY=vb_your_api_key_here
export VOCAL_BRIDGE_API_URL=https://vocalbridgeai.com  # optional
```

## Commands

### Agent Info

```bash
# Show current agent details
vb agent

# List all agents
vb agent list

# Select an agent to work with (interactive)
vb agent use

# Select by agent ID or name
vb agent use <agent_id>
vb agent use "Whiskers the Math Cat"
```

### Create Agent (Paid Subscribers)

Create and deploy a new voice agent programmatically. Requires an active paid subscription. Maximum 50 agents per account.

```bash
# Create a simple chatty agent
vb agent create --name "My Assistant" --style Chatty --prompt "You are a helpful assistant."

# Create with a greeting
vb agent create --name "Sales Bot" --style Focused \
  --prompt "You help customers find products." \
  --greeting "Hi! How can I help you today?"

# Create web-only agent (no phone number)
vb agent create --name "Web Agent" --style Chatty \
  --prompt "You are a support agent." --deploy-targets web

# Create from a prompt file
vb agent create --name "Custom Agent" --style Focused --prompt-file prompt.txt

# Create with model settings
vb agent create --name "Custom Voice" --style Focused \
  --prompt "You are helpful." --model-settings-file settings.json

# Create with MCP server integrations
vb agent create --name "Connected Agent" --style Chatty \
  --prompt "You help with scheduling." --mcp-servers-file servers.json

# Create a Listener agent (passive observer, never speaks — streams transcripts
# and coaching suggestions to your app via the data channel)
vb agent create --name "IR Coach" --style Listener \
  --prompt "You coach during earnings Q&A. Trigger on analyst questions. Respond with a bold recommended answer, 2-3 supporting bullets, and one italic caveat." \
  --coachee-description "the company CFO during earnings Q&A" \
  --coaching-debounce 8

# Output as JSON
vb agent create --name "Test" --style Chatty --prompt "Hello." --json
```

Suggestion: when setting a greeting, consider identifying the agent and company and including any disclosure, consent, or recording language your laws, regulations, or policies require.

**Required flags:**
- `--name` — Agent name
- `--style` (or `--mode`) — Agent style: Chatty, Focused, Gemini, Ultravox, or Listener
- `--prompt` or `--prompt-file` — System prompt (text or file path)

**Optional flags:**
- `--greeting` — Greeting message. Suggestion: identify the agent/company and include any disclosure, consent, or recording language your laws, regulations, or policies require.
- `--deploy-targets` — `phone`, `web`, or `both` (default: `both`)
- `--background-enabled` — Enable background AI: `true`/`false` (default: `true`)
- `--web-search-enabled` — Enable web search: `true`/`false` (default: `true`)
- `--hold-enabled` — Enable hold: `true`/`false` (default: `false`)
- `--hangup-enabled` — Enable hangup: `true`/`false` (default: `false`)
- `--debug-mode` — Enable debug mode: `true`/`false` (default: `false`)
- `--background-model` — Claude model for background AI jobs: `auto`, `claude-haiku-4-5`, or `claude-sonnet-4-6` (default: `auto`)
- `--post-processing-model` — Model for post-call processing: `auto`, `gemini-3.5-flash`, `gemini-2.5-flash`, or `gemini-2.5-flash-lite` (default: `auto`)
- `--model-settings-file` — JSON file with model settings
- `--mcp-servers-file` — JSON file with MCP servers array
- `--client-actions-file` — JSON file with client actions array
- `--api-tools-file` — JSON file with custom HTTP API tools array
- `--ai-agent-file` — JSON file with AI Agent integration config
- `--ai-agent-enabled`, `--ai-agent-description`, `--ai-agent-verbatim`, `--ai-agent-url`, `--ai-agent-header`, `--ai-agent-param`, `--ai-agent-protocol`, `--ai-agent-a2a-method`, `--ai-agent-response-mode`, `--ai-agent-response-ordering`, `--ai-agent-late-responses`, `--ai-agent-duplicate-responses`, `--ai-agent-max-responses-per-turn`, `--ai-agent-max-chars-per-turn` — Inline AI Agent integration settings
- `--json` — Output result as JSON

### Delete Agent

Permanently delete an agent and release its phone number. Requires typing the agent name to confirm.

```bash
# Delete the currently selected agent (interactive confirmation)
vb agent delete

# Delete a specific agent by ID
vb agent delete <agent_id>

# Skip confirmation prompt (use with caution)
vb agent delete --force

# Output as JSON
vb agent delete --json
```

The delete command will:
1. Show agent details and ask you to type the agent name to confirm
2. Delete the dispatch rule and release the phone number
3. Remove the agent record from the database

If the deleted agent was your currently selected agent, the selection is cleared automatically.

### Call Logs

```bash
# List recent call logs (default: 20)
vb logs
vb logs list

# List more logs
vb logs list -n 50

# Filter by status
vb logs list --status completed
vb logs list --status failed

# Paginate
vb logs list --offset 20 -n 20

# View details of a specific call
vb logs show <session_id>
vb logs <session_id>  # legacy shorthand

# Output as JSON
vb logs list --json
vb logs show <session_id> --json
```

For agents with post-call processing configured, `vb logs show` includes a `Post-processing` line indicating whether the post-call analysis/action run succeeded, timed out (10-minute limit), or failed — with a short reason. Same fields are available in `--json` output as `post_processing_status` and `post_processing_message`.

### Download Recordings

Download call recordings to your local machine.

```bash
# Download recording to current directory
vb logs download <session_id>

# Download with custom filename
vb logs download <session_id> -o call.ogg
```

Note: Recordings are only available if the agent has call recording enabled.

### Statistics

```bash
# Show call statistics
vb stats

# Output as JSON
vb stats --json
```

### Prompt Management

```bash
# Show current prompt and greeting
vb prompt show

# Edit prompt in your default editor ($EDITOR)
vb prompt edit

# Edit greeting instead
vb prompt edit --greeting

# Set prompt from file
vb prompt set --file prompt.txt

# Set prompt from stdin
echo "You are a helpful assistant." | vb prompt set

# Set greeting from file
vb prompt set --file greeting.txt --greeting
```

### Agent Configuration

Manage all agent settings including style, capabilities, and integrations.

```bash
# Show all agent settings
vb config show

# Show settings as JSON
vb config show --json

# Edit full config in your default editor ($EDITOR)
vb config edit
```

#### Export Config Sections

Export a specific config section as JSON. Output is pipe-friendly for roundtripping:

```bash
# Export current settings as JSON
vb config get model-settings
vb config get client-actions
vb config get mcp-servers
vb config get api-tools
vb config get ai-agent
vb config get builtin-tools
vb config get connectors

# Save to file, edit, then re-apply
vb config get model-settings > settings.json
# edit settings.json...
vb config set --model-settings-file settings.json
```

#### Discover Valid Options

Before updating settings, use `vb config options` to discover valid values:

```bash
# Show all available options for current agent style
vb config options

# Show options for a specific setting (by name or label)
vb config options voice
vb config options "TTS Model"
vb config options language

# Show all settings in a category
vb config options stt
vb config options audio
vb config options realtime

# Output as JSON
vb config options --json
```

#### Update Individual Settings

```bash
# Change agent style (Chatty, Focused, Gemini, Ultravox, Listener)
vb config set --style Focused

# Enable/disable capabilities
vb config set --debug-mode true
vb config set --hold-enabled true
vb config set --hangup-enabled true
vb config set --background-enabled false

# Update name or greeting
vb config set --name "My Agent"
vb config set --greeting "Hello! How can I help you today?"

# Set session limits
vb config set --max-call-duration 15
vb config set --max-history-messages 50

# End calls when the caller stays silent. After 120 seconds the agent checks in,
# waits through a 15-second warning window, then ends the call if there is still
# no caller activity. Any caller speech or configured client action resets it.
vb config set --end-call-on-user-silence true --user-silence-timeout 120
vb config set --end-call-on-user-silence false  # Disable

# Continuous speech ("keep talking" mode) — agent continues on its own after a
# short silence instead of waiting for the user each turn (tutors, narrators,
# guided experiences). The user can still interrupt at any time by speaking.
vb config set --continuous-mode true
vb config set --continuous-mode true --continuous-mode-delay 3   # wait 3s before continuing
vb config set --continuous-mode false  # back to normal turn-based behavior

# Set MCP servers from file
vb config set --mcp-servers-file servers.json

# Set model settings from file
vb config set --model-settings-file model.json

# Choose the background AI model (used for complex queries / MCP + API tools)
vb config set --background-model claude-sonnet-4-6   # auto | claude-haiku-4-5 | claude-sonnet-4-6

# Choose the post-call processing model
vb config set --post-processing-model gemini-2.5-flash   # auto | gemini-3.5-flash | gemini-2.5-flash | gemini-2.5-flash-lite

# AI Agent integration
vb config set --ai-agent-enabled true --ai-agent-description "Customer support agent"
vb config set --ai-agent-url "https://agent.example.com/vocal-bridge/query"
vb config set --ai-agent-protocol a2a --ai-agent-a2a-method message/stream
vb config set --ai-agent-response-mode multiple --ai-agent-response-ordering sequence
vb config set --ai-agent-late-responses speak --ai-agent-duplicate-responses ignore
vb config set --ai-agent-max-responses-per-turn 10 --ai-agent-max-chars-per-turn 12000
vb config set --ai-agent-header Authorization="Bearer <token>"
vb config set --ai-agent-param tenant_id=acme-prod
vb config set --ai-agent-file ai_agent.json
vb config set --ai-agent-enabled false  # Disable
```

Caller-silence termination is off by default. Its timeout accepts 30–600 seconds and cannot be enabled together with continuous mode, because continuous-mode agents intentionally keep the conversation moving during caller silence.

Suggestion: when updating a greeting, consider identifying the agent and company and including any disclosure, consent, or recording language your laws, regulations, or policies require.

#### Partial Updates with --merge

Use `--merge` to deep-merge file contents with current settings instead of replacing them. Only the fields you specify are changed:

```bash
# Update only the model, keeping all other settings intact
echo '{"realtime": {"model": "gpt-realtime-1.5"}}' > update.json
vb config set --model-settings-file update.json --merge

# Full roundtrip workflow
vb config get model-settings > settings.json
# edit settings.json to change only what you need...
vb config set --model-settings-file settings.json
```

`--merge` works with dict-based configs: `--model-settings-file`, `--builtin-tools-file`, `--ai-agent-file`, `--connectors-file`. Array-based configs (`--mcp-servers-file`, `--client-actions-file`, `--api-tools-file`) are always replaced.

#### Available Styles

| Style | Description |
|-------|-------------|
| **Chatty** | Best for snappy, low-latency conversations. Ideal when most context fits in the system prompt. |
| **Focused** | Best for information-heavy conversations like interviews or surveys. More thorough responses. |
| **Gemini** | Powered by Google Gemini Live API. Great for natural, flowing conversations. |
| **Ultravox** | Powered by Ultravox Realtime API. Optimized for voice-first interactions. |
| **Listener** | Passive observer that never speaks. Joins the room, transcribes multi-speaker audio with diarization, and streams coaching suggestions to your app via the data channel. Use for live coaching during multi-party calls (investor relations, sales, interviews). Web-only — no phone number provisioned. See `vb docs` after creation for the action schema, and the [Listener Mode Settings](#listener-mode-settings) section below for tunable behavior. |

### Listener Mode Settings

Listener-mode agents (`--style Listener`) accept additional settings that control coaching behavior. All settings are optional with sensible defaults; specify any subset.

| Flag | Range / values | Default | What it does |
|------|----------------|---------|--------------|
| `--coachee-description TEXT` | up to 500 chars | empty | Names the person you're coaching. When set, the agent only generates a coaching card when *someone else* is speaking (so it doesn't try to coach this person on their own words), and tailors each card as guidance for them. Example: `"the CFO during earnings Q&A"`. |
| `--coaching-debounce SECS` | 0–60 | 12 | Minimum seconds between coaching cards. Higher = fewer, more spaced-out suggestions; lower = more frequent. Set to 0 for back-to-back cards. |
| `--coaching-context-turns N` | 0–50 | 10 | How many recent turns of conversation the agent considers per coaching card. Higher = better-grounded; lower = faster and cheaper. |
| `--coaching-job-timeout SECS` | 5–120 | 30 | Maximum seconds to wait for each coaching card before giving up. Lower for snappier feedback; higher if your prompt relies on external data lookups. |
| `--coaching-gate true\|false` | — | true | When `true`, coaching only appears when the conversation matches the trigger conditions in your prompt. When `false`, every spoken turn produces a coaching card. |
| `--speaker-map true\|false` | — | true | When `true`, the agent identifies who's speaking (names, roles) as the conversation unfolds and sends `speaker_map_update` events. When `false`, your app only sees raw labels like `S0`, `S1`. |
| `--speaker-map-interval SECS` | 5–300 | 20 | How often the agent re-checks for new speaker identities. Lower = identities resolve faster. |

Examples:

```bash
# Set the coaching recipient and slow the cadence to one card every 20s
vb config set --coachee-description "the candidate being interviewed" \
              --coaching-debounce 20

# Turn off gating — get a coaching card for every spoken turn
vb config set --coaching-gate false

# Skip speaker identity inference entirely (you'll see only raw S0/S1 labels)
vb config set --speaker-map false

# Inspect or export current values
vb config options                 # lists all settings for the current agent
vb config get model-settings      # JSON dump of current settings
```

Each flag is also available on `vb agent create` for one-shot setup at deploy time.

### Outbound Calling (Paid Plans)

Place outbound phone calls through your agent. Requires an eligible paid plan and outbound calling enabled on the agent.

#### Enable Outbound Calling

Enabling outbound calling requires accepting the Outbound Calling Terms of Use:

```bash
# Enable outbound with ToS acceptance
vb config set --outbound-enabled true --accept-outbound-tos

# Set an outbound greeting (spoken when callee answers)
vb config set --outbound-greeting "Hi, this is a call from Acme Corp."

# Wait for the recipient to speak first before the agent talks
vb config set --outbound-wait-for-user true
```

**Outbound Calling Terms of Use:**
- **Compliance**: You are solely responsible for complying with all applicable laws, including the Telephone Consumer Protection Act (TCPA), the Telemarketing Sales Rule (TSR), and all state and local telemarketing regulations.
- **Consent**: You certify that you have obtained prior express consent from all individuals your agent will call, as required by applicable law.
- **Prohibited Uses**: You will not use outbound calling for unsolicited telemarketing, spam, robocalling, fraud, harassment, calls to emergency services, or any illegal or illicit purpose.
- **Indemnification**: Vocal Bridge bears no liability for claims, fines, or damages arising from your use of outbound calling. You agree to indemnify and hold Vocal Bridge harmless from any such claims.
- **Termination**: Vocal Bridge may monitor outbound calling activity and suspend or terminate access at any time for violations, without notice.

#### Place a Call

```bash
# Place an outbound call
vb call +14155551234

# With callee name
vb call +14155551234 --name "John Smith"

# Output as JSON
vb call +14155551234 --json
```

Phone numbers must be in E.164 format (e.g., `+14155551234`). Rate limits: 50 calls/day per agent, 200 calls/day per user.

### Background & MCP Testing

Test your agent's background AI — including any MCP servers, HTTP API tools, and connectors it has configured — by sending a query directly, without placing a call.

```bash
# Run a background query and print the result
vb mcp test "What's on my calendar tomorrow?"

# Adjust the timeout (seconds, 5-120) and get JSON
vb mcp test "Look up order 12345" --timeout 60 --json
```

### AI Agent Integration Testing

Preview delegated AI Agent responses from the CLI. Simulation mode uses Haiku as the AI Agent stand-in and follows your simulation prompt; endpoint mode calls your saved hosted endpoint. To hear the full voice handoff, use the dashboard Test tab and enable the Haiku simulated AI Agent during a browser voice call.

```bash
vb ai-agent test "What is the status of order 12345?" \
  --simulation-prompt "Act like our Acme support agent with access to order history."

vb ai-agent test --mode endpoint "What is the status of order 12345?"
```

### Post-Call Processing

Agents can run automated processing after each call ends (summaries, CRM updates, etc.). Configure the post-call prompt, an optional MCP server, and the model:

```bash
# Set the post-call processing prompt
vb config set --post-processing-prompt "Summarize the call and extract action items"

# Point post-processing at an MCP server (for post-call tool actions)
vb config set --post-processing-mcp-url "https://actions.zapier.com/mcp/..."

# Choose the post-call model
vb config set --post-processing-model gemini-2.5-flash
```

Test post-call processing against a sample transcript without placing a real call:

```bash
# Provide the transcript inline, from a file, or on stdin
vb post-processing test "Agent: Hello. User: I'd like to reschedule to Tuesday."
vb post-processing test --file transcript.txt
cat transcript.txt | vb post-processing test
```

> **Warning:** `post-processing test` runs your agent's live post-call tools — MCP, HTTP API tool, and connector actions can make real changes (e.g. creating records). Use a disposable/test transcript accordingly.

### Connectors

Native connectors let your agent use third-party services (e.g. Google Calendar) via OAuth. List available connectors and their status, and get a link to connect one:

```bash
# List connectors with connected / enabled-on-agent status
vb connectors list
vb connectors list --json

# Get a link to connect a connector (OAuth runs in your browser and auto-enables it on the agent)
vb connectors connect google_calendar
```

Connecting a connector in the browser auto-enables it on the selected agent. You can also export and adjust per-agent connector settings as JSON:

```bash
vb config get connectors > connectors.json
# edit connectors.json...
vb config set --connectors-file connectors.json --merge
```

### Debug Streaming

Stream real-time debug events from your agent during calls. First enable debug mode in your agent settings.

```bash
# Stream debug events via WebSocket (real-time)
vb debug

# Use HTTP polling instead (fallback)
vb debug --poll

# Adjust polling interval (only with --poll)
vb debug --poll -i 1.0
```

Debug events include:
- User transcriptions (what the caller says)
- Agent responses (what your agent says)
- Tool calls and results
- Background query results
- Session start/end events
- Errors

### Evaluate a Call (Paid Plans)

Run a multimodal evaluation of a recorded call session. The full audio recording, the agent's full configuration (system prompt, greeting, capabilities, configured client actions), the structured transcript (with the agent's tool calls), the client action events log, and the raw session report are all sent to a multimodal LLM for a qualitative QA score and concrete prompt-improvement suggestions.

```bash
# Basic eval against the agent's own configuration
vb eval <session_id>

# With an explicit objective (what the agent should accomplish)
vb eval <session_id> --objective "Schedule an interview for next Tuesday"

# With both an objective and an expected scenario
vb eval <session_id> \
  --objective "Confirm the candidate's availability" \
  --scenario "User is busy and tries to reschedule twice"

# Long objective/scenario from files
vb eval <session_id> --objective-file objective.txt --scenario-file scenario.txt

# Raw JSON output (pipe-friendly)
vb eval <session_id> --json
```

The session must already have a recording (check with `vb logs <session_id>`).

**Sample output:**

```
Call Evaluation
----------------------------------------
  Session:      550e8400...
  Score:        7/10
  Verdict:      partial

Summary:
  The agent answered the user's questions accurately but missed
  the scheduling objective when the user asked to reschedule.

What worked:
  + Greeted the caller naturally per the configured greeting
  + Recovered cleanly from a mid-sentence interruption

What didn't:
  - Did not call schedule_meeting tool when the user gave a date
  - Tone became impatient on the second reschedule attempt

Suggested prompt improvements:
  Add an explicit instruction to call schedule_meeting whenever
  the user proposes any time, including reschedules.
```

**Restrictions:**

- **Paid plan required** — `403` otherwise
- **100 evals/day per user** across all your agents — `429` when exceeded
- **18 MB inline audio cap** per recording — extremely long calls will be rejected
- API keys, MCP server URLs, and other secrets in your agent's configuration are **not** sent to the evaluator

The specific evaluator model is fixed by the platform.

### Developer Docs

Get integration documentation for building apps with your voice agent:

```bash
# Print integration docs (markdown)
vb docs

# Output as JSON
vb docs --json
```

Returns comprehensive documentation including:
- Agent configuration and capabilities
- MCP server, client actions, API tools, AI Agent integration
- API integration guide with token generation
- Implementation examples (JavaScript, React, Flutter)
- CLI and Claude Code plugin reference

Works with or without an agent selected. With an agent, docs include agent-specific configuration and tools.

## Configuration Files

### CLI Configuration

CLI settings are stored in `~/.vocal-bridge/config.json`:

```json
{
  "api_key": "vb_...",
  "api_url": "https://vocalbridgeai.com"
}
```

The config file has restricted permissions (600) to protect your API key.

### MCP Servers File

When using `--mcp-servers-file`, provide a JSON array:

```json
[
  {
    "url": "https://actions.zapier.com/mcp/...",
    "name": "Zapier",
    "tools": []
  }
]
```

### Model Settings File

When using `--model-settings-file`, provide a JSON object organized by category.

For Focused style:

```json
{
  "stt": {
    "model": "assemblyai:universal-streaming",
    "language": "en",
    "eot_threshold": 0.5
  },
  "tts": {
    "model": "eleven_multilingual_v2",
    "voice_id": "cgSgspJ2msm6clMCkdW9"
  },
  "session": {
    "max_call_duration_minutes": 30,
    "max_history_messages": 100,
    "end_call_on_user_silence": "true",
    "user_silence_timeout_seconds": 120
  }
}
```

`end_call_on_user_silence` is off by default. When enabled, the timeout must be 30–600 seconds. At the timeout the agent checks in and gives the caller 15 more seconds to respond before ending the call. Caller speech and configured client actions reset the inactivity timer. Do not enable it together with `session.continuous_mode`.

**Language options:**
- Preset: `en`, `multi` (auto-detect), `es`, `fr`, `de`, `pt`, `it`, `nl`, `ja`, `ko`, `zh`, `hi`, `ru`, `ar`, `pl`, `tr`, `vi`, `th`, `id`, `sv`, `da`, `fi`, `no`, `uk`, `cs`, `el`, `he`, `ro`, `hu`, `ms`, `bg`, `sk`, `hr`, `ca`, `ta`
- Custom: Use `language_source: "custom"` with `custom_language: "<BCP-47 code>"` (e.g., `en-US`, `pt-BR`, `zh-TW`)

For custom language code:

```json
{
  "stt": {
    "model": "deepgram:nova-3",
    "language_source": "custom",
    "custom_language": "pt-BR",
    "eot_threshold": 0.5
  }
}
```

### AI Agent Config File

When using `--ai-agent-file`, provide a JSON object:

```json
{
  "enabled": true,
  "description": "Customer support agent for Acme Corp",
  "verbatim": false,
  "endpoint": {
    "url": "https://agent.example.com/vocal-bridge/query",
    "protocol": "a2a",
    "a2a": {
      "method": "message/stream"
    },
    "headers": {
      "Authorization": "Bearer <token>"
    },
    "params": {
      "tenant_id": "acme-prod"
    }
  },
  "response_delivery": {
    "mode": "multiple",
    "ordering": "arrival",
    "late_response_behavior": "store",
    "duplicate_response_behavior": "ignore",
    "max_responses_per_turn": 10,
    "max_chars_per_turn": 12000
  }
}
```

**Fields:**
- `enabled` (boolean): Whether AI Agent integration is active
- `description` (string): What the developer's agent does (max 2000 chars). Helps the voice agent know when to delegate questions.
- `verbatim` (boolean): If true, the voice agent preserves responses exactly when direct TTS is configured; if false (default), it adapts for natural voice delivery. Chatty with OpenAI Native Voice uses strict generated-reply instructions and is best effort. For guaranteed verbatim delivery, set `model_settings.realtime.use_external_tts` to `"true"` and configure an ElevenLabs voice in `model_settings.tts`.
- `endpoint.url` (string): Optional HTTPS endpoint URL. When set, Vocal Bridge sends server-side `query_agent` requests there instead of requiring client-side delegation.
- `endpoint.protocol` (string): `http` (default) for the Vocal Bridge JSON contract, or `a2a` for Agent2Agent JSON-RPC.
- `endpoint.a2a.method` (string): `message/send` (default) or `message/stream`. Streaming can deliver progress/status chunks before the final answer in verbatim mode.
- `endpoint.headers` (object): Optional static headers sent with every endpoint request. Use this for auth or tenant routing. Header values are treated as secrets and hidden in CLI output.
- `endpoint.params` (object): Optional query params appended to every endpoint request. Values are treated as secrets and hidden after save.
- `response_delivery.mode` (string): `single` or `multiple` responses per `turn_id`. Defaults to `single` for HTTP endpoints, data-channel integrations, protocol-only configs without an endpoint URL, and non-streaming A2A `message/send` endpoints. Defaults to `multiple` only for configured A2A `message/stream` endpoints with a URL. Choose `single` for ordinary one-answer request/response agents and most non-A2A integrations. Choose `multiple` for A2A streaming, progress-plus-final flows, or any agent that intentionally sends more than one response for the same `turn_id`.
- `response_delivery.ordering` (string): `arrival` (default) speaks accepted responses as they arrive; `sequence` requires `agent_response.payload.sequence` starting at 1 and rejects out-of-order responses.
- `response_delivery.late_response_behavior` (string): `store` (default), `speak`, or `reject` for responses that arrive after the timeout grace period.
- `response_delivery.duplicate_response_behavior` (string): `ignore` (default) or `speak` for repeated response text.
- `response_delivery.max_responses_per_turn` (integer): hard cap for accepted responses on one `turn_id` (default 10, max 100).
- `response_delivery.max_chars_per_turn` (integer): hard cap for total spoken characters accepted on one `turn_id` (default 12000, max 50000).
- `endpoint_url` (string): Legacy alias for `endpoint.url`; still accepted for backwards compatibility.

Inline `--ai-agent-header` and `--ai-agent-param` flags merge into the existing map. To remove entries, provide a full replacement with `--ai-agent-file`.

## Examples

### Development Workflow

```bash
# 1. Check current agent setup
vb agent
vb prompt show

# 2. Make some test calls to your agent
# ...

# 3. Review the call logs
vb logs
vb logs show <session_id>  # detailed view with transcript

# 4. Download a recording for deeper analysis
vb logs download <session_id>

# 5. Update the prompt based on what you learned
vb prompt edit

# 6. Check statistics
vb stats
```

### CI/CD Integration

```bash
# Set API key via environment variable
export VOCAL_BRIDGE_API_KEY=$VOCAL_BRIDGE_API_KEY

# Update prompt from a file in your repo
vb prompt set --file prompts/production.txt

# Verify the update
vb prompt show
```

### Analyzing Call Logs

```bash
# Get all failed calls
vb logs --status failed --json | jq '.sessions[]'

# Get transcript of a specific call
vb logs <session_id> --json | jq '.transcript_text'
```

## Troubleshooting

### "No API key found"

Run `vb auth login` or set the `VOCAL_BRIDGE_API_KEY` environment variable.

### "Invalid API key"

- Check that your API key starts with `vb_`
- Verify the key hasn't been revoked in the dashboard
- Generate a new key if needed

### "Agent not found"

The API key may have been created for an agent that was deleted. Create a new key from an active agent.

### Connection errors

Check your network connection and that the API URL is correct.
