Sandbox self-hosted

Secara default, Managed Agents mengeksekusi alat dan kode di dalam sandbox cloud yang dikelola Anthropic. "Self-hosted sandboxes" (sandbox yang di-hosting sendiri) mempertahankan orkestrasi di sisi Anthropic tetapi memindahkan eksekusi alat ke infrastruktur yang Anda kendalikan, sehingga kode, sistem file, dan egress jaringan agen tidak pernah meninggalkan lingkungan Anda.

Eksekusi alat tetap berada di host Anda: sistem file yang dibaca dan ditulis agen, proses yang dijalankannya, dan jaringan yang dapat dijangkaunya semuanya berada di bawah kendali Anda. Input dan output alat tetap mengalir ke control plane Anthropic (tempat Claude berjalan) sehingga model dapat melihat hasil dan menentukan apa yang harus dilakukan selanjutnya. Skills agen dan isi memory store apa pun yang dilampirkan ke sesi disimpan oleh Anthropic dan disalin ke sandbox Anda untuk sesi tersebut; perubahan yang dibuat agen pada file memori disinkronkan kembali ke store. Lihat model keamanan untuk batas aliran data selengkapnya.

Perbedaannya dengan environment cloud

Self-hosting cocok ketika agen perlu beroperasi pada data yang tidak boleh meninggalkan batas jaringan Anda, menjangkau layanan internal yang tidak dapat dirutekan secara publik, atau berjalan di bawah kontrol kepatuhan dan audit organisasi Anda sendiri.

Untuk kelayakan Zero Data Retention dan HIPAA BAA, lihat API dan retensi data.

Kapan menggabungkan dengan MCP tunnel

Self-hosting mengontrol di mana kode agen dieksekusi. MCP tunnel mengontrol bagaimana Anthropic menjangkau server MCP di jaringan Anda. Keduanya independen: sesi yang berjalan di sandbox cloud Anthropic tetap dapat menjangkau server MCP privat melalui tunnel, dan sesi self-hosted dapat menggunakan server MCP yang di-tunnel maupun publik. Gunakan keduanya ketika Anda ingin eksekusi dan akses alat tetap berada di dalam batas Anda. Untuk memberi agen alat dari server MCP di dalam jaringan Anda tanpa menjalankan tunnel, Anda juga dapat membungkus server sebagai alat kustom yang dilayani oleh worker Anda.

Environment worker

"Environment worker" (pekerja environment) adalah proses yang Anda jalankan di infrastruktur Anda sendiri. Proses ini menerima permintaan eksekusi alat dari Anthropic dan menjalankannya secara lokal. Environment self_hosted bertindak sebagai antrean kerja: ketika sebuah sesi ditugaskan kepadanya, Anthropic memasukkan sesi tersebut ke antrean sebagai work item. Worker Anda mengklaim work item dari antrean itu, membuat konteks eksekusi untuk masing-masing, mengunduh skills agen (sumber daya berbasis sistem file yang dapat digunakan ulang dan memberi agen keahlian khusus domain), menjalankan panggilan alat, dan mengirimkan hasilnya kembali.

Work item diklaim dengan melakukan polling pada antrean environment: baik oleh worker always-on yang melakukan polling terus-menerus, atau handler yang dipicu webhook yang aktif saat session.status_run_started dan mulai melakukan polling.

CLI dan SDK sama-sama menyediakan worker siap pakai. CLI ant hanya mendukung pola always-on; SDK mendukung always-on maupun yang dipicu webhook. Keduanya dapat dikonfigurasi: lihat Self-hosted worker di referensi untuk flag CLI, dan Helper SDK di halaman ini untuk opsi SDK. Untuk kontrol lebih besar, panggil endpoint Environments Work secara langsung dan implementasikan worker Anda sendiri.

Sistem file sandbox

• /workspace: direktori kerja default sistem untuk eksekusi alat dan pengunduhan skill. Flag --workdir pada CLI secara default menggunakan direktori saat ini; berikan --workdir /workspace agar sesuai dengan default sistem. Skills diunduh ke <workdir>/skills/<name>/. Jika Anda menggunakan direktori kerja yang berbeda, perbarui prompt sistem agen Anda agar Claude dapat menemukan file skill.
• Output: pada environment self-hosted, prompt sistem sesi menghilangkan instruksi /mnt/session/outputs yang digunakan pada sandbox yang dikelola Anthropic, sehingga hasil akhir berada di mana pun agen menulisnya di sistem file sandbox Anda, biasanya di bawah direktori kerja.
• /mnt/memory/: memory store yang dilampirkan ke sesi diwujudkan di sini oleh worker SDK, satu direktori per store di mount_path store tersebut (misalnya, /mnt/memory/user-preferences/). Worker membuat direktori ini saat mengklaim sesi dan menghapusnya saat sesi berakhir; lihat Menggunakan memory store.

Sebelum Anda mulai

Anda memerlukan:

