---
title: Venom Line, an AI voice agent on your number
description: "Let an AI agent answer live calls on your org's number: set up the media bridge on your own orchestrator, pick the agent's knowledge, tools and voice, run local speech models, and see each call's transcript, ticket and latency afterwards."
section: comms
order: 60
audience: [operator, user]
sources: [services/go-orchestrator/internal/commsmedia, packages/voice/src/transports/bridge.ts, packages/voice/src/agent/line-tools.ts, services/nodejs-cloud/lib/comms/line.ts, services/nodejs-cloud/lib/comms/line-pure.ts, services/nodejs-cloud/app/api/integrations/comms/line, scripts/line-latency.mjs]
features: [orchestrator.api-comms]
---

Venom Line answers calls to one of your Comms numbers with an AI agent. The caller talks, the agent listens,
looks things up, answers, and can hand the call to a person. When the call ends, Venom files a Support ticket with
the summary and transcript, adds the call to the caller's People timeline (and to their open deal in Funnel), and
keeps a Comms call record with the cost and the measured latencies.

## How a call flows

```text
caller ──phone──▶ Sinch (or Twilio) ──WebSocket audio──▶ your orchestrator  GET /v1/comms/media
                                                              │  ticket check, codec, no buffering
                                                              ▼
                                         venom serve: the voice agent (speech to text, your gear,
                                         text to speech, barge-in) ── tools ──▶ Venom Cloud
```

1. A call reaches a number that has Venom Line on. Venom Cloud answers it with the provider's stream action,
   pointing at your orchestrator's media endpoint and carrying a ticket: signed with your line's media secret,
   bound to that call and your org, valid for two minutes, usable once.
2. Your orchestrator checks the ticket, asks the cloud for the line's settings, and starts the call on
   `venom serve`, where the agent runs. Audio goes both ways frame by frame.
3. The agent speaks your opening line (the consent notice, then your greeting), then answers the caller. Its
   tools run in the cloud with a token only the orchestrator holds.
4. When the call ends, the orchestrator posts the transcript and latencies to the cloud, which writes the
   ticket, the timeline entries and the call record.

The agent runs in `venom serve` and not in the cloud: a call holds a socket for minutes and needs audio every
20 ms, and `venom serve` already has the voice loop (turn detection, early replies, barge-in) built on the
harness. On the same host as the orchestrator, the hop between them costs microseconds.

## Set it up

You need a Comms provider with a voice number (see [Comms providers](/docs/comms/providers.md)), an orchestrator the
provider can reach over `wss://`, and `venom serve` next to it with a voice agent.

### 1. Turn the line on in the cloud

In **Settings, Comms, Venom Line**:

| Field | What |
|---|---|
| Number | the voice number callers ring |
| Media endpoint | your orchestrator's public URL, `wss://voice.example.com/v1/comms/media` |
| Answer calls | the switch: off, the number keeps saying it takes no calls |
| Greeting, persona and instructions | what the agent says first after the notice, and how it behaves |
| Knowledge | the Notes vault the agent answers from |
| Tools | which tools the agent may use (below) |
| Handover number | where "let me get you a person" goes |
| Voice | the text-to-speech voice |
| Consent | announce (default) or none, and the notice's text |
| Longest call, cost cap | the call ends at either |

The first save shows the **media secret** once. **Reveal secret** shows it again (audited), and **Rotate secret**
issues a new one and voids tickets that have not been used yet.

### 2. Run the bridge on your orchestrator

```bash
export VENOM_COMMS_MEDIA_SECRET=vmls_…          # from step 1
export VENOM_COMMS_CLOUD_URL=https://cloud.usevenom.dev
export VENOM_COMMS_SERVE_URL=http://127.0.0.1:8790
export VENOM_SERVER_TOKEN=…                      # the same token venom serve uses
```

| Variable | Default | What |
|---|---|---|
| `VENOM_COMMS_MEDIA_SECRET` | unset (bridge off, 404) | checks the cloud's tickets |
| `VENOM_COMMS_CLOUD_URL` | `VENOM_CLOUD_URL` | the cloud, for settings, tools and reports |
| `VENOM_COMMS_SERVE_URL` | `http://127.0.0.1:8790` | where the agent runs |
| `VENOM_COMMS_AGENT` | `line` | the voice agent that answers |
| `VENOM_COMMS_MAX_CALLS` | 16 | calls at once; more are refused |

