Repository files navigation

This repository serves as a reference implementation for integrating function calling capabilities with Deepgram's Voice Agent API using Python Flask. It demonstrates production-ready patterns for building AI Voice Agent applications with clientside function calling. In addition, it surfaces logs to the user to help understand the flow from user to assistant to LLM.

Before you start, it's essential to generate a Deepgram API key to use in this project.Sign-up now for Deepgram.

This reference implementation demonstrates:

• Core function calling patterns with Voice Agent API
• Using Python Flask to build a simple web application
• Natural conversation flow using agent filler messages
• Customer information lookup and verification
• Order history retrieval
• Appointment scheduling and management
• Graceful conversation termination through anend_call function
• Logging in the UI for debugging

The implementation uses a three-layer architecture:

• Function definitions that guide the LLM's behavior
• Function handlers that route requests
• Business logic that executes the actual functionality

Shows how to implement natural dialogue patterns:

• Agent filler messages for lookup operations
• Proper message sequencing
• Audio completion handling
• Clean session termination

├── common/│   ├── agent_functions.py    # Function definitions and routing│   ├── business_logic.py     # Core function implementations│   ├── config.py             # Configuration settings│   ├── log_formatter.py      # Logger setup├── client.py             # WebSocket client and message handling

The implementation uses a mock data system for demonstration:

• Generates realistic customer, order, and appointment data
• Saves data to timestamped JSON files inmock_data_outputs/
• Configurable throughconfig.py

The implementation demonstrates how to handle real-world latency:

• Configurable database operation delays inconfig.py
• Helps simulate production environment timing

0. Make sure you have portaudio installed.

In macOS:

brew install portaudio:

In Ubuntu:

sudo apt-get install portaudio19-dev

pipenv can be used to manage virtual env. and packages in one easy to use tool. Instead of running pip commands, you just usepipenv.

1. Install pipenv if not already installed.

pip install pipenv

2. Switch to the pipenv virtual environment:

pipenv shell

3. Install the project dependencies:

In the root directory of the project, run the following command to install the dependencies:

pipenv install -r requirements.txt

4. Set your Deepgram API key. Either programatically:

export DEEPGRAM_API_KEY=<your-key-here>

• or in a file named.env within your root directory which has this entry:

DEEPGRAM_API_KEY=<your-key-here>

1. Run the client:

   python client.py

The application will be available athttp://localhost:5000

2. Use headphones to prevent audio feedback (the agent hearing itself).

The voice agent handles natural conversations like:

User: "I need to check my order status"Agent: "Let me look that up for you..."[Agent executes customer lookup]Agent: "I can see you have two recent orders. Your most recent       order from last week is currently being shipped..."

Key settings inconfig.py:

• ARTIFICIAL_DELAY: Configurable delays for database operations
• MOCK_DATA_SIZE: Control size of generated test data

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. TheSecurity Policy details the procedure for contacting Deepgram.

Deepgram

This project is licensed under the MIT license. See theLICENSE file for more info.