Sandbox yang di-host sendiri

Secara default, Managed Agents mengeksekusi alat dan kode di dalam sandbox cloud yang dikelola Anthropic. Sandbox yang di-host sendiri menjaga orkestrasi tetap di sisi Anthropic tetapi memindahkan eksekusi alat ke infrastruktur yang Anda kendalikan, sehingga kode agen, filesystem, dan egress jaringan tidak pernah meninggalkan lingkungan Anda.

Eksekusi alat tetap berada di host Anda: filesystem 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. Lihat model keamanan untuk batasan aliran data lengkap.



Perbedaannya dengan lingkungan 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 yang di-host sendiri 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 memberikan 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 adalah proses yang Anda jalankan di infrastruktur Anda sendiri. Worker ini menerima permintaan eksekusi alat dari Anthropic dan menjalankannya secara lokal. Lingkungan self_hosted bertindak sebagai antrean kerja: ketika sebuah sesi ditugaskan ke lingkungan tersebut, Anthropic memasukkan sesi itu ke antrean sebagai item kerja. Worker Anda mengklaim item kerja dari antrean tersebut, membuat konteks eksekusi untuk masing-masing item, mengunduh skill agen (sumber daya berbasis filesystem yang dapat digunakan kembali dan memberikan keahlian spesifik domain kepada agen), menjalankan panggilan alat, dan mengirimkan hasilnya kembali.

Item kerja diklaim dengan melakukan polling pada antrean lingkungan: 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 keduanya menyertakan worker yang sudah dibangun sebelumnya. CLI ant hanya mendukung pola always-on; SDK mendukung always-on dan 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 lanjut, panggil endpoint Environments Work secara langsung dan implementasikan worker Anda sendiri.



Filesystem sandbox

• /workspace: direktori kerja default sistem untuk eksekusi alat dan pengunduhan skill. Flag --workdir CLI secara default menggunakan direktori saat ini; berikan --workdir /workspace untuk mencocokkan default sistem. Skill diunduh ke <workdir>/skills/<name>/. Jika Anda menggunakan direktori kerja yang berbeda, perbarui prompt sistem agen Anda sehingga Claude dapat menemukan file skill.
• Output: pada lingkungan yang di-host sendiri, 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 filesystem sandbox Anda, biasanya di bawah direktori kerja.



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 yang tepat tersebut. Alat bash worker memanggilnya secara langsung, tanpa memeriksa PATH. SDK TypeScript juga memerlukan unzip dan tar pada PATH serta Node.js 22 atau lebih baru; SDK Python dan Go menggunakan pustaka standar mereka untuk ekstraksi arsip dan tidak memiliki persyaratan biner tambahan.
• CLI ant atau SDK Anthropic (Python, TypeScript, atau Go) pada host worker.
• Dua kredensial: environment key (dihasilkan 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.



Menjalankan worker

Pilih always-on untuk pengaturan paling sederhana: proses yang berjalan lama melakukan polling antrean secara terus-menerus dan hanya memerlukan HTTPS keluar. Pilih dipicu webhook untuk menghindari menjalankan poller yang idle; ini memerlukan endpoint webhook yang dapat dijangkau Anthropic (lihat Webhook untuk pengaturan endpoint dan verifikasi signature).



Helper SDK

SDK menyediakan tiga helper pada 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, pengaturan, dan eksekusi dari awal hingga akhir.
  • .run(): berjalan tanpa batas waktu, mengambil sesi saat sesi tiba.
  • .handle_item(): menangani satu item kerja yang diklaim dan keluar. Berikan identifier work, session, dan environment secara eksplisit, atau biarkan membaca variabel ANTHROPIC_* yang diatur ant beta:worker poll --on-work untuk proses yang dijalankannya.
• work.poller(): melakukan polling antrean kerja atas nama Anda dan memberikan 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 polling ulang secara otomatis). Berikan null (None di Python, param.Null[int64]() di Go) untuk pemeriksaan non-blocking; menghilangkan parameter menggunakan long-poll default 999 ms.
  • reclaim_older_than_ms: klaim ulang item kerja yang diklaim tetapi tidak pernah di-acknowledge dalam jumlah milidetik ini.
  • auto_stop: apakah mengirimkan sinyal stop untuk setiap item kerja setelah body loop Anda selesai dengannya. Poller Go tidak memiliki opsi opt-out dan selalu mengirimkan sinyal stop, jadi blokir di body loop sampai sesi selesai alih-alih melepaskannya.
• 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


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Ganti dengan peluncur sandbox per-sesi milik Anda sendiri. Teruskan
    # ANTHROPIC_ENVIRONMENT_KEY ke dalam sandbox yang diluncurkan, jangan pernah
    # kunci API Anda.
    print(f"claimed session {work.data.id}")


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())

AgentToolContext adalah konteks eksekusi untuk panggilan alat. Ini mendefinisikan direktori kerja dan kebijakan path, dan dapat mengunduh skill sesi. 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 tersebut, atur 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)



Verifikasi worker terhubung

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

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

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



Memulai sesi

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

