Claude Platform Docs
Managed AgentsSandbox yang di-host sendiri

Menerapkan worker self-hosted

Pilih cara worker sandbox self-hosted mengklaim pekerjaan dan tempat sesi berjalan, lalu jalankan worker always-on atau picu worker dari webhook.

Panduan mulai cepat sandbox self-hosted menjalankan satu worker CLI ant yang melakukan polling secara terus-menerus dan menjalankan setiap sesi dalam satu proses. Halaman ini membantu Anda memilih pola deployment, lalu membahas worker always-on dan worker yang dipicu webhook.

Pilih pola deployment

Saat menerapkan worker, Anda perlu membuat dua pilihan: bagaimana worker mengklaim pekerjaan, dan di mana setiap sesi berjalan.

Bagaimana worker mengklaim pekerjaan:

  • Selalu aktif: Proses yang berjalan lama melakukan polling antrean secara terus-menerus. Proses ini hanya membuat permintaan HTTPS keluar, sehingga Anda tidak mengekspos endpoint kepada Anthropic.
  • Dipicu webhook: Sebuah handler aktif pada session.status_run_started dan mulai melakukan polling. Ini menghindari poller yang menganggur, tetapi memerlukan endpoint webhook yang dapat dijangkau oleh Anthropic.

Di mana setiap sesi berjalan:

  • Dalam proses: Worker yang mengklaim sebuah sesi juga menjalankan pemanggilan alatnya, dalam satu direktori kerja bersama.
  • Sandbox per sesi: Sebuah poller meluncurkan sandbox baru untuk setiap sesi yang diklaim. Pilih ini untuk isolasi yang lebih kuat: sistem file baru, batas sumber daya, atau kontrol jaringan per sesi. Lihat Menjalankan satu sandbox per sesi, yang juga membahas Helm chart untuk Kubernetes.

Worker CLI dan SDK mendukung kombinasi yang berbeda:

KemampuanCLI antSDK (Python, TypeScript, Go)
Polling always-onYaYa
Dipicu webhookTidakYa
Sandbox per sesiYaYa
Memory storeYa, dengan pengaturan sinkronisasi defaultYa, dengan sinkronisasi yang dapat dikonfigurasi
Alat kustomTidakYa

Lihat Referensi worker self-hosted untuk setiap flag CLI dan opsi SDK.

Untuk kontrol lebih, panggil endpoint Environments Work secara langsung dan implementasikan worker Anda sendiri. Worker Anda kemudian melakukan apa yang dilakukan worker SDK. Antara lain, worker tersebut melakukan acknowledge setiap item pekerjaan, mengirim heartbeat, dan mengunduh skill agen. Worker hanya menjalankan pemanggilan alat yang diizinkan oleh kebijakan izin sesi. Worker mengembalikan setiap hasil sebagai event user.tool_result atau user.custom_tool_result. Pada akhirnya, worker menghentikan item tersebut. Gunakan kode sumber worker di SDK Python, SDK TypeScript, atau SDK Go sebagai referensi.

Menjalankan worker always-on

Sampel ini menggunakan /workspace sebagai direktori kerja worker. Direktori tersebut harus sudah ada sebelum worker dimulai. Di host baru, buat direktori tersebut dan berikan akses tulis kepada pengguna worker, seperti pada langkah “Mulai worker” di Jalankan sesi pertama Anda.

Di macOS, mkdir tidak dapat membuat /workspace, karena volume root bersifat read-only. Buat ~/workspace sebagai gantinya, seperti yang ditunjukkan pada langkah tersebut. Sebagai pengganti /workspace, gunakan path lengkap yang dicetak oleh echo ~/workspace, karena SDK tidak mengekspansi ~.

Mulai worker yang melakukan polling antrean secara terus-menerus. Worker ini melakukan autentikasi dengan kunci lingkungan dari quickstart:

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


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,
            workdir="/workspace",
        )
        task = asyncio.create_task(worker.run())
        # Membatalkan task, alih-alih mematikan proses, memungkinkan worker menghentikan
        # item pekerjaan yang sedang berjalan dan mengunggah file memori yang berubah sebelum keluar.
        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())

