查询工具详情¶

读取当前工作区工具或可读取的系统工具，详情响应包含输入和输出 Schema。

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/tools/{tool_id}

调用前准备¶

先查询工具列表取得工具 ID。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求参数¶

调用示例

curl "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/tools/$TOOL_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

参数说明

路径参数

参数	类型	是否必填	说明
`workspace_id`	string	是	当前工作区 ID。
`tool_id`	string	是	要查询的工具 ID。

查询参数

参数	类型	是否必填	说明
`tool_workspace_id`	string	否	工具所属工作区 ID。未提供时使用当前工作区；只能指定当前工作区或系统工作区。

成功响应¶

响应示例

{
  "code": 0,
  "data": {
    "id": "tool_01",
    "workspace_id": "ws_01",
    "name": "查询工具",
    "status": "active",
    "kind": "http_api",
    "input_schema": {},
    "output_schema": {},
    "side_effect_class": "read",
    "version": 1,
    "bindable": true,
    "supported_runtimes": []
  }
}

字段说明

成功时返回 200。

响应字段如下。

通用字段

字段	类型	说明
`code`	integer	成功时为 `0`。

基本信息

字段	类型	说明
`id`	string	工具 ID、所属工作区和名称。
`workspace_id`	string	工具 ID、所属工作区和名称。
`name`	string	工具 ID、所属工作区和名称。
`status`	string	工具状态、类别和分类。
`kind`	string	工具状态、类别和分类。
`category`	string	工具状态、类别和分类。
`input_schema`	object	工具输入和输出 Schema。
`output_schema`	object	工具输入和输出 Schema。
`side_effect_class`	string	工具的副作用分类。
`credential_ref`	string	凭据、审批和脱敏策略引用；未设置时不返回。
`approval_policy_ref`	string	凭据、审批和脱敏策略引用；未设置时不返回。
`redaction_policy_ref`	string	凭据、审批和脱敏策略引用；未设置时不返回。
`bindable`	boolean	当前绑定能力、不可绑定原因和支持的运行环境。
`bindability_reason`	string	当前绑定能力、不可绑定原因和支持的运行环境。
`supported_runtimes`	array of string	当前绑定能力、不可绑定原因和支持的运行环境。
`version`	integer	工具版本与创建、最近更新时间。
`created_at`	string	工具版本与创建、最近更新时间。
`updated_at`	string	工具版本与创建、最近更新时间。

错误响应¶

响应示例

{
  "code": 3,
  "message": "tool not found"
}

字段说明

常见 HTTP 错误

通用字段

字段	类型	说明
`400`	`2`（`INVALID_ARGUMENT`）	常见原因：路径或 `tool_workspace_id` 无效。建议操作：检查路径和查询参数。
`401`	`6`（`UNAUTHENTICATED`）	常见原因：缺少有效身份凭据。建议操作：检查 API Key。
`403`	`5`（`PERMISSION_DENIED`）	常见原因：当前身份没有读取工具的权限。建议操作：检查工作区授权。
`404`	`3`（`NOT_FOUND`）	常见原因：指定工作区范围内不存在该工具。建议操作：检查工具 ID 和所属工作区。
`503`	`15`（`UNAVAILABLE`）	常见原因：工具资源服务或授权依赖暂不可用。建议操作：稍后重试。

后续操作¶

需要修改时更新工具。返回列表时查询工具标签。

最后更新于 2026 年 9 月 11 日