面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/schedule-agent-runs.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

定时运行 Agent

当同一个 Agent 需要按固定节奏反复处理任务，例如每天生成业务日报、定期巡检数据或按月汇总线索，可以用 Deployment 保存一份可重复运行的 Session 启动配置。

Deployment 本身不执行任务，而是保存可复用的 Session 启动配置。到达计划时间或手动触发时，平台会基于这份配置创建新的 Deployment Run 和 Session。不同 Run 不复用对话上下文，每次运行都会从同一批初始事件开始。

了解运行对象#

使用 Deployment 后，一个重复任务会拆成配置、启动记录、执行会话和初始事件模板。创建计划、临时补跑或排查结果时，先看当前问题属于哪一层，可以避免把“启动成功”误判为“任务完成”：

对象 说明
Deployment 保存固定的 Agent 版本、Environment、初始事件、资源、Vault 和触发计划。创建或更新后，这份配置只供后续新启动的 Run 使用。
Deployment Run 记录一次手动或定时启动。Run 成功说明平台已经创建 Session 并受理初始事件，后续 Agent 任务是否完成要继续看 Session。
Session 承载一次实际执行。模型输出、工具调用、任务状态和产物都在 Session 及其事件中查看。
Initial events 每个新 Session 收到的第一批事件。当前仅支持 user.message。

准备资源#

开始前，完成以下准备：

  • 创建方舟 API Key，并配置为 ARK_API_KEY。
  • 创建要运行的 Agent，并记录 Agent ID。
  • 创建 Environment，并记录 Environment ID。
  • 按需准备 Files、Memory Store 和 Vault。
Bash
export ARK_API_KEY="<ARK_API_KEY>"
export AGENT_ID="<AGENT_ID>"
export ENVIRONMENT_ID="<ENVIRONMENT_ID>"

配置定时计划#

schedule.expression 使用严格五段式 cron：

text
分钟 小时 日期 月份 星期

常见配置：

场景 表达式 说明
每小时整点 0 * * * * 每小时第 0 分钟运行
每天 09:00 0 9 * * * 按配置时区每天运行
工作日 09:00 0 9 * * 1-5 星期一到星期五运行
每周一 10:30 30 10 * * 1 每周一运行
每月 1 日 08:00 0 8 1 * * 当月 1 日运行

星期字段支持数字 0-7（0 和 7 都表示周日，其余对应周一至周六），也支持英文简写 SUN、MON、TUE、WED、THU、FRI、SAT（不区分大小写），并可与范围、步长组合使用，例如 5-7（周五到周日）、1,7（周一和周日）、1-7/2（周一、周三、周五、周日）。

schedule.timezone 必须是有效的 IANA 时区，例如 Asia/Shanghai、UTC 或 America/New_York。

创建 Deployment#

下面的示例适用于“每个工作日北京时间 09:00 生成业务日报”的场景。schedule.timezone 取值为 Asia/Shanghai，表示 cron 表达式里的 09:00 使用北京时间。

Bash
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/deployments" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
    "name": "工作日业务日报",
    "agent": "$AGENT_ID",
    "environment_id": "$ENVIRONMENT_ID",
    "initial_events": [
      {
        "type": "user.message",
        "content": [
          {
            "type": "text",
            "text": "分析昨日业务数据，生成日报并列出异常指标。"
          }
        ]
      }
    ],
    "schedule": {
      "type": "cron",
      "expression": "0 9 * * 1-5",
      "timezone": "Asia/Shanghai"
    }
}
EOF

示例中的关键配置如下：

  • agent：填写 Agent ID。服务端会固定请求受理时的当前有效版本。
  • environment_id：指定每次运行使用的 Environment。
  • initial_events：指定每次 Session 启动后收到的第一条用户消息。
  • schedule.expression：设置工作日 09:00 触发。
  • schedule.timezone：指定 cron 表达式使用的时区。

创建成功返回 deployment 对象。记录 id，后续查询、运行和管理都要使用：

Bash
export DEPLOYMENT_ID="<DEPLOYMENT_ID>"

调用创建接口后，平台只是保存这份配置，不会立刻启动 Session。配置了 schedule 时，Deployment 从下一个计划时间开始触发；省略 schedule 时，只能通过立即运行接口手动触发。

立即运行 Deployment#

创建定时计划后，通常可以等待平台在计划时间自动触发。立即运行主要用于两类情况：刚创建或更新 Deployment 后，先确认 Agent、Environment、资源和初始事件能顺利启动；计划外需要补跑一次任务。

Bash
curl -sS --fail-with-body -X POST "https://ark.cn-beijing.volces.com/api/v3/deployments/$DEPLOYMENT_ID/run" \
  -H "Authorization: Bearer $ARK_API_KEY"

接口会等到 Session 创建完成、初始事件受理完成，并把这次启动的最终状态写入 Run。启动成功时，返回类似下面的 Deployment Run：

json
{
  "type": "deployment_run",
  "id": "drun-20261027000103-8k2mq",
  "deployment_id": "depl-20261027000103-4rt6u",
  "agent": {
    "type": "agent",
    "id": "agent-20261027000103-2c7v9",
    "version": 3
  },
  "created_at": "2026-10-27T01:00:03Z",
  "trigger_context": {
    "type": "manual"
  },
  "session_id": "sesn-20261027000104-7v5n1"
}

重点关注以下字段：

  • id：Deployment Run ID。
  • session_id：本次运行创建的 Session ID。
  • trigger_context.type：手动运行时为 manual。

记录返回值：

Bash
export DEPLOYMENT_RUN_ID="<DEPLOYMENT_RUN_ID>"
export SESSION_ID="<SESSION_ID>"

查询运行结果#

查询 Run 详情#