• Agen yang sudah ada. Jika Anda belum memilikinya, selesaikan Quickstart terlebih dahulu dan catat ID agennya.
• Host Linux dengan /bin/bash di path persis tersebut. Alat bash milik worker memanggilnya secara langsung, tanpa memeriksa PATH. SDK TypeScript juga memerlukan unzip dan tar di PATH serta Node.js 22 atau lebih baru; SDK Python dan Go menggunakan pustaka standarnya untuk ekstraksi arsip dan tidak memiliki persyaratan biner tambahan.
• CLI ant atau SDK Anthropic (Python, TypeScript, atau Go) di host worker.
• Kredensial: environment key (dibuat di Console pada langkah-langkah berikut) mengautentikasi worker ke antreannya; kunci API Claude Anda membuat sesi dan membaca statistik antrean dari luar host worker. Pembuatan key hanya dapat dilakukan di Console. Work item yang diklaim juga membawa secret per sesi yang digunakan worker untuk me-mount memory store; Anda tidak membuatnya, tetapi dalam pola sandbox-per-sesi Anda sendiri yang meneruskannya ke dalam sandbox (lihat Menjalankan satu sandbox per sesi).
• Untuk memory store, host yang sudah disiapkan. Jika sesi pada environment ini akan melampirkan memory store, siapkan /mnt/memory di host worker sebelum Anda memulai worker; lihat Menyiapkan host.

1. 1

   Buat environment self-hosted

   Di Console: Workspace > Environments > New > Self-hosted

   Atau melalui API:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client = anthropic.Anthropic()
   
   environment = client.beta.environments.create(
       name="self-hosted", config={"type": "self_hosted"}
   )
   print(environment.id)

2. 2

   Buat environment key

   Di Console, buka environment dan klik Generate environment key. Pembuatan key hanya dapat dilakukan di Console, terlepas dari apakah Anda membuat environment melalui Console atau API. Kemudian ekspor ID environment dan key di host worker:

   export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
   export ANTHROPIC_ENVIRONMENT_ID="env_..."

   

Menjalankan worker

Pilih always-on untuk penyiapan paling sederhana: proses yang berjalan lama melakukan polling antrean terus-menerus dan hanya memerlukan HTTPS keluar. Pilih dipicu webhook untuk menghindari menjalankan poller yang menganggur; ini memerlukan endpoint webhook yang dapat dijangkau Anthropic (lihat Webhooks untuk penyiapan endpoint dan verifikasi tanda tangan).

Helper SDK

SDK menyediakan tiga helper dengan tingkat kontrol yang berbeda. EnvironmentWorker mencakup sebagian besar kasus penggunaan; turun ke helper tingkat lebih rendah ketika Anda perlu meluncurkan proses per sesi Anda sendiri atau menjalankan alat terhadap sesi yang sudah diklaim.

• EnvironmentWorker: worker siap pakai. Menangani polling, penyiapan, dan eksekusi dari awal hingga akhir.
  • .run(): berjalan tanpa batas waktu, mengambil sesi saat tiba.
  • .handle_item(): menangani satu work item yang diklaim lalu keluar. Berikan identifier work, sesi, dan environment secara eksplisit, atau biarkan ia membaca variabel ANTHROPIC_* yang diatur ant beta:worker poll --on-work untuk proses yang dijalankannya. Agar sesi dapat me-mount memory store-nya, berikan juga secret milik work item sebagai work_secret (workSecret di TypeScript, WorkSecret di Go) atau atur ANTHROPIC_WORK_SECRET; ant beta:worker poll --on-work tidak mengatur variabel itu, jadi baca secret dari JSON work item yang ditulisnya ke standard input skrip Anda, seperti ditunjukkan di Menjalankan satu sandbox per sesi.
  • memory_sync_interval (memorySyncIntervalMs di TypeScript, MemorySyncInterval di Go) dan memory_sync_deletions (memorySyncDeletions, MemorySyncDeletions): seberapa sering memory store yang dilampirkan direkonsiliasi dengan server saat sesi berjalan, dan apakah file yang dihapus agen secara lokal juga dihapus dari store. Lihat Mengonfigurasi sinkronisasi untuk satuan, default, dan cara menonaktifkan dukungan memori.
• work.poller(): melakukan polling antrean kerja atas nama Anda dan memberi Anda setiap sesi yang diklaim. Gunakan ini ketika Anda ingin memutuskan apa yang terjadi untuk setiap sesi, misalnya meluncurkan sandbox alih-alih menjalankan alat in-process.
  • drain: apakah berhenti melakukan polling setelah antrean kosong alih-alih menunggu pekerjaan baru.
  • block_ms: berapa lama menunggu pekerjaan tiba sebelum kembali, dalam milidetik. Harus antara 1 dan 999 (waktu tunggu per poll; helper melakukan poll ulang secara otomatis). Berikan null (None di Python, param.Null[int64]() di Go) untuk pemeriksaan non-blocking; menghilangkan parameter ini menggunakan long-poll default 999 ms.
  • reclaim_older_than_ms: mengklaim ulang work item yang telah diklaim tetapi tidak pernah di-acknowledge dalam jumlah milidetik ini.
  • auto_stop (autoStop di TypeScript, AutoStop di Go): apakah mengirimkan sinyal stop untuk setiap work item setelah badan loop Anda selesai dengannya. Matikan setiap kali apa pun yang menjalankan work item mengirimkan stop sendiri: handle_item() melakukannya, jadi atur ke false ketika Anda menyerahkan item yang diklaim ke handle_item() seperti yang dilakukan handler webhook di halaman ini, dan begitu pula sandbox yang Anda luncurkan yang memiliki panggilan stop.
