Claude Platform Docs
Managed AgentsSandbox yang di-host sendiri

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

PerintahDeskripsi
ant beta:worker pollMengklaim 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 runMenangani satu sesi yang diklaim lalu keluar. Gunakan sebagai entrypoint dari sandbox per sesi.
FlagDeskripsi
--environment-idEnvironment yang di-poll untuk mendapatkan pekerjaan. Juga dibaca dari ANTHROPIC_ENVIRONMENT_ID.
--environment-keyMengautentikasi worker dengan environment ini. Juga dibaca dari ANTHROPIC_ENVIRONMENT_KEY.
--workdirDirektori 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-workSkrip 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-idleBerapa 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-formatFormat output log. Gunakan json untuk penyerapan log terstruktur. Default-nya text.

Variabel lingkungan

VariabelDeskripsiDiatur oleh
ANTHROPIC_ENVIRONMENT_IDEnvironment yang antreannya dilayani oleh worker.Anda, di host worker. Poller meneruskannya ke skrip --on-work.
ANTHROPIC_ENVIRONMENT_KEYMengautentikasi worker ke antreannya.Anda, di host worker. Poller meneruskannya ke skrip --on-work.
ANTHROPIC_SESSION_IDSesi yang diwakili oleh item pekerjaan yang diklaim.Poller, untuk skrip --on-work.
ANTHROPIC_WORK_IDItem pekerjaan yang diklaim.Poller, untuk skrip --on-work.
ANTHROPIC_WORK_SECRETSecret milik item pekerjaan untuk sesinya.Anda. Poller tidak mengaturnya. Lihat Meneruskan secret item pekerjaan.
ANTHROPIC_BASE_URLMenimpa endpoint API default. Opsional.Anda, di host worker.
ANTHROPIC_WEBHOOK_SIGNING_KEYMemverifikasi payload webhook yang masuk.Anda, di host penangan webhook.

Persyaratan host

WorkerPersyaratan
Semua workerHost 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 SDKunzip dan tar pada PATH, serta Node.js 22 atau lebih baru.
Python dan Go SDKTidak 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

PathIsi
/workspaceDirektori 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/outputs jika 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:

HelperFungsinyaGunakan saat
EnvironmentWorkerMenangani 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

MetodeDeskripsi
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.
OpsiDeskripsi
toolsFactory yang menerima AgentToolContext milik sesi dan mengembalikan daftar alat. Default-nya adalah toolset agen standar.
max_idleBerapa 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_intervalWaktu 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_deletionsApakah 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

OpsiDeskripsi
drainApakah polling dihentikan setelah antrean kosong alih-alih menunggu pekerjaan baru.
block_msBerapa 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_msMengklaim ulang item pekerjaan yang telah diklaim tetapi tidak pernah di-acknowledge dalam jumlah milidetik ini.
auto_stopApakah 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:

  1. Loop Anda memanggil handle_item(), yang mengirim sinyal berhenti sendiri.
  2. 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 run dan handle_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.

OpsiDeskripsi
allowed_rootsDirektori, selain direktori kerja, yang dapat dijangkau oleh alat file (read, write, edit, glob, grep).
read_only_rootsDirektori 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?