This tutorial shows how to build an AI voice agent that answers questions using live external data by combining a conversational layer with function calls to a third-party API. It walks through extracting structured parameters from a caller request, fetching weather data for a requested location and timeframe, and converting the result into a concise spoken response. The same design applies to production AI agents that must look up real-time information, such as order status, appointment availability, shipment tracking, store hours, and support ticket updates.
A reusable voice AI agent example for real-time data retrieval
This demo is a practical template for building AI agents that rely on live data. It shows how to take a caller’s request, extract structured parameters like location and time range, call an external API, and turn the response into a short, speakable answer that fits voice. That is the same core architecture behind support and operations agents, where the agent must look up real information in real time instead of guessing.
The bigger lesson is that the agent does not need a giant prompt to “know” things. It needs reliable function calling and good boundaries. In this example, we illustrate how to keep the model focused on interpretation and dialogue, while deterministic code handles data retrieval, formatting, and error handling. Once you have that split, you can swap “weather” for any backend data source, and your agent becomes a reusable voice front end for your systems.
AI weather bot code deep dive
SignalWire AI Agent for voice allows you to create and deploy intelligent, human-like digital employees. With advanced natural language processing (NLP) and customizable configurations, you can elevate customer experiences with unique virtual agents for any industry.
In this example, we’ll examine a JSON configuration structured for AI-powered interactions about the weather, with special focus on information retrieval. This configuration is rich in functionalities, including voice recording, customizable AI behavior, and specialized tasks like sending messages and fetching weather information.
This post will hone in on specific snippets of the code. Follow along in the video below, or view the full example on GitHub. Test out the weather bot for yourself by calling 1 (206) 451-CAST.
This configuration is structured under a sections key, with different operational blocks in the main array. Each block serves a unique purpose, ranging from voice recording settings to complex AI operations.
Prompt
},
"prompt": {
"text": "You're a weather expert. You have three functions to help you get weather information for users.\r\n\r\nYou have to use get_lat_lon function to get the latitude and longitude by city and state\r\nThen you have to use get_weather_point, that takes latitude and longitude to get the detailed weather URL\r\nFinally you use get_weather_detailed_forecast, that takes the URL from get_weather_point\r\n\r\n# Step 1\r\nGreet the user\r\n\r\n# Step 2\r\nGet the detailed forecast for the user\r\n\r\n# Step 3\r\nTell the user the detailed forcast\r\n\r\n# Step 4\r\nOffer to send the details in a message to the user",
"temperature": 0.6,
"top_p": 0.6
}This snippet defines the AI agent’s area of expertise, personality, and outlines the steps the bot should take in the conversation. The prompt is the backbone for your unique AI agent, and helps the AI understand its mission.
Answer block
{
"answer": {}
}This block answers the call.
Record call block
{
"record_call": {
"format": "wav",
"stereo": "true"
}
}Here, the system is instructed to record calls in WAV format with stereo audio quality, essential for applications requiring audio analysis or legal compliance.
AI configuration block
Post-prompt configuration
"post_prompt_url": "https://webhook.site/a6196db2-75c2-4c36-98bf-e31245"
"post_prompt_auth_password": "this-is-optional-password"
"post_prompt_auth_user": "this-is-an-optional-user"
These configurations define the endpoint and authentication details for the AI to communicate with after executing prompts, ensuring secure data transmission.
Parameters
"params": {
"verbose_logs": "true",
"debug_webhook_url": "https://this-is-an-optional-user:this-is-optional-password@webhook.site/a6196db2-75c2-4c36-98bf-e31245"
}This enables detailed logging for debugging purposes and specifies a webhook URL for sending debug information, crucial for monitoring and troubleshooting AI operations.
Post prompt
"post_prompt": {
"top_p": 0.6,
"temperature": 0.6,
"text": "Summarize the conversation"
}The post_prompt dictates the AI's task to summarize the conversation, adjusting creativity and randomness with top_p and temperature. This guides the AI in generating concise summaries of interactions.
Pronunciation adjustments
"pronounce": [
{
"ignore_case": 0,
"with": "miles per hour",
"replace": "mph"
}
]This particular example aims to customize how the AI interprets and vocalizes "mph," ensuring clarity in pronunciation by expanding abbreviations where necessary. Pronunciation adjustments ensure clarity in vocalization, particularly useful for acronyms like “mph.”
Functions
There are several customizable functions that allow the weather bot to perform a selection of actions related to sending messages and retrieving weather information. You can view the entire code snippet for these functions in the GitHub repo.
These functions include:
Send text message
{
"purpose": "use to send text messages to a user",
"argument": {
"type": "object",
"properties": {
"to": {
"type": "string",
"description": "The users number in e.164 format"
},
"message": {
"description": "the message to send to the user",
"type": "string"
}
}
},
"data_map": {
"expressions": [
{
"string": "${args.message}",
"output": {
"response": "Message sent.",
"action": [
{
"SWML": {
"version": "1.0.0",
"sections": {
"main": [
{
"send_sms": {
"to_number": "${args.to}",
"region": "us",
"body": "${args.message}, Reply STOP to stop.",
"from_number": "+19184052049"
}
}
]
}
}
}
]
},
"pattern": ".*"
}
]
},
"function": "send_message"
}The send_message function allows the AI to send SMS messages to users. The user inputs for the recipient's phone number and message content. It showcases the use of SignalWire Markup Language (SWML) to structure the message sending action.
Send multimedia message
The send_mms function expands upon the SMS functionality to include the capability of sending multimedia content along with text messages. It demonstrates how to include media URLs in the message payload for a more engaging user experience.
Get latitude and longitude
The get_lat_lon function fetches geographic coordinates (latitude and longitude) for a given city or state. This function showcases the integration with external APIs (in this case, OpenStreetMap) to retrieve location data, essential for weather-related inquiries.
Get weather point
The get_weather_point function utilizes the geographic coordinates to fetch a specific weather forecast point from the National Weather Service. This function serves as a bridge to obtaining detailed weather forecasts by providing a URL for further querying.
Get weather detailed forecast
{
"function": "get_weather_detailed_forecast",
"data_map": {
"webhooks": [
{
"url": "${args.url}",
"method": "GET",
"output": {
"response": "${properties.periods[0].detailedForecast}"
}
}
]
},
"purpose": "get detailed forecast for a location using forecast URL",
"argument": {
"properties": {
"url": {
"type": "string",
"description": "complete forecast URL"
}
},
"type": "object"
}
}The get_weather_detailed_forecast function directly queries a detailed forecast for a specific location using a URL obtained from the previous step (get_weather_point). It exemplifies how to navigate from obtaining latitude and longitude to fetching and presenting a detailed weather forecast to the user.
By leveraging the rich functionalities of SignalWire AI Agent, you can build custom applications like this weather bot with functions like fetching weather information based on location and sending SMS or MMS messages to users.
This is just one example of how to make use of the functionalities of an AI agent. Incorporating AI into customer-facing applications is a strategic move for businesses looking to stay competitive. With tools like SignalWire's AI Agent, the future of customer engagement is smarter, more intuitive, and more engaging than ever.
Start building today for free by signing up for a space, and bring your questions to our developer community on Discord!
Frequently asked questions
What is function calling in an AI agent, and why does it matter?
Function calling lets an AI agent trigger deterministic code to fetch data or perform actions, so the agent can answer based on real systems instead of relying on model memory.
Why should an AI voice agent use live API lookups instead of letting the model answer directly?
Live lookups prevent stale or fabricated answers and let the agent return current, verifiable information, which is critical for operational use cases like orders, scheduling, and account updates.
What makes external data harder in voice than in chat?
Voice is interruptible and time-limited, so responses must be concise, and the agent must confirm parameters like location, date, or account identifiers before retrieving data.
How should an AI agent handle missing or ambiguous parameters, such as location or timeframe?
Ask a short clarifying question, confirm the user’s intent, then run the lookup only after the required parameters are known, instead of guessing and returning incorrect results.
What kinds of production workflows use the same “voice plus API” pattern?
Common examples include order status, appointment and availability checks, delivery tracking, store hours, pricing and inventory checks, account balance and billing lookups, and support ticket status.
