Skip to content
Docs menu

Venom Line, an AI voice agent on your number

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.

View .md

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

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), 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

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

# venom.yaml
voice:
  agents:
    line: ./agents/line
# 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.

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.

  • 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.