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 di tipo type: cloud. Per eseguire sandbox sulla tua infrastruttura, consulta Sandbox self-hosted.



Creare un ambiente

ant beta:environments create \
  --name "python-dev" \
  --config '{type: cloud, networking: {type: unrestricted}}'

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



Usare 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 package manager e memorizzati nella cache tra le sessioni che condividono lo stesso ambiente. Quando vengono specificati più package manager, 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 <<'YAML'
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted
YAML

Package manager supportati:



Networking

Il campo networking controlla l'accesso di rete in uscita della sandbox. Non influisce sui domini consentiti per gli strumenti web_search o web_fetch.

L'esempio seguente crea un ambiente con networking limited:

ant beta:environments create <<'YAML'
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true
YAML

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



Gestire 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 utility preinstallati.



Passaggi successivi