创建自动化任务

创建自动化任务并指定要调用的智能体、固定指令和触发方式。

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

调用前准备

先查询智能体列表取得要调用的智能体 ID。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

trigger.mode 支持 cron、api 和 callback。使用 cron 时在 trigger.cron_expression 提供 Cron 表达式；API 触发需要与相应认证策略一起配置。

请求体

请求示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agent-automation-tasks" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "每日摘要",
    "agent_id": "'"$AGENT_ID"'",
    "instruction_text": "汇总当天的输入内容。",
    "trigger": {
      "mode": "cron",
      "cron_expression": "0 9 * * *"
    },
    "status": "active"
  }'

字段说明

请求字段

字段	类型	必填	说明
name	string	是	任务名称。
agent_id	string	是	要调用的智能体 ID。
instruction_text	string	是	每次运行时使用的固定指令。
trigger	object	是	触发配置，至少包含 mode。
id	string	否	自定义任务 ID。
description	string	否	任务说明。
agent_workspace_id	string	否	智能体所属工作区；不传时使用路径中的工作区。
model	string	否	执行任务时使用的模型名称。
llm_backend_id	integer	否	LLM 后端 ID。
auth_policy	object	否	API 或回调触发使用的认证策略。
tool_policy_ref	string	否	工具策略引用。
runtime_policy_ref	string	否	运行策略引用。
approval_policy_ref	string	否	审批策略引用。
output_contract	object	否	结构化输出约束。
workflow_app_id	string	否	关联的工作流应用 ID。
agent_task_template_id	string	否	关联的智能体任务模板 ID。
agent_workflow_binding_id	string	否	关联的智能体工作流绑定 ID。
source_type	string	否	任务来源类型。
status	string	否	初始任务状态。
next_trigger_at	string	否	下次触发时间，使用 RFC 3339 格式。
api_summary	object	否	API 摘要。
labels	object	否	标签键值对。
annotations	object	否	注解键值对。

请求参数

请求示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agent-automation-tasks" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "每日摘要",
    "agent_id": "'"$AGENT_ID"'",
    "instruction_text": "汇总当天的输入内容。",
    "trigger": {
      "mode": "cron",
      "cron_expression": "0 9 * * *"
    },
    "status": "active"
  }'

参数说明

路径参数

字段	类型	必填	说明
workspace_id	string	是	工作区 ID。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "id": "task_01",
    "workspace_id": "ws_01",
    "agent_workspace_id": "ws_01",
    "name": "每日摘要",
    "agent_id": "agent_01",
    "trigger": {
      "mode": "cron",
      "cron_expression": "0 9 * * *"
    },
    "status": "active",
    "version": 1,
    "next_trigger_at": "2026-08-19T01:00:00Z",
    "created_at": "2026-08-18T01:00:00Z",
    "updated_at": "2026-08-18T01:00:00Z"
  }
}

字段说明

成功时返回 201。创建成功仅表示任务配置及其执行计划已保存；计划或外部触发是否已运行，应通过运行记录确认。

通用字段

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

响应数据

字段	类型	说明
data.id	string	新任务、工作区及目标智能体标识。
data.workspace_id	string	新任务、工作区及目标智能体标识。
data.agent_workspace_id	string	新任务、工作区及目标智能体标识。
data.agent_id	string	新任务、工作区及目标智能体标识。
data.name	string	任务名称、触发配置、初始状态和版本。
data.trigger	object	任务名称、触发配置、初始状态和版本。
data.status	string	任务名称、触发配置、初始状态和版本。
data.version	integer	任务名称、触发配置、初始状态和版本。
data.next_trigger_at	string	下次计划触发时间；可计算时返回，使用 RFC 3339 格式。
data.execution	object	保存后的任务执行计划。
data.created_at	string	创建和最近更新时间，使用 RFC 3339 格式。
data.updated_at	string	创建和最近更新时间，使用 RFC 3339 格式。

错误响应

响应示例

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

字段说明

常见 HTTP 错误

字段	类型	说明
400	2（INVALID_ARGUMENT）	任务名称、智能体、触发配置、认证策略或工作区范围无效。建议：检查请求字段及触发方式需要的配置。
401	6（UNAUTHENTICATED）	缺少有效身份凭据。建议：检查 API Key。
403	5（PERMISSION_DENIED）	当前身份没有经过工作区访问和有效角色校验。建议：使用具有工作区访问权限的身份和有效角色。
404	3（NOT_FOUND）	目标智能体不存在。建议：检查 agent_id 与 agent_workspace_id。
409	4（ALREADY_EXISTS）	指定的任务 ID 已存在，或任务状态发生冲突。建议：更换任务 ID 或刷新任务状态后重试。
503	15（UNAVAILABLE）	执行计划、工作流或任务服务暂不可用。建议：稍后重试。

后续操作

记录 data.id。需要立即执行时启动自动化任务运行；其他触发方式保存任务 ID 后，使用已验收的运行详情、事件或结果接口确认运行状态。

最后更新于 2026 年 9 月 28 日