Proteggi il tuo deployment di Managed Agents

Questa guida elenca le impostazioni che limitano ciò che un agente su Claude Managed Agents può raggiungere e fare, a partire dalle più importanti. Ogni sezione rimanda alla pagina che tratta l'impostazione in modo completo.

Rischi per la sicurezza e limiti della sandbox spiega perché queste impostazioni sono importanti e da cosa non proteggono. Per rivedere e monitorare le sessioni, consulta Rivedere e monitorare le sessioni degli agenti.

Scegli dove viene eseguito l'agente

Il luogo in cui vengono eseguiti gli strumenti dell'agente determina chi protegge la "sandbox" (ambiente isolato): Anthropic, con un ambiente cloud, oppure tu, con una sandbox self-hosted. Per scegliere tra le due opzioni e sapere cosa raggiunge Anthropic con ciascuna, consulta Scegliere un ambiente per l'agente.

Se usi una sandbox self-hosted, tieni presenti questi quattro punti:

• Rete: Limita la rete si applica agli ambienti cloud. Per una sandbox self-hosted, imposta limiti equivalenti sul suo traffico nel tuo firewall. Il tuo firewall non limita i server MCP dichiarati da un agente, quindi rivedili, insieme a quelli che la tua applicazione imposta per una sessione.
• Strumenti web: Gli strumenti web vengono eseguiti sui server di Anthropic, quindi il tuo firewall non li limita. Limitali con i loro elenchi di domini. Consulta Limita web search e web fetch.
• Credenziali: Le credenziali di tipo variabile d'ambiente non sono ancora supportate con le sandbox self-hosted.
• Isolamento e hardening: Sei responsabile di entrambi. Consulta il Modello di sicurezza.

Nessuna delle due opzioni modifica la copertura di conformità di Managed Agents né la durata di conservazione della cronologia delle sessioni. Consulta Monitora le sessioni e rivedi la conservazione.

Limita la rete

Imposta networking.type su limited ed elenca in allowed_hosts solo gli host di cui l'agente ha bisogno. Una richiesta di creazione di un ambiente che omette networking potrebbe ottenere unrestricted, quindi imposta networking in ogni richiesta di creazione. Consulta Rischi del networking senza restrizioni.

I file, i memory store e i repository GitHub che colleghi restano disponibili per l'agente indipendentemente da allowed_hosts.

Gli esempi in questa pagina usano un agente di supporto. Legge il ticket di un cliente, cerca l'ordine, legge il tuo centro assistenza e redige una risposta. La ricerca dell'ordine viene eseguita dalla tua applicazione e non richiede alcun host, quindi questo ambiente consente un solo host, il centro assistenza, per web_fetch:

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: support-agent
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - help.example.com

Un ambiente limited ha tre impostazioni di networking:

Le impostazioni allow_package_managers e allow_mcp_servers non aggiungono host per web search e web fetch.

Lascia allow_mcp_servers disattivato, che è il valore predefinito, ed elenca in allowed_hosts l'host di ogni server MCP che gestisci o di cui ti fidi. Ogni host che elenchi è aperto anche al codice nella sandbox. Con allow_mcp_servers disattivato, un controllo alla creazione della sessione rifiuta la richiesta se l'host di un server MCP non è elencato. Consulta Fornisci l'autenticazione alla creazione della sessione. Lo stesso controllo viene eseguito quando un aggiornamento della sessione modifica mcp_servers.

Quando scegli gli host per allowed_hosts, segui queste due regole:

• Elenca solo host che gestisci o di cui ti fidi.
• Evita i wildcard *. e i domini di hosting condiviso dove chiunque può pubblicare contenuti.

Se l'agente mantiene bash, imposta la policy di autorizzazione dello strumento bash come descritto in Approva le azioni rischiose.

Consulta Configurazione dell'ambiente cloud per tutte le impostazioni di networking.

Conserva le credenziali nei vault

