create-tool

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vapi Tool Creation

Vapi 工具创建

Create tools that give voice assistants the ability to take actions during calls — look up data, book appointments, transfer calls, send messages, and more.

Setup: Ensure
VAPI_API_KEY
is set. See the
setup-api-key
skill if needed.

创建可让语音助手在通话过程中执行操作的工具——例如查询数据、预约日程、转接电话、发送消息等。

设置说明：确保已配置
VAPI_API_KEY
。如有需要，请查看
setup-api-key
技能文档。

Quick Start

快速开始

Create a Function Tool (cURL)

创建函数工具（cURL）

bash

curl -X POST https://api.vapi.ai/tool \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name, e.g. San Francisco"
          }
        },
        "required": ["location"]
      }
    },
    "server": {
      "url": "https://your-server.com/api/tools"
    }
  }'

bash

curl -X POST https://api.vapi.ai/tool \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name, e.g. San Francisco"
          }
        },
        "required": ["location"]
      }
    },
    "server": {
      "url": "https://your-server.com/api/tools"
    }
  }'

TypeScript (Server SDK)

TypeScript（服务端SDK）

typescript

import { VapiClient } from "@vapi-ai/server-sdk";

const vapi = new VapiClient({ token: process.env.VAPI_API_KEY! });

const tool = await vapi.tools.create({
  type: "function",
  function: {
    name: "get_weather",
    description: "Get current weather for a location",
    parameters: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "City name, e.g. San Francisco",
        },
      },
      required: ["location"],
    },
  },
  server: {
    url: "https://your-server.com/api/tools",
  },
});

console.log("Tool created:", tool.id);

typescript

import { VapiClient } from "@vapi-ai/server-sdk";

const vapi = new VapiClient({ token: process.env.VAPI_API_KEY! });

const tool = await vapi.tools.create({
  type: "function",
  function: {
    name: "get_weather",
    description: "Get current weather for a location",
    parameters: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "City name, e.g. San Francisco",
        },
      },
      required: ["location"],
    },
  },
  server: {
    url: "https://your-server.com/api/tools",
  },
});

console.log("Tool created:", tool.id);

Tool Types

工具类型

Function Tool

函数工具

The most common tool type. Your server receives the function call and returns a result.

json

{
  "type": "function",
  "function": {
    "name": "lookup_order",
    "description": "Look up order status by order number",
    "parameters": {
      "type": "object",
      "properties": {
        "orderNumber": {
          "type": "string",
          "description": "The order number to look up"
        }
      },
      "required": ["orderNumber"]
    }
  },
  "server": {
    "url": "https://your-server.com/api/tools"
  },
  "messages": [
    {
      "type": "request-start",
      "content": "Let me look that up for you..."
    },
    {
      "type": "request-complete",
      "content": "I found your order information."
    },
    {
      "type": "request-failed",
      "content": "I'm having trouble looking that up. Let me try again."
    }
  ]
}

最常用的工具类型。你的服务器会接收函数调用请求并返回结果。

json

{
  "type": "function",
  "function": {
    "name": "lookup_order",
    "description": "Look up order status by order number",
    "parameters": {
      "type": "object",
      "properties": {
        "orderNumber": {
          "type": "string",
          "description": "The order number to look up"
        }
      },
      "required": ["orderNumber"]
    }
  },
  "server": {
    "url": "https://your-server.com/api/tools"
  },
  "messages": [
    {
      "type": "request-start",
      "content": "Let me look that up for you..."
    },
    {
      "type": "request-complete",
      "content": "I found your order information."
    },
    {
      "type": "request-failed",
      "content": "I'm having trouble looking that up. Let me try again."
    }
  ]
}

Transfer Call Tool

转接电话工具

Transfer the caller to another number or SIP endpoint.

json

{
  "type": "transferCall",
  "destinations": [
    {
      "type": "number",
      "number": "+1234567890",
      "message": "Transferring you to our billing department now.",
      "description": "Transfer to billing department when customer has billing questions"
    }
  ],
  "function": {
    "name": "transfer_to_billing",
    "description": "Transfer the caller to the billing department"
  }
}

