Build A Function Call

Learn how to build a Function Call to use with your Agent.

Voice Agent

This guide walks you through how to build a simple function call for a demo application. Please refer to this code repository for the complete application code.

Getting Started

We’ll setup a module called functions.py that defines a collection of functions and configurations which can be used in a Voice Agent API system for customer service automation. These functions will handle customer lookups, appointments, and order management through a set of async functions and standardized function definitions.

Please note: functions.py will rely on the business_logic.py and the client.py files to work end to end.

Prerequisites

  • Python 3.7+
  • Familiarity with Python
  • An understanding of how to use Python Virtual environments.
  • Familiarity with the Deepgram Voice Agent API

Create the file

Create a file called functions.py and at the top of the file:

Set Up the dependencies and Import the business logic

Python
1import json
2from datetime import datetime, timedelta
3import asyncio
4from business_logic import (
5    get_customer,
6    get_customer_appointments,
7    get_customer_orders,
8    schedule_appointment,
9    get_available_appointment_slots,
10    prepare_agent_filler_message,
11    prepare_farewell_message
12)

This guide doesn’t cover the development of the business logic for this application. Please see this code for more details on the business logic used.

Implement the Functions

We’ll start with the customer lookup function:

This function handles:

  • Multiple lookup methods (phone, email, ID)
  • Standardized ID formatting (CUSTXXXX)
  • Phone number normalization (+1XXXXXXXXXX)
  • Email address parsing
Python
1async def find_customer(params):
2    """Look up a customer by phone, email, or ID."""
3    phone = params.get("phone")
4    email = params.get("email")
5    customer_id = params.get("customer_id")
6    
7    result = await get_customer(phone=phone, email=email, customer_id=customer_id)
8    return result

Next we’ll create a function to find customer appointments for a specific customer:

This function handles:

  • retrieving all appointments for a specific customer using their customer ID.
Python
1async def get_appointments(params):
2    """Get appointments for a customer."""
3    customer_id = params.get("customer_id")
4    if not customer_id:
5        return {"error": "customer_id is required"}
6    
7    result = await get_customer_appointments(customer_id)
8    return result

Next we’ll create a function to do appointment management:

This function handles:

  • Scheduling new appointments
  • Checking availability
  • Retrieving existing appointments
Python
1async def get_orders(params):
2    """Get orders for a customer."""
3    customer_id = params.get("customer_id")
4    if not customer_id:
5        return {"error": "customer_id is required"}
6    
7    result = await get_customer_orders(customer_id)
8    return result

Next we’ll create a function to do order management:

This function handles:

  • Order history lookup
  • Order status checking
Python
1async def create_appointment(params):
2    """Schedule a new appointment."""
3    customer_id = params.get("customer_id")
4    date = params.get("date")
5    service = params.get("service")
6    
7    if not all([customer_id, date, service]):
8        return {"error": "customer_id, date, and service are required"}
9    
10    result = await schedule_appointment(customer_id, date, service)
11    return result

Next will create a function to find available appointment times:

This function handles:

  • Finding available appointment slots
  • Pre-scheduling availability checks
  • Responding to “When can I come in?” queries
Python
1async def check_availability(params):
2    """Check available appointment slots."""
3    start_date = params.get("start_date")
4    end_date = params.get("end_date", (datetime.fromisoformat(start_date) + timedelta(days=7)).isoformat())
5    
6    if not start_date:
7        return {"error": "start_date is required"}
8    
9    result = await get_available_appointment_slots(start_date, end_date)
10    return result

Next will setup a function to handle conversational flow:

This function handles:

  • Agent filler messages for natural interaction
  • Proper conversation closure handling
Python
1async def agent_filler(websocket, params):
2    """
3    Handle agent filler messages while maintaining proper function call protocol.
4    """
5    result = await prepare_agent_filler_message(websocket, **params)
6    return result

Finally we’ll create a function to end the call gracefully.

This function handles:

  • Conversation closure
  • Adding appropriate farewell messages
Python
1async def end_call(websocket, params):
2    """
3    End the conversation and close the connection.
4    """
5    farewell_type = params.get("farewell_type", "general")
6    result = await prepare_farewell_message(websocket, farewell_type)
7    return result

Create Function Definitions

Next well need to setup FUNCTION_DEFINITIONS Which is an array that defines the API contract for the Voice Agent system. It specifies all available operations, their parameters, and usage guidelines.

