自定义工具用于将企业自定义 API、函数能力或已发布应用封装为可被智能体调用的工具。开发者可以根据业务需要定义工具名称、描述、输入参数、输出参数和调用方式，让智能体在合适的上下文中自动选择并调用该工具。
基于 API 和代码新建
1. 填写工具基本信息
单击腾讯云智能体开发平台左侧菜单的连接器与工具 > 自定义工具 > 新建工具，选择基于API 或基于代码创建工具。
-
基于 API：手动填写 API 的基础信息、输入和输出参数。
-
基于代码：使用 Python 自定义函数代码以实现 API 功能。
以基于 API 创建为例：
1.1 填写工具基本信息
填写工具基本信息，包括名称、描述、上传工具图标等。
1.2 指定工具授权方式
根据工具 API 的实际鉴权要求，选择 授权方式。
APIKey 授权
APIKey 是通过密钥或令牌对请求方身份进行校验的认证方式。
在授权方式处选择 APIkey 后，在 Header（请求头）或 Query（查询参数）中配置密钥对应参数名称和密钥值：
OAuth 2.0 授权
智能体开发平台在创建 API 工具时，支持配置 OAuth 2.0 授权方式，用于对接需要 OAuth 鉴权的第三方 API 服务。OAuth 2.0 是一种用于访问授权的行业标准协议，允许用户将其在某个网站的信息授权给 ADP，但不需要将网站的账号密码给 ADP。通过平台统一的 OAuth 配置与授权流程，可简化工具接入与用户使用过程，提升安全性与易用性。
在授权方式处选择 OAuth 2.0 后，配置相关字段，字段相关信息均需在第三方 OAuth 应用管理后台中获取：
| 字段 | 是否必填 | 说明 |
|---|---|---|
| ClientId | 必填 | 第三方 OAuth 应用的客户端 ID |
| ClientSecret | 必填 | 第三方 OAuth 应用的客户端密钥 |
| AuthorizationUrl | 必填 | 第三方 OAuth 授权地址，用于发起用户登录授权 |
| Scope | 选填 | 授权范围，允许添加多个，可按第三方规范填写 |
| TokenUrl | 必填 | 第三方 OAuth 获取 Access Token 的地址 |
请复制以下重定向 URL，前往第三方 OAuth 应用的配置页面，将该 URL 填入第三方的回调地址配置中，未正确配置重定向 URL 将导致授权失败。
https://adp.tencent.com/api/plugin/oauth/callback
示例：
接下来将通过接入 GitCode API 为例，展示 OAuth 2.0 授权配置过程。
-
步骤一 在 GitCode 的官方 API 文档内找到 OAuth 配置说明，获取 AuthorizationUrl 和 TokenUrl 地址，以及 Scope 范围等信息。
-
步骤二 登录 GitCode 平台，在 个人设置中选择 OAuth 应用并创建应用，完成输入应用信息、配置 ADP 回调地址和选择应用权限等操作后，单击新建应用，GitCode 平台将自动为您生成 ClientId 和 ClientSecret。
-
步骤三 在 ADP 内创建 GitCode API 工具，选择 OAuth 2.0 授权，并将前两步获取的信息填入。
-
步骤四 单击下一步完成相关工具配置后，支持在 校验工具 进行授权测试，该授权状态为一次性校验，不会保存。校验通过后单击保存完成工具创建。
2. 配置工具
您可以通过手动添加工具或添加 YAML/json 格式代码文件导入 API 工具。以手动添加工具为例，在“添加工具（API）”步骤中填写工具名称、调用地址等信息，配置接口对应的入参和出参后完成配置。
您可以通过不同类型的代码格式导入工具。以下是不同规范的 API 接入说明和示例：
OpenAPI
OpenAPI 是一种开放的规范，用于描述和定义 RESTful API 的接口。它允许开发者以标准化的方式描述 API 的请求、响应、参数、认证等信息。
文件格式：支持 YAML 格式和 JSON 格式。
关键字段说明：
| 字段 | 说明 | 是否必需 |
|---|---|---|
| openapi | 规范版本号，如3.0.0 | 是 |
| servers | 定义 API 的基础 URL 列表 | 否，但建议填写以生成有效 URL |
| info | API 元数据，包括标题、版本、描述等 | 是 |
| paths | 定义所有端点（例如 /users）及其 HTTP 方法（GET/POST） | 是 |
| components | 存储可复用的模型、参数、响应等，例如：schemas 定义的数据结构 | 否 |
示例：
【YAML】
openapi: "3.0.0"
info:
title: "测试API"
version: "1.0.0"
description: "请在此填入工具描述"
servers:
- url: "https://example.com/api"
description: "请在此填入工具描述"
paths:
"/weatherInfo":
get:
summary: "API名称"
description: "请在此填入工具下面的API描述"
operationId: "getWeatherInfo"
parameters:
- name: "city"
in: "query"
description: "参数说明"
required: true
schema:
type: "string"
responses:
"200":
description: "成功的响应"
content:
application/json:
schema:
type: "object"
properties:
status:
type: "integer"
description: "返回状态"
enum: [0, 1]
"400":
description: "错误的请求"
"401":
description: "未授权"
"500":
description: "服务器内部错误"
【JSON】
{
"openapi": "3.0.0",
"info": {
"title": "测试API",
"version": "1.0.0",
"description": "请在此填入工具描述"
},
"servers": [
{
"url": "https://example.com/api",
"description": "请在此填入工具描述"
}
],
"paths": {
"/weatherInfo": {
"get": {
"summary": "API名称",
"description": "请在此填入工具下面的API描述",
"operationId": "getWeatherInfo",
"parameters": [
{
"name": "city",
"in": "query",
"description": "参数说明",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "成功的响应",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "返回状态",
"enum": [
0,
1
]
}
}
}
}
}
},
"400": {
"description": "错误的请求"
},
"401": {
"description": "未授权"
},
"500": {
"description": "服务器内部错误"
}
}
}
}
}
}
Swagger
Swagger 是 OpenAPI 规范的前身和实现工具（Swagger 2.0 是旧版规范），用于描述、文档化和测试 RESTful API，使用与 OpenAPI 相同的文件格式。
文件格式：支持 YAML 格式和 JSON 格式。
关键字段说明：
| 字段 | 说明 | 是否必需 |
|---|---|---|
| swagger | 规范版本号，如2.0 | 是 |
| host | 域名 | 否，但建议填写以生成有效 URL |
| basePath | 基础路径 | 否，但建议填写以生成有效 URL |
| schemes | 支持的协议，如 http 或 https | 否，但建议填写以生成有效 URL |
| info | API 元数据，包括标题、版本、描述等 | 是 |
| paths | 定义所有端点（如 /users）及其 HTTP 方法（GET/POST） | 是 |
| definitions | 数据模型，相当于 OpenAPI 的 components/schemas | 否 |
示例：
【YAML】
swagger: "2.0"
info:
title: User API
version: 1.0.0
description: 示例 Swagger 2.0 文档
host: "example.com"
basePath: "/api"
schemes:
- "https"
paths:
/users:
# GET 请求
get:
summary: 获取所有用户
responses:
'200':
description: 成功返回用户列表
schema:
type: object
properties:
users:
type: array
items:
$ref: '#/definitions/User'
# POST 请求
post:
summary: 创建新用户
parameters:
- in: body
name: user
required: true
schema:
$ref: '#/definitions/User'
responses:
'201':
description: 用户创建成功
definitions:
User:
type: object
required:
- name
properties:
id:
type: integer
readOnly: true
example: 1
name:
type: string
example: "张三"
email:
type: string
format: email
example: "user@example.com"
【JSON】
{
"swagger": "2.0",
"info": {
"title": "User API",
"version": "1.0.0",
"description": "示例 Swagger 2.0 文档"
},
"host": "example.com",
"basePath": "/api",
"schemes": ["https"],
"paths": {
"/users": {
"get": {
"summary": "获取所有用户",
"responses": {
"200": {
"description": "成功返回用户列表",
"schema": {
"type": "object",
"properties": {
"users": {
"type": "array",
"items": {
"$ref": "#/definitions/User"
}
}
}
}
}
}
},
"post": {
"summary": "创建新用户",
"parameters": [
{
"in": "body",
"name": "user",
"required": true,
"schema": {
"$ref": "#/definitions/User"
}
}
],
"responses": {
"201": {
"description": "用户创建成功"
}
}
}
}
},
"definitions": {
"User": {
"type": "object",
"required": ["name"],
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"example": 1
},
"name": {
"type": "string",
"example": "张三"
},
"email": {
"type": "string",
"format": "email",
"example": "user@example.com"
}
}
}
}
}
Postman
Postman 是一个 API 开发和测试工具，其 Collection 格式用于保存请求、测试脚本和环境变量，适合手动测试和团队协作。
文件格式：支持 JSON 格式。
关键字段说明：
| 字段 | 说明 | 是否必需 |
|---|---|---|
| info | 集合元数据，包括集合名称和集合版本 | 是 |
| item | 请求列表，每个请求需指定方法和 URL | 是 |
| request | 请求详情，包括 header, body, auth 等 | 是 |
| auth | 认证配置，如 API Key | 否 |
| event | 预请求脚本或测试脚本 | 否 |
示例：
{
"info": {
"name": "User API Collection",
"version": "1.0.0",
"description": "示例 Postman 集合，包含 GET 和 POST 请求"
},
"item": [
{
"name": "GetAllUsers",
"request": {
"method": "GET",
"description": "GetAllUsers",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"url": {
"raw": "https://api.example.com/users",
"protocol": "https",
"host": [
"api.example.com"
],
"path": [
"users"
]
}
},
"response": []
},
{
"name": "CreateUser",
"request": {
"method": "POST",
"description": "CreateUser",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\"name\": \"John Doe\", \"email\": \"john@example.com\"}"
},
"url": {
"raw": "https://api.example.com/users",
"protocol": "https",
"host": [
"api.example.com"
],
"path": [
"users"
]
}
},
"response": []
}
]
}
3. 校验工具
工具配置完后，进入校验环节。在校验窗口中，填写输入参数后试运行，查看调用结果，测试工具是否能够正常调用。支持将当前测试结果保存为示例。
如您创建的工具为 OAuth 授权，您可以在校验阶段进行授权测试，该授权状态为一次性校验，不会保存。
试运行通过之后，保存当前编辑的工具。
注意：
工具需通过校验后才可保存。
保存后的工具支持在工具广场进行查看、编辑、导出等操作。
基于 MCP 新建
接入自定义 MCP
-
点击腾讯云智能体开发平台左侧菜单的连接器与工具 > 自定义工具 > 新建工具，选择基于MCP 创建工具。
-
在接入页面填写 MCP Server 的基本信息，包括名称、描述等字段，选择接入类型，配置 MCP Server 的在线 URL 地址。
MCP 服务端要求：接入的 MCP Server 需要符合 MCP 协议，并能够完成初始化、工具列表查询和工具调用流程。平台会通过配置的 URL 与 MCP Server 建立连接，并按 MCP 协议发起调用。
-
初始化：Server 需要支持
initialize方法，并返回protocolVersion、capabilities、serverInfo。 -
工具能力声明：如果该服务端需要作为工具在工作流或 Multi-Agent 中使用，
capabilities中需要声明tools能力，不为空。 -
工具列表：Server 需要支持
tools/list方法，并返回可调用工具列表。若tools/list返回空数组，平台可以完成服务接入，但不会生成可用工具。 -
工具调用：Server 需要支持
tools/call方法，并按 MCP 协议返回调用结果。接入类型：支持接入 sse 和 streamableHttp 协议类型的 MCP。
-
sse：一种基于 HTTP 协议的单向实时通信机制。客户端通过建立一次持久的 HTTP 连接，服务器即可持续不断地向客户端推送事件数据，常用于实时消息、状态更新等场景。
-
streamableHttp：一种在 HTTP 协议之上实现的流式传输机制，常用于 AI 模型输出逐步生成内容（如大语言模型的流式响应）。它不是全新的协议，而是对 HTTP 长连接与分块传输能力的灵活利用，以便在推理过程中逐步向客户端返回数据。
除了指定服务器类型外，您还可以在高级设置中自定义 MCP 的 Header、请求超时时长以及 SSE 服务超时时长。
-
Header：发送给 MCP Server 的 HTTP 请求头，可以在这里补充认证信息或自定义字段。
-
请求超时时长 (秒)：普通 HTTP 请求的超时时间，超过这个时长没有响应就会中断。
-
SSE 服务超时时长 (秒)：针对 SSE 长连接的超时时间。
您也可以通过 JSON 代码一键添加 MCP Server。
- 保存后即可完成MCP接入，您可以在 智能工作台、Multi-Agent 模式 和 工作流 内添加连接器与工具，扩充智能体的服务边界。后续可以对已创建的MCP进行查看、编辑、导出等动作。
基于已发布的应用创建
基于已发布应用创建的工具支持平台内跨应用使用，便于用户复用已发布应用。
注意：
使用支持多轮，而创建为工具后，仅支持单轮调用。
- 包含工作流的应用，不建议在工作流中设置与用户交互的节点（例如选项卡节点、参数提取节点、文件提取节点），否则将会出现严重的效果问题。
- 在 Multi-Agent 模式应用中，若采用 Plan-and-Execute 协同方式，不建议将其发布为工具。即使发布，也无法正常使用。
- 为了确保调试效果与工具发布后的表现一致，建议在调试阶段将应用配置中的输入输出上下文轮数设置为0。
1. 新建工具
进入工具广场，单击新建工具，选择基于已发布的应用。
2. 选择应用
在已发布的应用列表中选择应用，单击确定。
3. 填写基本信息
填写基本信息，可编辑工具名称、工具描述和工具图标，默认展示应用名称、应用描述和应用头像，支持用户修改。
填写成功后，单击下一步。
4. 添加工具
填写工具名称和描述。输入参数中，仅支持编辑参数描述，参数名称和类型不可编辑，对于单工作流模式应用，输入参数为工作流开始节点的输入参数，输出参数为工作流结束节点的输出参数。
使用自定义工具
如需了解如何在应用内使用工具，详情请参见 使用工具。
删除自定义工具
当删除自定义工具时，如果工具已经被引用，会进行删除提示说明。