查询指定 Run 的触发来源和启动结果：

Bash
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/deployment_runs/$DEPLOYMENT_RUN_ID" \
  -H "Authorization: Bearer $ARK_API_KEY"

成功启动的 Run 会返回 session_id：

json
{
  "type": "deployment_run",
  "id": "drun-20261027000103-8k2mq",
  "deployment_id": "depl-20261027000103-4rt6u",
  "created_at": "2026-10-27T01:00:03Z",
  "trigger_context": {
    "type": "schedule",
    "scheduled_at": "2026-10-27T01:00:00Z"
  },
  "session_id": "sesn-20261027000104-7v5n1"
}

启动失败时，Run 会返回 error：

json
{
  "type": "deployment_run",
  "id": "drun-20261027000105-3m5n8",
  "deployment_id": "depl-20261027000103-4rt6u",
  "created_at": "2026-10-27T01:00:03Z",
  "trigger_context": {
    "type": "schedule",
    "scheduled_at": "2026-10-27T01:00:00Z"
  },
  "error": {
    "type": "InvalidFile.NotFound",
    "message": "file_id file-xxx not found or not accessible"
  }
}

排查时按下面的字段组合判断状态：

session_id error 含义
有值 不返回 Session 已经创建，初始事件已经受理；继续查询 Session 判断任务进展。
不返回 有值 启动失败。根据 error.type 和 error.message 排查；如果失败发生在初始事件阶段，Session 可能已经创建。
不返回 不返回 Run 还在启动中。

查询 Run 列表#

按 Deployment 查询历史 Run：

Bash
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/deployment_runs?deployment_id=$DEPLOYMENT_ID&limit=2" \
  -H "Authorization: Bearer $ARK_API_KEY"

定时 Run 的 trigger_context.type 为 schedule，scheduled_at 表示原定触发时间，不包含实际调度延迟。手动 Run 的类型为 manual，不返回 scheduled_at。

还有更多结果时，响应通过 next_page 返回下一页标识。继续查询时，将该值原样传入 page，不要解析、修改或自行生成。最后一页不返回 next_page，此时停止翻页。

查看 Session 执行结果#

Run 成功后，使用 session_id 查询 Session。Run 详情只能说明启动阶段是否成功；任务是否完成、模型是否报错、工具是否执行成功，都以 Session 状态和事件为准。Deployment 创建的 Session 会记录来源 Deployment ID。

详情请参见 管理 Session 和 Session 事件流。

更新运行配置#

以下示例将运行时间改为工作日 12:00：

Bash
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/deployments/$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "工作日午间业务日报",
    "schedule": {
      "type": "cron",
      "expression": "0 12 * * 1-5",
      "timezone": "Asia/Shanghai"
    }
  }'

更新接口是局部更新；请求里省略的字段保持原值：

  • description：传 null 或空字符串时清空。
  • schedule：传 null 时移除定时计划，保留手动运行能力。
  • resources、vault_ids、tags：传 null 或空数组时清空。
  • initial_events：不能传 null 或空数组。

更新后的配置只会被后续新受理的 Run 使用。已经受理的 Run 和已创建的 Session 不会被改写，它们继续使用受理时的配置快照。

管理生命周期#

暂停定时触发#

Bash
curl -sS --fail-with-body -X POST "https://ark.cn-beijing.volces.com/api/v3/deployments/$DEPLOYMENT_ID/pause" \
  -H "Authorization: Bearer $ARK_API_KEY"

暂停只停止后续定时触发，不会中断已经受理或正在运行的 Session。需要临时补跑时，暂停期间仍可调用立即运行接口。

恢复定时触发#

Bash
curl -sS --fail-with-body -X POST "https://ark.cn-beijing.volces.com/api/v3/deployments/$DEPLOYMENT_ID/unpause" \
  -H "Authorization: Bearer $ARK_API_KEY"

恢复时，平台会重新校验固定的 Agent 版本、Environment、Vault 和 Memory Store。type=file 资源是否可访问，仍在下一次 Run 启动时校验。恢复不会补跑暂停期间错过的计划，Deployment 会从下一个计划时间继续触发。

归档 Deployment#

Bash
curl -sS --fail-with-body -X POST "https://ark.cn-beijing.volces.com/api/v3/deployments/$DEPLOYMENT_ID/archive" \
  -H "Authorization: Bearer $ARK_API_KEY"

归档会停止后续触发。归档后，Deployment 不能更新、恢复或手动运行，但仍可以查询 Deployment、历史 Run 和关联 Session。

了解配置限制#

配置 上限 说明
initial_events 50 条 至少 1 条，当前仅支持 user.message。
resources 500 项 Memory Store 最多 10 个。自托管 Environment 不支持挂载资源。
vault_ids 50 个 每个 Vault 必须属于当前账号和项目。
tags 50 项 标签键最长 128 字符，标签值最长 256 字符。
Agent 树模型资源 1～50 个 主 Agent 和 Subagent 必须至少引用一个模型，且模型提供方必须为方舟。
推理接入点类型 不可混用 同一 Agent 树不能同时使用自定义推理接入点和预置接入点。
Run 配置快照 1 MiB 超出时，创建或更新接口返回 HTTP 413。

模型资源、文件可用性和临时凭据都会在 Run 启动时校验，所以创建 Deployment 不等于后续 Run 一定能启动成功。Agent 配置失效、文件无法访问或临时凭据获取失败时，Run 会失败；如果错误不可恢复，Deployment 还会被自动暂停。

如果挂载 type=file 资源，创建、更新或恢复 Deployment 时，平台只校验 file_id 和 mount_path 的格式。文件是否存在、当前账号是否仍有权限，会在每次 Run 启动时检查。校验失败时，本次 Run 失败，Deployment 也会自动暂停。