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 tetap menjaga orkestrasi 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 selengkapnya.

Perbedaannya dengan lingkungan cloud

Self-hosting cocok digunakan 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.

Environment worker

"Environment worker" (pekerja lingkungan) adalah proses yang Anda jalankan di infrastruktur Anda sendiri. Proses ini menerima permintaan eksekusi alat dari Anthropic dan menjalankannya secara lokal. Lingkungan self_hosted bertindak sebagai antrean kerja: ketika sebuah sesi ditetapkan 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 yang selalu aktif 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 selalu aktif; SDK mendukung pola selalu aktif 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. Pada Claude Platform on AWS, endpoint list GET /v1/environments/{id}/work dan padanan SDK-nya saat ini tidak tersedia; endpoint kerja lainnya (poll, ack, heartbeat, stop, post results, per-item get, dan stats) berfungsi normal.

Filesystem 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. Skill diunduh ke <workdir>/skills/<name>/. Jika Anda menggunakan direktori kerja yang berbeda, perbarui prompt sistem agen Anda agar Claude dapat menemukan file skill.
• /mnt/session/outputs: harness worker menginstruksikan Claude untuk menulis hasil akhir di sini. Dalam mode sandbox, mount direktori host di path ini untuk mengambil output setelah sesi berakhir. Dalam mode in-process, alat file worker menulis di bawah direktori kerja, sehingga path ini tidak berlaku.

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 persis sama. SDK TypeScript juga memerlukan unzip, tar, dan Node.js 22 atau yang lebih baru; SDK Python menggunakan pustaka standar untuk ekstraksi arsip dan tidak memiliki persyaratan biner tambahan. Dependensi ini di-resolve pada path tetap dan tidak mengikuti override PATH.
• CLI ant atau SDK Anthropic (Python, TypeScript, atau Go) pada host worker.
• Dua kredensial: environment key (dihasilkan pada langkah-langkah berikut) mengautentikasi worker ke antreannya; kunci API Claude Anda membuat sesi dan membaca statistik antrean dari luar host worker.

Menjalankan worker

Pilih selalu aktif untuk penyiapan paling sederhana: proses yang berjalan lama melakukan polling pada 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 penyiapan 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, penyiapan, dan eksekusi dari awal hingga akhir.
  • .run(): berjalan tanpa batas, mengambil sesi saat sesi tiba. Keluar dengan bersih saat menerima SIGTERM.
  • .handle_item(): mengambil satu sesi yang tertunda, menanganinya, dan keluar.
• work.poller(): melakukan polling pada antrean kerja atas nama Anda dan memberikan setiap sesi yang diklaim kepada Anda. Gunakan ini ketika Anda ingin memutuskan apa yang terjadi untuk setiap sesi, misalnya meluncurkan sandbox alih-alih menjalankan alat secara in-process.
  • drain: apakah akan 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 ini akan menggunakan long-poll default 999 ms.
  • reclaim_older_than_ms: klaim ulang item kerja yang di-lease ke worker yang telah berhenti merespons.
  • auto_stop: apakah akan mengirim sinyal stop pada item kerja setelah iterator keluar. Poller Go tidak memiliki opsi opt-out dan selalu mengirim sinyal stop, jadi lakukan blocking di dalam body loop hingga sesi selesai alih-alih melepaskannya.
• client.beta.sessions.events.tool_runner(): menjalankan panggilan alat untuk satu sesi, dengan diberikan 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 secara opsional mengunduh skill sesi ketika digunakan sebagai context manager. 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, 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 downloaded to /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

Verifikasi worker terhubung

Dari shell terpisah, menggunakan kunci API Claude Anda (bukan environment key), konfirmasi bahwa workers_polling setidaknya bernilai 1:

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

Jika workers_polling tetap 0, worker tidak menjangkau antrean: konfirmasi bahwa ANTHROPIC_ENVIRONMENT_KEY dan ANTHROPIC_ENVIRONMENT_ID telah 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. Sesi masuk ke antrean kerja lingkungan dan menunggu di sana hingga worker mengklaimnya; jika tidak ada worker yang terhubung, sesi tetap berada di antrean alih-alih gagal.

Anthropic tidak memasang file atau repositori GitHub ke dalam sandbox yang di-host sendiri. Untuk menyediakan file spesifik sesi, berikan referensi file (seperti path S3 atau commit SHA) di field metadata sesi. Skrip spawn atau handler --on-work Anda membaca metadata tersebut dari item kerja yang diklaim (melalui endpoint Environments Work) dan 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.

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, sehingga 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 buat peringatan backlog berdasarkan nilai ini.
• pending adalah jumlah item yang telah diklaim worker dan sedang diproses.
• oldest_queued_at adalah timestamp item tertua dalam antrean, atau null jika antrean kosong.
• 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 dengan bersih. Worker menyelesaikan panggilan alat yang sedang berjalan, mengirimkan status akhir, dan melepaskan sesi. Berikan force: true di body permintaan untuk menginterupsi segera alih-alih menunggu panggilan alat saat ini selesai.

Karena panggilan ini dijalankan dari tooling operasi Anda dan bukan dari host worker, ANTHROPIC_WORK_ID tidak diatur secara otomatis. Atur ke ID item kerja target sebelum menjalankan contoh berikut.

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