# 管理自动化任务

为选定智能体创建带固定指令与定时计划（Cron）的自动化任务，更新触发计划并启用调度，查询历史或手动运行结果，并在任务退役时停用或归档。

(sdk-ai-studio-automation-flow)=
## 任务流程

```text
以停用状态创建自动化任务并回读配置
                │
                ▼
更新 Cron 触发计划并将状态切换为 active
                │
                ▼
查询运行历史或手动触发单次运行
                │
                ▼
停用调度（disabled）或归档任务
```

(sdk-ai-studio-automation-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. 通过 [发现与选择智能体](发现与选择智能体.md#sdk-ai-studio-agents-s1) 获取目标智能体 ID（`AGENT_ID`）及所属工作区 ID（`AGENT_WORKSPACE_ID`）。
3. 确定执行模型标识（`AGENT_MODEL`），可通过 [查看模型后端与端点](../资源中心/管理模型后端.md) 或调用 `service.resource_get("llm", "/models", sdk.with_query_param("type", "chat"))` 查询。
4. 准备唯一的任务 ID（`AUTOMATION_TASK_ID`）、任务名称（`AUTOMATION_NAME`）、固定指令（`AUTOMATION_INSTRUCTION`）和 Cron 表达式（`CRON_EXPRESSION`）。建议先以 `disabled` 状态创建任务，核对配置无误后再启用；启用后的定时运行会自动调用模型和已授权工具。

(sdk-ai-studio-automation-create)=
## 创建并读取任务

向 `agent-automation-tasks` 提交任务定义并指定客户端生成的 `id`。创建时服务端会立即校验 Cron 表达式格式，即使初始 `status` 为 `disabled` 也会执行语法检查。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
workspace_id = os.environ["WORKSPACE_ID"]
service = client.workspace(workspace_id).agents()
task_id = os.environ["AUTOMATION_TASK_ID"]

body = {
    "id": task_id,
    "name": os.environ["AUTOMATION_NAME"],
    "agent_id": os.environ["AGENT_ID"],
    "agent_workspace_id": os.environ.get("AGENT_WORKSPACE_ID", workspace_id),
    "model": os.environ["AGENT_MODEL"],
    "instruction_text": os.environ["AUTOMATION_INSTRUCTION"],
    "trigger": {
        "mode": "cron",
        "cron_expression": os.environ["CRON_EXPRESSION"],
    },
    "status": "disabled",
}
created = service.resource_post("agent-automation-tasks", "", body)
if created.get("id") != task_id:
    raise RuntimeError("Created task identity does not match")

saved = service.resource_get("agent-automation-tasks", "/" + task_id)
print("Task:", saved["id"], "Status:", saved["status"], "Version:", saved["version"])
print("Trigger:", saved["trigger"], "Next trigger:", saved.get("next_trigger_at"))
```

::::

::::{tab-item} Go
:sync: go

```go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func mustObject(data *sdk.ProductData, err error) map[string]any {
	if err != nil {
		log.Fatal(err)
	}
	value, ok := data.Value.(map[string]any)
	if !ok {
		log.Fatal("expected an object response")
	}
	return value
}

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	workspaceID := os.Getenv("WORKSPACE_ID")
	workspace, err := client.Workspace(workspaceID)
	if err != nil {
		log.Fatal(err)
	}
	service := workspace.Agents()
	taskID := os.Getenv("AUTOMATION_TASK_ID")
	agentWorkspaceID := os.Getenv("AGENT_WORKSPACE_ID")
	if agentWorkspaceID == "" {
		agentWorkspaceID = workspaceID
	}

	body := map[string]any{
		"id":                 taskID,
		"name":               os.Getenv("AUTOMATION_NAME"),
		"agent_id":           os.Getenv("AGENT_ID"),
		"agent_workspace_id": agentWorkspaceID,
		"model":              os.Getenv("AGENT_MODEL"),
		"instruction_text":   os.Getenv("AUTOMATION_INSTRUCTION"),
		"trigger": map[string]any{
			"mode":            "cron",
			"cron_expression": os.Getenv("CRON_EXPRESSION"),
		},
		"status": "disabled",
	}
	created := mustObject(service.ResourcePost(ctx, "agent-automation-tasks", "", body))
	if created["id"] != taskID {
		log.Fatal("created task identity does not match")
	}

	saved := mustObject(service.ResourceGet(ctx, "agent-automation-tasks", "/"+taskID))
	fmt.Println("Task:", saved["id"], "Status:", saved["status"], "Version:", saved["version"])
	fmt.Println("Trigger:", saved["trigger"], "Next trigger:", saved["next_trigger_at"])
}
```

::::

:::::

保存返回的 `id` 作为后续读取、修改和查询运行记录的唯一标识。若创建请求因网络中断未能确认结果，先按同一 `task_id` 读取任务状态再决定后续操作。

(sdk-ai-studio-automation-enable)=
## 更新计划并启用

设置新的计划表达式（`NEW_CRON_EXPRESSION`，例如带时区声明的 `TZ=UTC 0 9 * * *`）。接续上例提取 `trigger` 中的可编辑字段（`mode`、`cron_expression`、`result_mode`、`input_schema`、`config`），将 `status` 设为 `active` 后提交更新，并回读确认 `next_trigger_at`：

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
editable_keys = ("mode", "cron_expression", "result_mode", "input_schema", "config")
trigger = {key: value for key, value in saved["trigger"].items() if key in editable_keys}
trigger["cron_expression"] = os.environ["NEW_CRON_EXPRESSION"]

service.resource_patch(
    "agent-automation-tasks",
    "/" + task_id,
    {"trigger": trigger, "status": "active"},
)
saved = service.resource_get("agent-automation-tasks", "/" + task_id)
print(saved["status"], saved["version"], saved["trigger"], saved.get("next_trigger_at"))
```

::::

::::{tab-item} Go
:sync: go

```go
trigger := map[string]any{}
previous, _ := saved["trigger"].(map[string]any)
for _, key := range []string{"mode", "cron_expression", "result_mode", "input_schema", "config"} {
	if value, exists := previous[key]; exists {
		trigger[key] = value
	}
}
trigger["cron_expression"] = os.Getenv("NEW_CRON_EXPRESSION")

mustObject(service.ResourcePatch(
	ctx,
	"agent-automation-tasks",
	"/"+taskID,
	map[string]any{"trigger": trigger, "status": "active"},
))
saved = mustObject(service.ResourceGet(ctx, "agent-automation-tasks", "/"+taskID))
fmt.Println(saved["status"], saved["version"], saved["trigger"], saved["next_trigger_at"])
```

::::

:::::

(sdk-ai-studio-automation-history)=
## 查询运行历史

查询工作区全局运行记录时访问 `agent-automation-runs`；查询单个任务下的历史运行时访问 `agent-automation-tasks/<task_id>/runs`。两个路径均支持 `status`、`created_from`、`created_to`（RFC 3339 时间戳，起点包含、终点不含）以及 `limit`（默认 `50`，最大 `200`）与 `offset` 分页参数。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
workspace_page = service.resource_get(
    "agent-automation-runs",
    "",
    sdk.with_query_param("status", "succeeded"),
    sdk.with_query_param("limit", "50"),
    sdk.with_query_param("offset", "0"),
)
print("Workspace succeeded runs:", workspace_page["total"])

offset = 0
while True:
    page = service.resource_get(
        "agent-automation-tasks",
        "/" + task_id + "/runs",
        sdk.with_query_param("limit", "50"),
        sdk.with_query_param("offset", str(offset)),
    )
    for item in page["items"]:
        print(item["id"], item["status"], item["automation_task_version"])
    next_offset = page["offset"] + page["limit"]
    if not page["items"] or next_offset >= page["total"]:
        break
    offset = next_offset
```

::::

::::{tab-item} Go
:sync: go

```go
workspacePage := mustObject(service.ResourceGet(
	ctx,
	"agent-automation-runs",
	"",
	sdk.WithQueryParam("status", "succeeded"),
	sdk.WithQueryParam("limit", "50"),
	sdk.WithQueryParam("offset", "0"),
))
fmt.Println("Workspace succeeded runs:", workspacePage["total"])

for offset := 0; ; {
	page := mustObject(service.ResourceGet(
		ctx,
		"agent-automation-tasks",
		"/"+taskID+"/runs",
		sdk.WithQueryParam("limit", "50"),
		sdk.WithQueryParam("offset", fmt.Sprint(offset)),
	))
	items, _ := page["items"].([]any)
	for _, raw := range items {
		item, _ := raw.(map[string]any)
		fmt.Println(item["id"], item["status"], item["automation_task_version"])
	}
	nextOffset := int(page["offset"].(float64)) + int(page["limit"].(float64))
	if len(items) == 0 || nextOffset >= int(page["total"].(float64)) {
		break
	}
	offset = nextOffset
}
```

::::

:::::

(sdk-ai-studio-automation-run)=
## 手动运行并查询结果

对已启用的任务向 `/<task_id>/runs` 发送 `POST` 请求可立即触发一次运行。保存返回的运行 ID（`run_id`），通过 `agent-automation-runs/<run_id>`、`/events` 和 `/result` 分别读取运行状态、事件分页与终态结果：

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
run = service.resource_post("agent-automation-tasks", "/" + task_id + "/runs", {"payload": {}})
run_id = run["id"]
print("Run:", run_id, "Initial state:", run["status"])

current = service.resource_get("agent-automation-runs", "/" + run_id)
events = service.resource_get(
    "agent-automation-runs",
    "/" + run_id + "/events",
    sdk.with_query_param("limit", "20"),
    sdk.with_query_param("offset", "0"),
)
print("State:", current["status"], "Events total:", events.get("total"))

if current["status"] in ("succeeded", "failed", "canceled", "expired"):
    result = service.resource_get("agent-automation-runs", "/" + run_id + "/result")
    print("Result:", result)
```

::::

::::{tab-item} Go
:sync: go

```go
run := mustObject(service.ResourcePost(
	ctx,
	"agent-automation-tasks",
	"/"+taskID+"/runs",
	map[string]any{"payload": map[string]any{}},
))
runID, _ := run["id"].(string)
fmt.Println("Run:", runID, "Initial state:", run["status"])

current := mustObject(service.ResourceGet(ctx, "agent-automation-runs", "/"+runID))
events := mustObject(service.ResourceGet(
	ctx,
	"agent-automation-runs",
	"/"+runID+"/events",
	sdk.WithQueryParam("limit", "20"),
	sdk.WithQueryParam("offset", "0"),
))
fmt.Println("State:", current["status"], "Events total:", events["total"])

switch current["status"] {
case "succeeded", "failed", "canceled", "expired":
	result := mustObject(service.ResourceGet(ctx, "agent-automation-runs", "/"+runID+"/result"))
	fmt.Println("Result:", result)
}
```

::::

:::::

当运行尚未进入终态（`succeeded`、`failed`、`canceled`、`expired`）时，继续按同一 `run_id` 轮询状态和后续事件页；到达终态后检查 `/result` 中的结构化输出校验结果、错误信息与生成产物。

(sdk-ai-studio-automation-stop)=
## 停用与归档任务

暂停后续定时触发时，将任务 `status` 更新为 `disabled` 并回读确认：

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
service.resource_patch("agent-automation-tasks", "/" + task_id, {"status": "disabled"})
saved = service.resource_get("agent-automation-tasks", "/" + task_id)
print(saved["status"], saved.get("next_trigger_at"))
```

::::

::::{tab-item} Go
:sync: go

```go
mustObject(service.ResourcePatch(ctx, "agent-automation-tasks", "/"+taskID, map[string]any{"status": "disabled"}))
saved = mustObject(service.ResourceGet(ctx, "agent-automation-tasks", "/"+taskID))
fmt.Println(saved["status"], saved["next_trigger_at"])
```

::::

:::::

确认任务不再使用后，调用 `resource_delete`（Go 为 `ResourceDelete`）归档任务。归档操作保留任务定义与历史运行记录，并将任务状态更新为已归档：

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
service.resource_delete("agent-automation-tasks", "/" + task_id)
saved = service.resource_get("agent-automation-tasks", "/" + task_id)
print("Archived task:", saved["id"], saved["status"])
```

::::

::::{tab-item} Go
:sync: go

```go
mustObject(service.ResourceDelete(ctx, "agent-automation-tasks", "/"+taskID))
saved = mustObject(service.ResourceGet(ctx, "agent-automation-tasks", "/"+taskID))
fmt.Println("Archived task:", saved["id"], saved["status"])
```

::::

:::::

(sdk-ai-studio-automation-limit)=
## 限制和注意事项

- 工作区运行列表 `agent-automation-runs` 按工作区范围筛选，按单任务筛选运行记录请访问 `agent-automation-tasks/<task_id>/runs`。并发产生新运行时，偏移分页结果可按运行 `id` 去重。
- 停用或归档任务会停止后续定时触发，已在执行中的运行仍按各自的 `run_id` 独立推进至终态。后续若需新建同名任务，需分配新的任务 ID。

(sdk-ai-studio-automation-next)=
## 下一步

- [调用智能体与跟踪任务](调用智能体并跟踪任务.md#sdk-ai-studio-agent-task-send)
- [读取智能体会话](管理会话和消息.md#sdk-ai-studio-sessions-s1)