Anthropic tidak memasang file atau repositori GitHub ke dalam sandbox yang di-host sendiri. Untuk membuat file spesifik sesi tersedia, berikan referensi file (seperti path S3 atau commit SHA) di field metadata sesi. Item kerja 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, kemudian menyiapkan file ke dalam 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.



Melayani alat kustom dari sandbox Anda

Alat kustom adalah alat yang dieksekusi oleh kode Anda sendiri: agen mengeluarkan event agent.custom_tool_use dan menunggu user.custom_tool_result yang sesuai. Worker dapat menjadi kode tersebut, dan karena berjalan di dalam sandbox Anda, alat tersebut menjangkau layanan internal, kredensial, dan egress jaringan yang Anda konfigurasikan untuk sandbox, dan tidak lebih dari itu. Environment key mengotorisasi pengiriman hasil alat kustom, sehingga kunci API Claude Anda tetap tidak berada di host worker.

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.



Membungkus server MCP sebagai alat kustom

MCP connector terhubung ke server MCP dari sisi Anthropic, sehingga server harus mengekspos endpoint HTTP yang dapat dijangkau Anthropic, secara langsung atau melalui MCP tunnel. Untuk menggunakan server yang hanya dapat dijangkau jaringan Anda, jadikan worker sebagai klien MCP dan deklarasikan 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 dikirimkan kembali oleh worker Anda. Saat runtime, model memanggil alat yang dibungkus seperti alat kustom lainnya:

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

Helper MCP sisi klien SDK mengonversi 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 request yang Anda berikan ke transport MCP (http_client di Python, requestInit di TypeScript, HTTPClient di Go).

Perhatikan hal-hal berikut saat Anda membungkus server MCP:

• Alat dideklarasikan, bukan ditemukan saat runtime. Worker mendaftar alat server MCP sekali saat startup dan tidak dapat menambahkan alat ke sesi yang sedang berjalan. Ketika 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 API Managed Agents. Nama alat kustom unik per agen dan menggunakan huruf, angka, garis bawah, dan tanda hubung (1–128 karakter); deskripsi yang tidak kosong diperlukan; dan array tools agen menerima paling banyak 128 entri (setiap alat yang dibungkus adalah satu entri, dan toolset bawaan adalah satu lagi). API menolak deklarasi yang menggunakan kembali 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 sendiri dengan nama yang diberi prefiks dan buat wrapper tersebut memanggil nama alat asli server.
• Sebagian besar skema diteruskan tanpa perubahan. API menerima kata kunci JSON Schema yang umumnya dikeluarkan server MCP, seperti additionalProperties dan title. API menolak kata kunci referensi seperti $ref di mana pun dalam input_schema alat kustom, jadi inline skema yang difaktorkan 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 direaksikan model. Konten MCP tanpa padanan hasil alat, seperti blok audio dan tautan resource, juga muncul sebagai error. Atur timeout pada klien MCP untuk kegagalan yang lebih cepat dan lebih jelas, seperti yang dilakukan contoh worker Python dengan read_timeout_seconds. Tanpa itu, panggilan yang menggantung menjadi hasil error hanya ketika timeout request default SDK MCP TypeScript terpicu (sekitar satu menit) atau ketika backstop worker sendiri terpicu: sekitar dua setengah menit di Python, dan dua menit di Go, di mana worker membatalkan panggilan alat yang melebihi default 120 detiknya dan mengirimkan hasil error.
• Bungkus server yang Anda operasikan atau percaya. Nama, deskripsi, dan hasil alat yang dibungkus masuk ke konteks model seperti alat lainnya: input yang tidak tepercaya yang dapat memengaruhi apa yang dilakukan agen dengan alat lainnya, termasuk bash pada 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 letakkan langkah persetujuan apa pun di kode alat Anda sendiri.



Pemantauan dan operasi

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.



Membaca kedalaman antrean

work.stats mengembalikan status antrean untuk sebuah lingkungan:

• depth adalah jumlah item yang menunggu untuk diklaim. Skalakan armada worker Anda atau beri peringatan pada 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 non-nol yang berkelanjutan berarti worker terhenti antara mengklaim dan meng-acknowledge.
• oldest_queued_at adalah timestamp item tertua yang masih dalam antrean, menunggu untuk diklaim atau 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
}



Menghentikan sesi dengan baik

Gunakan work.stop untuk meminta worker yang menangani sesi tertentu agar menutupnya. Secara default, work item berpindah ke status stopping: worker akan menyadarinya pada heartbeat lease berikutnya, membatalkan panggilan alat sesi yang sedang berjalan, dan mengonfirmasi penutupan, yang pada titik itu work item menjadi stopped. Sertakan force: true dalam body permintaan (dengan CLI, sertakan --force) untuk langsung menandai work item sebagai stopped tanpa menunggu konfirmasi dari worker.

Karena panggilan ini dijalankan dari perangkat operasional Anda dan bukan dari host worker, ANTHROPIC_WORK_ID tidak diatur secara otomatis. Atur variabel tersebut ke ID work item target sebelum menjalankan contoh berikut. Untuk menemukan ID work item, daftarkan 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)



Langkah selanjutnya