# 定时运行 Agent

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

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

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

<span id="understand-objects"></span>
## 了解运行对象

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

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

> **注意**
>
> Deployment Run 只覆盖启动阶段，不覆盖 Agent 的后续执行。接口返回 `session_id` 后，继续查询 Session 详情和事件流，确认模型输出、工具调用和任务状态；不要只凭 Run 成功判断业务任务已经完成。

<span id="prepare"></span>
## 准备资源

开始前，完成以下准备：

- 创建方舟 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>"
```

<span id="configure-schedule"></span>
## 配置定时计划

`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`。

> **注意**
>
> cron 不支持秒、年份、`@daily` 等快捷写法，也不支持 `L`、`W`、`#` 和 `?` 扩展语法。传入六段式表达式会返回参数错误。

<span id="create-deployment"></span>
## 创建 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` 时，只能通过立即运行接口手动触发。

<span id="run-deployment"></span>
## 立即运行 Deployment

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

> **注意**
>
> 立即运行接口不幂等。每调用一次，平台都会创建新的 Deployment Run 和 Session。请求超时或返回服务端错误时，先查询该 Deployment 最近的手动 Run，确认没有已经受理的 Run 或 Session，再决定是否重试。

```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>"
```

> **注意**
>
> 如果启动阶段出错，接口会返回 HTTP 错误，不会返回成功的 `deployment_run` 对象。错误信息会包含已经创建的 Run ID。记录这个 ID 后，调用 Run 详情接口查看失败原因；平台不会自动重试这次启动。
>
> 初始事件发送失败时，Session 可能已经创建，但失败的 Run 不返回 `session_id`。此时可以从 `error.message` 中找到 Session ID，再查询该 Session 的实际状态。确认任务没有继续执行后，再决定是否重新运行。

<span id="inspect-results"></span>
## 查询运行结果

<span id="get-deployment-run"></span>
### 查询 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 还在启动中。 |

<span id="list-deployment-runs"></span>
### 查询 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`，此时停止翻页。

<span id="inspect-session"></span>
### 查看 Session 执行结果

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

详情请参见 [管理 Session](/docs/manage-session) 和 [Session 事件流](/docs/session-event-stream)。

<span id="update-schedule"></span>
## 更新运行配置

以下示例将运行时间改为工作日 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 不会被改写，它们继续使用受理时的配置快照。

<span id="manage-lifecycle"></span>
## 管理生命周期

<span id="pause-deployment"></span>
### 暂停定时触发

```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。需要临时补跑时，暂停期间仍可调用立即运行接口。

<span id="unpause-deployment"></span>
### 恢复定时触发

```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 会从下一个计划时间继续触发。

<span id="archive-deployment"></span>
### 归档 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。

> **警告**
>
> 归档不可恢复。确认 Deployment 不再运行后再归档，并在操作前核对精确的 Deployment ID。

<span id="limits"></span>
## 了解配置限制

| 配置 | 上限 | 说明 |
| --- | --- | --- |
| `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 也会自动暂停。

<span id="related-docs"></span>
## 相关文档

- [创建 Deployment](/docs/create-deployment-api)
- [立即运行 Deployment](/docs/run-deployment-api)
- [查询 Deployment Run 列表](/docs/list-deployment-runs-api)
- [启动 Session](/docs/start-session)
- [管理 Session](/docs/manage-session)
- [Session 事件流](/docs/session-event-stream)
- [会话事件结构参考](/docs/sessions-events-reference-v2)
- [使用 Vaults 认证](/docs/use-vaults-authentication)