Each function definition follows a JSON Schema format with:

  • Name
  • Description
  • Parameters specification
  • Required fields
  • Enumerated values where applicable
Python
1# Function definitions that will be sent to the Voice Agent API
2FUNCTION_DEFINITIONS = [
3    {
4        "name": "agent_filler",
5        "description": """Use this function to provide natural conversational filler before looking up information.
6        ALWAYS call this function first with message_type='lookup' when you're about to look up customer information.
7        After calling this function, you MUST immediately follow up with the appropriate lookup function (e.g., find_customer).""",
8        "parameters": {
9            "type": "object",
10            "properties": {
11                "message_type": {
12                    "type": "string",
13                    "description": "Type of filler message to use. Use 'lookup' when about to search for information.",
14                    "enum": ["lookup", "general"]
15                }
16            },
17            "required": ["message_type"]
18        }
19    },
20    {
21        "name": "find_customer",
22        "description": """Look up a customer's account information. Use context clues to determine what type of identifier the user is providing:
23
24        Customer ID formats:
25        - Numbers only (e.g., '169', '42') → Format as 'CUST0169', 'CUST0042'
26        - With prefix (e.g., 'CUST169', 'customer 42') → Format as 'CUST0169', 'CUST0042'
27        
28        Phone number recognition:
29        - Standard format: '555-123-4567' → Format as '+15551234567'
30        - With area code: '(555) 123-4567' → Format as '+15551234567'
31        - Spoken naturally: 'five five five, one two three, four five six seven' → Format as '+15551234567'
32        - International: '+1 555-123-4567' → Use as is
33        - Always add +1 country code if not provided
34        
35        Email address recognition:
36        - Spoken naturally: 'my email is john dot smith at example dot com' → Format as '[email protected]'
37        - With domain: '[email protected]' → Use as is
38        - Spelled out: 'j o h n at example dot com' → Format as '[email protected]'""",
39        "parameters": {
40            "type": "object",
41            "properties": {
42                "customer_id": {
43                    "type": "string",
44                    "description": "Customer's ID. Format as CUSTXXXX where XXXX is the number padded to 4 digits with leading zeros. Example: if user says '42', pass 'CUST0042'"
45                },
46                "phone": {
47                    "type": "string",
48                    "description": """Phone number with country code. Format as +1XXXXXXXXXX:
49                    - Add +1 if not provided
50                    - Remove any spaces, dashes, or parentheses
51                    - Convert spoken numbers to digits
52                    Example: 'five five five one two three four five six seven' → '+15551234567'"""
53                },
54                "email": {
55                    "type": "string",
56                    "description": """Email address in standard format:
57                    - Convert 'dot' to '.'
58                    - Convert 'at' to '@'
59                    - Remove spaces between spelled out letters
60                    Example: 'j dot smith at example dot com' → '[email protected]'"""
61                }
62            }
63        }
64    },
65    {
66        "name": "get_appointments",
67        "description": """Retrieve all appointments for a customer. Use this function when:
68        - A customer asks about their upcoming appointments
69        - A customer wants to know their appointment schedule
70        - A customer asks 'When is my next appointment?'
71        
72        Always verify you have the customer's account first using find_customer before checking appointments.""",
73        "parameters": {
74            "type": "object",
75            "properties": {
76                "customer_id": {
77                    "type": "string",
78                    "description": "Customer's ID in CUSTXXXX format. Must be obtained from find_customer first."
79                }
80            },
81            "required": ["customer_id"]
82        }
83    },
84    {
85        "name": "get_orders",
86        "description": """Retrieve order history for a customer. Use this function when:
87        - A customer asks about their orders
88        - A customer wants to check order status
89        - A customer asks questions like 'Where is my order?' or 'What did I order?'
90        
91        Always verify you have the customer's account first using find_customer before checking orders.""",
92        "parameters": {
93            "type": "object",
94            "properties": {
95                "customer_id": {
96                    "type": "string",
97                    "description": "Customer's ID in CUSTXXXX format. Must be obtained from find_customer first."
98                }
99            },
100            "required": ["customer_id"]
101        }
102    },
103    {
104        "name": "create_appointment",
105        "description": """Schedule a new appointment for a customer. Use this function when:
106        - A customer wants to book a new appointment
107        - A customer asks to schedule a service
108        
109        Before scheduling:
110        1. Verify customer account exists using find_customer
111        2. Check availability using check_availability
112        3. Confirm date/time and service type with customer before booking""",
113        "parameters": {
114            "type": "object",
115            "properties": {
116                "customer_id": {
117                    "type": "string",
118                    "description": "Customer's ID in CUSTXXXX format. Must be obtained from find_customer first."
119                },
120                "date": {
121                    "type": "string",
122                    "description": "Appointment date and time in ISO format (YYYY-MM-DDTHH:MM:SS). Must be a time slot confirmed as available."
123                },
124                "service": {
125                    "type": "string",
126                    "description": "Type of service requested. Must be one of the following: Consultation, Follow-up, Review, or Planning",
127                    "enum": ["Consultation", "Follow-up", "Review", "Planning"]
128                }
129            },
130            "required": ["customer_id", "date", "service"]
131        }
132    },
133    {
134        "name": "check_availability",
135        "description": """Check available appointment slots within a date range. Use this function when:
136        - A customer wants to know available appointment times
137        - Before scheduling a new appointment
138        - A customer asks 'When can I come in?' or 'What times are available?'
139        
140        After checking availability, present options to the customer in a natural way, like:
141        'I have openings on [date] at [time] or [date] at [time]. Which works better for you?'""",
142        "parameters": {
143            "type": "object",
144            "properties": {
145                "start_date": {
146                    "type": "string",
147                    "description": "Start date in ISO format (YYYY-MM-DDTHH:MM:SS). Usually today's date for immediate availability checks."
148                },
149                "end_date": {
150                    "type": "string",
151                    "description": "End date in ISO format. Optional - defaults to 7 days after start_date. Use for specific date range requests."
152                }
153            },
154            "required": ["start_date"]
155        }
156    },
157    {
158        "name": "end_call",
159        "description": """End the conversation and close the connection. Call this function when:
160        - User says goodbye, thank you, etc.
161        - User indicates they're done ("that's all I need", "I'm all set", etc.)
162        - User wants to end the conversation
163        
164        Examples of triggers:
165        - "Thank you, bye!"
166        - "That's all I needed, thanks"
167        - "Have a good day"
168        - "Goodbye"
169        - "I'm done"
170        
171        Do not call this function if the user is just saying thanks but continuing the conversation.""",
172        "parameters": {
173            "type": "object",
174            "properties": {
175                "farewell_type": {
176                    "type": "string",
177                    "description": "Type of farewell to use in response",
178                    "enum": ["thanks", "general", "help"]
179                }
180            },
181            "required": ["farewell_type"]
182        }
183    }
184]

