Configurazione dell’ambiente cloud
Personalizza le sandbox cloud per le tue sessioni.
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. Per scegliere tra le due opzioni, consulta Scegliere un ambiente per l’agente.
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: trueant apply crea l’ambiente da environment.yaml, ne stampa l’ID e lo registra in claude-lock.json. Esegui il commit di claude-lock.json in modo che il successivo ant apply aggiorni questo ambiente invece di tentare di crearlo di nuovo.
Usa un name univoco e descrittivo per poter distinguere gli ambienti. Questo esempio usa il tipo di rete limited con i gestori di pacchetti consentiti, in modo che la sandbox possa raggiungere i registri dei pacchetti e gli host di codice. Per consentirle di raggiungere altri host, aggiungili a allowed_hosts.
Usa l’ambiente in una sessione
Passa l’ID dell’ambiente come stringa quando crei una sessione (consulta Avvia una sessione).
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
)Opzioni di configurazione
Pacchetti
Il campo packages installa i pacchetti nella sandbox prima che l’agente la usi. I gestori di pacchetti vengono eseguiti in ordine alfabetico (apt, cargo, gem, go, npm, pip). Puoi fissare versioni specifiche. Se l’ambiente usa il tipo di rete limited, imposta anche allow_package_managers in networking su true; altrimenti, l’API rifiuta la richiesta 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: limited
allow_package_managers: trueGestori di pacchetti supportati:
| Campo | Gestore di pacchetti | Esempio |
|---|---|---|
apt | Pacchetti di sistema (apt-get) | "graphviz" |
cargo | Rust (cargo) | "hyperfine@1.18.0" |
gem | Ruby (gem) | "rails:7.1.0" |
go | Moduli Go | "golang.org/x/tools/cmd/goimports@latest" |
npm | Node.js (npm) | "express@4.18.0" |
pip | Python (pip) | "sqlalchemy==2.0.30" |
Rete
Il campo networking controlla l’accesso di rete in uscita della sandbox.
Con la rete limited, allowed_hosts si applica anche agli strumenti web_search e web_fetch, che vengono eseguiti sui server di Anthropic. Una chiamata web_fetch per un URL su un host che non corrisponde a allowed_hosts restituisce un risultato di errore all’agente. web_search omette i risultati provenienti da host che non corrispondono a allowed_hosts. allow_package_managers e allow_mcp_servers non aggiungono host per questi strumenti. Quando allowed_hosts non elenca alcun host, nessuna chiamata web_fetch o web_search restituisce una pagina o un risultato di ricerca. Un host che aggiungi a allowed_hosts per questi strumenti è accessibile anche alla sandbox. La rete unrestricted e gli ambienti self-hosted non limitano questi strumenti. Per limitarli ulteriormente, imposta allowed_domains o blocked_domains nella voce dello strumento nel toolset dell’agente. Consulta Limitare i domini di ricerca web e web fetch.
| Modalità | Descrizione |
|---|---|
limited | Limita l’accesso di rete della sandbox agli host in allowed_hosts. Imposta allow_package_managers e allow_mcp_servers su true per consentire un accesso aggiuntivo. Usa questa modalità a meno che l’agente non debba raggiungere siti che non puoi elencare in anticipo. |
unrestricted | Accesso di rete in uscita completo, ad eccezione di una blocklist di sicurezza generale. Prima di usarla, leggi Rischi del networking senza restrizioni. |
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: trueCon il networking limited e nessun altro campo impostato, nessun host è consentito. I file, i memory store e i repository GitHub che colleghi alla sessione restano disponibili. Quando una richiesta dalla sandbox sulla porta 80 o 443 viene rifiutata perché il suo host non è consentito, la risposta è un 403 che indica l’host bloccato.
Quando usi il networking limited:
allowed_hostsspecifica gli host 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. Un nome host semplice corrisponde esattamente a quell’host:example.comnon corrisponde awww.example.com.*.example.comcorrisponde a ogni sottodominio diexample.com, ma non aexample.comstesso.allow_mcp_serversconsente l’accesso in uscita agli endpoint dei server MCP configurati sull’agente, oltre a quelli elencati nell’arrayallowed_hosts. Il valore predefinito èfalse. Finché èfalse, la creazione della sessione fallisce con un errore 400 se l’agente dichiara un server MCP il cui host non è inallowed_hosts. Lo stesso vale per un agente a cui può delegare. Per risolvere, aggiungi l’host aallowed_hostsoppure impostaallow_mcp_serverssutrue.allow_package_managersconsente l’accesso in uscita a un insieme di registri di pacchetti pubblici e host di codice oltre a quelli elencati nell’arrayallowed_hosts. Consulta Host dei gestori di pacchetti per l’elenco. Il valore predefinito èfalse. Impostalo sutrueogni volta che l’ambiente specificapackages. Altrimenti, l’API rifiuta la richiesta con un errore 400, anche seallowed_hostselenca gli host dei registri.
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.
| Ecosistema | Host |
|---|---|
| Hosting del codice | github.com, api.github.com, codeload.github.com, raw.githubusercontent.com, objects.githubusercontent.com, release-assets.githubusercontent.com, gitlab.com, bitbucket.org |
| Node.js | registry.npmjs.org, registry.yarnpkg.com, nodejs.org |
| Python | pypi.org, files.pythonhosted.org |
| Rust | crates.io, index.crates.io, static.crates.io, static.rust-lang.org |
| Go | proxy.golang.org, sum.golang.org |
| Java | repo1.maven.org, repo.maven.apache.org, services.gradle.org, plugins.gradle.org, plugins-artifacts.gradle.org |
| Ruby | rubygems.org, index.rubygems.org |
| PHP | packagist.org, repo.packagist.org |
| Ubuntu (apt) | archive.ubuntu.com, security.ubuntu.com, ppa.launchpad.net |
| Container | registry-1.docker.io, auth.docker.io, production.cloudflare.docker.com, download.docker.com, ghcr.io |
Rischi del networking senza restrizioni
Con il networking unrestricted, il codice nella sandbox può inviare richieste a qualsiasi host su internet, ad eccezione degli host presenti in una blocklist di sicurezza generale. Prima di scegliere questa modalità, considera cosa può fare l’agente con tale accesso:
- L’agente può modificare elementi su siti esterni, non solo leggerli: Lo strumento
bashpuò inviare qualsiasi richiesta. L’agente può pubblicare dati, inviare moduli, chiamare API ed eseguire script che modificano dati su siti esterni. Anche una richiesta che si limita a recuperare un URL può modificare dati su alcuni siti. - Per impostazione predefinita nulla mette in pausa queste richieste: La policy di autorizzazione predefinita del toolset dell’agente è
always_allow, quindi i comandibashvengono eseguiti senza approvazione. - Qualsiasi cosa nella sandbox può uscirne: Ciò include file, output degli strumenti e qualsiasi credenziale o segreto che inserisci nella sandbox.
- I contenuti recuperati possono orientare l’agente: Pagine web, risposte API e altri contenuti che l’agente legge possono contenere istruzioni (prompt injection) che cambiano ciò che fa successivamente.
- L’agente agisce per tuo conto: Le sue azioni possono violare i termini di servizio di un sito, oppure creare account e record su di esso.
- Il comportamento del modello non è un controllo di sicurezza: L’agente può agire su siti esterni in modi che non hai richiesto, incluso riprovare in modo diverso dopo che un sito ha bloccato una richiesta. Usa le impostazioni di rete e le policy di autorizzazione per limitare ciò che può fare.
- La blocklist di sicurezza non è una allowlist: Non limita quali altri siti l’agente raggiunge, né cosa l’agente fa su di essi.
Per ridurre questi rischi, usa il networking limited con un elenco esplicito di host. Il seguente valore di networking consente api.example.com, più gli host dei gestori di pacchetti per un agente che installa pacchetti:
{
"type": "limited",
"allowed_hosts": ["api.example.com"],
"allow_package_managers": true
}Un agente che usa solo gli strumenti web_search e web_fetch non ha bisogno della rete unrestricted se puoi elencare i siti di cui ha bisogno. Con la rete limited, allowed_hosts si applica anche a questi strumenti (consulta Rete), quindi elenca quei siti in allowed_hosts. Elencarli anche in allowed_domains di web_search fa sì che la ricerca avvenga su quei siti. Un host che aggiungi a allowed_hosts è accessibile anche alla sandbox. Per limitare ulteriormente gli strumenti, consulta Limitare i domini di ricerca web e web fetch.
Usa unrestricted solo quando l’agente deve raggiungere siti che non puoi elencare in anticipo. In tal caso, tieni segreti e file sensibili fuori dalla sandbox e fornisci all’agente solo le credenziali necessarie per l’attività. Valuta di impostare la policy di autorizzazione dello strumento bash su always_ask o auto, e monitora gli eventi della sessione.
Ciclo di vita dell’ambiente
- Gli ambienti persistono finché non li archivi o li elimini.
- 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
# Elenca gli ambienti
environments = client.beta.environments.list()
# Recupera un ambiente specifico
env = client.beta.environments.retrieve(environment.id)
# Archivia un ambiente (sola lettura, nessuna nuova sessione)
client.beta.environments.archive(environment.id)
# Elimina un ambiente
client.beta.environments.delete(environment.id)Runtime preinstallati
Le sandbox cloud includono 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
Pacchetti preinstallati, database e utilità disponibili nelle sandbox cloud.
Crea una sessione per eseguire il tuo agente e iniziare a svolgere attività.
Disponibilità
Claude API
- Stato
- Beta
- API
- Managed Agents
- Header beta
- Richiede
- Modelli
- Tutti i modelli
Claude Platform on AWS
- Stato
- Beta
- API
- Managed Agents
- Header beta
- Richiede
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Anthropic managed)
- Stato
- Beta
- API
- Managed Agents
- Header beta
- Richiede
- Modelli
- Tutti i modelli
Gestione dei dati
Panoramica sulla gestione dei datiEndpoint applicabili
/v1/agents/v1/sessions/v1/environments
Non idoneo per ZDR, ad eccezione di Managed Agents self-hosted. Le sessioni sono risorse con stato; le trascrizioni restano finché non le elimini. Scopri di più
Non idoneo per HIPAA. Si applica a tutte le sotto-funzionalità di Managed Agents.
Questa pagina ti è stata utile?