Memicu worker dari webhook

  1. Berlangganan webhook sesi

    Di Claude Console, tentukan endpoint webhook yang mendengarkan event session.status_run_started. Lihat Berlangganan webhook untuk detailnya.

  2. Ekspor kunci penandatanganan webhook

    Bersama dengan ID environment dan kunci dari Menjalankan sesi pertama Anda, ekspor kunci penandatanganan webhook di host handler Anda. Handler menggunakannya untuk memverifikasi payload yang masuk.

    export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."
  3. Implementasikan handler webhook

    Mulai worker saat session.status_run_started dipicu. Handler menguras antrean dan menyerahkan setiap item pekerjaan yang diklaim ke handle_item() (di SDK Python, TypeScript, dan Go). Metode tersebut mengunduh skill, menjalankan pemanggilan alat, mengirimkan hasil kembali, lalu kembali.

    Sampel menggunakan /workspace sebagai direktori kerja. Sebelum Anda memulai handler, buat direktori tersebut di host handler. Pastikan pengguna handler dapat menulis ke direktori tersebut, seperti pada langkah “Mulai worker” di Jalankan sesi pertama Anda.

    Untuk memverifikasi tanda tangan webhook, instal extra webhooks: pip install "anthropic[webhooks]".

    import asyncio
    import os
    import anthropic
    import standardwebhooks  # installed by the anthropic[webhooks] extra
    
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    client = anthropic.AsyncAnthropic(
        auth_token=environment_key,
    )
    # Dibatalkan oleh shutdown() agar item pekerjaan yang sedang berjalan dapat mengunggah file memori yang berubah dan
    # menghapus direktori store-nya sebelum proses keluar.
    inflight: set[asyncio.Task[None]] = set()
    
    
    # Await ini dari shutdown hook host, seperti shutdown lifespan ASGI (kode setelah
    # `yield` dalam lifespan FastAPI), yang dijalankan uvicorn saat SIGTERM. uvicorn membiarkan request terbuka
    # selesai sebelum hook itu berjalan, jadi atur --timeout-graceful-shutdown untuk membatasi waktu tunggu.
    async def shutdown() -> None:
        for task in inflight:
            task.cancel()
        await asyncio.gather(*inflight, return_exceptions=True)
    
    
    async def handle(raw: bytes, headers: dict[str, str]) -> tuple[dict[str, str], int]:
        try:
            event = client.beta.webhooks.unwrap(raw.decode(), headers=headers)
        except standardwebhooks.WebhookVerificationError:
            return {"error": "signature verification failed"}, 401
        if event.data.type != "session.status_run_started":
            return {"status": "ignored"}, 200
        task = asyncio.create_task(run_queued_work())
        inflight.add(task)
        task.add_done_callback(inflight.discard)
        try:
            # Di-shield: pengiriman yang terputus atau timeout tidak boleh membatalkan item; shutdown() yang melakukannya.
            await asyncio.shield(task)
        except asyncio.CancelledError:
            return {"status": "shutting down"}, 503
        return {"status": "ok"}, 200
    
    
    async def run_queued_work() -> None:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            block_ms=None,
            reclaim_older_than_ms=2000,
            drain=True,
            auto_stop=False,
        ):
            await client.beta.environments.work.worker(workdir="/workspace").handle_item(
                work_id=work.id,
                environment_id=environment_id,
                session_id=work.data.id,
                environment_key=environment_key,
                # Secret per sesi inilah yang memungkinkan worker me-mount memory store milik sesi tersebut.
                work_secret=work.secret,
            )

    Di SDK Python, TypeScript, dan Go, handle_item() memerlukan secret item pekerjaan untuk me-mount memory store. Worker yang melakukan polling dengan run() sudah memiliki secret tersebut. Handler ini mengklaim setiap item sendiri, sehingga handler meneruskan secret dalam argumen work_secret. Lihat Meneruskan secret item pekerjaan.

Handler ini menjalankan setiap item yang diklaim dalam satu proses, dan menjalankan item dari pengiriman webhook yang terpisah secara bersamaan. Sesi-sesi tersebut berbagi satu sistem file, termasuk /workspace dan /mnt/memory. Jika sesi Anda melampirkan memory store yang sama, lihat Mengisolasi sesi yang berbagi store.

Langkah selanjutnya

Luncurkan sandbox dengan Helm chart di Kubernetes, skrip spawn, atau poller SDK.

Baca kedalaman antrean, hentikan sesi dan worker dengan bersih, dan perbaiki kegagalan umum.

Model tanggung jawab bersama untuk environment sandbox self-hosted.

Ketersediaan

Worker self-hosted siap pakai
Persyaratan ketersediaan untuk Worker self-hosted siap pakai sama di semua platform yang didukung.
Status
Beta
API
  • Managed Agents
Header beta
Memerlukan
Model
  • Semua model

Endpoint yang berlaku

  • /v1/agents
  • /v1/sessions
  • /v1/environments
Retensi data nolTidak layak

Tidak memiliki kelayakan ZDR, kecuali untuk Managed Agents yang di-host sendiri. Sesi adalah sumber daya stateful; transkrip tetap tersimpan hingga Anda menghapusnya. Pelajari lebih lanjut

HIPAATidak layak

Tidak memiliki kelayakan HIPAA. Berlaku untuk semua subfitur Managed Agents.

Apakah halaman ini membantu?