Run Your Agent

zrt.serve() runs your agent as a worker: it registers the agent under its agent_id with the Zero Runtime and serves a session to each caller. Fire zrt.invoke() from on_ready to launch a session and print a link you can open.

import zrt
from zrt import Agent, Pipeline
from zrt.plugins import DeepgramSTT, GoogleLLM, CartesiaTTS, TurnDetector
from zrt.inference import AICousticsDenoise

AGENT_ID = "assistant"

pipeline = Pipeline(
    stt=DeepgramSTT(),
    llm=GoogleLLM(),
    tts=CartesiaTTS(),
    turn_detector=TurnDetector(model="echo-large"),
    denoise=AICousticsDenoise(model_id="quail-vf-2.2-l-16khz"),
)


class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            agent_id=AGENT_ID,
            instructions="You are a helpful assistant.",
            pipeline=pipeline,
        )


if __name__ == "__main__":
    # Pass the class itself (not an instance): serve() builds a fresh Assistant +
    # pipeline per call, which is required for correct per-call state under concurrent calls.
    zrt.serve(Assistant, on_ready=lambda: zrt.invoke(AGENT_ID, room=zrt.Room(playground=True)))

python main.py

serve() blocks and keeps the worker running, accepting a fresh session for every caller until you stop it. Scale out by running more serve() workers, each registering the same agent_id.

Pass the Agent subclass itself (Assistant, not Assistant()): serve(Assistant). serve() accepts the class only, never a pre-built instance, and builds a fresh agent and pipeline per call, which is required for correct per-call state and pipeline hooks under concurrent sessions.

Start a session

serve() keeps your agent registered and idle. You then start a session to connect a caller to it. There are two ways, depending on where you’re calling from:

Method	Best for	Called from
SDK: `zrt.invoke()`	Local development, scripts, CLIs, `on_ready`	Your agent’s codebase
Dispatch API: HTTP `POST`	Production, remote triggers, Agent Cloud agents	Any language or service

Both do the same thing: hand a session to a running worker registered under your agent_id. Use whichever fits where you start the session.

Invoke with the SDK

During development, call zrt.invoke() from a script, a CLI, a web handler, or your agent’s on_ready hook. It returns the session details (session_id, room_id, worker_id), plus a playground_url when the room has playground=True (the default). Open it to talk to your agent right away.

import zrt

# Invoke a playground session and print a link to talk to the agent.
result = zrt.invoke("assistant", room=zrt.Room(playground=True))
print(result["playground_url"])

Place a phone call

Pass Sip(...) to start the session on an outbound (or inbound) call instead of a playground room:

zrt.invoke(
    "assistant",
    sip=zrt.Sip(call_to="+1XXXXXXXXXX", call_from="+1XXXXXXXXXX"),
)

Dispatch with the API

In production, start a session over HTTP with the Dispatch API. It needs no SDK, works from any language or service, and supports both Agent Cloud and self-hosted agents, for both playground and SIP-connected sessions.

meetingId and room_id (the SDK’s Room(room_id=...)) are the same identifier. The Dispatch API just calls it meetingId. Pass a room ID you already have, or omit it to auto-create one.

Endpoint

POST https://api.videosdk.live/v2/agent/dispatch

Request body parameters

Parameter	Type	Required	Description
`meetingId`	string	Yes	The room ID to dispatch the agent into (same value as the SDK’s `room_id`).
`agentId`	string	Yes	The ID of the agent to dispatch.
`metadata`	object	No	Optional metadata to pass to the agent, such as variables.
`versionTag`	string	No	The specific commit version of an Agent Cloud agent to dispatch. If omitted, the latest deployed version is used. Not for self-hosted agents.

Example request

curl -X POST "https://api.videosdk.live/v2/agent/dispatch" \
  -H "Authorization: YOUR_ZRT_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "meetingId": "xxxx-xxxx-xxxx",
    "agentId": "ag_xxxxxx",
    "metadata": {
        "variables":[
            {
                "name":"fname",
                "value":"john"
            }
        ]
    },
    "versionTag":"cm_xxxxxx"
  }'

Responses

On success, the request returns a confirmation that the dispatch has been initiated:

{
    "message": "Agent dispatch requested successfully.",
    "data": {
        "success": true,
        "status": "assigned",
        "roomId": "xxxx-xxxx-xxxx",
        "agentId": "ag_xxxxxx"
    }
}

On error, you receive one of the following:

No Workers Available
No Workers Registered
Agent Not Deployed

No servers and agents are configured to handle the request.

{ "message": "No workers available" }

Specific to self-hosted agents: the agentId is valid, but no server has registered for it.

{ "message": "No workers have registered with agentId 'ag_xxxxxx'" }

Specific to Agent Cloud agents: the agent exists but has no deployed version available for dispatch.

{ "message": "No agent is deployed with agentId 'ag_xxxxxx'" }

Inside the session

However you started it, once a session is live you control it from the agent’s hooks and tools. Reach it as self.session:

Method	What it does
`say(text)`	Speak a fixed line (straight to TTS).
`reply(instructions)`	Generate a reply through the LLM.
`close()`	End the session and run `on_exit()`.

async def on_enter(self):
    await self.session.say("Hi! How can I help?")

Connect your agent to the phone network

With your agent running locally, connect it to the outside world by setting up gateways and routing rules in your Zero Runtime Dashboard or via the Zero Runtime API.

Via Dashboard
Via API

Add SIP Configuration

Go to the Zero Runtime Dashboard.
Click on Add Number.
Click on Configure SIP.
Give a name and add your phone number.

