Configurazione dell'ambiente cloud

Gli ambienti definiscono la configurazione della sandbox in cui viene eseguito il tuo agente. Crei un ambiente una 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 container Linux nuovo).

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



Crea 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.



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 che l'agente si avvii. 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.

ant beta:environments create <<'YAML'
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted
YAML

Gestori di pacchetti supportati:



Rete

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 rete 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 la rete 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 capire quale configurazione ha usato 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 il Riferimento delle sandbox cloud per l'elenco completo di linguaggi, database e utility preinstallati.



Prossimi passi