• client.beta.sessions.events.tool_runner(): menjalankan panggilan alat untuk satu sesi, dengan ID sesi dan daftar alat. Gunakan ketika Anda sudah mengklaim pekerjaan dan hanya memerlukan lapisan eksekusi.

Gunakan work poller secara langsung ketika Anda ingin meluncurkan proses per sesi Anda sendiri, misalnya menjalankan sandbox untuk setiap sesi yang diklaim:

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork

SANDBOX_ENV = (
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
)


async def launch_container(work: BetaSelfHostedWork) -> None:
    print(f"claimed session {work.data.id}")
    # Ganti `docker run` dengan peluncur sandbox Anda sendiri. Teruskan kunci
    # environment (jangan pernah kunci API Anda) dan secret per-sesi milik item kerja: worker
    # di dalamnya memerlukan secret tersebut untuk memasang penyimpanan memori sesi.
    env = os.environ | {
        "ANTHROPIC_WORK_ID": work.id,
        "ANTHROPIC_SESSION_ID": work.data.id,
        "ANTHROPIC_WORK_SECRET": work.secret or "",
    }
    forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
    launcher = await asyncio.create_subprocess_exec(
        "docker", "run", "--rm", "--detach", *forward, "your-sdk-worker-image", env=env
    )
    await launcher.wait()


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:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

Apa pun yang meluncurkan sandbox harus meneruskan secret milik work item yang diklaim ke dalamnya (misalnya sebagai ANTHROPIC_WORK_SECRET) bersama identifier sesi, work, dan environment, agar worker di dalamnya dapat me-mount memory store sesi; lihat Menjalankan satu sandbox per sesi.

AgentToolContext adalah konteks eksekusi untuk panggilan alat. Ia mendefinisikan direktori kerja dan kebijakan path, serta dapat mengunduh skills sesi. Alat file (read, write, edit, glob, grep) dibatasi pada direktori kerja ditambah direktori apa pun yang tercantum di allowed_roots (allowedRoots di TypeScript, AllowedRoots di Go), dan write serta edit juga menolak path di bawah read_only_roots (readOnlyRoots, ReadOnlyRoots). EnvironmentWorker sendiri menambahkan direktori memory store sesi ke daftar ini. Pembatasan ini adalah pagar pengaman untuk alat file saja, bukan sandbox; ia tidak membatasi bash. beta_agent_toolset_20260401(env) menerima AgentToolContext dan mengembalikan implementasi alat standar (bash, read, write, edit, glob, grep).

Dengan EnvironmentWorker: keduanya dikelola secara otomatis. Berikan factory tools untuk menyesuaikan daftar alat:

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

Dengan work.poller() dan tool_runner(): berikan daftar alat sebagai tools ke client.beta.sessions.events.tool_runner(). Untuk membangun daftar itu, 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)

Memverifikasi worker terhubung

Dari shell terpisah, dengan ANTHROPIC_API_KEY diatur ke kunci API Claude Anda (bukan environment key), pastikan workers_polling setidaknya 1:

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

Jika workers_polling tetap 0, worker tidak menjangkau antrean: pastikan ANTHROPIC_ENVIRONMENT_KEY dan ANTHROPIC_ENVIRONMENT_ID diatur di host worker. Lihat Membaca kedalaman antrean untuk respons statistik lengkap dan contoh bahasa lainnya.

Memulai sesi

Setelah worker Anda berjalan, buat sesi yang menargetkan environment tersebut. Atur AGENT_ID ke ID agen yang Anda catat di Sebelum Anda mulai. Sesi masuk ke antrean kerja environment dan menunggu di sana hingga worker mengklaimnya; jika tidak ada worker yang terhubung, sesi tetap dalam antrean alih-alih gagal.

Anthropic tidak me-mount file atau repositori GitHub ke sandbox self-hosted. Untuk menyediakan file khusus sesi, berikan referensi file (seperti path S3 atau commit SHA) di field metadata sesi. Work item yang diklaim tidak membawa metadata sesi, tetapi membawa ID sesi: skrip spawn atau handler --on-work Anda mengambil sesi (GET /v1/sessions/{session_id}) untuk membaca field metadata, lalu menyiapkan file ke direktori kerja sebelum eksekusi alat dimulai.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

Lihat Self-hosted worker di referensi untuk daftar lengkap flag CLI, dan Helper SDK untuk opsi helper SDK.

Menggunakan memory store

Sesi pada environment self-hosted melampirkan memory store persis seperti sesi pada environment cloud: cantumkan di resources saat Anda membuat sesi, seperti ditunjukkan di Melampirkan memory store ke sesi. Sebuah sesi menerima hingga 8 memory store. Pada environment self-hosted, worker SDK, bukan infrastruktur Anthropic, yang mewujudkan setiap store untuk agen, sehingga memory store di sana memerlukan EnvironmentWorker (atau metode handle_item()-nya) dari SDK Python, TypeScript, atau Go.

