You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -4,93 +4,132 @@ subtitle: Learn how to create and configure Custom Tools for use by your Vapi as
4
4
slug: tools/custom-tools
5
5
---
6
6
7
+
This guide shows you how to create custom tools for your Vapi assistants. We recommend using the Vapi dashboard's dedicated Tools section, which provides a visual interface for creating and managing tools that can be reused across multiple assistants. For advanced users, API configuration is also available.
7
8
8
-
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.
9
+
## Creating Tools in the Dashboard (Recommended)
9
10
10
-
##Understanding the Tool Structure
11
+
### Step 1: Navigate to the Tools Section
11
12
12
-
The sample payload demonstrates the configuration for a "function" type tool. Let's break down its key components:
13
+
1. Open your [Vapi Dashboard](https://dashboard.vapi.ai)
14
+
2. Click **Tools** in the left sidebar
15
+
3. Click **Create Tool** to start building your custom tool
13
16
14
-
```json
15
-
{
16
-
"type": "function",
17
-
"messages": [ ... ],
18
-
"function": { ... },
19
-
"async": false,
20
-
"server": { ... }
21
-
}
22
-
```
23
-
1.**type:** This remains as "function" if you're setting up an API call.
24
-
2.**messages:** This array holds the messages the AI will communicate to the user at different stages of the tool's execution.
25
-
3.**function:** Defines the function details:
26
-
-**name:** The unique identifier for your function.
27
-
-**parameters:** (Optional) An object describing the parameters expected by the function.
28
-
-**description:** (Optional) A description of the function's purpose.
29
-
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.
30
-
5.**server:** Provides the URL of the server where the function is hosted.
31
-
32
-
## Adapting the Payload for Your Needs
33
-
34
-
1.**Modify Function Details:**
35
-
- Change the "name" to reflect your specific function.
36
-
- Adjust the "parameters" object according to the data your function requires.
37
-
- Update the "description" to accurately explain the function's purpose.
38
-
2.**Customize Messages:**
39
-
- Edit the content of each message within the "messages" array to align with your desired communication style and information.
40
-
- 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.
41
-
3.**Set Server URL:**
42
-
- Replace the existing URL in the "server" object with the endpoint of your server hosting the function.
43
-
4.**Choose Asynchronous Behavior (Optional):**
44
-
- Change "async" to "true" if you want the AI to continue without waiting for the function's response.
45
-
46
-
### Example Modification
47
-
48
-
Let's say you want to create a tool that fetches the weather for a given location. You would modify the payload as follows:
17
+
### Step 2: Configure Your Tool
49
18
50
-
```json
51
-
{
19
+
The dashboard provides a user-friendly interface to configure your tool:
20
+
21
+
1.**Tool Type**: Select "Function" for custom API integrations
22
+
2.**Tool Name**: Give your tool a descriptive name (e.g., "Weather Lookup")
23
+
3.**Description**: Explain what your tool does
24
+
4.**Tool Configuration**:
25
+
-**Tool Name**: The identifier for your function (e.g., `get_weather`)
26
+
-**Parameters**: Define the input parameters your function expects
27
+
-**Server URL**: The endpoint where your function is hosted
28
+
29
+
### Step 3: Configure Messages
30
+
31
+
Set up the messages your assistant will speak during tool execution. For example, if you want custom messages you can add something like this:
32
+
33
+
-**Request Start**: "Checking the weather forecast. Please wait..."
34
+
-**Request Complete**: "The weather information has been retrieved."
35
+
-**Request Failed**: "I couldn't get the weather information right now."
36
+
-**Request Delayed**: "There's a slight delay with the weather service."
37
+
38
+
### Step 4: Advanced Settings
39
+
40
+
Configure additional options:
41
+
-**Async Mode**: Enable if the tool should run asynchronously
42
+
-**Timeout Settings**: Set how long to wait for responses
43
+
-**Error Handling**: Define fallback behaviors
44
+
45
+
## Example: Creating a Weather Tool
46
+
47
+
Let's walk through creating a weather lookup tool:
48
+
49
+
### Dashboard Configuration
50
+
51
+
1.**Tool Name**: "Weather Lookup"
52
+
2.**Description**: "Retrieves current weather information for any location"
53
+
3.**Function Name**: `get_weather`
54
+
4.**Parameters**:
55
+
-`location` (string, required): "The city or location to get weather for"
This example uses OpenWeatherMap's free API. You'll need to sign up at [openweathermap.org](https://openweathermap.org/api) to get a free API key and add it as a query parameter: `?appid=YOUR_API_KEY&q={location}`
60
+
</Note>
61
+
62
+
### Messages Configuration
63
+
64
+
-**Request Start**: "Let me check the current weather for you..."
65
+
-**Request Complete**: "Here's the weather information you requested."
66
+
-**Request Failed**: "I'm having trouble accessing weather data right now."
67
+
68
+
## Using Tools in Assistants
69
+
70
+
Once created, your tools can be easily added to any assistant:
71
+
72
+
### In the Dashboard
73
+
74
+
1. Go to **Assistants** → Select your assistant
75
+
2. Navigate to the **Tools** tab
76
+
3. Click **Add Tool** and select your custom tool from the dropdown
77
+
4. Save your assistant configuration
78
+
79
+
### In Workflows
80
+
81
+
Tools created in the Tools section are automatically available in the workflow builder:
82
+
83
+
1. Add a **Tool Node** to your workflow
84
+
2. Select your custom tool from the **Tool** dropdown
85
+
3. Configure any node-specific settings
86
+
87
+
## Alternative: API Configuration
88
+
89
+
For advanced users who prefer programmatic control, you can also create and manage tools via the Vapi API:
90
+
91
+
### Creating Tools via API
92
+
93
+
```bash
94
+
curl --location 'https://api.vapi.ai/tool' \
95
+
--header 'Content-Type: application/json' \
96
+
--header 'Authorization: Bearer <YOUR_API_KEY>' \
97
+
--data '{
52
98
"type": "function",
53
-
"messages": [
54
-
{
55
-
"type": "request-start",
56
-
"content": "Checking the weather forecast. Please wait..."
57
-
},
58
-
{
59
-
"type": "request-complete",
60
-
"content": "The weather in location is"
61
-
},
62
-
{
63
-
"type": "request-failed",
64
-
"content": "I couldn't get the weather information right now."
65
-
},
66
-
{
67
-
"type": "request-response-delayed",
68
-
"content": "It appears there is some delay in communication with the weather API.",
69
-
"timingMilliseconds": 2000
70
-
}
71
-
],
72
99
"function": {
73
100
"name": "get_weather",
101
+
"description": "Retrieves current weather information for any location",
74
102
"parameters": {
75
103
"type": "object",
76
104
"properties": {
77
105
"location": {
78
-
"type": "string"
106
+
"type": "string",
107
+
"description": "The city or location to get weather for"
79
108
}
80
-
}
81
-
},
82
-
"description": "Retrieves the current weather for a specified location."
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.
0 commit comments