Sécuriser votre déploiement Managed Agents

Ce guide répertorie les paramètres qui limitent ce qu'un agent sur Claude Managed Agents peut atteindre et faire, du plus important au moins important. Chaque section renvoie à la page qui couvre le paramètre en détail.

Risques de sécurité et limites du sandbox explique pourquoi ces paramètres sont importants et contre quoi ils ne protègent pas. Pour examiner et surveiller les sessions, consultez Examiner et surveiller les sessions d'agent.

Choisir où l'agent s'exécute

L'endroit où s'exécutent les outils de l'agent détermine qui sécurise le sandbox : Anthropic, avec un environnement cloud, ou vous, avec un sandbox auto-hébergé. Pour choisir entre les deux et savoir ce qui parvient à Anthropic dans chaque cas, consultez Choisir un environnement d'agent.

Si vous utilisez un sandbox auto-hébergé, gardez ces quatre points à l'esprit :

• Réseau : Limiter le réseau s'applique aux environnements cloud. Pour un sandbox auto-hébergé, définissez les limites équivalentes sur son trafic dans votre propre pare-feu. Votre pare-feu ne limite pas les serveurs MCP qu'un agent déclare, alors examinez-les, ainsi que ceux que votre application définit pour une session.
• Outils web : Les outils web s'exécutent sur les serveurs d'Anthropic, votre pare-feu ne les limite donc pas. Limitez-les avec leurs listes de domaines. Consultez Restreindre la recherche web et la récupération web.
• Identifiants : Les identifiants de variables d'environnement ne sont pas encore pris en charge avec les sandboxes auto-hébergés.
• Isolation et durcissement : Vous êtes responsable des deux. Consultez le Modèle de sécurité.

Aucune des deux options ne modifie la couverture de conformité de Managed Agents ni la durée pendant laquelle il conserve l'historique des sessions. Consultez Surveiller les sessions et examiner la conservation.

Limiter le réseau

Définissez networking.type sur limited et listez uniquement les hôtes dont l'agent a besoin dans allowed_hosts. Une requête de création d'environnement qui omet networking peut obtenir unrestricted, alors définissez networking dans chaque requête de création. Consultez Risques de la mise en réseau non restreinte.

Les fichiers, les magasins de mémoire et les dépôts GitHub que vous attachez restent accessibles à l'agent, quel que soit allowed_hosts.

Les exemples de cette page utilisent un agent de support. Il lit le ticket d'un client, recherche la commande, lit votre centre d'aide et rédige une réponse. Votre application exécute la recherche de commande, qui ne nécessite aucun hôte, donc cet environnement autorise un seul hôte, le centre d'aide, pour 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 environnement limited possède trois paramètres réseau :

Les paramètres allow_package_managers et allow_mcp_servers n'ajoutent aucun hôte pour la recherche web et la récupération web.

Laissez allow_mcp_servers désactivé, ce qui est la valeur par défaut, et listez l'hôte de chaque serveur MCP que vous exploitez ou auquel vous faites confiance dans allowed_hosts. Chaque hôte que vous listez est également ouvert au code dans le sandbox. Avec allow_mcp_servers désactivé, une vérification lors de la création de la session rejette la requête si l'hôte d'un serveur MCP n'est pas listé. Consultez Fournir l'authentification à la création de la session. La même vérification s'exécute lorsqu'une mise à jour de session modifie mcp_servers.

Lorsque vous choisissez les hôtes pour allowed_hosts, suivez ces deux règles :

• Listez uniquement les hôtes que vous exploitez ou auxquels vous faites confiance.
• Évitez les caractères génériques *. et les domaines d'hébergement partagé où n'importe qui peut publier du contenu.

Si l'agent conserve bash, définissez la politique d'autorisation de l'outil bash comme le décrit Approuver les actions risquées.

Consultez Configuration de l'environnement cloud pour tous les paramètres réseau.

Conserver les identifiants dans des coffres

Stockez chaque secret dans un coffre (vault). Pour chaque identifiant de variable d'environnement, définissez l'emplacement d'injection sur les en-têtes de requête uniquement et listez uniquement les hôtes auxquels le secret est destiné. Le code dans le sandbox voit un espace réservé au lieu du secret. Managed Agents substitue le vrai secret uniquement dans les requêtes HTTPS sortantes vers les hôtes que l'identifiant autorise. Le secret reste ainsi hors de portée directe du modèle, sauf si un service le renvoie, comme un point de terminaison qui renvoie en écho les en-têtes de requête. Si le networking de l'identifiant est unrestricted, Managed Agents substitue le vrai secret dans les requêtes vers tout hôte que l'environnement permet au sandbox d'atteindre. Pour utiliser un coffre, transmettez son ID dans vault_ids lorsque vous créez la session ou le déploiement.