Worker CLI ant (ant beta:worker poll dan ant beta:worker run) tidak me-mount memory store. Untuk menggabungkan poller CLI dengan memory store, jalankan worker SDK di dalam sandbox per sesi seperti dijelaskan di Menjalankan satu sandbox per sesi.

Memory store tidak dapat dilampirkan ke sesi pada environment self-hosted di Claude Platform on AWS.

Cara worker menangani memori

Ketika worker mengklaim work item yang sesinya memiliki memory store terlampir, ia:

1. Mengunduh setiap store yang dilampirkan ke mount_path-nya di host worker, mengautentikasi dengan secret per sesi milik work item. mount_path adalah direktori yang sama di bawah /mnt/memory/ yang digunakan sesi cloud (misalnya, /mnt/memory/user-preferences/ untuk store bernama "User Preferences"), dan prompt sistem sesi menjelaskannya kepada agen.
2. Menambahkan direktori tersebut ke allowed roots alat file, dan direktori store yang dilampirkan dengan access: "read_only" ke read-only roots-nya, sehingga agen bekerja pada memori dengan alat read, write, edit, glob, dan grep yang sama yang digunakannya di direktori kerja.
3. Merekonsiliasi perubahan lokal dan remote setelah panggilan alat, paling banyak sekali per interval sinkronisasi (15 detik secara default): memori yang berubah di store ditulis ke disk, dan file yang diubah agen diunggah ke store.
4. Menjalankan sinkronisasi akhir saat sesi berakhir, menyelesaikan unggahan apa pun yang masih tertunda hingga 30 detik, lalu menghapus direktori yang dibuatnya. Worker yang dibatalkan saat sesi berjalan melewatkan sinkronisasi akhir tetapi tetap mengunggah file yang berubah dan menghapus direktori sebelum keluar.

Memory store di sisi Anthropic tetap menjadi sumber kebenaran. Versi memori, redaksi, dan melihat atau mengedit memori di Console berfungsi seperti pada sesi cloud, dan pembacaan serta penulisan memori oleh agen muncul di event stream sebagai event alat biasa. Karena setiap worker melakukan sinkronisasi berdasarkan interval, perubahan yang ditulis di satu sesi baru terlihat oleh sesi lain yang sedang berjalan setelah keduanya melakukan sinkronisasi, biasanya jauh di bawah satu menit pada interval default; sesi pada sandbox cloud melihat perubahan satu sama lain hampir seketika.

Setiap direktori store berisi file penanda bernama .anthropic-memory-store yang mengikat direktori ke store-nya. Biarkan di tempatnya: worker tidak menyinkronkan direktori yang penandanya hilang atau diubah.

Menyiapkan host

Memory store pada sandbox self-hosted memerlukan sistem file POSIX di host worker (host Linux dari Sebelum Anda mulai); host Windows tidak didukung, karena worker memerlukan O_NOFOLLOW saat membuka file memori. Sistem file yang case-sensitive direkomendasikan, agar path memori yang hanya berbeda huruf besar-kecilnya tidak bertabrakan.

Sebelum Anda memulai worker, buat direktori induk dan jadikan dapat ditulis oleh pengguna yang menjalankan worker:

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

Jangan membuat direktori per store sendiri. Worker membuat direktori mount_path setiap store (misalnya, /mnt/memory/user-preferences) saat sesi dimulai, menolak memulai pekerjaan sesi jika sudah ada sesuatu di path tersebut, dan menghapus direktori saat sesi berakhir. Dua aturan operasional berlaku:

• Jalankan satu sesi per sistem file ketika sesi melampirkan store yang sama. Dua sesi tidak dapat me-mount store yang sama di satu host pada waktu yang sama, karena keduanya memerlukan path yang sama. Memberi setiap sesi sandbox-nya sendiri, seperti dijelaskan di Menjalankan satu sandbox per sesi, memenuhi aturan ini.
• Hentikan worker dengan baik. Ketika Anda menghentikan worker saat sesi berjalan, EnvironmentWorker mengunggah file memori sesi yang berubah dan menghapus direktori store-nya hanya jika ia dibatalkan, bukan di-kill: proses yang di-kill tidak menjalankan teardown, dan worker tidak memasang signal handler sendiri. Hubungkan SIGTERM dan SIGINT ke pembatalan di proses yang menjalankannya: abort signal yang Anda berikan ke worker di TypeScript, batalkan context di Go, dan di Python batalkan task yang menjalankan run() atau handle_item(). Lakukan itu dari signal handler ketika worker Anda adalah prosesnya, seperti yang dilakukan worker mandiri di halaman ini, atau dari shutdown hook server Anda sendiri ketika worker berjalan di dalam handler webhook, yang tidak boleh mengambil alih sinyal server. Kemudian hentikan worker dengan SIGTERM dan beri setidaknya 30 detik untuk keluar sebelum hard kill apa pun, karena unggahan akhir dapat memakan waktu selama itu. Jika worker di-kill sebelum teardown-nya berjalan, hapus direktori store yang tersisa di bawah /mnt/memory/ sebelum sesi berikutnya yang melampirkan store tersebut; edit apa pun di dalamnya yang belum tersinkronisasi akan hilang.