Archivia ogni segreto in un "vault" (cassaforte per credenziali). Per ogni credenziale di tipo variabile d'ambiente, imposta la posizione di iniezione solo sugli header della richiesta ed elenca solo gli host a cui è destinato il segreto. Il codice nella sandbox vede un segnaposto al posto del segreto. Managed Agents sostituisce il segnaposto con il segreto reale solo nelle richieste HTTPS in uscita verso gli host consentiti dalla credenziale. In questo modo il segreto resta fuori dalla portata diretta del modello, a meno che un servizio non lo rimandi indietro, come un endpoint che restituisce gli header della richiesta. Se il networking della credenziale è unrestricted, Managed Agents sostituisce il segnaposto con il segreto reale nelle richieste verso qualsiasi host che l'ambiente consente alla sandbox di raggiungere. Per usare un vault, passa il suo ID in vault_ids quando crei la sessione o il deployment.

L'agente di supporto non ha bisogno di alcuna credenziale nel vault, perché la chiave API per la tua API degli ordini è detenuta dalla tua applicazione. Se il tuo agente detiene una credenziale nel vault, consulta Aggiungi una credenziale per la richiesta in ogni linguaggio.

Tieni le chiavi fuori dai prompt di sistema, dalle definizioni degli agenti e dai messaggi. Non dare all'agente una chiave API di Claude. Anche quando una chiave API di Claude si trova in un vault, il codice nella sandbox può usarla per chiamare direttamente la Claude API. Può fare tutto ciò che quella chiave consente, come avviare o eliminare sessioni, o usare web search e web fetch. Le impostazioni degli strumenti dell'agente, le approvazioni e il budget non si applicano a quelle chiamate. In un ambiente limited, il codice può effettuare queste chiamate solo se allowed_hosts consente alla sandbox di raggiungere api.anthropic.com.

Recupera tu stesso i token e archiviali nel vault, perché un token che il codice nella sandbox recupera con un segreto archiviato torna indietro senza oscuramento.

Tieni i vault per carichi di lavoro con livelli di attendibilità diversi in workspace separati, perché qualsiasi chiave API con accesso a un workspace può fare riferimento ai suoi vault. Usa chiavi API limitate a un solo workspace.

Consulta Autenticazione con i vault per le credenziali MCP e la rotazione.

Limita web search e web fetch

Imposta allowed_domains su web_fetch con i siti di cui l'agente ha bisogno. Qualsiasi URL recuperato dall'agente può trasportare dati verso il sito a cui punta, quindi questo elenco è un controllo di sicurezza. Su web_search, imposta allowed_domains con i siti da cui vuoi ottenere risultati, in modo che i risultati provengano solo da siti che ritieni accurati. L'elenco non impedisce alla query di ricerca di raggiungere il provider di ricerca. I risultati di ricerca includono testo delle pagine, quindi l'elenco limita anche i siti il cui testo raggiunge l'agente. Imposta allowed_domains su entrambi gli strumenti per ogni tipo di ambiente.

Un elenco blocked_domains blocca gli host che elenchi e i loro sottodomini, e nessun altro host. Lo stesso contenuto può comunque raggiungere l'agente da archivi web, cache, mirror o domini correlati che non hai elencato. Non fare affidamento su blocked_domains per la sicurezza. Usa allowed_domains e indica gli host di cui ti fidi.

In un ambiente limited, l'elenco allowed_hosts di Limita la rete limita anche gli strumenti web. Un ambiente unrestricted o una sandbox self-hosted non limita gli strumenti web.

I due elenchi confrontano gli host in modo diverso:

Se l'agente ha bisogno di un sito e di tutti i suoi sottodomini, elenca sia example.com sia *.example.com in allowed_hosts, altrimenti elenca host esatti. Se uno strumento elenca example.com e allowed_hosts elenca solo *.example.com, la sessione viene creata. Il controllo alla creazione della sessione considera example.com come compreso in *.example.com, ma lo strumento non restituisce nulla da example.com stesso. Consulta Impostare elenchi di domini su un agente per sapere come vengono confrontati i due elenchi.

