Configurazione dell'ambiente cloud

Gli ambienti definiscono la configurazione della sandbox in cui viene eseguito il tuo agente. Crei un ambiente una sola volta, quindi fai riferimento al suo ID ogni volta che avvii una sessione. Più sessioni possono condividere lo stesso ambiente, ma ogni sessione ottiene la propria sandbox isolata (un nuovo container Linux).

Questa pagina tratta gli ambienti type: cloud. Per eseguire le sandbox sulla tua infrastruttura, consulta Sandbox self-hosted.

Crea un ambiente

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

Usa un name univoco e descrittivo in modo da poter distinguere gli ambienti tra loro.

Usa l'ambiente in una sessione

Passa l'ID dell'ambiente come stringa quando crei una sessione.

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

Opzioni di configurazione

Pacchetti

Il campo packages preinstalla i pacchetti nella sandbox prima dell'avvio dell'agente. I pacchetti vengono installati dai rispettivi gestori di pacchetti e memorizzati nella cache tra le sessioni che condividono lo stesso ambiente. Quando vengono specificati più gestori di pacchetti, questi vengono eseguiti in ordine alfabetico (apt, cargo, gem, go, npm, pip). Puoi facoltativamente fissare versioni specifiche. I pacchetti senza versione fissata installano la versione più recente. Se l'ambiente usa il networking limited, imposta anche networking.allow_package_managers su true; in caso contrario la richiesta viene rifiutata con un errore 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

Gestori di pacchetti supportati:

Networking

Il campo networking controlla l'accesso di rete in uscita della sandbox. Non influisce sugli strumenti web_search o web_fetch, che vengono eseguiti sui server di Anthropic; per limitare i siti che tali strumenti possono raggiungere, imposta allowed_domains o blocked_domains nella voce dello strumento nel toolset dell'agente. Consulta Limita i domini di web search e web fetch.

L'esempio seguente crea un ambiente con networking 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

Quando usi il networking limited:

• allowed_hosts specifica i domini che la sandbox può raggiungere. Specifica nomi host semplici o pattern con wildcard (come *.example.com). Non includere uno schema URL, una porta o un percorso.
• allow_mcp_servers consente l'accesso in uscita agli endpoint dei server MCP configurati sull'agente, oltre a quelli elencati nell'array allowed_hosts. Il valore predefinito è false.
• allow_package_managers consente l'accesso in uscita a un insieme di registri di pacchetti pubblici e host di codice oltre a quelli elencati nell'array allowed_hosts. Consulta Host dei gestori di pacchetti per l'elenco. Il valore predefinito è false. Impostalo su true ogni volta che l'ambiente specifica packages; altrimenti la richiesta viene rifiutata con un errore 400, anche se gli host dei registri sono elencati in allowed_hosts.

Host dei gestori di pacchetti

Quando allow_package_managers è true, la sandbox può raggiungere i seguenti host oltre a quelli in allowed_hosts. Anthropic gestisce questo elenco e può modificarlo.

Ciclo di vita dell'ambiente

• Gli ambienti persistono finché non vengono esplicitamente archiviati o eliminati.
• Ogni sessione ottiene la propria istanza di sandbox, anche quando più sessioni fanno riferimento allo stesso ambiente. Le sessioni non condividono lo stato del filesystem.
• Gli ambienti non sono versionati. Se aggiorni un ambiente frequentemente, tieni un tuo registro delle modifiche in modo da poter sapere quale configurazione ha usato ciascuna sessione.

Gestisci gli ambienti

# 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 preinstallati

Le sandbox cloud includono fin da subito i runtime dei linguaggi più comuni, database e strumenti da riga di comando. Consulta il Riferimento delle sandbox cloud per l'elenco completo.

Passaggi successivi