To make calls, see the Making calls using SIP quickstart.
This guide walks you through the following steps to create an AI voice agent that responds to incoming calls:
- Creating a voice agent using the LiveKit Agents framework.
- Setting up an inbound LiveKit trunk.
- Adding a dispatch rule to place callers in rooms.
Pre-requisites
The following are required to complete the steps in this quickstart:
- A phone number purchased from your SIP trunk provider.
- A SIP trunk with your provider.
- LiveKit CLI installed.
- SIP server: LiveKit Cloud or a self-hosted SIP server.
Instructions for setting up a SIP trunk with Twilio or Telnyx are available in the Create and configure SIP trunk quickstart.
Step 1: Set up environment variables
Log in to see your real credentials populated in many places throughout this page
Set up the following environment variables to configure the LiveKit CLI to use your LiveKit Cloud or self-hosted LiveKit server instance:
export LIVEKIT_URL=<your LiveKit server URL>export LIVEKIT_API_KEY=<your API Key>export LIVEKIT_API_SECRET=<your API Secret>
Step 2: Create an AI voice agent
The fastest way to create an agent is by using the LiveKit CLI:
lk app create --template voice-pipeline-agent-python
Enter your API keys at the prompts. Alternatively, you can skip the prompts and manually edit the
.env.local
file with your API keys.Follow the instructions in the command output to start your agent.
Step 3: Create an inbound LiveKit trunk
An inbound SIP trunk instructs LiveKit to accept calls to one or more numbers that you own. Create a file inbound-trunk.json
with the following content. This example assumes +12223334444
is the phone number that you own:
{"trunk": {"name": "Twilio inbound trunk","numbers": ["+12223334444"]}}
Create the LiveKit inbound SIP trunk using the CLI:
lk sip inbound create inbound-trunk.json
The output includes the LiveKit trunk ID:
SIPTrunkID: <livekit_trunk_id>
Add dispatch rule
Dispatch rules route inbound SIP calls into LiveKit rooms. The dispatchRuleIndividual
rule in this example, routes each caller into an individual room with the agent. The name of the room is prefixed with call
:
Create dispatch-rule.json
file:
{"name": "My dispatch rule","trunk_ids": ["<livekit_trunk_id>"],"rule": {"dispatchRuleIndividual": {"roomPrefix": "call"}}}
Apply the dispatch rule for the trunk using the CLI:
lk sip dispatch create dispatch-rule.json
Step 4: Call your agent
Calling the phone number you assigned to the LiveKit trunk places you in a room named my-sip-room
. After you join the room, your agent is dispatched to the room and you can talk to your agent.
Next steps
Using SIP participant attributes: Modify the agent you created in Step 2 based on a caller's attributes.
To learn more, see the following topics:
- Dispatch rules: You can create dispatch rules to control how callers are dispatched to rooms, configure authentication, and add participant attributes.
- SIP participant: You can manage SIP participants like any other LiveKit participant. You can also use SIP specific attributes to manage callers based on the number they call or the number they're calling from, and more.