Lo strumento web_fetch apre inoltre solo URL che sono già comparsi nella sessione:

In una sessione multiagente, web_fetch apre un URL proveniente da un altro agente solo se ha raggiunto quell'agente tramite una fonte contrassegnata con Sì. Il risultato di uno strumento personalizzato da una chiamata diretta conta come fonte contrassegnata con Sì. Questo vale anche se il testo è stato scritto da Claude, ad esempio quando lo strumento ripete il proprio input. Un URL può essere valido anche quando è scritto senza https://, come example.com/docs. Lo strumento web_fetch non sempre riesce ad aprire un link che mostra parole invece del suo URL, come "Contatta l'assistenza". Se l'agente deve recuperare un URL che non è comparso nella sessione, invialo in un messaggio utente.

Questa regola riduce la probabilità che un testo iniettato costruisca un URL che trasporta dati privati. Il testo dell'utente finale, i risultati di ricerca, le pagine recuperate e i risultati degli strumenti personalizzati possono comunque aggiungere URL, quindi mantieni impostato allowed_domains. La Messages API applica una regola simile con un elenco di fonti diverso. Consulta Validazione degli URL.

Un elenco di domini su web_fetch non limita lo strumento bash. Limita la rete anche in questo caso. Consulta Regole degli elenchi di domini.

Approva le azioni rischiose

Imposta auto su bash, write, edit e web_fetch, e sugli strumenti MCP che leggono solo dati. Usa invece always_ask su uno strumento se non puoi annullare le sue modifiche al di fuori della sandbox. Usalo anche su uno strumento che non dovrebbe essere eseguito solo perché lo richiede il testo dell'utente finale che inoltri. Una policy di autorizzazione determina se una chiamata a uno strumento viene eseguita, attende la tua approvazione o viene valutata dal server.

Il toolset in Dai all'agente il set di strumenti più ridotto applica queste policy.

La policy auto consente al server di eseguire una chiamata, negarla o mettersi in pausa in attesa di approvazione. Una persona non può approvare ogni chiamata in un'esecuzione lunga, quindi è il server a controllarle una per una. Abbina auto a un networking limitato, a una chiave con permessi ristretti, a un budget e a un avviso sulle sessioni inattive. auto non è un punto di controllo umano, quindi se una persona deve rivedere le chiamate a uno strumento prima che vengano eseguite, configura always_ask su quello strumento.

auto tratta il testo negli eventi user.message e la descrizione in un evento user.define_outcome come tue istruzioni, incluso il testo dell'utente finale che inoltri.

Una sessione in pausa attende indefinitamente, quindi una sessione non presidiata ha bisogno di un client che risponda alle chiamate in pausa o interrompa la sessione.

Rivedi ogni chiamata in pausa prima di consentirla. Un client che consente ogni chiamata senza mostrarla a una persona equivale a always_allow. Consulta Rispondere alle richieste di conferma e Vedere come è stata valutata ogni chiamata.

Dai all'agente il set di strumenti più ridotto

Imposta default_config.enabled su false e abilita solo gli strumenti di cui l'agente ha bisogno. Il toolset dell'agente abilita per impostazione predefinita tutti e otto gli strumenti integrati.

L'agente di supporto ha bisogno di tre strumenti integrati: read e write per la sua bozza, e web_fetch per il centro assistenza. Cerca gli ordini tramite uno strumento personalizzato, lookup_order, eseguito dalla tua applicazione. La chiave API per la tua API degli ordini è detenuta dalla tua applicazione, quindi l'agente non ha bisogno né di bash né di una credenziale.

