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 self-hosted.

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 dengan lainnya.

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, mereka dijalankan dalam urutan alfabetis (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 networking.allow_package_managers 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: unrestricted

Package manager yang didukung:

Jaringan

Field networking mengontrol akses jaringan keluar dari sandbox. Field ini tidak memengaruhi alat web_search atau web_fetch, yang berjalan di server Anthropic; untuk membatasi situs yang dapat dijangkau alat-alat tersebut, 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

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.
• 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.
• allow_package_managers mengizinkan akses keluar ke sekumpulan registry 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 registry 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.

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

# List environments
environments = client.beta.environments.list()

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
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