Deployment terjadwal

Sebuah scheduled deployment (deployment terjadwal) memungkinkan sebuah agen untuk memulai sesi secara otonom, memungkinkan penyelesaian tugas dengan irama yang dapat diprediksi.

Membuat scheduled deployment

Saat membuat deployment, Anda meneruskan konfigurasi sesi yang diperlukan untuk eksekusi, selain sebuah schedule.

• Deployment memerlukan konfigurasi agen dan konfigurasi lingkungan, dan secara opsional menerima file, GitHub, memory store, dan vault.
• Deployment juga memerlukan event user.message awal yang memulai pekerjaan sesi.
• Dalam schedule, Anda mendefinisikan sebuah expression cron dan sebuah timezone. Granularitas maksimum yang didukung adalah pada tingkat menit.

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
)

Respons menyertakan objek deployment dengan schedule.upcoming_runs_at yang terisi dengan waktu pemicuan mendatang berikutnya, untuk mengonfirmasi bahwa jadwal Anda telah diatur dengan benar.

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

Timestamp eksekusi mendatang didasarkan pada jadwal persis yang dikonfigurasi. Namun, untuk mendistribusikan beban, deployment dapat menerapkan jitter hingga 10 detik.

Maksimum 1.000 scheduled deployment didukung per organisasi. Hubungi dukungan Anthropic jika Anda membutuhkan lebih banyak.

Semantik cron dan timezone

• Expression: Cron POSIX standar (minute hour day-of-month month day-of-week). Anda dapat menghasilkan dan memvalidasi ekspresi cron ini di Claude Console.
• Timezone: Pengidentifikasi timezone IANA (misalnya, "America/Los_Angeles").
• DST: Jadwal cron menggunakan pencocokan waktu jam dinding secara literal, sehingga "0 20 * * *" di America/New_York terpicu pada pukul 8
  malam waktu setempat terlepas dari apakah EST atau EDT sedang berlaku.

Deployment run

Deployment dapat gagal terpicu karena berbagai alasan: misalnya, jika sumber daya environment telah diarsipkan, atau jika pembuatan sesi dibatasi oleh batas laju. Setiap upaya mengeksekusi deployment menghasilkan catatan deployment run, memungkinkan Anda melacak keberhasilan dan kegagalan secara independen dari siklus hidup sesi.

Deployment yang berhasil menghasilkan sesi aktif, dan deployment run yang berhasil berisi session_id terkait. Untuk mengikuti siklus hidup sesi, lacak event sesi melalui event stream atau webhooks.

Daftarkan semua deployment run untuk sebuah deployment sebagai berikut:

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

Anda juga dapat memfilter deployment run yang memiliki error:

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

Run yang gagal menyertakan error dengan type yang menjelaskan mengapa pembuatan sesi ditolak (misalnya, environment_archived_error, agent_archived_error, atau 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"
}

Mengelola siklus hidup deployment

Pause menekan pemicu terjadwal ke depannya; sesi yang sedang berjalan dari deployment run sebelumnya terus dieksekusi. Run manual melalui endpoint run masih diizinkan saat dijeda. Menjeda mengatur paused_reason menjadi {"type": "manual"}; membatalkan jeda menghapusnya.

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

Unpause melanjutkan jadwal dari kemunculan terjadwal berikutnya. Pemicu yang terlewat tidak dijalankan ulang.

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

Archive, tidak seperti pause, bersifat terminal: jadwal berakhir dan deployment tidak dapat dimodifikasi.

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

Perilaku kegagalan

Respons batas laju pembuatan sesi dicatat segera sebagai run session_rate_limited_error tanpa percobaan ulang; jadwal mencoba lagi pada kemunculan terjadwal berikutnya. Batas laju pada panggilan API yang mendasari dalam sebuah sesi ditangani oleh sesi itu sendiri.

Jika agen dari sebuah deployment telah diarsipkan atau dihapus, deployment tersebut secara otomatis diarsipkan dalam operasi yang sama; tidak ada deployment run yang dicatat. Jika subagen yang direferensikan oleh agen telah diarsipkan, pemicu berikutnya mencatat run yang gagal dengan error.type: "agent_archived_error" dan deployment secara otomatis dijeda sehingga Anda dapat memperbarui agen dan melanjutkan.

Memicu run manual

Untuk menjalankan deployment di luar jadwalnya, panggil endpoint run. Ini membuat sesi segera dan menulis deployment run dengan trigger_context.type: "manual". Ini memungkinkan Anda menguji deployment sebelum berkomitmen pada jadwal.

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