Referensi worker self-hosted
Referensi untuk worker sandbox self-hosted: flag CLI ant, variabel lingkungan, persyaratan host, path sistem file, dan opsi helper SDK.
Halaman ini mendokumentasikan worker siap pakai yang melayani environment self_hosted. Untuk panduan berorientasi tugas, mulailah dengan Sandbox self-hosted dan Menerapkan worker self-hosted.
Perintah dan flag CLI
| Perintah | Deskripsi |
|---|---|
ant beta:worker poll | Mengklaim item pekerjaan dari antrean environment dan menjalankan setiap sesi di dalam proses. Dengan --on-work, memanggil skrip Anda untuk setiap item pekerjaan sebagai gantinya. |
ant beta:worker run | Menangani satu sesi yang diklaim lalu keluar. Gunakan sebagai entrypoint dari sandbox per sesi. |
| Flag | Deskripsi |
|---|---|
--environment-id | Environment yang di-poll untuk mendapatkan pekerjaan. Juga dibaca dari ANTHROPIC_ENVIRONMENT_ID. |
--environment-key | Mengautentikasi worker dengan environment ini. Juga dibaca dari ANTHROPIC_ENVIRONMENT_KEY. |
--workdir | Direktori tempat worker mengunduh skill, dan tempat alat membaca serta menulis file. Default-nya . (direktori saat ini). Direktori ini harus sudah ada sebelum worker dimulai. |
--on-work | Skrip yang dipanggil untuk setiap item pekerjaan yang diklaim alih-alih menjalankan alat di dalam proses. Menerima detail sesi sebagai variabel lingkungan dan item pekerjaan sebagai JSON pada standard input. |
--max-idle | Berapa lama worker menunggu selama sesi dalam keadaan idle sebelum ant beta:worker run keluar atau ant beta:worker poll beralih ke item pekerjaan berikutnya. Waktu idle dengan alasan berhenti requires_action tidak dihitung. Default-nya 60s. Atur ke 0 untuk menonaktifkan batas waktu. Dengan skrip --on-work, ant beta:worker poll mengabaikan flag ini. Sebagai gantinya, teruskan flag ini ke perintah ant beta:worker run yang dijalankan oleh skrip Anda. |
--log-format | Format output log. Gunakan json untuk penyerapan log terstruktur. Default-nya text. |
Variabel lingkungan
| Variabel | Deskripsi | Diatur oleh |
|---|---|---|
ANTHROPIC_ENVIRONMENT_ID | Environment yang antreannya dilayani oleh worker. | Anda, di host worker. Poller meneruskannya ke skrip --on-work. |
ANTHROPIC_ENVIRONMENT_KEY | Mengautentikasi worker ke antreannya. | Anda, di host worker. Poller meneruskannya ke skrip --on-work. |
ANTHROPIC_SESSION_ID | Sesi yang diwakili oleh item pekerjaan yang diklaim. | Poller, untuk skrip --on-work. |
ANTHROPIC_WORK_ID | Item pekerjaan yang diklaim. | Poller, untuk skrip --on-work. |
ANTHROPIC_WORK_SECRET | Secret milik item pekerjaan untuk sesinya. | Anda. Poller tidak mengaturnya. Lihat Meneruskan secret item pekerjaan. |
ANTHROPIC_BASE_URL | Menimpa endpoint API default. Opsional. | Anda, di host worker. |
ANTHROPIC_WEBHOOK_SIGNING_KEY | Memverifikasi payload webhook yang masuk. | Anda, di host penangan webhook. |
Persyaratan host
| Worker | Persyaratan |
|---|---|
| Semua worker | Host Linux atau macOS dengan /bin/bash tepat di path tersebut. Alat bash milik worker menjalankannya secara langsung, tanpa merujuk ke PATH. Di macOS, itu adalah Bash 3.2 bawaan sistem. |
| TypeScript SDK | unzip dan tar pada PATH, serta Node.js 22 atau lebih baru. |
| Python dan Go SDK | Tidak ada binary tambahan. SDK ini menggunakan pustaka standarnya untuk ekstraksi arsip. |
Memory store menambahkan persyaratannya sendiri.
Di macOS, volume root bersifat read-only, sehingga mkdir tidak dapat membuat /workspace. Atur direktori kerja worker ke direktori yang dapat Anda tulisi, seperti direktori workspace di direktori home Anda. Untuk menggunakan memory store di macOS, terlebih dahulu siapkan host macOS.
Sistem file sandbox
| Path | Isi |
|---|---|
/workspace | Direktori kerja dalam contoh-contoh di halaman sandbox self-hosted. Ini bukan default worker: worker menggunakan direktori saat ini kecuali Anda mengatur --workdir atau workdir. Sandbox cloud Anthropic menyimpan skill dan repositori di /workspace. Jika Anda menggunakan direktori kerja yang berbeda, perbarui prompt sistem agen Anda agar Claude dapat menemukan file skill. |
<workdir>/skills/<name>/ | Skill agen yang telah diunduh. |
/mnt/memory/<store>/ | Salinan lokal dari setiap memory store yang terlampir, satu direktori per store. API mengembalikan path lengkap setiap direktori di field mount_path pada resource memory store milik sesi (misalnya, /mnt/memory/user-preferences/). |
Worker membuat direktori memory store saat mengklaim sesi. Worker menghapusnya saat selesai menangani sesi tersebut atau saat Anda menghentikan worker dengan baik. Tindakan ini hanya menghapus salinan lokal, dan memori tetap berada di store.
Skill dapat menyertakan file yang dapat dieksekusi, yang bisa langsung dijalankan oleh agen. Worker CLI dan SDK mempertahankan izin eksekusi yang tercatat dalam bundel skill saat mengekstraknya. Jika Anda mengunduh skill sendiri, atur sendiri izin eksekusinya.
Saat worker selesai menangani sesi
Worker selesai menangani sesi dalam salah satu kasus berikut:
- Sesi berakhir.
- Anda menghentikan item pekerjaan milik sesi tersebut.
- Sesi tetap idle selama batas idle worker. Sesi itu sendiri tetap terbuka. Ketika Anda kemudian mengirimkan event baru ke sesi tersebut, seperti pesan pengguna, worker yang sama atau worker lain akan mengklaimnya. Worker tersebut mengunduh store lagi.
Batas idle default-nya adalah 60 detik. Untuk mengubahnya, gunakan --max-idle untuk worker CLI ant atau max_idle untuk EnvironmentWorker. Helm chart cma-sandboxes memulai worker-nya dengan batas 30 menit sebagai gantinya. Untuk mengubah batas tersebut, ubah pengaturan sandbox.idleTimeout milik chart.
Hasil akhir
Sandbox self-hosted tidak memiliki direktori /mnt/session/outputs. Pada sandbox cloud Anthropic, prompt sistem sesi memberi tahu agen untuk menyalin hasil akhir ke sana. Pada environment self-hosted, prompt sistem menghilangkan instruksi tersebut. Hasil akhir tetap berada di mana pun agen menuliskannya, biasanya di bawah direktori kerja, dan worker tidak mengunggahnya.
Untuk mengumpulkan hasil akhir di satu tempat, berikan path lengkap sebuah direktori di prompt sistem agen Anda. Pilih direktori yang dapat ditulisi oleh alat file worker:
- Di dalam direktori kerja: Misalnya,
/workspace/outputsjika direktori kerjanya adalah/workspace. - Di tempat lain, hanya dengan worker SDK: Tambahkan direktori tersebut ke
allowed_roots. Lihat AgentToolContext dan toolset agen.
Helper SDK
SDK Python, TypeScript, dan Go menyediakan tiga helper dengan tingkat kontrol yang berbeda:
| Helper | Fungsinya | Gunakan saat |
|---|---|---|
EnvironmentWorker | Menangani polling, penyiapan, dan menjalankan alat secara menyeluruh. | Sebagian besar kasus. |
work.poller() | Melakukan polling pada antrean kerja dan memberikan setiap sesi yang diklaim kepada Anda. | Anda menentukan cara menangani setiap sesi, misalnya dengan meluncurkan sandbox alih-alih menjalankan alat di dalam proses. |
client.beta.sessions.events.tool_runner() | Menjalankan pemanggilan alat untuk satu sesi, berdasarkan ID sesi dan daftar alat. | Anda sudah mengklaim pekerjaan dan hanya perlu menjalankan alat. |
EnvironmentWorker
| Metode | Deskripsi |
|---|---|
run() | Berjalan tanpa batas waktu, mengambil sesi saat sesi tersebut tiba. |
handle_item() | Menangani satu item pekerjaan yang sudah diklaim oleh poller. Poller tersebut dapat berupa ant beta:worker poll --on-work atau kode Anda sendiri. Metode ini kembali saat worker selesai menangani sesi milik item tersebut. Anda dapat meneruskan work_id, session_id, environment_id, dan work_secret. Untuk setiap nilai yang tidak Anda teruskan, metode ini membaca variabel ANTHROPIC_* yang sesuai. |
| Opsi | Deskripsi |
|---|---|
tools | Factory yang menerima AgentToolContext milik sesi dan mengembalikan daftar alat. Default-nya adalah toolset agen standar. |
max_idle | Berapa lama worker menunggu selama sesi dalam keadaan idle sebelum selesai menangani sesi tersebut. Waktu idle dengan alasan berhenti requires_action tidak dihitung. Default-nya 60 detik. Untuk menunggu 5 menit, atur ke 300. Untuk menonaktifkan batas ini, atur ke None. |
memory_sync_interval | Waktu terpendek antara dua sinkronisasi memory store yang terlampir selama sesi berjalan. Worker memeriksa interval ini setelah setiap pemanggilan alat yang berjalan di sandbox Anda, bukan berdasarkan timer. Default-nya 15 detik. Lihat Interval sinkronisasi. |
memory_sync_deletions | Apakah file yang dihapus agen secara lokal juga dihapus dari store. Lihat Penghapusan. |
EnvironmentWorker mengelola AgentToolContext dan toolset secara otomatis. Teruskan factory tools untuk menyesuaikan daftar alat:
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic, beta_async_tool
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_bash_tool
@beta_async_tool
async def get_order_status(order_id: str) -> str:
"""Look up an order in the internal fulfillment system by order ID."""
return f"Order {order_id}: shipped"
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
async with AsyncAnthropic(auth_token=environment_key) as client:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
# Daftarkan setiap alat yang dapat dipanggil agen. Worker tidak menjawab alat lain.
tools=lambda env: [beta_bash_tool(env), get_order_status],
)
task = asyncio.create_task(worker.run())
loop = asyncio.get_running_loop()
for signum in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(signum, task.cancel)
with contextlib.suppress(asyncio.CancelledError):
await task
asyncio.run(main())Work poller
| Opsi | Deskripsi |
|---|---|
drain | Apakah polling dihentikan setelah antrean kosong alih-alih menunggu pekerjaan baru. |
block_ms | Berapa lama setiap polling menunggu pekerjaan tiba sebelum kembali, dalam milidetik. Harus antara 1 dan 999. Helper melakukan polling ulang secara otomatis. Teruskan None untuk pemeriksaan non-blocking. Default-nya long-polling 999ms. |
reclaim_older_than_ms | Mengklaim ulang item pekerjaan yang telah diklaim tetapi tidak pernah di-acknowledge dalam jumlah milidetik ini. |
auto_stop | Apakah poller mengirim sinyal berhenti untuk setiap item pekerjaan setelah badan loop Anda selesai memprosesnya. Default-nya True. Atur ke False dalam dua kasus yang dijelaskan setelah tabel ini. |
Atur auto_stop ke False dalam dua kasus:
- Loop Anda memanggil
handle_item(), yang mengirim sinyal berhenti sendiri. - Loop Anda meluncurkan sandbox untuk item tersebut lalu beralih ke item berikutnya. Worker di sandbox tersebut harus mengirim sinyal berhenti saat pekerjaan sesi berakhir, seperti yang dilakukan
ant beta:worker rundanhandle_item().
Untuk contoh lengkap, lihat Meluncurkan sandbox dari poller SDK.
Tool runner sesi
client.beta.sessions.events.tool_runner() menerima daftar alat sebagai tools. Untuk membangun daftar tersebut, siapkan AgentToolContext sendiri dan panggil beta_agent_toolset_20260401(env):
from anthropic.lib.tools.agent_toolset import (
AgentToolContext,
beta_agent_toolset_20260401,
)
async with AgentToolContext(
workdir="/workspace", client=client, session_id=work.data.id
) as env:
# skills diunduh ke /workspace/skills/<name>/
tools = beta_agent_toolset_20260401(env)AgentToolContext dan toolset agen
AgentToolContext adalah konteks eksekusi untuk pemanggilan alat. Konteks ini mendefinisikan direktori kerja dan kebijakan path, serta dapat mengunduh skill milik sesi.
| Opsi | Deskripsi |
|---|---|
allowed_roots | Direktori, selain direktori kerja, yang dapat dijangkau oleh alat file (read, write, edit, glob, grep). |
read_only_roots | Direktori yang path di bawahnya ditolak oleh write dan edit. |
EnvironmentWorker sendiri menambahkan direktori memory store milik sesi ke allowed_roots, dan direktori store yang dilampirkan dengan access: "read_only" ke read_only_roots.
Pembatasan ini hanyalah pengaman untuk alat file, bukan sandbox. Pembatasan ini tidak membatasi bash.
beta_agent_toolset_20260401(env) menerima AgentToolContext dan mengembalikan implementasi alat standar (bash, read, write, edit, glob, grep).
Apakah halaman ini membantu?