创建工具

在当前工作区创建一个平台工具。创建成功后返回工具定义及其当前可绑定状态。

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

调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

路径参数

参数	类型	是否必填	说明
workspace_id	string	是	当前工作区 ID。

请求体

调用示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/tools" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "查询工具",
    "kind": "http_api",
    "side_effect_class": "read"
  }'

参数说明

参数	类型	是否必填	说明
name	string	是	工具名称。
description	string	否	工具描述和展示分类。
status	string	否	工具描述和展示分类。
kind	string	否	工具描述和展示分类。
category	string	否	工具描述和展示分类。
icon_ref	string	否	工具描述和展示分类。
tags	array of string	否	工具描述和展示分类。
phase	string	否	工具描述和展示分类。
market_metadata	object	否	工具市场展示和分发元数据。
source_ref	object	否	工具来源；可包含 type、id、uri、version 和 config。
input_schema	object	否	输入和输出 JSON Schema。
output_schema	object	否	输入和输出 JSON Schema。
side_effect_class	string	否	副作用分类：read、write 或 external_effect。
credential_ref	string	否	凭据、审批和脱敏策略引用。
approval_policy_ref	string	否	凭据、审批和脱敏策略引用。
redaction_policy_ref	string	否	凭据、审批和脱敏策略引用。
sync	object	否	同步状态，可包含 status、last_sync_at 和 last_sync_error。
labels	object	否	扩展标签、注释和元数据。
annotations	object	否	扩展标签、注释和元数据。
metadata	object	否	扩展标签、注释和元数据。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "id": "tool_01",
    "workspace_id": "ws_01",
    "name": "查询工具",
    "status": "draft",
    "kind": "http_api",
    "side_effect_class": "read",
    "version": 1,
    "bindable": true,
    "supported_runtimes": [],
    "created_at": "2026-01-02T15:04:05Z",
    "updated_at": "2026-01-02T15:04:05Z"
  }
}

字段说明

成功时返回 201。

响应字段如下。

通用字段

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

基本信息

字段	类型	说明
id	string	工具 ID、所属工作区和名称。
workspace_id	string	工具 ID、所属工作区和名称。
name	string	工具 ID、所属工作区和名称。
status	string	工具状态、类别和副作用分类。
kind	string	工具状态、类别和副作用分类。
side_effect_class	string	工具状态、类别和副作用分类。
source_ref	object	来源、输入 Schema 和输出 Schema；未设置时不返回。
input_schema	object	来源、输入 Schema 和输出 Schema；未设置时不返回。
output_schema	object	来源、输入 Schema 和输出 Schema；未设置时不返回。
version	integer	工具资源版本。
bindable	boolean	当前绑定能力、不可绑定原因和支持的运行环境。
bindability_reason	string	当前绑定能力、不可绑定原因和支持的运行环境。
supported_runtimes	array of string	当前绑定能力、不可绑定原因和支持的运行环境。
created_at	string	创建和最近更新时间，使用 RFC 3339 格式。
updated_at	string	创建和最近更新时间，使用 RFC 3339 格式。

错误响应

响应示例

{
  "code": 2,
  "message": "<错误信息>"
}

字段说明

常见 HTTP 错误

通用字段

字段	类型	说明
400	2（INVALID_ARGUMENT）	**常见原因：**请求体、工具定义或凭据引用无效。**建议操作：**检查字段值和关联资源。
401	6（UNAUTHENTICATED）	**常见原因：**缺少有效身份凭据。**建议操作：**检查 API Key。
403	5（PERMISSION_DENIED）	**常见原因：**当前身份没有在工作区中创建工具的权限。**建议操作：**检查工作区授权。
409	4（ALREADY_EXISTS）	**常见原因：**工具 ID 或工具定义已存在。**建议操作：**更换工具 ID 或检查已有工具。
503	15（UNAVAILABLE）	**常见原因：**工具资源服务或授权依赖暂不可用。**建议操作：**稍后重试。

后续操作

创建完成后查询工具详情确认结果。

最后更新于 2026 年 9 月 11 日