管理自动化任务¶
为选定智能体创建带固定指令与定时计划(Cron)的自动化任务,更新触发计划并启用调度,查询历史或手动运行结果,并在任务退役时停用或归档。
任务流程¶
以停用状态创建自动化任务并回读配置
│
▼
更新 Cron 触发计划并将状态切换为 active
│
▼
查询运行历史或手动触发单次运行
│
▼
停用调度(disabled)或归档任务
准备¶
已完成 使用 SDK 中的服务地址、个人访问令牌与工作区配置。
通过 发现与选择智能体 获取目标智能体 ID(
AGENT_ID)及所属工作区 ID(AGENT_WORKSPACE_ID)。确定执行模型标识(
AGENT_MODEL),可通过 查看模型后端与端点 或调用service.resource_get("llm", "/models", sdk.with_query_param("type", "chat"))查询。准备唯一的任务 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。