Create a Function Map

Finally we’ll need to create aFUNCTION_MAP which is a dictionary that maps function names to their corresponding implementation functions. It serves as a routing mechanism to connect the function definitions with their actual implementations.

Python
1# Map function names to their implementations
2FUNCTION_MAP = {
3    "find_customer": find_customer,
4    "get_appointments": get_appointments,
5    "get_orders": get_orders,
6    "create_appointment": create_appointment,
7    "check_availability": check_availability,
8    "agent_filler": agent_filler,
9    "end_call": end_call
10}

Call the functions from client.py

This guide doesn’t cover the development of the client application but you can refer to the client code for how you can connect your Voice Agent tofunctions.py as well as the documentation Configuring the Voice Agent.

Python
1# Example of the Voice Agent Settings Configuration used the Demo app
2
3SETTINGS = {
4    "type": "SettingsConfiguration",
5    "audio": {
6        "input": {
7            "encoding": "linear16",
8            "sample_rate": USER_AUDIO_SAMPLE_RATE,
9        },
10        "output": {
11            "encoding": "linear16",
12            "sample_rate": AGENT_AUDIO_SAMPLE_RATE,
13            "container": "none",
14        },
15    },
16    "agent": {
17        "listen": {"model": "nova-3"},
18        "think": {
19            "provider": {"type": "open_ai"},
20            "model": "gpt-4o-mini",
21            "instructions": PROMPT_TEMPLATE,
22            "functions": FUNCTION_DEFINITIONS,
23        },
24        "speak": {"model": VOICE},
25    },
26    "context": {
27        "messages": [
28            {"role": "assistant", "content": "Hello! I'm Sarah from TechStyle customer service. How can I help you today?"}
29        ],
30        "replay": True
31    }
32}

What’s Next?

  • For more ideas and function code samples for using Function Calling with your Agent check out this repository.
Built with