Jalankan satu sandbox per sesi

Pola sandbox-per-sesi di Jalankan worker memberi setiap sesi filesystem yang baru, yang merupakan hal yang diminta oleh Siapkan host ketika sesi-sesi melampirkan store yang sama. Pertahankan ant beta:worker poll --on-work (atau work poller milik SDK) sebagai poller di host.

Entrypoint ant beta:worker run yang ditampilkan di sana tidak me-mount memory store, jadi bangun image per-sesi di sekitar worker SDK sebagai gantinya: entrypoint-nya membangun EnvironmentWorker dan memanggil handle_item() (handleItem di TypeScript, HandleItem di Go), yang membaca pengenal sesi, work, dan environment dari variabel ANTHROPIC_* serta secret per-sesi milik work item dari ANTHROPIC_WORK_SECRET. Anda juga dapat meneruskan secret secara eksplisit sebagai work_secret (workSecret di TypeScript, WorkSecret di Go).

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


async def main() -> None:
    async with AsyncAnthropic(auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]) as client:
        worker = EnvironmentWorker(client, workdir="/workspace")
        # Tanpa argumen, handle_item() membaca variabel ANTHROPIC_* yang diteruskan oleh
        # skrip spawn, termasuk ANTHROPIC_WORK_SECRET.
        task = asyncio.create_task(worker.handle_item())
        # Membatalkan task saat container dihentikan memungkinkan worker mengunggah
        # file memori yang berubah dan menghapus direktori store 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())

ant beta:worker poll --on-work tidak menetapkan ANTHROPIC_WORK_SECRET untuk skrip yang dijalankannya, jadi skrip spawn membaca secret dari JSON work item pada standard input-nya dan meneruskannya ke dalam sandbox:

#!/bin/bash
# spawn.sh: dipanggil sekali per item kerja yang diklaim
# Item kerja yang diklaim tiba sebagai JSON di stdin. Secret-nya adalah
# kredensial per sesi yang diperlukan oleh endpoint memory store.
ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
export ANTHROPIC_WORK_SECRET
mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
exec docker run --rm \
  -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
  -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
  -e ANTHROPIC_WORK_SECRET \
  -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
  your-sdk-worker-image

Jika Anda mengklaim work dengan work poller milik SDK sebagai gantinya, teruskan secret setiap item yang diklaim ke dalam sandbox yang Anda luncurkan dengan cara yang sama. Teruskan hanya ke dalam sandbox yang melayani sesi tersebut, dan jangan pernah mencatatnya ke log.

Image sandbox juga memerlukan /mnt/memory yang dapat ditulis (lihat Siapkan host). Karena setiap sandbox melayani satu sesi dan dibuang setelahnya, tidak ada direktori sisa yang perlu dibersihkan, dan direktori memori tidak perlu di-bind-mount ke host: worker mengunggah isinya ke store sebelum sandbox keluar. Jika Anda menghentikan container sebelum sesinya berakhir, kirim sinyal yang diubah entrypoint menjadi pembatalan (lihat Siapkan host) alih-alih mematikannya secara paksa, sehingga unggahan tersebut tetap berjalan. Beri container waktu untuk menyelesaikan unggahan juga: Docker menyusul sinyal stop dengan SIGKILL setelah 10 detik secara default, jadi naikkan batas itu menjadi setidaknya 30 detik seperti yang diminta Siapkan host, dengan --stop-timeout pada docker run atau termination grace period milik orkestrator Anda.

Konfigurasikan sinkronisasi

Dua opsi EnvironmentWorker mengontrol perilaku memori:

• memory_sync_interval (Python, dalam detik; memorySyncIntervalMs di TypeScript, dalam milidetik; MemorySyncInterval di Go, sebuah duration): seberapa sering store yang terlampir direkonsiliasi dengan server saat sesi berjalan. Default-nya 15 detik; minimumnya 5 detik. Interval yang lebih pendek mempersempit jendela waktu di mana sesi lain melihat memori yang usang, dengan biaya lebih banyak permintaan memory store. None di Python, null di TypeScript, atau duration negatif di Go menonaktifkan dukungan memori sepenuhnya: worker tidak mengunduh maupun menyinkronkan store, dan sesi dengan memory store terlampir berjalan tanpanya meskipun prompt sistemnya masih mendeskripsikannya, jadi nonaktifkan dukungan memori hanya pada worker yang sesinya tidak melampirkan memory store. Selama dukungan memori diaktifkan, work item yang tiba tanpa secret per-sesi untuk sesi dengan store terlampir akan gagal alih-alih berjalan tanpa memori (lihat Pecahkan masalah mount memori).
• memory_sync_deletions (memorySyncDeletions di TypeScript, MemorySyncDeletions di Go): apakah file yang dihapus agen secara lokal juga dihapus dari store. Nilainya salah satu dari "enabled" (default), "log_only", atau "disabled" di Python dan TypeScript, dan salah satu dari konstanta environments.MemorySyncDeletionsEnabled (zero value), environments.MemorySyncDeletionsLogOnly, atau environments.MemorySyncDeletionsDisabled di Go. Ketika diaktifkan, worker menghapus memori dari store setelah sinkronisasi berikutnya mengonfirmasi bahwa file tersebut masih hilang; dalam mode log-only, worker menjalankan pemeriksaan yang sama tetapi hanya mencatat ke log apa yang akan dihapusnya, yang memungkinkan Anda mengamati apa yang akan dihapus worker Anda sebelum Anda mempercayai mode enabled; ketika dinonaktifkan, worker tidak pernah menghapus dari store. Unggahan dan unduhan tidak terpengaruh oleh pengaturan ini.

