Configurazione dell'ambiente cloud

Gli ambienti definiscono la configurazione della sandbox in cui viene eseguito il tuo agente. Crei un ambiente una sola volta, poi 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 di tipo type: cloud. Per eseguire sandbox sulla tua infrastruttura, consulta Sandbox self-hosted.



Crea un ambiente

ant beta:environments create < python-dev.environment.yaml

name: python-dev
config:
  type: cloud
  networking:
    type: unrestricted

Usa un name univoco e descrittivo per poter distinguere gli ambienti tra loro.



Usa l'ambiente in una sessione

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

ant 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 opzionalmente fissare versioni specifiche. I pacchetti senza versione fissata installano la versione più recente.

ant beta:environments create < environment.yaml

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 all'interno del toolset dell'agente. Consulta Limitare i domini di web search e web fetch.

L'esempio seguente crea un ambiente con networking limited:

ant beta:environments create < environment.yaml

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 caratteri jolly (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 ai registri pubblici di pacchetti (come PyPI e npm) oltre a quelli elencati nell'array allowed_hosts. Il valore predefinito è false.



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 frequentemente un ambiente, mantieni un tuo registro delle modifiche in modo da poter identificare quale configurazione è stata utilizzata da ciascuna sessione.



Gestisci gli ambienti

# Elenca gli ambienti
ant beta:environments list

# Recupera un ambiente specifico
ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

# Archivia un ambiente (sola lettura, le sessioni esistenti continuano)
ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

# Elimina un ambiente (solo se nessuna sessione vi fa riferimento)
ant beta:environments delete --environment-id "$ENVIRONMENT_ID"



Runtime preinstallati

Le sandbox cloud includono runtime comuni già pronti all'uso. Consulta Riferimento sandbox cloud per l'elenco completo di linguaggi, database e utilità preinstallati.



Passaggi successivi