SIP transfer:

json

{
  "type": "transferCall",
  "destinations": [
    {
      "type": "sip",
      "sipUri": "sip:billing@company.com",
      "description": "Transfer to billing via SIP"
    }
  ]
}

将来电转接至其他号码或SIP端点。

json

{
  "type": "transferCall",
  "destinations": [
    {
      "type": "number",
      "number": "+1234567890",
      "message": "Transferring you to our billing department now.",
      "description": "Transfer to billing department when customer has billing questions"
    }
  ],
  "function": {
    "name": "transfer_to_billing",
    "description": "Transfer the caller to the billing department"
  }
}

SIP转接：

json

{
  "type": "transferCall",
  "destinations": [
    {
      "type": "sip",
      "sipUri": "sip:billing@company.com",
      "description": "Transfer to billing via SIP"
    }
  ]
}

End Call Tool

结束通话工具

Allows the assistant to end the call programmatically.

json

{
  "type": "endCall",
  "function": {
    "name": "end_call",
    "description": "End the call when the conversation is complete"
  }
}

允许助手通过编程方式结束通话。

json

{
  "type": "endCall",
  "function": {
    "name": "end_call",
    "description": "End the call when the conversation is complete"
  }
}

DTMF Tool

DTMF工具

Send DTMF tones (touch-tone signals) during a call for IVR navigation.

json

{
  "type": "dtmf",
  "function": {
    "name": "press_digits",
    "description": "Press phone keypad digits to navigate phone menus",
    "parameters": {
      "type": "object",
      "properties": {
        "digits": {
          "type": "string",
          "description": "Digits to press (0-9, *, #)"
        }
      },
      "required": ["digits"]
    }
  }
}

在通话过程中发送DTMF tones（按键音信号）以实现IVR导航。

json

{
  "type": "dtmf",
  "function": {
    "name": "press_digits",
    "description": "Press phone keypad digits to navigate phone menus",
    "parameters": {
      "type": "object",
      "properties": {
        "digits": {
          "type": "string",
          "description": "Digits to press (0-9, *, #)"
        }
      },
      "required": ["digits"]
    }
  }
}

Voicemail Tool

语音信箱工具

Detect and handle voicemail.

json

{
  "type": "voicemail",
  "function": {
    "name": "leave_voicemail",
    "description": "Leave a voicemail message"
  }
}

检测并处理语音信箱。

json

{
  "type": "voicemail",
  "function": {
    "name": "leave_voicemail",
    "description": "Leave a voicemail message"
  }
}

Google Calendar Tool

Google Calendar工具

json

{
  "type": "google.calendar.event.create",
  "function": {
    "name": "create_calendar_event",
    "description": "Schedule a meeting on Google Calendar"
  }
}

json

{
  "type": "google.calendar.event.create",
  "function": {
    "name": "create_calendar_event",
    "description": "Schedule a meeting on Google Calendar"
  }
}

Google Sheets Tool

Google Sheets工具

json

{
  "type": "google.sheets.row.append",
  "function": {
    "name": "log_to_sheet",
    "description": "Log call data to a Google Sheet"
  }
}

json

{
  "type": "google.sheets.row.append",
  "function": {
    "name": "log_to_sheet",
    "description": "Log call data to a Google Sheet"
  }
}

Slack Tool

Slack工具

json

{
  "type": "slack.message.send",
  "function": {
    "name": "notify_slack",
    "description": "Send a notification to Slack"
  }
}

json

{
  "type": "slack.message.send",
  "function": {
    "name": "notify_slack",
    "description": "Send a notification to Slack"
  }
}

MCP Tool

MCP工具

Connect to Model Context Protocol servers.

json

{
  "type": "mcp",
  "server": {
    "url": "https://your-mcp-server.com"
  }
}

连接至Model Context Protocol服务器。

json

{
  "type": "mcp",
  "server": {
    "url": "https://your-mcp-server.com"
  }
}

Tool Server Implementation

工具服务器实现