Tetapkan opsi-opsi ini di tempat Anda membangun worker, baik melalui konstruktor EnvironmentWorker atau, di Python dan TypeScript, factory client.beta.environments.work.worker() yang digunakan oleh webhook handler.

Misalnya, untuk menyinkronkan setiap 10 detik dan hanya mencatat ke log penghapusan yang akan dilakukan worker:

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

Store read-only dan konflik

Untuk store yang dilampirkan dengan access: "read_only", alat write dan edit menolak mengubah file di dalam direktorinya, dan worker tidak pernah mengunggah apa pun darinya. Perubahan yang dibuat melalui bash, atau melalui alat kustom atau server MCP yang Anda layani dari sandbox, tidak diblokir secara lokal: perubahan tersebut tidak pernah disinkronkan ke store, dan perubahan remote berikutnya pada memori itu akan menimpanya. Jika Anda memerlukan salinan lokal itu sendiri tetap tidak berubah selama sesi, nonaktifkan alat bash untuk agen tersebut dan jangan berikan alat kustom yang menulis ke filesystem sandbox; jangan me-mount path store sebagai read-only, karena worker itu sendiri harus membuat direktori dan menulis memori yang diunduh ke dalamnya.

Konflik diselesaikan dengan memenangkan store. Ketika agen mengubah file memori yang juga berubah di store sejak sesi terakhir menyinkronkannya, worker mempertahankan versi store pada sinkronisasi berikutnya, menimpa file lokal dengannya, dan mencatat peringatan ke log; alat write dan edit itu sendiri berhasil dan tidak ada error yang sampai ke agen. Jika perubahan agen masih berlaku, agen dapat membaca ulang file setelah sinkronisasi dan membuat perubahan itu lagi.

Pecahkan masalah mount memori

Worker mencatat kegagalan mount dan sinkronisasi latar belakang ke log alih-alih melaporkannya ke sesi; hanya penolakan read-only yang sampai ke agen, sebagai error alat (lihat Store read-only dan konflik). Jika memory store tidak dapat di-mount ketika worker mengklaim sesi, worker menggagalkan work item: sesi tidak memancarkan event error dan tetap idle.

Layani alat kustom dari sandbox Anda

Alat kustom adalah alat yang dieksekusi oleh kode Anda sendiri: agen memancarkan event agent.custom_tool_use dan menunggu user.custom_tool_result yang cocok. Worker dapat menjadi kode tersebut, dan karena berjalan di dalam sandbox Anda, alat tersebut menjangkau layanan internal, kredensial, dan network egress yang Anda konfigurasikan untuk sandbox, dan tidak lebih. Kunci environment mengotorisasi pengiriman hasil alat kustom, sehingga kunci API Claude Anda tetap berada di luar host worker.

1. 1

   Deklarasikan alat pada agen

   Tambahkan entri custom ke tools milik agen yang name-nya cocok dengan alat yang didaftarkan worker Anda. Lihat Alat kustom untuk bentuk deklarasi lengkapnya.

   {
     "type": "custom",
     "name": "get_order_status",
     "description": "Look up an order in the internal fulfillment system by order ID.",
     "input_schema": {
       "type": "object",
       "properties": {
         "order_id": { "type": "string", "description": "The order ID" }
       },
       "required": ["order_id"]
     }
   }

   
2. 2

   Daftarkan implementasi pada worker

   Teruskan alat melalui factory tools milik worker (lihat Helper SDK), bersama toolset bawaan:

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   import os
   from anthropic import AsyncAnthropic, beta_async_tool
   from anthropic.lib.environments import EnvironmentWorker
   from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
   
   
   @beta_async_tool
   async def get_order_status(order_id: str) -> str:
       """Look up an order in the internal fulfillment system by order ID."""
       # Berjalan di host worker: dapat memanggil apa pun yang bisa dijangkau sandbox.
       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:
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
               tools=lambda env: [*beta_agent_toolset_20260401(env), get_order_status],
           ).run()
   
   
   asyncio.run(main())

Worker hanya menjawab alat yang terdaftar padanya. Alat kustom yang dideklarasikan pada agen tetapi tidak terdaftar pada worker atau klien mana pun membuat sesi terjeda dengan stop reason requires_action sampai sesuatu mengirimkan hasilnya; lihat Menangani panggilan alat kustom untuk alur event-nya.

Bungkus server MCP sebagai alat kustom

