Memantau dan memecahkan masalah worker self-hosted

Panggilan pemantauan di halaman ini dijalankan dari alat pemantauan atau operasional Anda, diautentikasi dengan kunci API Claude Anda. Helper worker menangani loop klaim dan keep-alive, sehingga Anda tidak memanggil endpoint tersebut secara langsung.

Membaca kedalaman antrean

client.beta.environments.work.stats() mengembalikan status antrean untuk sebuah environment:

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

Menghentikan sesi dengan baik

Gunakan client.beta.environments.work.stop() untuk meminta worker yang menangani sesi tertentu agar mematikannya.

Secara default, work item berpindah ke stopping. Worker menyadarinya pada heartbeat lease berikutnya, membatalkan panggilan alat sesi yang sedang berjalan, dan mengonfirmasi penghentian. Work item kemudian menjadi stopped.

Berikan force=True untuk menandai work item sebagai stopped secara langsung alih-alih menunggu konfirmasi dari worker.

Karena panggilan ini dijalankan dari alat operasional Anda, bukan dari host worker, ANTHROPIC_WORK_ID tidak ditetapkan secara otomatis. Tetapkan ke ID work item target sebelum menjalankan contoh berikut. Untuk menemukan ID work item, ambil daftar work item environment melalui endpoint Environments Work.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)

Menghentikan worker dengan baik

Worker yang dibatalkan saat sebuah sesi berjalan akan menghentikan pekerjaan yang sedang berlangsung sebelum keluar. Jika sesi memiliki memory store yang terlampir, worker melewati sinkronisasi akhir tetapi tetap mengunggah file yang berubah dan menghapus direktori store.

Proses yang di-kill tidak menjalankan teardown. Untuk menghentikan worker dengan bersih:

1. Pastikan SIGTERM dan SIGINT membatalkan worker. Caranya bergantung pada worker:

   Worker	Yang harus dilakukan
   CLI ant	Tidak ada. CLI menangani kedua sinyal itu sendiri: CLI membatalkan panggilan alat yang sedang berjalan, mengirimkan hasil error-nya, dan melepaskan work item.
   Worker SDK yang merupakan prosesnya sendiri	EnvironmentWorker tidak memasang signal handler. Batalkan worker dari signal handler, seperti yang dilakukan contoh worker mandiri.
   Worker SDK di dalam server webhook	Batalkan worker dari shutdown hook milik server itu sendiri, seperti yang dilakukan contoh webhook. Worker tidak boleh mengambil alih sinyal server.

2. Hentikan worker dengan SIGTERM, dan beri waktu setidaknya 30 detik sebelum hard kill apa pun. Unggahan akhir dapat memakan waktu selama itu. Docker mengirim SIGKILL 10 detik setelah sinyal stop secara default. Naikkan batas tersebut dengan --stop-timeout pada docker run, atau dengan termination grace period dari orchestrator Anda.

Jika worker di-kill sebelum teardown-nya berjalan, setiap suntingan memori yang belum tersinkronisasi akan hilang. Pada host yang berumur panjang, hapus juga direktori store sisa di bawah /mnt/memory/ sebelum sesi berikutnya yang melampirkan store tersebut. Sandbox yang melayani satu sesi lalu dibuang tidak memerlukan pembersihan.

Pemecahan masalah

Worker tidak terhubung

Jika workers_polling tetap 0, worker tidak menjangkau antrean. Pastikan bahwa ANTHROPIC_ENVIRONMENT_KEY dan ANTHROPIC_ENVIRONMENT_ID telah ditetapkan pada host worker.

Sesi tetap dalam antrean

Tidak ada worker yang mengklaim pekerjaan. Sesi yang berada dalam antrean akan menunggu alih-alih gagal. Periksa workers_polling dan depth di Membaca kedalaman antrean.

Memory store gagal di-mount

Worker mencatat kegagalan mount dan sinkronisasi latar belakang di log alih-alih melaporkannya ke sesi. Hanya penolakan read-only yang mencapai agen, sebagai error alat (lihat Store read-only dan konflik).

Jika worker tidak dapat me-mount memory store saat mengklaim sesi, worker akan menggagalkan work item. Sesi tidak memancarkan event error dan tetap idle.

Panggilan alat kustom tidak pernah kembali

Jika sesi berada dalam keadaan dijeda dengan stop reason requires_action, tidak ada worker atau klien yang melayani alat tersebut. Lihat Melayani alat kustom.

Panggilan alat MCP yang dibungkus macet

Tanpa timeout pada klien MCP, panggilan yang macet ke server MCP yang dibungkus baru menjadi hasil alat error ketika sebuah backstop terpicu: