排程部署

排程部署（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 秒的抖動（jitter）。

每個組織最多支援 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"