Penyiapan environment cloud

Environment (lingkungan) mendefinisikan konfigurasi sandbox tempat agen Anda berjalan. Anda membuat environment satu kali, lalu mereferensikan ID-nya setiap kali Anda memulai sesi. Beberapa sesi dapat berbagi environment yang sama, tetapi setiap sesi mendapatkan sandbox terisolasinya sendiri (container Linux baru).

Halaman ini membahas environment type: cloud. Untuk menjalankan sandbox di infrastruktur Anda sendiri, lihat Sandbox yang di-host sendiri. Untuk memilih di antara keduanya, lihat Memilih lingkungan agen.

Membuat environment

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: python-dev
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

Gunakan name yang unik dan deskriptif agar Anda dapat membedakan environment satu sama lain. Contoh ini menggunakan jaringan limited dengan package manager diizinkan, sehingga sandbox dapat menjangkau registri paket dan host kode. Untuk mengizinkannya menjangkau host lain, tambahkan host tersebut ke allowed_hosts.

Menggunakan environment dalam sesi

Teruskan ID environment sebagai string saat membuat sesi.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

Opsi konfigurasi

Paket

Field packages melakukan pra-instalasi paket ke dalam sandbox sebelum agen dimulai. Paket diinstal oleh package manager masing-masing dan di-cache di seluruh sesi yang berbagi environment yang sama. Ketika beberapa package manager ditentukan, package manager tersebut berjalan dalam urutan abjad (apt, cargo, gem, go, npm, pip). Anda dapat secara opsional mengunci versi tertentu. Paket yang tidak dikunci akan menginstal versi terbaru. Jika environment menggunakan jaringan limited, atur juga allow_package_managers di networking ke true; jika tidak, permintaan akan ditolak dengan error 400.

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: limited
    allow_package_managers: true

Package manager yang didukung:

Jaringan

Field networking mengontrol akses jaringan keluar sandbox.

Dengan jaringan limited, allowed_hosts juga berlaku untuk alat web_search dan web_fetch, yang berjalan di server Anthropic. Panggilan web_fetch untuk URL pada host yang tidak cocok dengan allowed_hosts akan mengembalikan hasil error kepada agen. web_search menghilangkan hasil dari host yang tidak cocok dengan allowed_hosts. allow_package_managers dan allow_mcp_servers tidak menambahkan host apa pun untuk alat-alat ini. Ketika allowed_hosts tidak mencantumkan host apa pun, tidak ada panggilan web_fetch atau web_search yang mengembalikan halaman atau hasil pencarian. Host yang Anda tambahkan ke allowed_hosts untuk alat-alat ini juga terbuka bagi sandbox. Jaringan unrestricted dan environment self-hosted tidak membatasi alat-alat ini. Untuk membatasinya lebih lanjut, atur allowed_domains atau blocked_domains pada entri alat tersebut di toolset agen. Lihat Membatasi domain web search dan web fetch.

Contoh berikut membuat environment dengan jaringan limited:

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true

Dengan jaringan limited dan tanpa field lain yang diatur, tidak ada host yang diizinkan. File, memory store, dan repositori GitHub yang Anda lampirkan ke sesi tetap tersedia. Ketika permintaan dari sandbox pada port 80 atau 443 ditolak karena host-nya tidak diizinkan, responsnya adalah 403 yang menyebutkan host yang diblokir.

Saat menggunakan jaringan limited:

• allowed_hosts menentukan domain yang dapat dijangkau sandbox. Tentukan hostname saja atau pola wildcard (seperti *.example.com). Jangan sertakan skema URL, port, atau path. Hostname tanpa wildcard hanya cocok dengan host yang persis sama: example.com tidak cocok dengan www.example.com. *.example.com cocok dengan setiap subdomain dari example.com, tetapi tidak dengan example.com itu sendiri.
• allow_mcp_servers mengizinkan akses keluar ke endpoint server MCP yang dikonfigurasi pada agen, di luar yang tercantum dalam array allowed_hosts. Default-nya false. Selama nilainya false, pembuatan sesi gagal dengan error 400 jika agen mendeklarasikan server MCP yang host-nya tidak ada di allowed_hosts. Hal yang sama berlaku untuk agen yang dapat menerima delegasi tugas darinya. Untuk memperbaikinya, tambahkan host tersebut ke allowed_hosts atau atur allow_mcp_servers ke true.
• allow_package_managers mengizinkan akses keluar ke sekumpulan registri paket publik dan host kode di luar yang tercantum dalam array allowed_hosts. Lihat Host package manager untuk daftarnya. Default-nya false. Atur ke true setiap kali environment menentukan packages; jika tidak, permintaan akan ditolak dengan error 400, bahkan jika host registri tercantum di allowed_hosts.

Host package manager

Ketika allow_package_managers bernilai true, sandbox dapat menjangkau host berikut selain yang ada di allowed_hosts. Anthropic memelihara daftar ini dan dapat mengubahnya.

Risiko jaringan tanpa batasan

Dengan jaringan unrestricted, kode di sandbox dapat mengirim permintaan ke host mana pun di internet, kecuali host yang ada di daftar blokir keamanan umum. Sebelum Anda memilih mode ini, pertimbangkan apa yang dapat dilakukan agen dengan akses tersebut:

• Agen dapat mengubah hal-hal di situs eksternal, tidak hanya membacanya: Alat bash dapat mengirim permintaan apa pun. Agen dapat mengirim data, mengirimkan formulir, memanggil API, dan menjalankan skrip yang mengubah data di situs eksternal. Bahkan permintaan yang hanya mengambil URL dapat mengubah data di beberapa situs.
• Tidak ada yang menjeda permintaan ini secara default: Kebijakan izin default toolset agen adalah always_allow, sehingga perintah bash berjalan tanpa persetujuan.
• Apa pun di sandbox dapat keluar darinya: Ini termasuk file, output alat, dan kredensial atau rahasia apa pun yang Anda masukkan ke sandbox.
• Konten yang diambil dapat mengarahkan agen: Halaman web, respons API, dan konten lain yang dibaca agen dapat berisi instruksi (prompt injection) yang mengubah apa yang dilakukannya selanjutnya.
• Agen bertindak atas nama Anda: Tindakannya dapat melanggar ketentuan layanan suatu situs, atau membuat akun dan catatan di sana.
• Perilaku model bukanlah kontrol keamanan: Agen dapat bertindak di situs eksternal dengan cara yang tidak Anda minta, termasuk mencoba ulang dengan cara berbeda setelah situs memblokir permintaan. Gunakan pengaturan jaringan dan kebijakan izin untuk membatasi apa yang dapat dilakukannya.
• Daftar blokir keamanan bukanlah daftar izin (allowlist): Daftar ini tidak membatasi situs lain mana yang dijangkau agen, atau apa yang dilakukan agen di situs tersebut.

Untuk mengurangi risiko ini, gunakan jaringan limited dengan daftar host yang eksplisit. Nilai networking berikut mengizinkan api.example.com, ditambah host package manager untuk agen yang memasang paket:

{
  "type": "limited",
  "allowed_hosts": ["api.example.com"],
  "allow_package_managers": true
}

Agen yang hanya menggunakan alat web_search dan web_fetch tidak memerlukan jaringan unrestricted jika Anda dapat mencantumkan situs yang dibutuhkannya. Dengan jaringan limited, allowed_hosts juga berlaku untuk alat-alat tersebut (lihat Jaringan), jadi cantumkan situs-situs tersebut di allowed_hosts. Mencantumkannya juga di allowed_domains milik web_search membuatnya mencari di situs-situs tersebut. Host yang Anda tambahkan ke allowed_hosts juga terbuka bagi sandbox. Untuk membatasi alat-alat tersebut lebih lanjut, lihat Membatasi domain web search dan web fetch.

Gunakan unrestricted hanya ketika agen harus menjangkau situs yang tidak dapat Anda cantumkan sebelumnya. Dalam hal ini, jauhkan rahasia dan file sensitif dari sandbox, dan berikan agen hanya kredensial yang dibutuhkan tugas tersebut. Pertimbangkan untuk mengatur kebijakan izin alat bash ke always_ask atau auto, dan pantau event sesi.

Siklus hidup environment

• Environment tetap ada hingga diarsipkan atau dihapus secara eksplisit.
• Setiap sesi mendapatkan instance sandbox-nya sendiri, bahkan ketika beberapa sesi mereferensikan environment yang sama. Sesi tidak berbagi state filesystem.
• Environment tidak memiliki versi. Jika Anda sering memperbarui environment, simpan catatan perubahan Anda sendiri agar Anda dapat mengetahui konfigurasi mana yang digunakan setiap sesi.

Mengelola environment

# Daftar environment
environments = client.beta.environments.list()

# Ambil environment tertentu
env = client.beta.environments.retrieve(environment.id)

# Arsipkan environment (hanya-baca, sesi yang ada tetap berjalan)
client.beta.environments.archive(environment.id)

# Hapus environment (hanya jika tidak ada sesi yang mereferensikannya)
client.beta.environments.delete(environment.id)

Runtime pra-instal

Sandbox cloud sudah menyertakan runtime bahasa umum, database, dan alat command-line secara bawaan. Lihat Referensi sandbox cloud untuk daftar lengkapnya.

Langkah selanjutnya