创建工具

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

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

调用前准备

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

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：要创建工具的工作区 ID，通过 X-Workspace-ID Header 传递。

路径参数

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

请求体

字段	类型	是否必填	说明
name	string	是	工具名称。
description	string	否	工具描述和展示分类。
status	string	否	工具描述和展示分类。
kind	string	否	工具描述和展示分类。
category	string	否	工具描述和展示分类。
icon_ref	string	否	工具描述和展示分类。
tags	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	否	扩展标签、注释和元数据。

请求示例

curl -X POST "https://moi.matrixorigin.cn/newmoi/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"
  }'

成功响应

成功时返回 201。

{
  "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"
  }
}

响应字段如下。

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

错误响应

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

常见 HTTP 错误

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

后续操作

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

最后更新于 2026 年 8 月 22 日