Tools Calling

This guide focuses on configuring tools within your Vapi assistant using the provided sample payload as a reference. We’ll explore how to adapt the existing structure to fit your specific needs and desired functionalities.

​

Understanding the Tool Structure

The sample payload demonstrates the configuration for a “function” type tool. Let’s break down its key components:

{
    "type": "function",
    "messages": [ ... ],
    "function": { ... },
    "async": false,
    "server": { ... }
}

1. type: This remains as “function” if you’re setting up an API call.
2. messages: This array holds the messages the AI will communicate to the user at different stages of the tool’s execution.
3. function: Defines the function details:
   • name: The unique identifier for your function.
   • parameters: (Optional) An object describing the parameters expected by the function.
   • description: (Optional) A description of the function’s purpose.
4. async: Set to “true” if the function call should be asynchronous, allowing the AI to continue without waiting for the response. Use “false” for synchronous calls.
5. server: Provides the URL of the server where the function is hosted.

​

Adapting the Payload for Your Needs

1. Modify Function Details:
   • Change the “name” to reflect your specific function.
   • Adjust the “parameters” object according to the data your function requires.
   • Update the “description” to accurately explain the function’s purpose.
2. Customize Messages:
   • Edit the content of each message within the “messages” array to align with your desired communication style and information.
   • Add or remove messages as needed. You can include messages like “request-start”, “request-response-delayed”, “request-complete”, and “request-failed” to inform the user about the tool’s progress.
3. Set Server URL:
   • Replace the existing URL in the “server” object with the endpoint of your server hosting the function.
4. Choose Asynchronous Behavior (Optional):
   • Change “async” to “true” if you want the AI to continue without waiting for the function’s response.

​

Example Modification

Let’s say you want to create a tool that fetches the weather for a given location. You would modify the payload as follows:

{
    "type": "function",
    "messages": [
        {
            "type": "request-start",
            "content": "Checking the weather forecast. Please wait..."
        },
        {
            "type": "request-complete",
            "content": "The weather in location is"
        },
        {
            "type": "request-failed",
            "content": "I couldn't get the weather information right now."
        },
        {
            "type": "request-response-delayed",
            "content": "It appears there is some delay in communication with the weather API.",
            "timingMilliseconds": 2000
        }
    ],
    "function": {
        "name": "get_weather",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string"
                }
            }
        },
        "description": "Retrieves the current weather for a specified location."
    },
    "async": false,
    "server": {
        "url": "https://your-weather-api.com/weather"
    }
}

​

Adding More Tools

Simply create additional tool objects within the “tools” array, following the same structure and modifying the details as needed. Each tool can have its own unique configuration and messages.

​

Server Response Format: Providing Results and Context

When your Vapi assistant calls a tool (via the server URL you configured), your server will receive an HTTP request containing information about the tool call. Upon processing the request and executing the desired function, your server needs to send back a response in the following JSON format:

{
    "results": [
        {
            "toolCallId": "X",
            "result": "Y"
        }
    ]
}

Breaking down the components:

• toolCallId (X): This is a unique identifier included in the initial request from Vapi. It allows the assistant to match the response with the corresponding tool call, ensuring accurate processing and context preservation.
• result (Y): This field holds the actual output or result of your tool’s execution. The format and content of “result” will vary depending on the specific function of your tool. It could be a string, a number, an object, an array, or any other data structure that is relevant to the tool’s purpose.

Example:

Let’s revisit the weather tool example from before. If the tool successfully retrieves the weather for a given location, the server response might look like this:

{
  "results": [
    {
      "toolCallId": "call_VaJOd8ZeZgWCEHDYomyCPfwN",
      "result": "San Francisco's weather today is 62°C, partly cloudy."
    }
  ]
}

Some Key Points:

• Pay attention to the required parameters and response format of your functions.
• Ensure your server is accessible and can handle the incoming requests from Vapi.
• Make sure to add “Tools Calls” in both the Server and Client messages and remove the function calling from it.

By following these guidelines and adapting the sample payload, you can easily configure a variety of tools to expand your Vapi assistant’s capabilities and provide a richer, more interactive user experience.