L'agent de support n'a besoin d'aucun identifiant de coffre, car votre application détient la clé API de votre API de commandes. Si votre agent détient un identifiant de coffre, consultez Ajouter un identifiant pour la requête dans chaque langage.

Gardez les clés hors des invites système, des définitions d'agent et des messages. Ne donnez pas de clé API Claude à l'agent. Même lorsqu'une clé API Claude se trouve dans un coffre, le code dans le sandbox peut l'utiliser pour appeler directement l'API Claude. Il peut faire tout ce que cette clé permet, comme démarrer ou supprimer des sessions, ou utiliser la recherche web et la récupération web. Les paramètres d'outils, les approbations et le budget de l'agent ne s'appliquent pas à ces appels. Dans un environnement limited, le code ne peut effectuer ces appels que si allowed_hosts permet au sandbox d'atteindre api.anthropic.com.

Récupérez vous-même les jetons et stockez-les dans le coffre, car un jeton que le code dans le sandbox récupère avec un secret stocké revient sans masquage.

Conservez les coffres des charges de travail ayant des niveaux de confiance différents dans des espaces de travail distincts, car toute clé API ayant accès à un espace de travail peut référencer ses coffres. Utilisez des clés API limitées à un seul espace de travail.

Consultez S'authentifier avec des coffres-forts pour les identifiants MCP et la rotation.

Restreindre la recherche web et la récupération web

Définissez allowed_domains sur web_fetch avec les sites dont l'agent a besoin. Toute URL que l'agent récupère peut transporter des données vers le site vers lequel elle pointe, cette liste est donc un contrôle de sécurité. Sur web_search, définissez allowed_domains avec les sites dont vous souhaitez obtenir des résultats, afin que les résultats proviennent uniquement de sites auxquels vous faites confiance pour leur exactitude. La liste n'empêche pas la requête de recherche d'atteindre le fournisseur de recherche. Les résultats de recherche incluent du texte provenant de pages, la liste limite donc aussi les sites dont le texte parvient à l'agent. Définissez allowed_domains sur les deux outils pour chaque type d'environnement.

Une liste blocked_domains bloque les hôtes que vous listez et leurs sous-domaines, et aucun autre hôte. Le même contenu peut toujours parvenir à l'agent depuis des archives web, des caches, des miroirs ou des domaines apparentés que vous n'avez pas listés. Ne comptez pas sur blocked_domains pour la sécurité. Utilisez allowed_domains et nommez les hôtes auxquels vous faites confiance.

Dans un environnement limited, la liste allowed_hosts de Limiter le réseau limite également les outils web. Un environnement unrestricted ou un sandbox auto-hébergé ne limite pas les outils web.

Les deux listes font correspondre les hôtes différemment :

Si l'agent a besoin d'un site et de tous ses sous-domaines, listez à la fois example.com et *.example.com dans allowed_hosts, et sinon listez des hôtes exacts. Si un outil liste example.com et que allowed_hosts liste uniquement *.example.com, la session est créée. La vérification lors de la création de la session considère example.com comme inclus dans *.example.com, mais l'outil ne renvoie rien depuis example.com lui-même. Consultez Définir des listes de domaines sur un agent pour savoir comment les deux listes font correspondre les hôtes.

L'outil web_fetch n'ouvre également que les URL qui sont déjà apparues dans la session :

Dans une session multi-agents, web_fetch n'ouvre une URL provenant d'un autre agent que si elle a atteint cet agent par une source marquée Oui. Le résultat d'un outil personnalisé issu d'un appel direct compte comme une source marquée Oui. Cela reste vrai même si Claude a écrit son texte, par exemple lorsque l'outil répète son entrée. Une URL peut compter même lorsqu'elle est écrite sans https://, comme example.com/docs. L'outil web_fetch ne peut pas toujours ouvrir un lien qui affiche des mots au lieu de son URL, comme « Contacter le support ». Si l'agent doit récupérer une URL qui n'est pas apparue dans la session, envoyez-la dans un message utilisateur.

Cette règle réduit le risque qu'un texte injecté construise une URL transportant des données privées. Le texte des utilisateurs finaux, les résultats de recherche, les pages récupérées et les résultats d'outils personnalisés peuvent toujours ajouter des URL, alors gardez allowed_domains défini. L'API Messages applique une règle similaire avec une liste de sources différente. Consultez Validation des URL.

Une liste de domaines sur web_fetch ne limite pas l'outil bash. Limitez également le réseau. Consultez Règles des listes de domaines.

Approuver les actions risquées

