Configurazione dell'ambiente cloud

Gli ambienti definiscono la configurazione del container 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 istanza di container isolata.

Tutte le richieste API di Managed Agents richiedono l'intestazione beta managed-agents-2026-04-01. L'SDK imposta automaticamente l'intestazione beta.

Crea un ambiente

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "python-dev",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)
environment_id=$(jq -r '.id' <<< "$environment")

echo "Environment ID: $environment_id"

Il campo name deve essere univoco all'interno della tua organizzazione e workspace.

Usa l'ambiente in una sessione

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

Opzioni di configurazione

Pacchetti

Il campo packages pre-installa i pacchetti nel container 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, vengono eseguiti in ordine alfabetico (apt, cargo, gem, go, npm, pip). Puoi facoltativamente specificare versioni precise; il valore predefinito è l'ultima versione disponibile.

Gestori di pacchetti supportati:

Campo	Gestore di pacchetti	Esempio
`apt`	Pacchetti di sistema (apt-get)	`"ffmpeg"`
`cargo`	Rust (cargo)	`"[email protected]"`
`gem`	Ruby (gem)	`"rails:7.1.0"`
`go`	Moduli Go	`"golang.org/x/tools/cmd/goimports@latest"`
`npm`	Node.js (npm)	`"[email protected]"`

Networking

Il campo networking controlla l'accesso alla rete in uscita del container. Non influisce sui domini consentiti degli strumenti web_search o web_fetch.

Modalità	Descrizione
`unrestricted`	Accesso completo alla rete in uscita, ad eccezione di una lista di blocco generale per la sicurezza. Questa è l'impostazione predefinita.
`limited`	Limita l'accesso alla rete del container alla lista `allowed_hosts`. L'accesso aggiuntivo è abilitato tramite i bool `allow_package_managers` e `allow_mcp_servers`.

Per i deployment in produzione, usa il networking limited con una lista allowed_hosts esplicita. Segui il principio del privilegio minimo concedendo solo l'accesso di rete minimo richiesto dal tuo agente, e controlla regolarmente i tuoi domini consentiti.

Quando si utilizza il networking limited:

allowed_hosts specifica i domini raggiungibili dal container. Devono essere preceduti dal prefisso HTTPS.
allow_mcp_servers consente l'accesso in uscita agli endpoint del 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 di pacchetti pubblici (PyPI, npm, ecc.) oltre a quelli elencati nell'array allowed_hosts. Il valore predefinito è false.

Ciclo di vita dell'ambiente

Gli ambienti persistono fino a quando non vengono esplicitamente archiviati o eliminati.
Più sessioni possono fare riferimento allo stesso ambiente.
Ogni sessione ottiene la propria istanza di container. Le sessioni non condividono lo stato del file system.
Gli ambienti non sono versionati. Se aggiorni frequentemente i tuoi ambienti, potresti voler registrare questi aggiornamenti dalla tua parte, per mappare lo stato dell'ambiente con le sessioni.

Gestisci gli ambienti

Runtime pre-installati

I container cloud includono runtime comuni già pronti all'uso. Consulta il Riferimento container per l'elenco completo dei linguaggi, database e utility pre-installati.

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id"
}
EOF
)

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "data-analysis",
  "config": {
    "type": "cloud",
    "packages": {
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["express"]
    },
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

config=$(cat <<'EOF'
{
  "type": "cloud",
  "networking": {
    "type": "limited",
    "allowed_hosts": ["api.example.com"],
    "allow_mcp_servers": true,
    "allow_package_managers": true
  }
}
EOF
)

# List environments
environments=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Retrieve a specific environment
env=$(curl -fsS "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Archive an environment (read-only, existing sessions continue)
curl -fsS -X POST "https://api.anthropic.com/v1/environments/$environment_id/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

# Delete an environment (only if no sessions reference it)
curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"