Put the orchestrator behind a TLS reverse proxy or a tunnel you run, forwarding `/v1/comms/media` with WebSocket
upgrades. The endpoint takes no API key (providers have none); the ticket is the only credential, and without
`VENOM_COMMS_MEDIA_SECRET` the endpoint does not exist.

### 3. Give venom serve a line agent

```yaml
# venom.yaml
voice:
  agents:
    line: ./agents/line
```

```yaml
# agents/line/agent.yaml
model: venom-voice
language: en-US
stt: { model: venom-stt-stream }
tts: { model: venom-tts, voice: alloy }
```

Leave `instructions.md` empty to use Venom Line's built-in instructions: the persona and instructions from the
cloud reach the agent in each call's context, so they change without a restart and the system prompt stays the
same across calls. Voice agents are described in the [voice section](/docs/voice.md).

### 4. Test it

**Test call** in the Venom Line card rings your own verified number (Settings, Comms, your phone) and connects it
to the agent. With the fake provider, **Simulate, a call comes in** shows the answer the provider would get.

## Tools

| Tool | What it does |
|---|---|
| `lookup_caller` | finds the caller in People by number, with their company and open Funnel deals |
| `ask_knowledge` | answers from the line's Notes vault with the hybrid Ask of Notes |
| `create_ticket` | opens a Support ticket; the transcript is added when the call ends |
| `book_follow_up` | a note on the caller's open deal, and a Tasks issue when Tasks is on |
| `transfer` | moves the call to the handover number through the provider |

The agent only sees people and deals visible to the whole org. Ticket and booking tools finish even when the
caller interrupts; lookups stop.

## Speech models

The agent uses the orchestrator's routes for speech, so you choose the models there:

- **Speech to text** streams through `/v1/realtime?intent=transcription` (OpenAI, FunASR, WhisperLive,
  ElevenLabs, DashScope). For a fully local line, run WhisperLive or FunASR and route `venom-stt-stream` to it.
- **Text to speech** goes through `/v1/audio/speech` and the voice provider registry (ElevenLabs and others, or a
  local Kokoro, CosyVoice or Fish Speech server). Replies are split into sentences, so the first sentence plays
  while the rest is written.
- **The reply** uses the gear behind `venom-voice`. A small local model on a GPU keeps the first turn fast; on
  a CPU the first turn waits for the prompt to load.

The caller can talk over the agent: playback stops as soon as the caller's speech is detected, and the agent
remembers what the caller actually heard.

## Consent, limits and cost

- With consent set to announce (the default), the notice is spoken before anything else on every call. Recording
  and transcription laws differ by place; check yours.
- The call ends at the longest call length and when the agent's model spend reaches the cost cap.
- Your org's prompt filters and guardrails apply to every model request the agent makes, because those go through
  the orchestrator.
- The provider's per-minute cost comes from its end-of-call report. The agent's model cost is recorded on the
  call and in Admin, Usage.

## Latency

The target is under 800 ms at the median and 1.2 s at p95 from the end of the caller's speech to the agent's first
audio, with barge-in stopping playback within 200 ms. `make line-latency` drives a whole call through the real
bridge and voice loop with a fake provider and prints where the time goes:

| Setup | End of speech to first audio, p50 / p95 | Barge-in p50 / p95 | Bridge per frame |
|---|---|---|---|
| Fake speech and model at typical latencies, Sinch wire | 756 / 763 ms | 81 / 84 ms | 13 µs in, 9 µs out |
| The same over Twilio's wire (µ-law) | 779 / 787 ms | 81 / 86 ms | 47 µs in, 15 µs out |
| Real local LLM (qwen2.5 0.5B, CPU), fake speech | 790 ms / 3.6 s (cold first turn) | 83 / 85 ms | 25 µs in, 18 µs out |

Each call's numbers are on its Comms call record afterwards.

## Not yet

- **Hosted media edges.** Orgs that don't run an orchestrator with a public ingress can't use Venom Line yet. The
  planned path is a regional edge the cloud points the provider at, which relays the audio to the org's daemon
  over the connection the daemon already dials out.
- **Self-hosted PBX calls** (the gateway provider, Asterisk) still refuse line calls.
- One line per org.
