管理自动化任务

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

任务流程

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

准备

  1. 已完成 使用 SDK 中的服务地址、个人访问令牌与工作区配置。

  2. 通过 发现与选择智能体 获取目标智能体 ID(AGENT_ID)及所属工作区 ID(AGENT_WORKSPACE_ID)。

  3. 确定执行模型标识(AGENT_MODEL),可通过 查看模型后端与端点 或调用 service.resource_get("llm", "/models", sdk.with_query_param("type", "chat")) 查询。

  4. 准备唯一的任务 ID(AUTOMATION_TASK_ID)、任务名称(AUTOMATION_NAME)、固定指令(AUTOMATION_INSTRUCTION)和 Cron 表达式(CRON_EXPRESSION)。建议先以 disabled 状态创建任务,核对配置无误后再启用;启用后的定时运行会自动调用模型和已授权工具。

创建并读取任务

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

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"))
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 读取任务状态再决定后续操作。

更新计划并启用

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

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"))
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"])

查询运行历史

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

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

手动运行并查询结果

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

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)
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 中的结构化输出校验结果、错误信息与生成产物。

停用与归档任务

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

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"))
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)归档任务。归档操作保留任务定义与历史运行记录,并将任务状态更新为已归档:

service.resource_delete("agent-automation-tasks", "/" + task_id)
saved = service.resource_get("agent-automation-tasks", "/" + task_id)
print("Archived task:", saved["id"], saved["status"])
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"])

限制和注意事项

  • 工作区运行列表 agent-automation-runs 按工作区范围筛选,按单任务筛选运行记录请访问 agent-automation-tasks/<task_id>/runs。并发产生新运行时,偏移分页结果可按运行 id 去重。

  • 停用或归档任务会停止后续定时触发,已在执行中的运行仍按各自的 run_id 独立推进至终态。后续若需新建同名任务,需分配新的任务 ID。

下一步

最后更新于