Run a LiveKit Agent on ClutchCall Transport

You have a working LiveKit agent. You want to put it on the phone, or on ClutchCall’s QUIC transport. You do not want to rewrite it, and you do not want to operate a LiveKit server. This recipe builds that end to end:

Install the transport plugin into your existing agent process.
Run the process as a worker that dials out to the edge.
Point a ClutchCall agent at the worker.
Route an inbound number.
Place a real call.

Your agent code does not change. Your AgentSession, your STT/LLM/TTS plugins, your provider keys, and your tool calls all stay verbatim. Only the bytes on the wire are ours.

This is the plugin path. If you must keep your LiveKit server running (other participants join the room), use the front-proxy sidecar instead: Bridge a LiveKit Agent. The integration reference compares both paths.

What you’ll build

 PSTN / SIP trunk ─▶ ┌──────────────────┐                   ┌────────────────────────────┐
                     │  voice gateway   │  ONE QUIC/WT      │ your livekit-agents worker  │
 browser (QUIC/MoQT) │  (owns the       │◀── session ──────▶│  + transport plugin         │
 on :443 ──────────▶ │  caller leg)     │  (agent dials out)│  (your STT/LLM/TTS keys)    │
                     └──────────────────┘                   └────────────────────────────┘
     caller audio ──▶ 8 kHz PCM bus ──▶ QUIC datagrams ──▶ session.input.audio
     agent audio  ◀── back onto the call ◀── QUIC datagrams ◀── session.output.audio

The gateway owns the hard edge: a SIP trunk or a browser leg over QUIC on the single :443 plane. It decodes that edge to the runtime’s 8 kHz PCM bus. Your worker holds one outbound QUIC/WebTransport session to the edge. The session carries three lanes:

presence (liveness),
audio over datagrams, and
per-call control (job assign, flush, barge-in, playback finished) over a stream.

Why the agent is the client. Your worker dials out and opens no inbound ports. It works behind NAT, in a private subnet, or in a container with no public address. Nothing about your network has to change.

Prerequisites

required

A working livekit-agents (Python) or @livekit/agents (TypeScript) agent with an entrypoint, plus the provider keys it already uses.

required

A media app key + secret for your tenant, in CLUTCHCALL_MEDIA_KEY and CLUTCHCALL_MEDIA_SECRET. These are distinct from your API credentials. Issue them from the console (agent.clutchcall.dev) or the control-plane API.

required

See SIP Trunking / Number Provisioning.

required

The worker needs QUIC egress to engine.clutchcall.dev. The WebSocket fallback covers presence only. Media over TCP is a degraded last resort.

Build the mini-app

Start from your unmodified agent

Any LiveKit agent works. It needs no ClutchCall awareness. This is the file that you already have, untouched:

Python
TypeScript

my_agent.py

from livekit.agents import AgentSession, Agent, JobContext
from livekit.plugins import openai, deepgram, elevenlabs, silero

async def entrypoint(ctx: JobContext):
    session = AgentSession(
        vad=silero.VAD.load(),
        stt=deepgram.STT(),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=elevenlabs.TTS(),
    )
    await session.start(
        room=ctx.room,
        agent=Agent(instructions="You are a helpful phone assistant."),
    )

my-agent.ts

import { voice } from "@livekit/agents";
import * as openai from "@livekit/agents-plugin-openai";

export async function entrypoint(ctx: any): Promise<void> {
  const session = new voice.AgentSession({
    llm: new openai.realtime.RealtimeModel({ voice: "alloy" }),
  });

  await session.start({
    agent: new voice.Agent({
      instructions: "You are a helpful phone assistant. Keep replies short.",
    }),
    room: ctx.room,
  });

  session.generateReply({ instructions: "Greet the caller and ask how you can help." });
}

Your entrypoint still calls session.start(room=ctx.room, ...). Leave it. The plugin wraps AgentSession.start, binds our audio IO, and drops the room argument. The SDK skips its own RoomIO whenever custom audio IO is set, so the code never touches the room.

Install the transport plugin

Python
TypeScript

pip install "livekit-plugins-clutchcall[quic]"

The quic extra pulls in aioquic. Without it, the package imports but cannot connect.