Konektor MCP terhubung ke server MCP dari sisi Anthropic, sehingga server harus mengekspos endpoint HTTP yang dapat dijangkau Anthropic, secara langsung atau melalui tunnel MCP. Untuk menggunakan server yang hanya dapat dijangkau jaringan Anda, jadikan worker sebagai klien MCP sebagai gantinya dan deklarasikan alat-alat server sebagai alat kustom. Server MCP tidak memerlukan konektivitas masuk dari luar jaringan Anda; Anthropic menerima definisi alat yang Anda deklarasikan pada agen, input setiap panggilan, dan hasil yang dikirim balik oleh worker Anda. Saat runtime, model memanggil alat yang dibungkus seperti alat kustom lainnya:

1. Agen memancarkan event agent.custom_tool_use.
2. Worker, di dalam sandbox Anda, meneruskan panggilan melalui sesi MCP terbukanya ke server di jaringan Anda.
3. Worker mengirimkan respons server sebagai user.custom_tool_result.

Helper MCP sisi klien milik SDK mengonversi alat-alat server menjadi alat yang dapat dijalankan yang diterima worker; instal SDK MCP bersama SDK Anthropic (pip install "anthropic[mcp]" "mcp>=1.24", npm install @modelcontextprotocol/sdk, go get github.com/modelcontextprotocol/go-sdk). Contoh-contoh ini terhubung tanpa autentikasi; untuk mengirim kredensial, konfigurasikan klien HTTP atau opsi permintaan yang Anda serahkan ke transport MCP (http_client di Python, requestInit di TypeScript, HTTPClient di Go).

1. 1

   Deklarasikan alat-alat server pada agen

   Daftar alat-alat server MCP dan deklarasikan masing-masing sebagai alat custom; name, description, dan inputSchema MCP dipetakan satu-ke-satu ke field alat kustom. Jika server memaginasi daftar alatnya, deklarasikan setiap halaman; worker harus mendaftar halaman-halaman yang sama.

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   from typing import Any, cast
   from anthropic import AsyncAnthropic
   from anthropic.types.beta import BetaManagedAgentsCustomToolParams
   from mcp import ClientSession, types
   # Memerlukan mcp >= 1.24, yang mengganti nama streamablehttp_client menjadi streamable_http_client.
   from mcp.client.streamable_http import streamable_http_client
   
   MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
   
   
   def to_custom_tool(tool: types.Tool) -> BetaManagedAgentsCustomToolParams:
       # Field MCP dipetakan satu-ke-satu ke deklarasi alat kustom. Cast ini
       # meneruskan dictionary skema ke parameter bertipe milik SDK tanpa perubahan.
       return {
           "type": "custom",
           "name": tool.name,
           "description": tool.description or tool.name,
           "input_schema": cast(Any, tool.inputSchema),
       }
   
   
   async def main() -> None:
       # Jalankan ini di tempat Anda membuat agen, bukan di host worker: skrip ini
       # melakukan autentikasi dengan kunci API Claude Anda (ANTHROPIC_API_KEY).
       async with (
           streamable_http_client(MCP_SERVER_URL) as (read, write, _),
           ClientSession(read, write) as mcp_session,
           AsyncAnthropic() as client,
       ):
           await mcp_session.initialize()
           listed = await mcp_session.list_tools()
           agent = await client.beta.agents.create(
               name="Internal tools agent",
               model="claude-opus-5",
               tools=[
                   {"type": "agent_toolset_20260401"},
                   *[to_custom_tool(tool) for tool in listed.tools],
               ],
           )
           print(agent.id)
   
   
   asyncio.run(main())

2. 2

   Layani alat-alat dari worker

   Hubungkan ke server MCP yang sama saat startup, konversi alat-alatnya dengan helper MCP, dan daftarkan bersama toolset bawaan. Pertahankan satu sesi MCP terbuka selama masa hidup worker.

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   import os
   from datetime import timedelta
   from anthropic import AsyncAnthropic
   from anthropic.lib.environments import EnvironmentWorker
   from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
   from anthropic.lib.tools.mcp import async_mcp_tool
   from mcp import ClientSession
   # Memerlukan mcp >= 1.24, yang mengganti nama streamablehttp_client menjadi streamable_http_client.
   from mcp.client.streamable_http import streamable_http_client
   
   MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
   
   
   async def main() -> None:
       environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
       environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
       # Hubungkan ke server MCP sekali saat startup dan biarkan sesi tetap terbuka selama
       # masa hidup worker. Timeout mengubah panggilan alat yang macet menjadi hasil
       # error alih-alih panggilan yang terhenti.
       async with (
           streamable_http_client(MCP_SERVER_URL) as (read, write, _),
           ClientSession(read, write, read_timeout_seconds=timedelta(seconds=60)) as mcp_session,
           AsyncAnthropic(auth_token=environment_key) as client,
       ):
           await mcp_session.initialize()
           listed = await mcp_session.list_tools()
           mcp_tools = [async_mcp_tool(tool, mcp_session) for tool in listed.tools]
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
               tools=lambda env: [*beta_agent_toolset_20260401(env), *mcp_tools],
           ).run()
   
   
   asyncio.run(main())

Perhatikan hal-hal berikut ketika Anda membungkus server MCP:

