ai-telephony-demo

ai-telephony-demo

Build an AI Telephony Agent for Inbound and Outbound Calls

Stars: 218

Visit
 screenshot

Build a fully functional AI telephony agent using VideoSDK Agent. The project covers setting up the agent locally, configuring SIP trunks for inbound and outbound calls, and connecting the agent to the phone network. It provides step-by-step instructions, including creating environment variables, installing dependencies, and running the Python script. The agent can handle incoming calls, greet users, engage in conversations using natural speech, and respond using the Gemini Live model with voice synthesis. Additionally, it explains how to make outbound calls through API requests to the VideoSDK SIP endpoint. The project aims to help users create and deploy an AI agent for telephony tasks.

README:

AI Telephony Agent

Build a fully functional AI telephony agent using VideoSDK Agent. We will cover the complete workflow, from running the agent locally to configuring SIP trunks for live inbound and outbound phone calls.

Architecture : Connecting Voice Agent to Telephony Agent

Documentation Video Tutorials Discord Community

Project Structure

This simple structure is our final goal for the worker. By following along, you'll create this complete project from scratch.

worker/
├── main.py                 # The core logic for your AI voice agent
├── requirements.txt        # Python package dependencies
└── .env.example            # Environment variables

Prerequisites

Running the AI Agent Locally

1. Setup Env. Variables

Create a .env file with your credentials from template .env.example:

VIDEOSDK_TOKEN=your_videosdk_token_here
GOOGLE_API_KEY=your_google_api_key_here

API Keys - Get GOOGLE API KEY ↗, and sign up to VideoSDK Dashboard ↗ to generate videosdk token

2. Create the environment

  • On MacOS/Linux
python3 -m venv .venv
  • On Windows

Next, Activate it! Command differ based on your environment

source .venv/bin/activate

You'll know the environment is active when you see (.venv) at the beginning of your terminal prompt.

3. Install Dependencies

With the virtual environment active, install the necessary Python packages listed in your requirements.txt file:

pip install -r requirements.txt

4. Run the Python Script

Finally, run the agent:

python main.py

This will start your agent locally and register it with VideoSDK. You should see output confirming that your agent is running and registered with the agent_id "agent1".

Running AI Agent Locally

Important: Keep this terminal running! Your agent needs to stay active to handle incoming calls.

Connect Your AI Phone Agent to the Phone Network

1. Set up an Inbound Gateway

  • In the VideoSDK Dashboard ↗, go to Telephony > Inbound Gateways and click Add.
  • Name the gateway, add your phone number, and copy the generated Inbound Gateway URL.
  • In your SIP provider's dashboard (e.g., Twilio ↗), paste this URL into the Origination SIP URI field.

Inbound Gateway

2. Set up an Outbound Gateway

  • In VideoSDK, go to Telephony > Outbound Gateways and click Add.
  • Name the gateway and paste the Termination SIP URI from your SIP provider into the Address field.

Outbound Gateway

3. Create a Routing Rule

  • Go to Telephony > Routing Rules and click Add.
  • Configure the rule:
    • Gateway: Choose the gateway you just created.
    • Agent Type: Set to Self Hosted.
    • Agent ID: Enter agent1 (this matches the agent_id in your main.py file).
    • Click Create to link the gateway to your agent.

Routing Rules

Making an Inbound Call

Once your routing rule is configured, you can test your AI agent by making an inbound call:

  1. Call your SIP provider number (the number you configured in your Inbound Gateway)
  2. Your AI agent will automatically answer and start the conversation
  3. The agent will greet you with: "Hello! I'm your real-time AI avatar assistant. How can I help you today?"
  4. You can have a conversation with the AI agent using natural speech
  5. The agent will respond using the Gemini Live model with voice synthesis

Making an Outbound Call

To trigger an outbound call from your agent, you can make a simple API request to the VideoSDK SIP endpoint.

Use a POST request with your VIDEOSDK_TOKEN for authorization. In the body, specify the gatewayId (from your Outbound Gateway) and the phone number to call in sipCallTo.

curl --request POST \
  --url <https://api.videosdk.live/v2/sip/call> \
  --header 'Authorization: YOUR_VIDEOSDK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "gatewayId": "gw_123456789",
    "sipCallTo": "+14155550123"
  }'

Next Step

That's it! You've successfully built a Python AI agent, run it locally, and connected it to the global telephone network for both inbound and outbound calls. Simply make a call to your SIP provider number and your AI agent will handle the conversation!

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for ai-telephony-demo

Similar Open Source Tools

For similar tasks

For similar jobs