---

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

orphan: true
---

# 创建智能体任务模板

创建供工作流节点调用的智能体任务模板。创建成功仅保存模板，不会执行智能体任务。

```text
POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/agent-task-templates
```

## 调用前准备

准备个人访问令牌、工作区 ID 和已存在的智能体 ID。

## 路径参数

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

## 请求体

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

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/agent-task-templates" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "'$AGENT_ID'",
    "name": "摘要任务",
    "message_template": {"template": "请总结输入内容"}
  }'
```

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

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `agent_id` | string | 是 | 目标智能体 ID。 |
| `name` | string | 是 | 模板名称。 |
| `message_template` | object | 是 | 任务消息模板。 |
| `description` | string | 否 | 模板说明。 |
| `input_schema` | object | 否 | 输入结构定义。 |
| `default_context_refs` | array | 否 | 默认上下文引用。 |
| `runtime_policy_ref` | string | 否 | 运行策略引用。 |
| `idempotency_policy` | object | 否 | 幂等策略。 |
| `output_contract` | object | 否 | 输出契约。 |
| `status` | string | 否 | 模板状态。 |
| `labels` | object | 否 | 标签键值对。 |
| `annotations` | object | 否 | 注解键值对。 |

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

## 成功响应

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

```json
{"code": 0, "data": {"id": "template_01", "agent_id": "agent_01", "name": "摘要任务"}}
```

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

成功时返回 `201` 和新建模板。



响应字段如下。

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

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

:::

:::{tab-item} 基本信息

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 新建模板 ID。 |
| `agent_id` | string | 关联智能体 ID。 |
| `name` | string | 模板名称。 |

:::
::::

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

## 错误响应

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

```json
{"code": 2, "message": "invalid agent task template"}
```

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

### 常见 HTTP 错误

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `400` | `2` | **常见原因：**请求体或模板引用无效。**建议操作：**检查智能体 ID 和消息模板。 |
| `409` | `4` | **常见原因：**模板标识或工作流节点关联已存在。**建议操作：**改用新的标识或查询现有资源。 |

:::
::::

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

## 后续操作

保存 `data.id`，再[创建智能体工作流绑定](../workflow-bindings/create-workflow-binding.md)。