When the assistant calls a tool, Vapi sends a POST request to your server URL.

当助手调用工具时，Vapi会向你的服务器URL发送POST请求。

Request Format

请求格式

json

{
  "message": {
    "type": "tool-calls",
    "toolCallList": [
      {
        "id": "call_abc123",
        "name": "get_weather",
        "arguments": {
          "location": "San Francisco"
        }
      }
    ],
    "call": {
      "id": "call-uuid",
      "orgId": "org-uuid",
      "type": "webCall"
    }
  }
}

json

{
  "message": {
    "type": "tool-calls",
    "toolCallList": [
      {
        "id": "call_abc123",
        "name": "get_weather",
        "arguments": {
          "location": "San Francisco"
        }
      }
    ],
    "call": {
      "id": "call-uuid",
      "orgId": "org-uuid",
      "type": "webCall"
    }
  }
}

Response Format

响应格式

Your server must return:

json

{
  "results": [
    {
      "toolCallId": "call_abc123",
      "result": "San Francisco: 65°F, partly cloudy"
    }
  ]
}

你的服务器必须返回以下格式：

json

{
  "results": [
    {
      "toolCallId": "call_abc123",
      "result": "San Francisco: 65°F, partly cloudy"
    }
  ]
}

Example Server (Express.js)

示例服务器（Express.js）

typescript

import express from "express";

const app = express();
app.use(express.json());

app.post("/api/tools", async (req, res) => {
  const { message } = req.body;
  const results = [];

  for (const toolCall of message.toolCallList) {
    let result: string;

    switch (toolCall.name) {
      case "get_weather":
        const weather = await fetchWeather(toolCall.arguments.location);
        result = `${toolCall.arguments.location}: ${weather.temp}°F, ${weather.condition}`;
        break;
      case "lookup_order":
        const order = await lookupOrder(toolCall.arguments.orderNumber);
        result = `Order ${order.number}: ${order.status}`;
        break;
      default:
        result = "Unknown tool";
    }

    results.push({ toolCallId: toolCall.id, result });
  }

  res.json({ results });
});

app.listen(3000);

typescript

import express from "express";

const app = express();
app.use(express.json());

app.post("/api/tools", async (req, res) => {
  const { message } = req.body;
  const results = [];

  for (const toolCall of message.toolCallList) {
    let result: string;

    switch (toolCall.name) {
      case "get_weather":
        const weather = await fetchWeather(toolCall.arguments.location);
        result = `${toolCall.arguments.location}: ${weather.temp}°F, ${weather.condition}`;
        break;
      case "lookup_order":
        const order = await lookupOrder(toolCall.arguments.orderNumber);
        result = `Order ${order.number}: ${order.status}`;
        break;
      default:
        result = "Unknown tool";
    }

    results.push({ toolCallId: toolCall.id, result });
  }

  res.json({ results });
});

app.listen(3000);

Attaching Tools to Assistants

将工具关联至助手

By tool ID (recommended for reusable tools)

通过工具ID（推荐用于可复用工具）

bash

curl -X PATCH https://api.vapi.ai/assistant/{assistant-id} \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": {
      "provider": "openai",
      "model": "gpt-4.1",
      "toolIds": ["tool-id-1", "tool-id-2"],
      "messages": [{"role": "system", "content": "Your prompt here"}]
    }
  }'

bash

curl -X PATCH https://api.vapi.ai/assistant/{assistant-id} \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": {
      "provider": "openai",
      "model": "gpt-4.1",
      "toolIds": ["tool-id-1", "tool-id-2"],
      "messages": [{"role": "system", "content": "Your prompt here"}]
    }
  }'

Inline (for one-off tools)

内联方式（用于一次性工具）

Define tools directly in the assistant's model configuration — see the

create-assistant

skill.

在助手的模型配置中直接定义工具——请查看

create-assistant

技能文档。

Managing Tools

工具管理

bash

undefined

bash

undefined

List all tools

列出所有工具

curl https://api.vapi.ai/tool -H "Authorization: Bearer $VAPI_API_KEY"