npm i @clutchcall/livekit-transport @fails-components/webtransport

@livekit/agents and @livekit/rtc-node stay yours. They are optional peers, so the plugin never pins your SDK version.

Run it as a worker

Replace your worker runner (cli.run_app(...)) with ours. This is the only new file in your repo.

Python
TypeScript

worker.py

import asyncio, os
from livekit.plugins import clutchcall

from my_agent import entrypoint   # unchanged

asyncio.run(clutchcall.run_agent_worker(
    clutchcall.WebTransportConfig(
        engine_url="https://engine.clutchcall.dev",
        app_key=os.environ["CLUTCHCALL_MEDIA_KEY"],
        app_secret=os.environ["CLUTCHCALL_MEDIA_SECRET"],
        agent_name="salesbot",
        sample_rate=8000,
    ),
    host="engine.clutchcall.dev",
    entrypoint=entrypoint,
))

CLUTCHCALL_MEDIA_KEY=ck_... CLUTCHCALL_MEDIA_SECRET=... \
  OPENAI_API_KEY=sk-... python worker.py

worker.ts

import { runAgentWorker, defaultConfig } from "@clutchcall/livekit-transport";
import { entrypoint } from "./my-agent.js";   // unchanged

const host = "engine.clutchcall.dev";

await runAgentWorker(
  defaultConfig({
    engineUrl:  `https://${host}`,
    appKey:     process.env.CLUTCHCALL_MEDIA_KEY!,
    appSecret:  process.env.CLUTCHCALL_MEDIA_SECRET!,
    agentName:  "salesbot",
    sampleRate: 8000,
  }),
  { host, port: 443, entrypoint },
);

CLUTCHCALL_MEDIA_KEY=ck_... CLUTCHCALL_MEDIA_SECRET=... \
  OPENAI_API_KEY=sk-... node --import tsx worker.ts

The worker authenticates, registers under agent_name, and waits. You should see it report ready and await calls. It stays connected with a keepalive. If the link drops, it reconnects with exponential backoff. An engine restart therefore does not strand it on a dead socket.

sample_rate must match the call leg. The pcm16 codec is a raw passthrough. A wideband TTS voice (24 kHz / 48 kHz) sent onto an 8 kHz telephony leg plays at the wrong speed. The plugin declares the wire rate on the session output, and the SDK resamples to it. But the SDK resamples only to the rate that you set here. Use 8000 for PSTN.

Point a ClutchCall agent at the worker

The engine models a remote agent as a VENDOR_BRIDGE node whose vendor_provider is clutchcall. The decision lives in the agent config, so your dialplan and trunk routing stay untouched.

agent-config.json

{
  "entry_node": "bridge",
  "pipeline": {
    "bridge": {
      "node_type": "VENDOR_BRIDGE",
      "vendor_provider": "clutchcall",
      "vendor_room": "salesbot"
    }
  }
}

Field	Meaning
`vendor_provider`	`clutchcall` — your agent runs on our transport
`vendor_room`	The `agent_name` your worker registered under

With this config, the runtime runs no turn detection and no model in the engine. It hands the caller’s audio to your worker. It streams your agent’s audio back onto the call. The full field reference is in Runtime Configuration.

Route a number to the agent

Attach an inbound DID or SIP trunk to this agent. Use the same routing that you would use for any native ClutchCall agent. See SIP Trunking and Number Provisioning.

Connect a caller

Dial the number. To drive it programmatically, place an outbound call from the SDK. On answer, the engine dispatches to your worker in the same way as for an inbound call:

TypeScript
Python

import { Voice } from "@clutchcall/sdk/voice";

const v = new Voice({
  baseUrl: "https://engine.clutchcall.dev",
  apiKey:  process.env.CLUTCHCALL_CREDENTIALS!,
  orgId:   "org_abc",
});

// The agent's VENDOR_BRIDGE node dispatches this call to your worker.
const call = await v.calls.originate({
  to:      "+15551234567",
  from:    "+15558675309",
  trunkId: "trunk_main",
  agent:   "livekit-on-quic",   // the VENDOR_BRIDGE agent above
  ringTimeoutSec: 25,
});

