创建智能体任务模板

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

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-task-templates

调用前准备

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

请求体

输入示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/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": "请总结输入内容"
    }
  }'

参数说明

参数	类型	是否必填	说明
workspace_id	string	是	目标工作区 ID。
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	否	注解键值对。
message_template.role	string	否	消息角色，省略时使用 user。
message_template.template	string	条件必填	非空消息模板文本。与非空 parts 至少提供一项。
message_template.parts	array of object 或 null	条件必填	消息组成项。每项可为对象或 null。
message_template.variables	object 或 null	否	模板变量。
default_context_refs[].type	string	有引用时必填	上下文资源类型。
default_context_refs[].id	string	条件必填	资源 ID。与 uri 至少提供一项。
default_context_refs[].uri	string	条件必填	资源地址。与 id 至少提供一项。
default_context_refs[].version	string	否	资源版本。
default_context_refs[].config	object 或 null	否	资源配置。
idempotency_policy.mode	string	否	none、workflow_case 或 custom。
idempotency_policy.key_template	string	custom 时必填	非空幂等键模板。
idempotency_policy.window_seconds	integer	否	幂等窗口秒数。负值按 0 处理。
id	string	否	模板 ID。省略或空值时生成。

上下文引用的类型、ID、地址和版本不能带首尾空白，ID 不能包含路径分隔符。服务只校验引用格式，不检查每项资源是否存在。幂等策略省略时使用 workflow_case。custom 模式须提供非空的幂等键模板。

状态省略时使用 draft。关联智能体和非空运行策略引用必须在当前工作区存在。创建成功只保存模板，不会检查所有上下文引用或启动任务。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "id": "template_01",
    "workspace_id": "workspace_example",
    "agent_id": "agent_01",
    "name": "摘要任务",
    "message_template": {
      "role": "user",
      "template": "请总结输入内容"
    },
    "idempotency_policy": {
      "mode": "workflow_case"
    },
    "status": "draft",
    "version": 1,
    "created_at": "2026-10-14T00:00:00Z",
    "updated_at": "2026-10-14T00:00:00Z"
  }
}

字段说明

字段	类型	说明
code	integer	请求处理成功时为 0。
data	object	响应数据。
data.id	string	对象 ID。
data.workspace_id	string	所属工作区 ID。
data.agent_id	string	关联的智能体 ID。
data.name	string	名称。
data.description	string	说明。未设置时可省略。
data.message_template	object	消息模板。
data.input_schema	object	输入参数的 JSON Schema。未设置时可省略。
data.default_context_refs	object（对象数组）	默认上下文资源引用。未设置时可省略。
data.default_context_refs[].id	string	对象 ID。
data.runtime_policy_ref	string	运行策略引用。未设置时可省略。
data.idempotency_policy	object	幂等策略。
data.idempotency_policy.mode	string	策略或范围模式。取值：none、workflow_case、custom。
data.idempotency_policy.key_template	string	自定义幂等键模板。未设置时可省略。
data.idempotency_policy.window_seconds	integer	幂等窗口，单位为秒。未设置时可省略。
data.output_contract	object	输出约定。未设置时可省略。
data.status	string	当前状态。取值：draft、active、disabled、archived。
data.version	integer	当前版本号。
data.labels	object	标签键值对。未设置时可省略。
data.annotations	object	扩展注解。未设置时可省略。
data.created_by	string	创建者标识。未设置时可省略。
data.updated_by	string	最近更新者标识。未设置时可省略。
data.created_at	string	创建时间，采用 RFC 3339 格式。
data.updated_at	string	最近更新时间，采用 RFC 3339 格式。
data.message_template.role	string	消息角色。
data.message_template.template	string	消息模板文本。使用 parts 时可省略。
data.message_template.parts	array 或 null	结构化消息组成项，内容由模板保留。
data.message_template.variables	object 或 null	模板变量。
data.default_context_refs[].type	string	上下文资源类型。
data.default_context_refs[].uri	string	资源地址。使用 id 时可省略。
data.default_context_refs[].version	string	资源版本。未设置时省略。
data.default_context_refs[].config	object 或 null	资源配置。未设置时省略。

错误响应

响应示例

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

字段说明

常见 HTTP 错误

HTTP 状态码	错误代码	说明
400	2	**常见原因：**请求体或模板引用无效。**建议操作：**检查智能体 ID 和消息模板。
409	4	**常见原因：**模板标识或工作流节点关联已存在。**建议操作：**改用新的标识或查询现有资源。

最后更新于 2026 年 10 月 19 日