计划部署

计划部署（scheduled deployment）允许代理自主启动会话，从而以可预测的节奏完成任务。

创建计划部署

创建部署时，除了 schedule 之外，您还需要传递执行所需的会话配置。

• 部署需要代理配置和环境配置，并可选择接受文件、GitHub、记忆存储和保险库。
• 部署还需要一个初始的 user.message 事件来启动会话的工作。
• 在 schedule 中，您需要定义一个 cron expression 和一个 timezone。支持的最大粒度为分钟级别。

DEPLOYMENT_ID=$(ant beta:deployments create <<YAML | jq -er '.id'
name: Weekly compliance scan
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
  - type: user.message
    content:
      - type: text
        text: Run the weekly compliance scan.
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
YAML
)

响应包含一个部署对象，其中填充了 schedule.upcoming_runs_at，显示接下来即将触发的时间，以确认您的计划已正确设置。

{
  "id": "depl_01xyz",
  "status": "active",
  "paused_reason": null,
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York",
    "last_run_at": null,
    "upcoming_runs_at": [
      "2026-05-09T00:00:00Z",
      "2026-05-16T00:00:00Z",
      "2026-05-23T00:00:00Z"
    ]
  }
}

即将运行的时间戳基于所配置的确切计划。但是，为了分散负载，部署可能会应用最多 10 秒的抖动。

每个组织最多支持 1,000 个计划部署。如果您需要更多，请联系 Anthropic 支持团队。

Cron 和时区语义

• Expression： 标准 POSIX cron（minute hour day-of-month month day-of-week）。您可以在 Claude Console 中生成和验证这些 cron 表达式。
• Timezone： IANA 时区标识符（例如 "America/Los_Angeles"）。
• DST： Cron 计划使用字面的挂钟时间匹配，因此 America/New_York 中的 "0 20 * * *" 会在当地时间晚上 8
  触发，无论当前生效的是 EST 还是 EDT。

部署运行

部署可能因多种原因而无法触发：例如，environment 资源已被归档，或会话创建受到速率限制。每次执行部署的尝试都会生成一条部署运行（deployment run）记录，使您能够独立于会话生命周期来跟踪成功和失败情况。

成功的部署会生成活跃会话，成功的部署运行包含关联的 session_id。要跟踪会话的生命周期，请通过事件流或 webhooks 跟踪会话事件。

按如下方式列出某个部署的所有部署运行：

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID"

您还可以额外筛选出包含错误的部署运行：

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID" --has-error

失败的运行包含一个 error，其中的 type 描述了会话创建被拒绝的原因（例如 environment_archived_error、agent_archived_error 或 session_rate_limited_error）。

{
  "type": "deployment_run",
  "id": "drun_01abc124",
  "deployment_id": "depl_01xyz",
  "trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
  "session_id": null,
  "error": {
    "type": "environment_archived_error",
    "message": "environment `env_01abc` is archived"
  },
  "agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 },
  "created_at": "2026-05-09T00:00:01Z"
}

管理部署生命周期

暂停（Pause）会从此刻起抑制计划触发；来自先前部署运行的正在运行的会话将继续执行。暂停期间仍允许通过 run 端点进行手动运行。暂停会将 paused_reason 设置为 {"type": "manual"}；取消暂停会将其清除。

ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"

取消暂停（Unpause）会从下一个计划时间点恢复计划。错过的触发不会被补发。

ant beta:deployments unpause --deployment-id "$DEPLOYMENT_ID"

与暂停不同，归档（Archive）是终结性的：计划终止，且部署无法再被修改。

ant beta:deployments archive --deployment-id "$DEPLOYMENT_ID"

失败行为

会话创建的速率限制响应会立即记录为 session_rate_limited_error 运行，不会重试；计划会在下一个计划时间点再次尝试。会话内底层 API 调用的速率限制由会话本身处理。

如果部署的代理已被归档或删除，该部署会在同一操作中被自动归档；不会记录部署运行。如果代理引用的子代理已被归档，下一次触发会记录一次失败的运行，其 error.type: "agent_archived_error"，并且部署会被自动暂停，以便您更新代理并恢复。

触发手动运行

要在计划之外运行部署，请调用 run 端点。这会立即创建一个会话，并写入一条 trigger_context.type: "manual" 的部署运行记录。这使您可以在正式启用计划之前测试部署。

ant beta:deployments run --deployment-id "$DEPLOYMENT_ID"