Deployment terjadwal

Scheduled deployment (deployment terjadwal) memungkinkan agen untuk memulai sesi secara otonom, sehingga tugas dapat diselesaikan dengan ritme yang dapat diprediksi. Anda membuat dan mengelola deployment dengan Deployments API, bagian dari Claude API.

Untuk konteks peluncuran dan contoh hal-hal yang dijalankan tim secara terjadwal, lihat scheduled deployments and vaults in Claude Managed Agents di blog.

Membuat deployment terjadwal

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

• Deployment memerlukan konfigurasi agen dan konfigurasi environment, serta secara opsional menerima file, GitHub, memory store, dan vault. Deployment yang menargetkan environment self-hosted dapat melampirkan memory store; resource file dan github_repository memerlukan environment cloud. Formulir deployment di Claude Console saat ini tidak menawarkan memory store untuk environment self-hosted; lampirkan melalui API atau SDK sebagai gantinya.
• Deployment juga memerlukan setidaknya satu event awal, yaitu user.message atau user.define_outcome, yang memulai pekerjaan setiap sesi. Dalam file deployment untuk ant apply, teks di bawah frontmatter menjadi user.message tersebut.
• Di dalam schedule, Anda mendefinisikan expression cron dan timezone. Granularitas maksimum yang didukung adalah tingkat menit.

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.

Respons mencakup objek deployment dengan schedule.upcoming_runs_at yang terisi waktu-waktu pemicuan 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 mencerminkan jadwal persis yang dikonfigurasi. Namun, untuk mendistribusikan beban, eksekusi aktual menerapkan "jitter" (variasi waktu acak) hingga 15% dari interval antar-eksekusi, dengan minimum 5 detik dan maksimum 9 menit.

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

Lihat referensi Create Deployment untuk parameter lengkap dan skema respons.

Semantik cron dan zona waktu

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

Menetapkan anggaran untuk setiap eksekusi

Teruskan objek opsional budget saat Anda membuat atau memperbarui deployment. Objek ini memiliki bentuk yang sama dengan anggaran sesi. Deployment menyalin batas tersebut ke setiap sesi yang dimulainya, sehingga anggaran membatasi setiap eksekusi secara terpisah alih-alih bertindak sebagai batas kumulatif di seluruh eksekusi: deployment dengan batas "2000" dapat menghabiskan hingga sekitar $20 pada setiap eksekusi.

Sesi yang dimulai oleh deployment berperilaku persis seperti sesi beranggaran lainnya: sesi dijeda dengan budget_reached ketika biaya daftarnya sendiri mencapai batas. Mengubah anggaran deployment berlaku untuk eksekusi yang dimulai setelahnya; sesi yang sudah berjalan mempertahankan batas yang digunakannya saat dimulai, yang dapat Anda ubah melalui sesi itu sendiri. Tidak seperti anggaran sesi, anggaran deployment dapat dihapus dengan budget=None dan ditetapkan kembali nanti.

Contoh berikut menetapkan anggaran pada deployment yang sudah ada:

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.

Eksekusi deployment

Deployment dapat gagal dipicu karena berbagai alasan: misalnya, jika resource environment telah diarsipkan, atau jika pembuatan sesi terkena batas laju. Setiap upaya mengeksekusi deployment menghasilkan catatan deployment run (eksekusi deployment), sehingga Anda dapat melacak keberhasilan dan kegagalan secara independen dari siklus hidup sesi.

Deployment yang berhasil menghasilkan sesi aktif, dan eksekusi deployment yang berhasil berisi session_id terkait. Untuk mengikuti siklus hidup sesi, lacak event sesi melalui event stream atau webhook. Perubahan siklus hidup deployment dan hasil setiap eksekusi terjadwal juga dikirimkan sebagai event webhook, yang tercantum di tab Deployment events dan Deployment run events pada Jenis event yang didukung.

Tampilkan daftar semua eksekusi deployment untuk sebuah deployment sebagai berikut:

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

Anda juga dapat memfilter eksekusi deployment yang mengalami error:

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)

Eksekusi yang gagal menyertakan error dengan type yang menjelaskan mengapa pembuatan sesi ditolak (misalnya, environment_archived_error, agent_archived_error, atau session_rate_limited_error). Lihat referensi List Deployment Runs untuk semua parameter filter dan skema respons.

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

Untuk mengambil satu eksekusi berdasarkan ID, panggil GET /v1/deployment_runs/{deployment_run_id}. Event webhook deployment_run membawa ID eksekusi sebagai data.id-nya.

Mengelola siklus hidup deployment

Setiap perubahan siklus hidup memancarkan event webhook, sehingga Anda dapat bereaksi terhadap deployment yang dijeda, dilanjutkan, atau diarsipkan tanpa polling; lihat tab Deployment events.

Pause (jeda) menghentikan pemicu terjadwal mulai saat itu dan seterusnya; sesi yang sedang berjalan dari eksekusi deployment sebelumnya tetap dieksekusi. Eksekusi manual melalui endpoint run tetap diizinkan selama dijeda. Menjeda akan mengatur paused_reason menjadi {"type": "manual"}; melanjutkan akan menghapusnya.

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

Unpause (lanjutkan) melanjutkan jadwal dari kemunculan terjadwal berikutnya. Pemicu yang terlewat tidak diisi ulang.

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

Archive (arsipkan), tidak seperti pause, bersifat final: jadwal berakhir dan deployment tidak dapat dimodifikasi.

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

Perilaku saat gagal

Respons batas laju pembuatan sesi langsung dicatat sebagai eksekusi session_rate_limited_error tanpa percobaan ulang; jadwal akan mencoba lagi pada kemunculan terjadwal berikutnya. Batas laju pada panggilan API yang mendasarinya di dalam sesi ditangani oleh sesi itu sendiri.

Jika agen sebuah deployment telah diarsipkan, deployment tersebut otomatis diarsipkan dalam operasi yang sama. Jika agen telah dihapus, pemicu terjadwal berikutnya mendeteksi agen yang hilang dan secara otomatis mengarsipkan deployment. Dalam kedua kasus, tidak ada eksekusi deployment yang dicatat. Jika subagen yang direferensikan oleh agen telah diarsipkan, pemicu berikutnya mencatat eksekusi gagal dengan error.type: "agent_archived_error" dan deployment otomatis dijeda sehingga Anda dapat memperbarui agen dan melanjutkannya. Error pembuatan sesi lain yang tidak dapat dipulihkan, seperti environment atau vault yang diarsipkan, berperilaku sama: pemicu mencatat eksekusi gagal dan deployment otomatis dijeda. paused_reason.error.type milik deployment mencerminkan error.type dari eksekusi yang gagal.

Memicu eksekusi manual

Untuk menjalankan deployment di luar jadwalnya, panggil endpoint run. Ini langsung membuat sesi dan menulis eksekusi deployment dengan trigger_context.type: "manual". Hal ini memungkinkan Anda menguji deployment sebelum menerapkan jadwal.

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