L'esempio seguente limita web_fetch a help.example.com con allowed_domains. Imposta auto su write e web_fetch, come raccomandato in Approva le azioni rischiose. Se il ticket di un cliente induce l'agente a usare questi strumenti, l'agente può solo modificare file nella sandbox o aprire pagine del centro assistenza. Ecco perché nessuno dei due strumenti ha bisogno di always_ask. L'esempio imposta anche always_ask in default_config, così uno strumento che abiliti in seguito senza una propria policy usa always_ask:

ant apply agent.md

---
name: Support Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: false
      permission_policy:
        type: always_ask
    configs:
      - name: read
        enabled: true
        permission_policy:
          type: always_allow
      - name: write
        enabled: true
        permission_policy:
          type: auto
      - name: web_fetch
        enabled: true
        allowed_domains: [help.example.com]
        permission_policy:
          type: auto
  - type: custom
    name: lookup_order
    description: Look up one order by its ID. Returns the status, the items, and the delivery date.
    input_schema:
      type: object
      properties:
        order_id:
          type: string
          description: The order ID from the ticket
      required:
        - order_id
---

Un aggiornamento dell'agente sostituisce l'intero array tools, quindi invia ogni voce che vuoi mantenere.

Un aggiornamento dell'agente raggiunge solo le nuove sessioni, quindi controlla anche i deployment, gli agenti che elencano questo agente e le sessioni esistenti:

• Un deployment fissa una versione dell'agente, quindi fai puntare ogni deployment alla nuova versione.
• Un agente che elenca questo in subagents.predefined_agents o in workflows.predefined_agents mantiene la versione che ha fissato, quindi aggiorna anche quell'agente.
• Per rendere più restrittiva una sessione già esistente, aggiorna gli strumenti di quella sessione. La sessione deve essere idle, e l'aggiornamento sostituisce l'intero array tools. In una sessione multiagente, i nuovi elenchi allowed_domains e blocked_domains sugli strumenti web dell'agente eseguito dalla sessione si applicano anche a tutti gli altri agenti. Si applicano a partire dal turno successivo di ciascun agente. Gli strumenti abilitati e le policy di autorizzazione di quegli agenti non cambiano. Per modificarli, aggiorna ciascun agente, quindi avvia una nuova sessione.

Limita anche i server MCP e gli strumenti personalizzati a ciò di cui l'agente ha bisogno:

• Server MCP: Un toolset MCP abilita per impostazione predefinita ogni strumento esposto dal server. Imposta default_config.enabled su false e abilita gli strumenti per nome, così gli strumenti aggiunti in seguito da un server restano disattivati. Rimuovi i server che l'agente non usa. Consulta Connettore MCP.
• Strumenti personalizzati: Li esegue la tua applicazione, e le policy di autorizzazione non si applicano. Convalida l'input di ogni chiamata nella tua applicazione e limita ciò che lo strumento può toccare.

Tieni l'input non attendibile lontano dagli strumenti potenti

Controlla quali strumenti e credenziali possiede un agente ogni volta che legge input non attendibile, ovvero testo che qualcuno al di fuori del tuo team può scrivere. Questa sezione usa due termini:

• Input non attendibile: Pagine web, risultati di ricerca, ticket di supporto, email, file di repository, caricamenti, risultati di server MCP e messaggi dell'utente finale che inoltri.
• Strumenti potenti: bash, write, edit, web_fetch, web_search, strumenti MCP e strumenti personalizzati che scrivono o inviano dati, e qualsiasi strumento che usa una credenziale.

Il testo in un input non attendibile può indicare all'agente di usare uno strumento potente che possiede. L'agente di supporto legge i ticket, quindi raggiunge la tua API degli ordini solo tramite lo strumento personalizzato lookup_order. La tua applicazione verifica che l'ordine appartenga al mittente del ticket.

