工具 API 参考

本页汇总工具目录、工作区工具和专用外部服务连接接口。认证与工作区规则见 Product API 开始使用。

工具接口

方法	相对路径	用途
GET	/workspaces/{workspace_id}/tools	列出系统或工作区工具。
GET	/workspaces/{workspace_id}/tools/tags	列出工具标签及数量。
GET	/workspaces/{workspace_id}/tools/{tool_id}	读取工具详情。
POST	/workspaces/{workspace_id}/tools	创建工作区工具。
PATCH	/workspaces/{workspace_id}/tools/{tool_id}	部分更新或归档工作区工具。

列表支持 query、status、kind、category、phase、side_effect_class、运行时可见性、绑定类型、重复的 tags、catalog、limit 和 offset。

创建和更新字段

字段	类型	必需	默认值	说明
name	string	创建时是	—	工具名称。
description	string	否	—	工具完成的单一动作。
status	string	否	—	工具状态。归档使用 archived。
kind	string	否	—	工具类型。
category、tags、phase	string、array、string	否	—	分类和检索信息。
source_ref	object	否	—	执行来源的类型、ID、URI、版本和配置。
input_schema	object	否	—	输入 JSON Schema。
output_schema	object	否	—	输出 JSON Schema。
side_effect_class	string	否	—	工具副作用类别。
credential_ref	string	否	—	已保存凭据的引用。
approval_policy_ref	string	否	—	批准策略引用。
redaction_policy_ref	string	否	—	脱敏策略引用。

详情响应还可能包含 bindable、bindability_reason 和 supported_runtimes。这些字段反映当前可绑定状态，不是工具定义的静态承诺。

专用连接接口

方法	相对路径	用途
POST、GET、DELETE	/workspaces/{workspace_id}/tools/github/connect	连接、查询或断开 GitHub 工具。
POST	/workspaces/{workspace_id}/tools/wecom/callback-secrets/generate	生成企业微信回调密钥材料。
POST、GET、DELETE	/workspaces/{workspace_id}/tools/mail/{provider}/connect	连接、查询或断开邮件工具；provider 为 qq 或 wecom。
POST、GET、DELETE	/workspaces/{workspace_id}/tools/grafana/connect	连接、查询或断开 Grafana 工具。

创建连接时传入第三方凭据。查询连接时检查 status、credential_ref 和是否需要重新连接；不要依赖服务回显明文密钥。

错误和限制

现象	先检查	处理方式
工具存在但不可绑定	bindable、bindability_reason、目标运行时	补齐凭据或改用受支持运行时。
调用参数无效	input_schema 与实际参数	修正 Schema 或调用参数，避免用提示词猜测字段。
第三方认证失败	连接状态、令牌范围和过期时间	使用最小必要权限重新连接。
更新冲突或资源不可修改	工具来源和所属工作区	不修改系统工具；对正确的工作区工具提交更新。

任务指南

• 发现和管理工具

• 连接 MCP 服务并导入工具

最后更新于 2026 年 8 月 14 日