# 创建工具

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```


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

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

## 调用前准备

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

## 路径参数

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

## 请求体

`labels` 和 `annotations` 要求 JSON 对象，其值只能为字符串或 `null`。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 调用示例

```bash
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"
  }'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 否 | 自定义工具标识；省略或空字符串时由服务端生成。 |
| `name` | string | 是 | 工具名称。 |
| `description` | string | 否 | 工具描述和展示分类。 |
| `status` | string | 否 | 工具描述和展示分类。 |
| `kind` | string | 是 | 工具类型：`system`、`http_api`、`operator`、`market` 或 `code`。MCP 工具通过批量注册接口创建。 |
| `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 | 否 | 扩展标签、注释和元数据。 |

:::::
::::::
:::::::

## 成功响应

请求成功时返回以下结果。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "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",
    "display_name": "示例工具",
    "source_ref": {},
    "sync": {}
  }
}
```

:::::
:::::{tab-item} 字段说明

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功时为 `0`。 |
| `data` | object | 本次请求的结果。 |
| `data.id` | string | 资源标识。始终返回。 |
| `data.workspace_id` | string | 所属工作区标识。始终返回。 |
| `data.name` | string | 名称。始终返回。 |
| `data.description` | string | 说明。为空或未设置时可省略。 |
| `data.display_name` | string | 展示名称。始终返回。 |
| `data.display_description` | string | 展示说明。为空或未设置时可省略。 |
| `data.status` | string | 状态。可取 `draft`、`active`、`disabled`、`archived`。始终返回。 |
| `data.kind` | string | 工具类型。可取 `system`、`mcp`、`http_api`、`operator`、`market`、`code`。始终返回。 |
| `data.category` | string | 分类。为空或未设置时可省略。 |
| `data.icon_ref` | string | 图标引用。为空或未设置时可省略。 |
| `data.tags` | array | 标签。为空或未设置时可省略。 |
| `data.phase` | string | 使用阶段。为空或未设置时可省略。 |
| `data.market_metadata` | object | 市场元数据。为空或未设置时可省略。 |
| `data.source_ref` | object | 来源信息。始终返回。没有子字段时返回空对象。 |
| `data.source_ref.type` | string | 来源类型。为空或未设置时可省略。 |
| `data.source_ref.id` | string | 资源标识。为空或未设置时可省略。 |
| `data.source_ref.uri` | string | 来源地址。为空或未设置时可省略。 |
| `data.source_ref.version` | string | 版本号。为空或未设置时可省略。 |
| `data.source_ref.config` | object | 资源配置。为空或未设置时可省略。 |
| `data.input_schema` | object | 工具输入 JSON Schema。为空或未设置时可省略。 |
| `data.output_schema` | object | 工具输出 JSON Schema。为空或未设置时可省略。 |
| `data.side_effect_class` | string | 副作用分类。可取 `read`、`write`、`external_effect`。始终返回。 |
| `data.credential_ref` | string | 凭据引用。为空或未设置时可省略。 |
| `data.approval_policy_ref` | string | 审批策略引用。为空或未设置时可省略。 |
| `data.redaction_policy_ref` | string | 脱敏策略引用。为空或未设置时可省略。 |
| `data.sync` | object | 同步信息。始终返回。没有子字段时返回空对象。 |
| `data.sync.status` | string | 状态。为空或未设置时可省略。 |
| `data.sync.last_sync_at` | string 或 null | 最近同步时间。为空或未设置时可省略。 |
| `data.sync.last_sync_error` | string | 最近同步错误。为空或未设置时可省略。 |
| `data.version` | integer | 版本号。始终返回。 |
| `data.labels` | object | 扩展标签。为空或未设置时可省略。 |
| `data.annotations` | object | 扩展注释。为空或未设置时可省略。 |
| `data.metadata` | object | 扩展元数据。为空或未设置时可省略。 |
| `data.bindable` | boolean | 是否可绑定。始终返回。 |
| `data.bindability_reason` | string | 绑定能力说明。为空或未设置时可省略。 |
| `data.supported_runtimes` | array | 支持的运行时。为空或未设置时可省略。 |
| `data.created_by` | string | 创建者标识。为空或未设置时可省略。 |
| `data.updated_by` | string | 最近更新者标识。为空或未设置时可省略。 |
| `data.created_at` | string | 创建时间。使用 RFC 3339 格式。始终返回。 |
| `data.updated_at` | string | 最近更新时间。使用 RFC 3339 格式。始终返回。 |

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

### 常见 HTTP 错误

::::{tab-set}
:::{tab-item} 通用字段

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

:::
::::

:::::
::::::
:::::::

## 后续操作

创建完成后[查询工具详情](get-tool.md)确认结果。