Définissez auto sur bash, write, edit et web_fetch, ainsi que sur les outils MCP qui ne font que lire des données. Utilisez plutôt always_ask sur un outil si vous ne pouvez pas annuler ses modifications en dehors du sandbox. Utilisez-le également sur un outil qui ne devrait pas s'exécuter simplement parce que le texte d'un utilisateur final que vous relayez le demande. Une politique d'autorisation détermine si un appel d'outil s'exécute, attend votre approbation ou est évalué par le serveur.

L'ensemble d'outils de Donner à l'agent le plus petit ensemble d'outils applique ces politiques.

La politique auto permet au serveur d'exécuter un appel, de le refuser ou de se mettre en pause pour approbation. Une personne ne peut pas approuver chaque appel d'une longue exécution, le serveur vérifie donc chacun d'eux à sa place. Associez auto à un réseau limité, une clé aux autorisations restreintes, un budget et une alerte sur les sessions inactives. auto n'est pas un point de contrôle humain, donc si une personne doit examiner les appels d'un outil avant leur exécution, configurez always_ask sur cet outil.

auto traite le texte des événements user.message et la description d'un événement user.define_outcome comme votre instruction, y compris le texte d'utilisateurs finaux que vous relayez.

Une session en pause attend indéfiniment, donc une session sans surveillance a besoin d'un client qui répond aux appels en pause ou interrompt la session.

Examinez chaque appel en pause avant de l'autoriser. Un client qui autorise chaque appel sans le montrer à une personne équivaut à always_allow. Consultez Répondre aux demandes de confirmation et Voir comment chaque appel a été évalué.

Donner à l'agent le plus petit ensemble d'outils

Définissez default_config.enabled sur false et activez uniquement les outils dont l'agent a besoin. L'ensemble d'outils de l'agent active par défaut les huit outils intégrés.

L'agent de support a besoin de trois outils intégrés : read et write pour son brouillon, et web_fetch pour le centre d'aide. Il recherche les commandes via un outil personnalisé, lookup_order, que votre application exécute. Votre application détient la clé API de votre API de commandes, l'agent n'a donc besoin ni de bash ni d'un identifiant.

L'exemple suivant limite web_fetch à help.example.com avec allowed_domains. Il définit auto sur write et web_fetch, comme le recommande Approuver les actions risquées. Si le ticket d'un client amène l'agent à utiliser ces outils, l'agent peut uniquement modifier des fichiers dans le sandbox ou ouvrir des pages du centre d'aide. C'est pourquoi aucun des deux outils n'a besoin de always_ask. L'exemple définit également always_ask dans default_config, de sorte qu'un outil que vous activez ultérieurement sans politique propre utilise 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
---

Une mise à jour d'agent remplace l'intégralité du tableau tools, alors envoyez chaque entrée que vous souhaitez conserver.

Une mise à jour d'agent n'atteint que les nouvelles sessions, vérifiez donc également les déploiements, les agents qui listent cet agent et les sessions existantes :

• Un déploiement épingle une version d'agent, alors faites pointer chaque déploiement vers la nouvelle.
• Un agent qui liste celui-ci dans subagents.predefined_agents ou workflows.predefined_agents conserve la version qu'il a épinglée, alors mettez également cet agent à jour.
• Pour restreindre davantage une session qui existe déjà, mettez à jour les outils de cette session. La session doit être idle, et la mise à jour remplace l'intégralité du tableau tools. Dans une session multi-agents, les nouvelles listes allowed_domains et blocked_domains sur les outils web de l'agent que la session exécute s'appliquent également à tous les autres agents. Elles s'appliquent à partir du tour suivant de chaque agent. Les outils activés et les politiques d'autorisation de ces agents ne changent pas. Pour les modifier, mettez à jour chaque agent, puis démarrez une nouvelle session.

Limitez également les serveurs MCP et les outils personnalisés à ce dont l'agent a besoin :

• Serveurs MCP : Un ensemble d'outils MCP active par défaut chaque outil que le serveur expose. Définissez default_config.enabled sur false et activez des outils nommés, afin que les outils qu'un serveur ajoute ultérieurement restent désactivés. Supprimez les serveurs que l'agent n'utilise pas. Consultez Connecteur MCP.
• Outils personnalisés : Votre application les exécute, et les politiques d'autorisation ne s'appliquent pas. Validez l'entrée de chaque appel dans votre application et limitez ce que l'outil peut toucher.

Tenir les entrées non fiables à l'écart des outils puissants

Vérifiez les outils et identifiants dont dispose un agent chaque fois qu'il lit des entrées non fiables, c'est-à-dire du texte que quelqu'un en dehors de votre équipe peut écrire. Cette section utilise deux termes :

• Entrées non fiables : Pages web, résultats de recherche, tickets de support, e-mails, fichiers de dépôt, téléversements, résultats de serveurs MCP et messages d'utilisateurs finaux que vous relayez.
• Outils puissants : bash, write, edit, web_fetch, web_search, les outils MCP et outils personnalisés qui écrivent ou envoient des données, et tout outil qui utilise un identifiant.

