Managed Agents 定时部署（Scheduled Deployments）实践指南：用 cron 调度让 Agent 自主跑批

• 人工智能
• AI 技能
• AI 评测

本指南以 Claude API 技能库中的 managed-agents-scheduled-deployments.md 为核心，系统讲解 Managed Agents 的**定时部署（Scheduled Deployments）**能力：如何把一个 Agent 与环境、初始事件和 cron 计划打包成 deployment，让平台按固定节奏自动创建 session 自主执行任务。读完本文，你将掌握 deployment 的创建与校验、cron/时区/DST 语义、预算（budget）的"可清零可重加"更新规则、deployment run 审计记录、暂停/恢复/归档生命周期，以及用手动运行在正式排程前验证任务的全套实战方案。

什么是定时部署：让 Agent 按 cron 自主跑批

Scheduled Deployment（定时部署）会在一个周期性的 cron 计划上运行 Agent——每次触发（firing）都会自动创建一个 session 并自主开始工作。它适用于节奏可预测的任务：夜间巡检（nightly triage）、每周合规扫描（weekly compliance scans）、每小时监控（hourly monitors）等。

它是 Managed Agents 体系中的一等资源，对应depl_前缀的 ID，端点位于/v1/deployments与/v1/deployment_runs。在技能库的选型表中，当需要"按计划（cron、'every night'）运行的 Agent"时，Managed Agents 的 scheduled deployments 是明确的推荐方案——由平台负责触发 session，无需自建客户端调度器（参见 SKILL.md 的 "Which Surface Should I Use" 部分）。

前置要求：所有 deployments 调用都需要managed-agents-2026-04-01beta 请求头。SDK 会在client.beta.deployments.*/client.beta.deployment_runs.*调用时自动携带该头（参见 managed-agents-api-reference.md 的 Beta Headers 一节）；使用 cURL 时必须手工添加。在动手之前，请先确保已经创建了Agent与Environment——deployment 只是把二者与计划绑定，model/system/tools都保存在 Agent 对象上，不会出现在 deployment 请求体里（核心概念详见 managed-agents-core.md）。

创建 Deployment

一个 deployment 把 session 运行所需的一切打包在一起：

• Agent 与环境：agent和environment_id为必填项，其取值形状与sessions.create完全一致（见 managed-agents-core.md）。此外还可附加可选的 files、GitHub 仓库、memory stores、vaults 等资源。
  • 面向自托管环境（self-hosted）的 deployment 可以挂载memory_store资源（要求使用 Python/TypeScript/Go 的EnvironmentWorker等 SDK worker，详见 managed-agents-self-hosted-sandboxes.md 的 Memory stores 一节）；而file与github_repository资源需要云环境（cloud）。
  • 注意：Console 的 deployment 表单不为自托管环境提供 memory store 选项——需要通过 API/SDK 挂载。
• 初始事件initial_events：必须包含至少一个起始事件——user.message或user.define_outcome。与 session 的initial_events不同，deployment 的initial_events额外接受system.message（session 的 initial_events 不接受，见 managed-agents-core.md 的 "Seeding a session withinitial_events" 一节）。
• 调度计划schedule：接受 cronexpression与 IANAtimezone，最大粒度到分钟级。

cURL 创建示例

curl -fsSL https://api.anthropic.com/v1/deployments \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d @- <<EOF { "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" } } EOF

Python SDK 创建示例

