三方服务调用说明

模块说明

本页汇总三方服务（Third-party Service）模块的 OpenAPI 接口，包括 服务列表、工具列表、工具调用 三个通用接口。

具体某一类服务（例如 Tavily 搜索、豆包语音）的工具清单、入参字段与返回结构，请到对应子页面查阅。

三方服务以「服务（service） + 工具（tool）」两级组织，URL 中的 :service 与 :tool 均为 slug 字符串（如 tavily_search、doubao_speech），不是 UUID。

TIP

当前工作空间可用的服务清单、工具入参 Schema 与配置状态以服务列表、工具列表接口返回为准；下文示例中出现的 tavily_search、current_time、doubao_speech 等 slug 仅用于演示调用方式，请勿在调用方硬编码。

接口	方法	路径	说明
服务列表	GET	`/third-party-service`	列出当前 workspace 可用的全部三方服务
工具列表	GET	`/third-party-service/:service/tools`	列出指定服务下的全部工具及入参 schema
工具调用	POST	`/third-party-service/:service/:tool/invoke`	调用指定工具，阻塞返回结构化结果

参数名	必填	说明
Authorization	是	鉴权凭证，格式 `Bearer sk_xxx`

json

{
  "code": 200,
  "data": {},
  "message": "",
  "trace_id": "xxx"
}

三方服务模块的资源分为两级：

概念	说明
服务（service）	顶层资源，对应一类三方能力（如「Tavily 搜索」「豆包语音」），通过 `:service` slug 调用
工具（tool）	服务下的具体能力（如「网页搜索」「语音合成」），通过 `:tool` slug 调用

服务按是否需要凭证可分为两类：

`need_credentials`	说明
`false`	零配置本地服务（如 `current_time`），开箱可用
`true`	需要在控制台为当前 workspace 配置凭证后才能调用（如 `tavily_search`、`doubao_speech`）

推荐调用顺序：服务列表 → 工具列表 → 工具调用，避免调用方维护本地服务清单。
三方服务凭证统一在平台控制台按工作空间维度配置，OpenAPI 调用方无需在请求中传递三方服务的 API Key；平台会根据调用方 API Key 绑定的工作空间自动选用对应凭证。
对于 need_credentials=true 且 is_configured=false 的服务，需先在控制台完成凭证配置后再调用。
文档中出现的 slug 仅用于示例。当某个服务在当前工作空间不可用，服务列表接口不会返回该服务，工具列表与工具调用接口将返回 服务不存在，调用方应据此做兜底而非依赖文档示例。
鉴权类错误（401/403）由网关直接返回，不会进入业务错误清单。详见错误处理。