Le texte d'une entrée non fiable peut demander à l'agent d'utiliser un outil puissant dont il dispose. L'agent de support lit des tickets, il n'accède donc à votre API de commandes que via l'outil personnalisé lookup_order. Votre application vérifie que la commande appartient à l'expéditeur du ticket.

Dans un environnement cloud, la lecture d'un fichier avec read peut également charger des fichiers CLAUDE.md et AGENTS.md comme instructions. Ils sont chargés depuis le répertoire du fichier et ses répertoires parents, jusqu'au répertoire de travail du sandbox. Les fichiers qu'ils référencent avec @ et un chemin, comme @docs/setup.md, sont également chargés, jusqu'à cinq niveaux de références. Une référence peut pointer n'importe où dans le sandbox, par exemple @/etc/hosts. Aucun paramètre ne désactive ce comportement, hormis la désactivation de read, alors traitez un dépôt, un paquet ou une archive que quelqu'un en dehors de votre équipe peut écrire comme une entrée non fiable.

Lorsqu'un agent doit lire des entrées non fiables et également agir, ce guide recommande l'une de trois conceptions :

• Séparer la lecture de l'action. Dans une même session multi-agents, un agent principal confie des tâches à un récupérateur, qui lit le web, et à un rédacteur, qui modifie des fichiers ou des enregistrements.
• Donner à l'agent un seul outil personnalisé restreint. Votre application exécute l'outil, vérifie son entrée et détient l'identifiant. L'agent de support utilise cette conception, et non la séparation. Consultez Répondre aux appels d'outils qui mettent la session en pause.
• Garder une personne dans la boucle. Utilisez always_ask sur l'outil puissant afin qu'une personne approuve chaque appel.

La séparation utilise trois agents :

Les résultats du récupérateur sont construits à partir de pages non fiables, et l'agent principal peut transmettre leur texte au rédacteur. Conservez auto ou always_ask sur les outils du rédacteur. Le récupérateur peut toujours envoyer une partie de ce qu'il lit aux sites de sa liste web_fetch, et au fournisseur de recherche dans ses requêtes.

Les agents d'une même session multi-agents partagent le sandbox, ses fichiers et les identifiants du coffre, donc cette séparation ne sépare que leurs outils et leurs conversations. Pour une séparation plus forte, utilisez deux sessions avec des environnements et des coffres distincts. Faites en sorte que votre application ne transmette que des champs fixes, comme un ID de commande, entre les deux sessions.

Définir des limites et un moyen d'arrêter

Définissez un budget lorsque vous créez chaque session, et décidez à l'avance comment vous arrêtez un agent.

Pour arrêter un agent en cours d'exécution, suivez ces étapes :

1. Envoyez user.interrupt seul.
2. Pour un agent planifié, mettez également le déploiement en pause afin qu'aucune nouvelle exécution planifiée ne démarre. Pour mettre fin définitivement à la planification, archivez le déploiement.
3. Si une clé a pu être exposée, effectuez sa rotation auprès du service qui l'a émise.
4. Si l'agent a des exécutions de workflow ouvertes, envoyez également un user.message lui demandant de les arrêter, car une interruption ne met fin à aucune exécution. Consultez Interrompre une session avec des exécutions ouvertes pour les appels d'outils à annuler en premier.
5. Attendez que la session passe à idle. Une session en cours d'exécution ne peut être ni archivée ni supprimée.
6. Archivez la session pour conserver son historique. Supprimez-la lorsque vous n'avez plus besoin de l'historique.

Une interruption n'annule pas ce que l'agent a déjà fait ou envoyé. L'archivage d'un agent n'arrête pas ses sessions en cours.

Le max_list_cost.amount d'un budget est un nombre entier de cents américains écrit sous forme de chaîne, donc "125" signifie 1,25 $. Consultez Définir un budget à la création de la session.

Vous ne pouvez pas ajouter de budget à une session créée sans budget. Pour modifier ou supprimer un plafond, consultez Reprendre une session ayant atteint son budget. Après avoir supprimé le plafond d'une session, vous ne pouvez pas en définir un nouveau.

Un budget plafonne les dépenses, mais il ne limite pas ce que fait l'agent avant d'atteindre le plafond. Pour séparer les charges de travail ayant des niveaux de confiance différents, utilisez des espaces de travail distincts. Donnez à chaque charge de travail une clé API limitée à un seul espace de travail, car une clé qui peut atteindre plusieurs espaces de travail peut agir dans n'importe lequel d'entre eux.

Consultez Budgets de session, Opérations sur les sessions et Déploiements planifiés.

Étapes suivantes