deployment = client.beta.deployments.create( 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", }, )

通用请求头模板（cURL 场景）：Content-Type: application/json、x-api-key: $ANTHROPIC_API_KEY、anthropic-version: 2023-06-01、anthropic-beta: managed-agents-2026-04-01——四个头缺一不可，完整示例见 curl/managed-agents.md。SDK 调用无需手动处理 beta 头（SKILL.md 的 Managed Agents 一节明确说明 SDK 对deployments、deployment_runs命名空间自动添加该头）。

校验计划：检查upcoming_runs_at

创建请求的响应是一个 deployment 对象（depl_ID 前缀）。务必检查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"] } }

从 managed-agents-api-reference.md 的 CreateDeployment Request Body 一节可以看到，响应包含status、paused_reason与schedule.upcoming_runs_at，且 deployment 支持与 CreateSession 相同的可选 session 配置（resources、vault_ids等），包括budget。

两个必须注意的边界

1. 执行抖动（jitter）：upcoming_runs_at反映的是精确配置的计划，但实际执行会为分散负载而被抖动：最多延迟间隔时长的 15%，下限 5 秒、上限 9 分钟。这意味着一个每小时执行的 deployment 可能最多延迟 9 分钟触发。不要把下游的截止时间建立在列表所给的时间戳之上。
2. 组织级配额：每个组织最多1000 个定时部署（需要更多请联系 Anthropic 支持）。

Cron 与时区语义

⚠️ DST 边界：在春季拨快（spring-forward）当天不存在的墙钟时间（如凌晨 2 点）会被跳过；在秋季拨慢（fall-back）当天出现两次的时间会触发两次。当漏执行或重复执行不可接受时，请把计划排到本地 1–3 AM 之外，或直接使用 UTC。

Deployment 预算（Budgets）

deployment 接受与 session 相同的budget对象：{type: "limit", max_list_cost: {amount, currency}}——amount是以美分为单位的小数位整数串，仅支持USD（详细清单见 managed-agents-core.md 的 Session budgets 一节；例如"2500"表示 $25.00，"50"表示五十美分，字符串形式避免任何浮点舍入，"25.00"这类小数形式会被拒绝）。

触发时刻语义：该上限会在每次触发时复制到新创建的 session 上，随后该 session 的行为与任何带预算的 session 完全一致——按公开列表价（list rates）持续计费，达到上限后暂停进入idle（stop_reason: budget_reached），而非终止。

与 session 预算更新语义的关键差异（务必对照理解，session 侧的规则见 managed-agents-core.md）：

Deployment Runs：审计每一次触发

每一次触发尝试——无论成功与否——都会写入一条 deployment run 记录（drun_前缀），因此你可以独立于 session 生命周期审计失败。

• 成功的 run携带所创建的session_id；之后按常规方式通过事件流（managed-agents-events.md）或 webhook（managed-agents-webhooks.md）跟进该 session。
• 失败的 run携带一个error，其type说明 session 创建为何被拒绝。

列出与过滤 Runs（Python）

# All runs for a deployment for run in client.beta.deployment_runs.list(deployment_id=deployment.id): print(run.created_at, run.session_id or run.error.type) # Failures only 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)

列出与过滤 Runs（TypeScript）

for await (const run of client.beta.deploymentRuns.list({ deployment_id: deployment.id, has_error: true, })) { console.log(run.created_at, run.error?.type, run.error?.message); }

原始 HTTP：GET /v1/deployment_runs?deployment_id=...&has_error=true（分页列表）。按 ID 取单个 run：GET /v1/deployment_runs/{deployment_run_id}（SDK：client.beta.deployment_runs.retrieve(run_id)）——一条deployment_run.*webhook 事件会把 run ID 作为其data.id携带，方便从事件反查详情（端点表见 managed-agents-api-reference.md 的 Deployment Runs 一节）。

失败 Run 的典型形态

{ "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", "message": "environment `env_01abc` is archived" }, "agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 }, "created_at": "2026-05-09T00:00:01Z" }

错误类型包括：environment_archived、agent_archived、vault_not_found、session_rate_limited、service_unavailable。

Webhook 集成（免轮询）

每次定时（scheduled）run 的结果（started/succeeded/failed）以及每次 deployment 生命周期变更（created/updated/paused/unpaused/archived/deleted）也会以 webhook 事件投递——详见 managed-agents-webhooks.md 的deployment.*与deployment_run.*事件类型表，可以做到无需轮询即可响应。注意两点：

• 手动运行（manual runs）不会发出deployment_run.*webhook 事件。
• webhook 的data.type命名空间与 SSE 事件类型（如session.status_idle）是两个独立命名空间，不要复用。

生命周期：暂停 / 恢复 / 归档

原始 HTTP：POST /v1/deployments/{deployment_id}/pause（/unpause、/archive同理）。完整端点映射见 managed-agents-api-reference.md 的 Deployments 一节（另有POST /v1/deployments/{deployment_id}更新配置、POST /v1/deployments/{deployment_id}/run手动运行）。

失败行为（Failure Behavior）

• 被限流（rate-limited）：立即记录为一条session_rate_limitedrun，不重试——计划只是在下一次触发时再次尝试。（session内部API 调用的限流由 session 自身处理。）
• 其他失败 run（如environment_archived、vault_not_found、service_unavailable）：run 记录下error.type——监控 runs 并修复引用的资源，或暂停 deployment。
• Agent 被归档：deployment 会在同一操作中被自动归档（终态）。Agent 被删除：下一次定时触发检测到缺失的 Agent，随后归档该 deployment。无论哪种情况，都不会记录 deployment run，也不再创建任何 session。

补充观察（可结合 webhook 语义理解）：在 managed-agents-webhooks.md 中，deployment.paused的触发条件明确包括"定时 run 以不可恢复错误（归档的 agent、缺失的环境）失败时自动暂停"；而可恢复的失败（包括限流）不会自动暂停——这正是上面失败行为在事件层的映射。

手动运行：上线前的最后验证

POST /v1/deployments/{deployment_id}/run（SDK：client.beta.deployments.run(id)）会立即创建一个 session，并写入一条trigger_context.type: "manual"的 run。

• 用途：在正式排程之前先测试 deployment——确认 Agent、环境、资源挂载与初始事件链路都能跑通。
• 关键特性：即使 deployment 处于暂停状态，手动运行依然可用，所以你可以"暂停 → 手动验证 → 恢复"作为安全的发布流程。

与周边能力的关联速查

为方便继续深入，定时部署在 Managed Agents 知识体系中与以下文档紧密关联：

• Agent / Session / Environment 基础：managed-agents-core.md——agent字段的三种取值形态、initial_events校验规则、session 预算的完整语义；
• 自托管环境与 memory store 挂载：managed-agents-self-hosted-sandboxes.md——deployment 面向 self-hosted 环境时的资源限制与 SDK worker 要求；
• 事件流与 steering：managed-agents-events.md——run 成功后如何沿 session 事件流跟进；
• Webhook 事件类型：managed-agents-webhooks.md——deployment.*与deployment_run.*的完整触发条件表；
• 端点与请求体参考：managed-agents-api-reference.md——Deployments / Deployment Runs 的 REST 路径、SDK 方法名与 CreateDeployment 请求体；
• cURL 与 SDK 实操：curl/managed-agents.md、python/managed-agents/README.md——通用请求头与客户端初始化模式。

核心要点小结

1. 创建：POST /v1/deployments，agent+environment_id必填，initial_events至少一个起始事件（user.message或user.define_outcome，也接受system.message），schedule使用标准 POSIX cron + IANA 时区，分钟级为上限精度。
2. 校验：用响应的schedule.upcoming_runs_at确认计划解析；记住执行有最多 9 分钟的抖动，不要对时间戳做硬性下游依赖；组织上限 1000 个 deployment。
3. 预算：每次触发把 budget 复制到新 session；deployment 的 budget 支持 create/update 均可设置、null清除后可重新添加，变更从下一次触发的 session 生效。
4. 审计：每次触发都写drun_run 记录，失败带error.type（environment_archived、agent_archived、vault_not_found、session_rate_limited、service_unavailable）；限流不重试、不可恢复失败对应自动暂停/归档。
5. 生命周期：pause（暂停期间手动运行仍可用）→ unpause（不补跑）→ archive（终态不可逆）；agent 被归档/删除会级联归档 deployment。
6. 手动运行：POST /v1/deployments/{id}/run立即建 session 并写trigger_context.type: "manual"，是排程前验证和暂停态下调试的标准手段。

• 人工智能
• AI 技能
• AI 评测