运行自动化任务并读取历史记录¶

触发自动化任务后，保存返回的历史记录 ID，并使用它查询状态、结果和事件。触发请求被接受只表示历史记录已经创建或进入队列，不表示智能体已经完成任务。

开始之前¶

已创建并启用自动化任务；
已根据任务的 trigger.mode 取得任务 ID 或服务名称；
本次 payload 符合任务配置的输入 Schema；
已评估任务可能调用的外部工具、写入操作和模型用量。

选择运行方式¶

场景	使用方式	需要保存的值
调用 API 类型任务	按服务名称调用 Dynamic Service	历史记录 ID `run_id`
手动验证已有任务	对任务 ID 创建一次运行	历史记录的 `id`
等待计划触发	从任务或工作区历史记录列表查找新记录	历史记录的 `id`
由第三方事件触发	检查回调规则目标，再查询历史记录列表	历史记录的 `id`

调用 API 类型任务¶

服务名称仅在任务响应或详情中的 api_summary.service_name 存在时可用。不要根据任务名称自行拼接：

curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/dynamic-services/invoke" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "service_name": "<SERVICE_NAME>",
    "payload": {
      "input": "Summarize this incident report"
    }
  }'

命中自动化任务时，接口返回已创建历史记录的标识和初始状态。保存 data.run_id；如果响应提供 result_url，仍应先根据状态判断结果是否已经可读取。

手动运行任务¶

下面的请求对已有 Cron 任务创建一次手动运行，适合联调计划任务：

curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-automation-tasks/<TASK_ID>/runs" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"input":"test"}}'

请求成功后，从 data.id 保存历史记录 ID。手动运行不会改变任务的 Cron 配置。

查询历史记录状态¶

curl \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-automation-runs/<RUN_ID>" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

状态	含义	调用方动作
`queued`	历史记录已经创建，任务尚未开始运行	有界等待后再次查询。
`running`	智能体正在执行	继续查询；需要定位进度时读取事件。
`input_required`	运行需要补充输入	检查事件和任务设计；不要继续无条件轮询。
`pending_approval`	运行等待批准	按当前产品提供的批准入口处理。
`succeeded`	运行成功终止	读取最终结果。
`failed`	运行失败终止	检查 `error` 和最近事件，修正后再决定是否重新运行任务。
`canceled`	运行已取消	不再等待结果；确认是否需要重新运行。
`expired`	历史记录已经过期	检查任务和依赖耗时，再重新运行任务。

轮询时设置总等待时间和最大次数。不要对写入或具有外部副作用的任务自动无限重试。

读取结果¶

历史记录进入 succeeded 后读取结果：

curl \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-automation-runs/<RUN_ID>/result" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

字段	返回条件	说明
`final_text`	运行产生最终文本时	面向读者的最终文本结果。
`structured_output`	运行产生结构化输出时	应结合任务的输出契约解析。
`output_validation_status`	配置或执行输出校验时	表示结构化输出是否通过校验。
`output_validation_error`	输出校验失败时	用于定位不符合输出契约的字段。
`artifact_refs`	本次运行产生可引用产物时	指向本次运行输出的资源引用；它不是工作流 ArtifactHandle。
`error`	本次运行失败或结果包含错误时	保存错误代码和脱敏消息用于排查。

artifact_refs 中的引用用于定位自动化任务本次运行产生的外部或持久化结果。具体引用类型、ID、URI 和元数据由实际历史记录返回，不应假定每次运行都有 Artifact。

查看历史记录事件¶

当状态长时间不变、工具调用失败或需要了解执行顺序时，查询事件列表：

curl \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-automation-runs/<RUN_ID>/events?limit=50&offset=0" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

事件用于检查运行过程中记录的类型、状态、消息和时间。事件列表不代替最终结果；历史记录成功结束后仍应读取结果接口。

常见问题¶

现象	先检查	下一步
触发返回成功但没有结果	初始状态和历史记录 ID	查询历史记录详情，不立即重复触发。
历史记录一直处于 `queued`	创建时间、最近事件和依赖资源	设置等待上限；超出后保留历史记录 ID 和事件摘要。
运行 `failed`	`error`、输出校验错误和最近事件	修正输入、凭据或工具配置后创建新运行。
结果没有 `artifact_refs`	`final_text`、`structured_output` 和任务设计	只有运行实际产生引用型结果时才会返回该字段。

下一步¶

最后更新于 2026 年 8 月 14 日