• Alat dideklarasikan, bukan ditemukan saat runtime. Worker mendaftar alat-alat server MCP sekali saat startup dan tidak dapat menambahkan alat ke sesi yang sedang berjalan. Ketika alat-alat server berubah, deklarasikan lagi, pada agen atau pada sesi idle melalui Memperbarui konfigurasi agen, dan mulai ulang worker.
• Nama dan deskripsi harus sesuai dengan Managed Agents API. Nama alat kustom unik per agen dan menggunakan huruf, angka, garis bawah, dan tanda hubung (1–128 karakter); deskripsi yang tidak kosong wajib ada; dan array tools milik agen menerima paling banyak 128 entri (setiap alat yang dibungkus adalah satu entri, dan toolset bawaan adalah satu entri lagi). API menolak deklarasi yang menggunakan ulang nama alat, menamai alat kustom dengan nama alat agen bawaan seperti bash atau read, atau menggunakan prefiks mcp__ yang dicadangkan. Helper MCP mempertahankan nama dan deskripsi server, jadi ganti nama atau pangkas jika diperlukan. Ketika dua server mengekspos nama alat yang sama, definisikan wrapper-nya sendiri dengan nama berprefiks dan buat wrapper itu memanggil nama alat asli milik server.
• Sebagian besar skema diteruskan tanpa perubahan. API menerima kata kunci JSON Schema yang umum dipancarkan server MCP, seperti additionalProperties dan title. API menolak kata kunci referensi seperti $ref di mana pun dalam input_schema alat kustom, jadi inline-kan skema yang difaktorkan oleh generator seperti pydantic ke dalam $defs. API juga menolak oneOf, anyOf, dan allOf tingkat atas, serta nama properti di luar huruf, angka, garis bawah, titik, dan tanda hubung (1–64 karakter).
• Kegagalan alat muncul sebagai hasil alat error. Ketika server MCP melaporkan error alat, worker mengirimkan hasil alat error yang dapat ditanggapi model. Konten MCP yang tidak memiliki padanan hasil alat, seperti blok audio dan tautan resource, juga muncul sebagai error. Tetapkan timeout pada klien MCP untuk kegagalan yang lebih cepat dan lebih jelas, seperti yang dilakukan contoh worker Python dengan read_timeout_seconds. Tanpa timeout, panggilan yang macet baru menjadi hasil error ketika timeout permintaan default SDK MCP TypeScript terpicu (sekitar satu menit) atau ketika backstop milik worker sendiri terpicu: sekitar dua setengah menit di Python, dan dua menit di Go, di mana worker membatalkan panggilan alat yang melampaui default 120 detiknya dan mengirimkan hasil error.
• Bungkus server yang Anda operasikan atau percayai. Nama, deskripsi, dan hasil alat yang dibungkus masuk ke konteks model seperti alat lainnya: input tak tepercaya yang dapat memengaruhi apa yang dilakukan agen dengan alat-alat lainnya, termasuk bash di host worker. Deklarasikan hanya alat yang Anda maksudkan untuk digunakan agen.
• Kebijakan izin tidak berlaku untuk alat kustom. Kebijakan izin mengatur toolset bawaan dan MCP; worker mengeksekusi setiap panggilan alat yang dibungkus yang dibuat model, jadi tempatkan langkah persetujuan apa pun di kode alat Anda sendiri.

Pemantauan dan operasi

Panggilan-panggilan ini dijalankan dari tooling pemantauan atau operasi Anda, diautentikasi dengan kunci API Claude Anda, untuk mengamati dan mengelola armada worker. Loop klaim dan keep-alive ditangani di dalam helper worker, jadi Anda tidak memanggil endpoint tersebut secara langsung.

Baca kedalaman antrean

work.stats mengembalikan status antrean untuk sebuah environment:

• depth adalah jumlah item yang menunggu untuk diklaim. Skalakan armada worker Anda atau buat peringatan atas backlog berdasarkan nilai ini.
• pending adalah jumlah item yang diklaim oleh worker tetapi belum di-acknowledge. Helper worker meng-acknowledge setiap item sebelum memprosesnya, sehingga nilai ini tetap mendekati nol dalam operasi normal; nilai bukan nol yang berkelanjutan berarti sebuah worker macet di antara mengklaim dan meng-acknowledge.
• oldest_queued_at adalah timestamp item tertua yang masih berada di antrean, menunggu untuk diklaim atau sudah diklaim tetapi belum di-acknowledge, atau null ketika tidak ada.
• workers_polling adalah jumlah worker yang telah melakukan polling dalam 30 detik terakhir. Gunakan ini untuk peringatan liveness.

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
}

Hentikan sesi dengan anggun

Gunakan 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 pematian, dan pada titik itu work item menjadi stopped. Teruskan force: true di body permintaan (dengan CLI, teruskan --force) untuk menandai work item sebagai stopped segera alih-alih menunggu konfirmasi worker.

Karena panggilan-panggilan ini dijalankan dari tooling operasi Anda dan bukan dari host worker, ANTHROPIC_WORK_ID tidak ditetapkan secara otomatis. Tetapkan ke ID work item target sebelum menjalankan contoh-contoh berikut. Untuk menemukan ID work item, daftar work item milik 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)

Langkah selanjutnya