Setup Inbound Gateway

Copy the Inbound URL from the Zero Runtime Dashboard.
Go to Twilio and create a new SIP Trunk.
Go to the Origination section, paste the Inbound URL there, and save it.

Setup Outbound Gateway

Go to the Termination section in Twilio, create a URI, and paste it into the outbound section in the Zero Runtime Dashboard.
Create a username and password in Twilio and add it to the Zero Runtime outbound section.

Setup Routing Rules

Click on Configure rule then Create new routing rule.
Add Routing Rule Name.
Select API Key.
Add Call Direction (Inbound or Outbound).
Add Phone Number.
Add Room Type.
Add Agent ID.
Click Save.

Create Phone Number

Register your phone numbers and provision inbound and outbound SIP gateways in a single request. Replace $YOUR_TOKEN and update the phone numbers, SIP region, and outbound gateway settings for your provider.

curl -H 'Authorization: $YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My SIP Setup",
    "phoneNumbers": [
      "+14155551234",
      "+14155555678"
    ],
    "isShared": true,
    "mediaEncryption": "disable",
    "inbound": {
      "sipRegion": "us002"
    },
    "outbound": {
      "sipRegion": "us002",
      "address": "sip.telnyx.com:5061",
      "transport": "tls",
      "auth": {
        "username": "sip-user",
        "password": "sip-pass"
      }
    }
  }' \
  -X POST https://api.videosdk.live/v2/sip/phone-numbers

API reference: Create Phone Numbers + SIP Gateways.

Create Routing Rule

Create a routing rule to route inbound calls to your agent. Set agentId to your agent’s ID (from above) and replace $YOUR_TOKEN, $YOUR_API_KEY, and the phone numbers with your own values.

curl -H 'Authorization: $YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Inbound support rule",
    "type": "inbound",
    "phoneNumbers": [
      "+14155551234"
    ],
    "apiKey": "$YOUR_API_KEY",
    "agentId": "$YOUR_AGENT_ID",
    "agentMetadata": {
      "team": "support"
    },
    "room": {
      "type": "dynamic",
      "prefix": "blank"
    },
    "includeHeaders": "SIP_X_HEADERS",
    "headersToAttributes": {
      "X-Caller-Id": "callerId"
    },
    "headers": {
      "X-Customer-Id": "cust_42"
    },
    "allowedNumbers": [],
    "allowedIpAddresses": [],
    "tags": [
      "support",
      "v2"
    ],
    "recording": false,
    "dtmf": false,
    "noiseCancellation": false,
    "hidePhoneNumber": true
  }' \
  -X POST https://api.videosdk.live/v2/sip/routing-rule

API reference: Create Routing Rule.

You have now configured Zero Runtime to route inbound calls from your configured phone number(s) to your running agent.

Make and receive calls

Your setup is complete. Test it out.

Make sure your AI agent is running locally before configuring the telephony settings. The agent must be active to receive incoming calls.

Making an inbound call

Using any phone, dial the SIP number you configured.
Your local agent will automatically answer.
You’ll hear the greeting: “Hello! I’m your real-time assistant. How can I help you today?”
Start talking. The agent will listen and respond in real time.

Making an outbound call

Trigger an outbound call from your agent with a simple API request. Use curl or any API client to make a POST request to the Zero Runtime API. Replace $YOUR_TOKEN and the routingRuleId with your own.

curl -H 'Authorization: $YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "sipCallFrom" : "+14155550100",
    "sipCallTo" : "+14155550199",
    "routingRuleId" : "rr_2554md"
  }' \
  -X POST https://api.videosdk.live/v2/sip/call

This commands your agent to dial the specified number and start a conversation.

For optimal performance, run your agent in the same geographic region as your SIP provider (for example, US East for Twilio, US West for Telnyx, Europe for Plivo). This reduces latency and improves call quality.

What’s Next

Create an Agent

Define the agent that serve runs.

Tools and Capabilities

Give the agent function tools and external services.

Telephony

DTMF, call transfer, and voicemail detection.

Deploy an Agent

Take your agent to production.

References

Python

Examples

Cascade Basic

Smallest complete agent showing serve + invoke.

SDK Reference

_serve.py

_serve.py in the Python API reference.

_invoke.py

_invoke.py in the Python API reference.

Get started

Modalities

Configure Pipeline

Tools and Capabilities

Turn Detection and Interruptions

Telephony Agents

Context Management

Observability and Monitoring

Start a session

Invoke with the SDK

Place a phone call

Dispatch with the API

Endpoint

Request body parameters

Example request

Responses

Inside the session

Connect your agent to the phone network

Make and receive calls

Making an inbound call

Making an outbound call

What’s Next

Create an Agent

Tools and Capabilities

Telephony

Deploy an Agent

References

Examples

Cascade Basic

SDK Reference

_serve.py

_invoke.py

​Start a session

​Invoke with the SDK

​Place a phone call

​Dispatch with the API

​Endpoint

​Request body parameters

​Example request

​Responses

​Inside the session

​Connect your agent to the phone network

​Make and receive calls

​Making an inbound call

​Making an outbound call

​What’s Next

Create an Agent

Tools and Capabilities

Telephony

Deploy an Agent

​References

​Examples

Cascade Basic

​SDK Reference

_serve.py

_invoke.py

Start a session

Invoke with the SDK

Place a phone call

Dispatch with the API

Endpoint

Request body parameters

Example request

Responses

Inside the session

Connect your agent to the phone network

Make and receive calls

Making an inbound call

Making an outbound call

What’s Next

References

Examples

SDK Reference