工具调用

接口说明

调用指定服务下的指定工具，并在当前请求内返回结构化 JSON 结果。

• 接口路径：POST /v1/openapi/third-party-service/:service/:tool/invoke

TIP

不同工具的响应耗时受工具类型、入参规模及三方服务自身响应情况影响，建议调用方按业务场景设置合理的客户端超时时间，并对错误响应进行重试或降级处理。

请求头

参数名	必填	说明
Content-Type	是	application/json
Authorization	是	鉴权凭证，格式 Bearer sk_xxx

请求参数

路径参数

参数	类型	必填	说明
service	string	是	服务 slug，如 tavily_search，可通过服务列表接口获取
tool	string	是	工具 slug，如 tavily_search，可通过工具列表接口获取

请求体

{
  "inputs": {
    "query": "OpenAI o1",
    "max_results": 2
  }
}

字段	类型	必填	说明
inputs	object	否	工具入参，字段定义参见工具列表；零参数工具可省略请求体

成功响应示例（以 tavily_search/tavily_search 真实返回为例）

{
  "code": 200,
  "data": {
    "service": "tavily_search",
    "tool": "tavily_search",
    "output": {
      "answer": null,
      "follow_up_questions": null,
      "images": [],
      "query": "OpenAI o1",
      "request_id": "06cfcac5-08ca-4f30-9029-16b2ab59543b",
      "response_time": 0.77,
      "results": [
        {
          "title": "OpenAI o1 - Wikipedia",
          "url": "https://en.wikipedia.org/wiki/OpenAI_o1",
          "content": "OpenAI o1 is a generative pre-trained transformer (GPT)...",
          "raw_content": null,
          "score": 0.9544823
        }
      ]
    }
  },
  "message": "success",
  "trace_id": "ece1bfa480da3a5bb346cf83cfc29454"
}

TIP

不同工具的 output 字段结构由各服务自身的输出契约决定。建议调用前先通过工具列表确认入参定义，或直接参阅对应服务子页面（Tavily 搜索 / 豆包语音）。

data 字段说明

字段	类型	说明
service	string	实际执行的服务 slug
tool	string	实际执行的工具 slug
output	object | string	工具结构化结果；少数返回非 JSON 的工具会原样回传字符串

失败响应示例

{
  "code": 0,
  "data": null,
  "message": "三方服务凭证未配置",
  "trace_id": "e3302bb5788035dec7160e58d2261824"
}

业务错误清单

message（示例）	触发条件	处理建议
缺少工作空间标识（请通过网关访问）	请求绕过网关直连 app 层时的兜底文案；正常通过网关访问不会出现	通过网关地址访问并携带 Authorization，由网关注入工作空间上下文；参见认证与鉴权
服务不存在	:service slug 不存在或已下架	通过服务列表确认可用 slug
未找到对应的提供商插件: xxx	:tool 不属于该服务	通过工具列表确认
三方服务凭证未配置	该服务需要凭证但当前 workspace 未配置	在控制台为该 workspace 配置凭证后重试
provider xxx does not support tool: yyy	服务存在但工具未注册	检查工具 slug 拼写
其他	工具内部执行错误（如远端 API 报错）	按错误信息排查，必要时联系平台

WARNING

鉴权类错误（401/403）由网关直接返回，不会进入本错误清单。详见错误处理。

调用示例

调用工具（带参数）

curl -X POST 'https://runtime-api.invalid/v1/openapi/third-party-service/tavily_search/tavily_search/invoke' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -d '{
    "inputs": {
      "query": "OpenAI o1",
      "max_results": 2
    }
  }'

调用零参数工具（如 current_time/get_timestamp）

curl -X POST 'https://runtime-api.invalid/v1/openapi/third-party-service/current_time/get_timestamp/invoke' \
  -H 'Authorization: Bearer sk_your_api_key'

返回示例：

{
  "code": 200,
  "data": {
    "service": "current_time",
    "tool": "get_timestamp",
    "output": { "timestamp": 1778231301 }
  },
  "message": "success",
  "trace_id": "1c2b23f18c73fc0540423f0c2923a654"
}

注意事项

• 推荐调用顺序：服务列表 → 工具列表 → 工具调用，避免调用方维护本地服务清单。
• 三方服务凭证统一在平台控制台按工作空间维度配置，OpenAPI 调用方无需在请求中传递三方服务的 API Key；平台会根据调用方 API Key 绑定的工作空间自动选用对应凭证。
• 对于 need_credentials=true 且 is_configured=false 的服务，需先在控制台完成凭证配置后再调用。