Create automated tasks¶

Create automated tasks and specify the agents to be called, fixed instructions, and triggering methods.

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

Preparation before calling¶

First query the agent list to obtain the ID of the agent to be called. Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: The workspace ID of the task to be created, passed in the X-Workspace-ID Header and also as workspace_id in the path.
$AGENT_ID: The ID of the agent to be called, obtained through query agent list, used for agent_id in the request body.

trigger.mode supports cron, api and callback. Provide a cron expression in trigger.cron_expression when using cron; API triggering needs to be configured with the corresponding authentication policy.

Request example¶

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

Path parameters¶

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Workspace ID.

Request body¶

Parameters	Type	Is it required	Description
`name`	string	Yes	Task name.
`agent_id`	string	Yes	The ID of the agent to be called.
`instruction_text`	string	Yes	Fixed instruction used every time it is run.
`trigger`	object	Yes	Trigger configuration that contains at least `mode`.
`id`	string	No	Custom task ID.
`description`	string	No	Task description.
`agent_workspace_id`	string	No	The workspace to which the agent belongs; if not passed, the workspace in the path will be used.
`model`	string	No	The model name to use when executing the task.
`llm_backend_id`	integer	No	LLM backend ID.
`auth_policy`	object	No	The authentication policy used by the API or callback trigger.
`tool_policy_ref`	string	No	Tool policy reference.
`runtime_policy_ref`	string	No	Run policy reference.
`approval_policy_ref`	string	No	Approval policy reference.
`output_contract`	object	No	Structured output constraints.
`workflow_app_id`	string	No	The associated workflow application ID.
`agent_task_template_id`	string	No	The associated agent task template ID.
`agent_workflow_binding_id`	string	No	The associated agent workflow binding ID.
`source_type`	string	No	Task source type.
`status`	string	No	Initial task status.
`next_trigger_at`	string	No	Next trigger time, using RFC 3339 format.
`api_summary`	object	No	API summary.
`labels`	object	No	Tag key-value pair.
`annotations`	object	No	Annotation key-value pair.

Successful response¶

Returns 201 on success. Successful creation only means that the task configuration and its execution plan have been saved; whether the plan or external trigger has been run should be confirmed through the running record.

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

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.id`	string	New task, workspace, and target agent identifiers.
`data.workspace_id`	string	New task, workspace, and target agent identifiers.
`data.agent_workspace_id`	string	New task, workspace, and target agent identifiers.
`data.agent_id`	string	New task, workspace, and target agent identifiers.
`data.name`	string	Task name, trigger configuration, initial status and version.
`data.trigger`	object	Task name, trigger configuration, initial state and version.
`data.status`	string	Task name, trigger configuration, initial status and version.
`data.version`	integer	Task name, trigger configuration, initial status and version.
`data.next_trigger_at`	string	Next scheduled trigger time; returned when computable, using RFC 3339 format.
`data.execution`	object	The saved task execution plan.
`data.created_at`	string	Creation and last update times, using RFC 3339 format.
`data.updated_at`	string	Creation and last update times, using RFC 3339 format.

Error response¶

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

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	Invalid task name, agent, trigger configuration, authentication policy, or workspace scope.	Check the configuration required for request fields and triggering methods.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity has not been verified for workspace access and valid roles.	Use an identity and a valid role with access to the workspace.
`404`	`3`（`NOT_FOUND`）	The target agent does not exist.	Check `agent_id` and `agent_workspace_id`.
`409`	`4`（`ALREADY_EXISTS`）	The specified task ID already exists, or the task status conflicts.	Change the task ID or refresh the task status and try again.
`503`	`15`（`UNAVAILABLE`）	Execution plan, workflow or task services are temporarily unavailable.	Try again later.

Follow-up operations¶

Log data.id. When immediate execution is required Start automated task running; other triggering methods save the task ID and use the accepted running details, events or result interfaces to confirm the running status.

Last updated on Sep 3, 2026