Overview: Custom Tools
Create powerful integrations that enable your agent to communicate with external systems and perform real-world actions.
Custom tools enable you to communicate with the outside world. Anything that you can do in a function can now be done by your agent via a custom tool.
If you already run a server with a well-defined OpenAPI spec, you can quickly create tools for all your API endpoints by
uploading that spec. Your OpenAPI spec must be either json
or yaml
format.
Once uploaded, your tools are just like any other durable tool, so you can use, modify, or delete them as you wish.
Creating Your First Custom Tool
Let’s look at creating a tool that sends an email with a summary of the conversation.
There are three steps:
Step 1: Define the Tool
We need to define the tool and provide it to our agent. The name, description, and parameters we provide here will be seen by the agent so we need to be thoughtful with them.
What’s happening here:
- We are adding
selectedTools
to the request body of the Create Call API request. - There’s a single tool named
sendConversationSummary
. - This tool requires a single dynamic parameter called
conversationSummary
that is passed in the request body. - The tool’s functionality is available via POST at the url
https://foo.bar/sendSummary
. - The tool is a temporary tool, so it will only be available for this call.
Step 2: Implement the Function
Now that we’ve defined the tool, let’s implement the functionality. This is a simplified example using Express.js and imagines a generic email API provider.
This function does the following:
- Accepts the
conversationSummary
via a POST. - Passes the data along to another function (
sendEmail
) that will send it via email.
Step 3: Instruct the Agent on Tool Use
The last thing we need to do is provide additional instructions to the agent on how to use the tool. This is primarily done using the tool’s own description along with the systemPrompt
. Let’s update what we used in the first step.
We’ve updated the system prompt that is used when the Ultravox call is created to instruct the agent when and how to use the tool.
Debugging Tool Calls
The Ultravox SDK enables viewing debug messages for any active call. These messages include tool calls.
Keep Learning
- Learn all about Tool Parameters →
- Learn how to secure tool calls in Tool Authentication →
- Check out our API reference for all tools endpoints.