console.log("dialing", call.sid, "→ worker salesbot");

import os
from clutchcall.voice import Voice

v = Voice(
    base_url="https://engine.clutchcall.dev",
    api_key=os.environ["CLUTCHCALL_CREDENTIALS"],
    org_id="org_abc",
)

# The agent's VENDOR_BRIDGE node dispatches this call to your worker.
call = v.calls.originate(
    to="+15551234567",
    from_="+15558675309",
    trunk_id="trunk_main",
    agent="livekit-on-quic",   # the VENDOR_BRIDGE agent above
    ring_timeout_sec=25,
)

print("dialing", call.sid, "→ worker salesbot")

What your agent sees

Your entrypoint gets a JobContext whose ctx.room is a veneer, not a LiveKit room. It carries the fields that agents actually read. The fields mirror how LiveKit surfaces SIP participant attributes. An agent that reads the caller’s number therefore keeps working unchanged:

Field	Value
`ctx.room.name`	The dispatched agent/call name. It is the identity, so “get agent by room” still works
`ctx.room.attributes["sip.phoneNumber"]`	Caller number (ANI)
`ctx.room.attributes["sip.trunkPhoneNumber"]`	Called number (DNIS)
`ctx.room.attributes["sip.trunkID"]`	The trunk the call arrived on

Room APIs beyond these fields are not backed. This includes track publication, participant enumeration, and room data messages. There is no room behind the veneer.

Verify it worked

The gateway gives this agent everything that it gives a native agent. The caller edge is identical:

Call events & CDR — the call appears in reports with an initiated → established → cleared lifecycle and a Q.850 clear cause.
Media quality — per-call MOS / jitter / loss scoring lands on the CDR.
Recording — the engine captures both legs if recording is enabled for the trunk.
Transcripts — the plugin forwards finalized turns over the control stream. Your remote agent’s history lands in the same store as a native agent’s history.

See Observability for where these appear.

Troubleshooting

The worker registers, but calls find no agent

Presence is tied to a live connection. If the worker’s session drops and the reconnect did not land yet, dispatch finds nothing. Check that the worker logs a ready line after the most recent reconnect. Check that vendor_room in the agent config exactly matches agent_name in the worker config.

The agent speaks, but the caller hears nothing or a click

The cause is almost always a sample-rate mismatch. Check sample_rate / sampleRate against the leg (8000 for PSTN). The plugin paces and re-chunks outbound audio into steady 20 ms frames, so it handles bursty TTS. It does not handle a wrong rate.

The worker connects but no audio flows

Media travels on QUIC datagrams. Check that outbound UDP/443 to engine.clutchcall.dev is open. A network that permits TCP/443 but drops UDP will complete presence and stall media.

Audio bandwidth is higher than expected

The wire codec is raw pcm16 today. Opus is not yet wired. Budget for uncompressed audio between your worker and the edge.

LiveKit integration reference

All three paths side by side: plugin, front-proxy, browser shim.

Bridge a LiveKit Agent

The front-proxy sidecar. Use it when your LiveKit room must keep running.

From Self-Hosted LiveKit

The full migration plan: trunks, tokens, rollout.

Runtime Configuration

Every pipeline node field, including VENDOR_BRIDGE.

Overview

Quickstart

Core Concepts

Build Guides

Agent Runtime

Transport to Web & Apps

Transport to Telephony

CTI (CSTA)

High Availability

Comparison & Benchmarks

Migration

Integrations

Observability

SDK Reference

API Reference

Troubleshooting

Cookbooks

Recipes

Run a LiveKit Agent on ClutchCall Transport

What you’ll build

Prerequisites

Build the mini-app

What your agent sees

Verify it worked

Troubleshooting

LiveKit integration reference

Bridge a LiveKit Agent

From Self-Hosted LiveKit

Runtime Configuration

​What you’ll build

​Prerequisites

​Build the mini-app

​What your agent sees

​Verify it worked

​Troubleshooting

​Related

LiveKit integration reference

Bridge a LiveKit Agent

From Self-Hosted LiveKit

Runtime Configuration

What you’ll build

Prerequisites

Build the mini-app

What your agent sees

Verify it worked

Troubleshooting

Related