Create automated tasks¶

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

HTTP
POST $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/agent-automation-tasks

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the agent list to obtain the ID of the agent to be called.

Set the operation-specific values used in the request:

$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¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/agent-automation-tasks" \
  -H "X-API-Key: $CLOUDSIGMA_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"
  }'

Parameter reference

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.

Response example

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

Field reference

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¶

Response example

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

Field reference

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 15, 2026