In un ambiente cloud, la lettura di un file con read può anche caricare i file CLAUDE.md e AGENTS.md come istruzioni. Vengono caricati dalla directory del file e dalle sue directory padre, fino alla directory di lavoro della sandbox. Vengono caricati anche i file a cui fanno riferimento con @ e un percorso, come @docs/setup.md, fino a cinque livelli di riferimento. Un riferimento può puntare a qualsiasi punto della sandbox, ad esempio @/etc/hosts. Nessuna impostazione disattiva questo comportamento tranne la disabilitazione di read, quindi tratta come input non attendibile un repository, un pacchetto o un archivio che qualcuno al di fuori del tuo team può scrivere.

Quando un agente deve leggere input non attendibile e anche agire, questa guida raccomanda uno di tre design:

• Separa la lettura dall'azione. In una sessione multiagente, un agente principale assegna compiti a un fetcher, che legge il web, e a un writer, che modifica file o record.
• Dai all'agente un unico strumento personalizzato ristretto. La tua applicazione esegue lo strumento, ne controlla l'input e detiene la credenziale. L'agente di supporto usa questo design, non la separazione. Consulta Rispondere alle chiamate agli strumenti che mettono in pausa la sessione.
• Mantieni una persona nel ciclo. Usa always_ask sullo strumento potente in modo che una persona approvi ogni chiamata.

La separazione usa tre agenti:

I risultati del fetcher sono costruiti a partire da pagine non attendibili, e l'agente principale può trasmetterne il testo al writer. Mantieni auto o always_ask sugli strumenti del writer. Il fetcher può comunque inviare parte di ciò che legge ai siti del suo elenco web_fetch, e al provider di ricerca nelle sue query.

Gli agenti in una sessione multiagente condividono la sandbox, i suoi file e le credenziali del vault, quindi questa separazione divide solo i loro strumenti e le loro conversazioni. Per una separazione più forte, usa due sessioni con ambienti e vault separati. Fai in modo che la tua applicazione trasmetta tra le due sessioni solo campi fissi, come un ID ordine.

Imposta limiti e un modo per fermare l'agente

Imposta un budget quando crei ogni sessione e decidi in anticipo come fermare un agente.

Per fermare un agente in esecuzione, segui questi passaggi:

1. Invia user.interrupt da solo.
2. Per un agente pianificato, metti anche in pausa il deployment in modo che non venga avviata alcuna nuova esecuzione pianificata. Per terminare la pianificazione in modo permanente, archivia il deployment.
3. Se una chiave potrebbe essere esposta, ruotala presso il servizio che l'ha emessa.
4. Se l'agente ha esecuzioni di workflow aperte, invia anche un user.message che gli chieda di fermarle, perché un'interruzione non termina alcuna esecuzione. Consulta Interrompere una sessione con esecuzioni aperte per le chiamate agli strumenti da annullare prima.
5. Attendi che la sessione passi a idle. Una sessione in esecuzione non può essere archiviata né eliminata.
6. Archivia la sessione per conservarne la cronologia. Eliminala quando la cronologia non ti serve più.

Un'interruzione non annulla ciò che l'agente ha già fatto o inviato. L'archiviazione di un agente non ferma le sue sessioni in esecuzione.

Il valore max_list_cost.amount di un budget è un numero intero di centesimi di dollaro USA scritto come stringa, quindi "125" significa $1,25. Consulta Imposta un budget alla creazione della sessione.

Non puoi aggiungere un budget a una sessione creata senza. Per modificare o rimuovere un tetto, consulta Riprendi una sessione che ha raggiunto il budget. Dopo aver rimosso il tetto di una sessione, non puoi impostarne uno nuovo.

Un budget limita la spesa, ma non limita ciò che l'agente fa prima di raggiungere il tetto. Per tenere separati carichi di lavoro con livelli di attendibilità diversi, usa workspace separati. Assegna a ogni carico di lavoro una chiave API limitata a un solo workspace, perché una chiave che può raggiungere più workspace può agire in ognuno di essi.

Consulta Budget di sessione, Operazioni sulle sessioni e Deployment pianificati.

Passaggi successivi