排程部署

「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 與時區語意

• 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: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 事件會以其 data.id 攜帶執行 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)