计划部署

scheduled deployment（计划部署）允许智能体自主启动会话，从而按可预测的节奏完成任务。您可以使用 Deployments API（Claude API 的一部分）来创建和管理部署。

有关发布背景以及团队按计划运行的任务示例，请参阅博客上的 Claude Managed Agents 中的计划部署和保管库。

创建计划部署

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

• 部署需要智能体配置和环境配置，并可选择接受文件、GitHub、记忆存储和保管库。以自托管环境为目标的部署可以附加记忆存储；file 和 github_repository 资源需要云环境。Claude Console 的部署表单目前不为自托管环境提供记忆存储选项；请改为通过 API 或 SDK 附加它们。
• 部署还需要至少一个初始事件，即 user.message 或 user.define_outcome，用于启动每个会话的工作。在用于 ant apply 的部署文件中，frontmatter 下方的文本会成为该 user.message。
• 在 schedule 中，您需要定义 cron expression 和 timezone。支持的最大粒度为分钟级。

ant apply deployment.md

---
name: Weekly compliance scan
agent: agent_011CYm1BLqPXpQRk5khsSXrs
environment_id: env_01595EKxaaTTGwwY3kyXdtbs
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
---

Run the weekly compliance scan.

响应包含一个部署对象，其中 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"
    ]
  }
}

即将运行的时间戳反映了所配置的确切计划。但为了分散负载，实际执行会施加最多为运行间隔 15% 的 jitter（抖动），最小 5 秒，最大 9 分钟。

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

有关完整参数和响应架构，请参阅 Create Deployment 参考。

Cron 和时区语义

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

为每次运行设置预算

在创建或更新部署时，传入可选的 budget 对象。它的结构与会话预算相同。部署会将该上限复制到它启动的每个会话上，因此预算分别限制每次运行，而不是作为跨运行的累计上限：上限为 "2000" 的部署每次运行最多可花费约 20 美元。

由部署启动的会话与任何其他设有预算的会话行为完全相同：当其自身的标价成本达到上限时，它会以 budget_reached 暂停。更改部署的预算会应用于之后启动的运行；已在运行的会话保留其启动时的上限，您可以通过会话本身更改该上限。与会话预算不同，部署的预算可以通过 budget=None 移除，并在之后重新设置。

以下示例为现有部署设置预算：

ant apply deployment.md

---
name: Weekly compliance scan
agent: agent_011CYm1BLqPXpQRk5khsSXrs
environment_id: env_01595EKxaaTTGwwY3kyXdtbs
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
budget:
  type: limit
  max_list_cost:
    amount: "2000"
    currency: USD
---

Run the weekly compliance scan.

部署运行

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

成功的部署会生成活动会话，成功的部署运行包含关联的 session_id。要跟踪会话的生命周期，请通过事件流或 webhooks 跟踪会话事件。部署生命周期变更以及每次计划运行的结果也会作为 webhook 事件传递，这些事件列在支持的事件类型的 Deployment events 和 Deployment run events 选项卡中。

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

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
):
    print(run.created_at, run.session_id or run.error.type)

您还可以筛选出带有错误的部署运行：

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
    has_error=True,
):
    print(run.created_at, run.error.type, run.error.message)

失败的运行包含一个 error，其 type 描述了会话创建被拒绝的原因（例如 environment_archived_error、agent_archived_error 或 session_rate_limited_error）。有关所有筛选参数和响应架构，请参阅 List Deployment Runs 参考。

{
  "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"
}

要按 ID 检索单个运行，请调用 GET /v1/deployment_runs/{deployment_run_id}。deployment_run webhook 事件会将运行 ID 作为其 data.id 携带。

管理部署生命周期

每次生命周期变更都会发出一个 webhook 事件，因此您无需轮询即可对部署的暂停、取消暂停或归档做出响应；请参阅 Deployment events 选项卡。

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

client.beta.deployments.pause(deployment.id)

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

client.beta.deployments.unpause(deployment.id)

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

client.beta.deployments.archive(deployment.id)

失败行为

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

如果部署的智能体已被归档，该部署会在同一操作中被自动归档。如果智能体已被删除，下一次计划触发会检测到智能体缺失并自动归档该部署。在这两种情况下都不会记录部署运行。如果智能体引用的子智能体已被归档，下一次触发会记录一个带有 error.type: "agent_archived_error" 的失败运行，并且部署会被自动暂停，以便您更新智能体后恢复。其他不可恢复的会话创建错误（例如已归档的环境或保管库）的行为相同：触发会记录一个失败运行，并且部署会被自动暂停。部署的 paused_reason.error.type 与失败运行的 error.type 一致。

触发手动运行

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

run = client.beta.deployments.run(deployment.id)