The Problem

Enterprises that want to route inbound or outbound phone calls through an AI‑driven voice bot need a ready‑made bridge between telephony SIP trunks and a conversational model. Building that bridge from scratch involves handling authentication, media streaming, and prompt engineering, which consumes engineering time and introduces integration risk.

What This Does

The repository delivers a minimal, runnable Python worker that registers an AI Telephony Agent with VideoSDK’s Agent service. The core logic lives in main.py; it reads credentials from a .env file (template in .env.example), creates a VideoSDK client, and attaches a Gemini‑based LLM handler. All third‑party packages are listed in requirements.txt, so a fresh virtual environment can reproduce the runtime with a single pip install -r requirements.txt. The README.md walks a user through the exact commands needed to get the agent online and connect it to SIP trunks via VideoSDK’s inbound/outbound gateway UI.

How It Is Wired

Execution starts at main.py. The script:

  1. Loads environment variables using dotenv (imported from python-dotenv in requirements.txt).
  2. Instantiates a VideoSDKAgent (or the equivalent client class provided by videosdk-live/agents). The constructor consumes VIDEOSDK_API_KEY and VIDEOSDK_SECRET_KEY.
  3. Registers the agent with the VideoSDK backend, receiving an agent_id (“agent1” by default).
  4. Attaches a callback that forwards received audio to Google’s Gemini model, using the GOOGLE_API_KEY. The callback returns text, which the SDK then synthesizes back to the caller.
  5. Enters an event loop (async or threaded, depending on the SDK) that keeps the process alive and responsive to inbound call events.

No file besides main.py contains executable code, so all side‑effects (network calls to VideoSDK, HTTP requests to Google’s API, and audio streaming) originate from that single entry point. Because the worker does not touch a database or the filesystem beyond reading .env, its blast radius is limited to external service interactions. The repository does not expose any internal modules or reusable libraries, which makes the call graph a straight line: main.py → VideoSDK client → Google Gemini API.

How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/ai-telephony-demo
cd ai-telephony-demo

# 2. Create a .env from the example
cp .env.example .env
# Edit .env and fill in:
#   VIDEOSDK_API_KEY, VIDEOSDK_SECRET_KEY, GOOGLE_API_KEY

# 3. Set up a Python 3.12+ virtual environment
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Run the agent
python main.py

Keep the process running; the console will print the assigned agent_id. After that, follow the UI steps in the README to create inbound and outbound gateways in the VideoSDK dashboard and point your SIP provider to the generated URIs.

Real‑World Use

A contact‑center can deploy this worker on a modest VM, configure the VideoSDK inbound gateway to receive calls from Twilio, and let the Gemini model handle routine queries (e.g., order status). The agent replies with synthesized speech, and the call is terminated or transferred based on the LLM’s response.

Code Health & Issues

  • Medium – No test suite – repository contains no tests/ directory or test files.
  • Medium – No CI/CD – no .github/workflows/ or other pipeline definitions.
  • Low – No lockfile – dependencies are declared only in requirements.txt; reproducibility depends on PyPI versions at install time.

No additional static analysis warnings were detected.

The Bottom Line

The demo provides a clear, single‑file starter for hooking an LLM into VideoSDK’s telephony platform, useful for quick prototyping or proof‑of‑concept work. It lacks automated testing, CI, and a dependency lockfile, so production adoption will require adding those safeguards and possibly refactoring the monolithic main.py into a more modular package. Engineers comfortable with Python and external API integration can extend it without major architectural hurdles.