Get a tool

获取单个工具详情

curl https://api.vapi.ai/tool/{id} -H "Authorization: Bearer $VAPI_API_KEY"

Update a tool

更新工具

curl -X PATCH https://api.vapi.ai/tool/{id}
-H "Authorization: Bearer $VAPI_API_KEY"
-H "Content-Type: application/json"
-d '{"function": {"description": "Updated description"}}'

Delete a tool

删除工具

curl -X DELETE https://api.vapi.ai/tool/{id}
-H "Authorization: Bearer $VAPI_API_KEY"

undefined

curl -X DELETE https://api.vapi.ai/tool/{id}
-H "Authorization: Bearer $VAPI_API_KEY"

undefined

Async Tools

异步工具

For long-running operations, mark a tool as async. The assistant continues speaking while the tool executes:

json

{
  "type": "function",
  "async": true,
  "function": {
    "name": "send_email",
    "description": "Send a confirmation email (runs in background)"
  },
  "server": {
    "url": "https://your-server.com/api/tools"
  }
}

对于长时间运行的操作，可将工具标记为异步。助手会在工具执行过程中继续与用户对话：

json

{
  "type": "function",
  "async": true,
  "function": {
    "name": "send_email",
    "description": "Send a confirmation email (runs in background)"
  },
  "server": {
    "url": "https://your-server.com/api/tools"
  }
}

Tool Messages

工具消息

Control what the assistant says during tool execution:

json

{
  "messages": [
    {
      "type": "request-start",
      "content": "One moment while I look that up..."
    },
    {
      "type": "request-complete",
      "content": "Got it!"
    },
    {
      "type": "request-failed",
      "content": "Sorry, I couldn't complete that action."
    },
    {
      "type": "request-response-delayed",
      "content": "This is taking a bit longer than usual, please hold.",
      "timingMilliseconds": 5000
    }
  ]
}

控制助手在工具执行过程中的话术：

json

{
  "messages": [
    {
      "type": "request-start",
      "content": "One moment while I look that up..."
    },
    {
      "type": "request-complete",
      "content": "Got it!"
    },
    {
      "type": "request-failed",
      "content": "Sorry, I couldn't complete that action."
    },
    {
      "type": "request-response-delayed",
      "content": "This is taking a bit longer than usual, please hold.",
      "timingMilliseconds": 5000
    }
  ]
}

References

参考资料

Tool Server Implementation — Detailed server setup guide
Vapi Tools Docs — Official documentation

工具服务器实现 — 详细的服务器搭建指南
Vapi 工具文档 — 官方文档

Additional Resources

额外资源

This skills repository includes a Vapi documentation MCP server (

vapi-docs

) that gives your AI agent access to the full Vapi knowledge base. Use the

searchDocs

tool to look up anything beyond what this skill covers — advanced configuration, troubleshooting, SDK details, and more.

Auto-configured: If you cloned or installed these skills, the MCP server is already configured via

.mcp.json

(Claude Code),

.cursor/mcp.json

(Cursor), or

.vscode/mcp.json

(VS Code Copilot).

Manual setup: If your agent doesn't auto-detect the config, run:

bash

claude mcp add vapi-docs -- npx -y mcp-remote https://docs.vapi.ai/_mcp/server

See the README for full setup instructions across all supported agents.

本技能仓库包含一个Vapi文档MCP服务器（

vapi-docs

），可让你的AI Agent访问完整的Vapi知识库。使用

searchDocs

工具可查询本技能未覆盖的内容——包括高级配置、故障排查、SDK细节等。

自动配置：如果你克隆或安装了这些技能，MCP服务器已通过

.mcp.json

（Claude Code）、

.cursor/mcp.json

（Cursor）或

.vscode/mcp.json

（VS Code Copilot）完成配置。

手动配置：如果你的Agent未自动检测到配置，请运行以下命令：

bash

claude mcp add vapi-docs -- npx -y mcp-remote https://docs.vapi.ai/_mcp/server

查看README获取所有支持Agent的完整配置说明。