Protege tu implementación de Managed Agents

Esta guía enumera las opciones de configuración que limitan lo que un agente en Claude Managed Agents puede alcanzar y hacer, de la más importante a la menos importante. Cada sección enlaza a la página que cubre la configuración en detalle.

Riesgos de seguridad y límites del sandbox explica por qué importa esta configuración y contra qué no protege. Para revisar y supervisar sesiones, consulta Revisar y supervisar sesiones de agentes.

Elige dónde se ejecuta el agente

El lugar donde se ejecutan las herramientas del agente decide quién protege el sandbox: Anthropic, con un entorno en la nube, o tú, con un sandbox autoalojado. Para elegir entre ellos y saber qué llega a Anthropic con cada uno, consulta Elegir un entorno para el agente.

Si usas un sandbox autoalojado, ten en cuenta estos cuatro puntos:

• Red: Limita la red se aplica a los entornos en la nube. Para un sandbox autoalojado, establece los límites equivalentes sobre su tráfico en tu propio firewall. Tu firewall no limita los servidores MCP que declara un agente, así que revísalos, junto con los que tu aplicación establezca para una sesión.
• Herramientas web: Las herramientas web se ejecutan en los servidores de Anthropic, por lo que tu firewall no las limita. Limítalas con sus listas de dominios. Consulta Restringe la búsqueda web y la obtención web.
• Credenciales: Las credenciales de variables de entorno aún no son compatibles con los sandboxes autoalojados.
• Aislamiento y endurecimiento: Eres responsable de ambos. Consulta el Modelo de seguridad.

Ninguna de las dos opciones cambia la cobertura de cumplimiento de Managed Agents ni el tiempo que conserva el historial de la sesión. Consulta Supervisa las sesiones y revisa la retención.

Limita la red

Establece networking.type en limited e incluye en allowed_hosts solo los hosts que el agente necesita. Una solicitud de creación de entorno que omite networking podría obtener unrestricted, así que establece networking en cada solicitud de creación. Consulta Riesgos de las redes sin restricciones.

Los archivos, los almacenes de memoria y los repositorios de GitHub que adjuntes siguen disponibles para el agente independientemente de allowed_hosts.

Los ejemplos de esta página usan un agente de soporte. Lee el ticket de un cliente, busca el pedido, lee tu centro de ayuda y redacta una respuesta. Tu aplicación ejecuta la búsqueda del pedido, que no necesita ningún host, así que este entorno permite un solo host, el centro de ayuda, para 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 entorno limited tiene tres opciones de red:

Las opciones allow_package_managers y allow_mcp_servers no añaden hosts para la búsqueda web ni la obtención web.

Deja allow_mcp_servers desactivado, que es el valor predeterminado, e incluye en allowed_hosts el host de cada servidor MCP que operas o en el que confías. Cada host que incluyas también queda abierto al código en el sandbox. Con allow_mcp_servers desactivado, una comprobación al crear la sesión rechaza la solicitud si el host de un servidor MCP no está en la lista. Consulta Proporcionar autenticación al crear la sesión. La misma comprobación se ejecuta cuando una actualización de sesión cambia mcp_servers.

Cuando elijas hosts para allowed_hosts, sigue estas dos reglas:

• Incluye solo hosts que operas o en los que confías.
• Evita los comodines *. y los dominios de alojamiento compartido donde cualquiera puede publicar contenido.

Si el agente conserva bash, establece la política de permisos de la herramienta bash como se describe en Aprueba las acciones riesgosas.

Consulta Configuración del entorno en la nube para ver todas las opciones de red.

Guarda las credenciales en vaults

Almacena cada secreto en un vault. Para cada credencial de variable de entorno, establece la ubicación de inyección solo en los encabezados de solicitud e incluye solo los hosts para los que es el secreto. El código en el sandbox ve un marcador de posición en lugar del secreto. Managed Agents sustituye el marcador de posición por el secreto real solo en las solicitudes HTTPS salientes a los hosts que permite la credencial. Así, el secreto queda fuera del alcance directo del modelo, a menos que un servicio lo devuelva, como un endpoint que repite los encabezados de la solicitud. Si el networking de la credencial es unrestricted, Managed Agents sustituye el marcador de posición por el secreto real en las solicitudes a cualquier host al que el entorno permita que acceda el sandbox. Para usar un vault, pasa su ID en vault_ids cuando crees la sesión o la implementación.

El agente de soporte no necesita ninguna credencial de vault, porque tu aplicación tiene la clave de API de tu API de pedidos. Si tu agente sí tiene una credencial de vault, consulta Agregar una credencial para ver la solicitud en todos los lenguajes.

Mantén las claves fuera de las indicaciones del sistema, las definiciones de agentes y los mensajes. No le des al agente una clave de API de Claude. Incluso cuando una clave de API de Claude está en un vault, el código en el sandbox puede usarla para llamar directamente a la API de Claude. Puede hacer cualquier cosa que esa clave permita, como iniciar o eliminar sesiones, o usar la búsqueda web y la obtención web. La configuración de herramientas, las aprobaciones y el presupuesto del agente no se aplican a esas llamadas. En un entorno limited, el código puede hacer estas llamadas solo si allowed_hosts permite que el sandbox llegue a api.anthropic.com.

Obtén los tokens tú mismo y guárdalos en el vault, porque un token que el código en el sandbox obtiene con un secreto almacenado vuelve sin redactar.

Mantén los vaults de cargas de trabajo con distintos niveles de confianza en espacios de trabajo separados, porque cualquier clave de API con acceso a un espacio de trabajo puede hacer referencia a sus vaults. Usa claves de API limitadas a un solo espacio de trabajo.

Consulta Autenticar con vaults para las credenciales de MCP y la rotación.

Restringe la búsqueda web y la obtención web

Establece allowed_domains en web_fetch con los sitios que el agente necesita. Cualquier URL que obtenga el agente puede llevar datos al sitio al que apunta, así que esta lista es un control de seguridad. En web_search, establece allowed_domains con los sitios de los que quieres obtener resultados, para que los resultados provengan solo de sitios en cuya exactitud confías. La lista no impide que la consulta de búsqueda llegue al proveedor de búsqueda. Los resultados de búsqueda incluyen texto de las páginas, así que la lista también limita de qué sitios llega texto al agente. Establece allowed_domains en ambas herramientas para todo tipo de entorno.

Una lista blocked_domains bloquea los hosts que incluyes y sus subdominios, y ningún otro host. El mismo contenido aún puede llegar al agente desde archivos históricos de la web, cachés, espejos o dominios relacionados que no incluiste. No dependas de blocked_domains para la seguridad. Usa allowed_domains e indica los hosts en los que confías.

En un entorno limited, la lista allowed_hosts de Limita la red también limita las herramientas web. Un entorno unrestricted o un sandbox autoalojado no limita las herramientas web.

Las dos listas coinciden con los hosts de forma diferente:

Si el agente necesita un sitio y todos sus subdominios, incluye tanto example.com como *.example.com en allowed_hosts; de lo contrario, incluye hosts exactos. Si una herramienta incluye example.com y allowed_hosts incluye solo *.example.com, la sesión se crea. La comprobación al crear la sesión considera que example.com está dentro de *.example.com, pero la herramienta no devuelve nada del propio example.com. Consulta Establecer listas de dominios en un agente para ver cómo coinciden las dos listas.

La herramienta web_fetch además solo abre URLs que ya han aparecido en la sesión:

En una sesión multiagente, web_fetch abre una URL de otro agente solo si llegó a ese agente a través de una fuente marcada con Sí. El resultado de una herramienta personalizada de una llamada directa cuenta como una fuente marcada con Sí. Esto se cumple incluso si Claude escribió su texto, por ejemplo cuando la herramienta repite su entrada. Una URL puede contar incluso cuando está escrita sin https://, como example.com/docs. La herramienta web_fetch no siempre puede abrir un enlace que muestra palabras en lugar de su URL, como "Contactar con soporte". Si el agente debe obtener una URL que no ha aparecido en la sesión, envíala en un mensaje de usuario.

Esta regla reduce la probabilidad de que un texto inyectado construya una URL que lleve datos privados. El texto de usuario final, los resultados de búsqueda, las páginas obtenidas y los resultados de herramientas personalizadas aún pueden añadir URLs, así que mantén allowed_domains establecido. La Messages API aplica una regla similar con una lista de fuentes diferente. Consulta Validación de URLs.

Una lista de dominios en web_fetch no limita la herramienta bash. Limita la red también. Consulta Reglas de las listas de dominios.

Aprueba las acciones riesgosas

Establece auto en bash, write, edit y web_fetch, y en las herramientas MCP que solo leen datos. Usa always_ask en su lugar en una herramienta si no puedes deshacer sus cambios fuera del sandbox. Úsalo también en una herramienta que no debería ejecutarse solo porque lo pida el texto de usuario final que retransmites. Una política de permisos determina si una llamada a una herramienta se ejecuta, espera tu aprobación o la evalúa el servidor.

El conjunto de herramientas de Dale al agente el conjunto de herramientas más pequeño aplica estas políticas.

La política auto permite que el servidor ejecute una llamada, la deniegue o se detenga para pedir aprobación. Una persona no puede aprobar cada llamada en una ejecución larga, así que el servidor comprueba cada una en su lugar. Combina auto con red limitada, una clave con permisos reducidos, un presupuesto y una alerta sobre sesiones inactivas. auto no es un punto de control humano, así que si una persona debe revisar las llamadas de una herramienta antes de que se ejecuten, configura always_ask en esa herramienta.

auto trata el texto de los eventos user.message y la descripción de un evento user.define_outcome como tu instrucción, incluido el texto de usuario final que retransmites.

Una sesión en pausa espera indefinidamente, así que una sesión desatendida necesita un cliente que responda a las llamadas en pausa o interrumpa la sesión.

Revisa cada llamada en pausa antes de permitirla. Un cliente que permite cada llamada sin mostrársela a una persona equivale a always_allow. Consulta Responder a solicitudes de confirmación y Ver cómo se evaluó cada llamada.

Dale al agente el conjunto de herramientas más pequeño

Establece default_config.enabled en false y habilita solo las herramientas que el agente necesita. El conjunto de herramientas del agente habilita las ocho herramientas integradas de forma predeterminada.

El agente de soporte necesita tres herramientas integradas: read y write para su borrador, y web_fetch para el centro de ayuda. Busca pedidos mediante una herramienta personalizada, lookup_order, que ejecuta tu aplicación. Tu aplicación tiene la clave de API de tu API de pedidos, así que el agente no necesita ni bash ni una credencial.

El siguiente ejemplo limita web_fetch a help.example.com con allowed_domains. Establece auto en write y web_fetch, como recomienda Aprueba las acciones riesgosas. Si el ticket de un cliente lleva al agente a usar estas herramientas, el agente solo puede modificar archivos en el sandbox o abrir páginas del centro de ayuda. Por eso ninguna de las dos herramientas necesita always_ask. El ejemplo también establece always_ask en default_config, de modo que una herramienta que habilites más adelante sin su propia política use 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
---

Una actualización del agente reemplaza todo el arreglo tools, así que envía todas las entradas que quieras conservar.

Una actualización del agente solo llega a las sesiones nuevas, así que revisa también las implementaciones, los agentes que incluyen a este agente y las sesiones existentes:

• Una implementación fija una versión del agente, así que apunta cada implementación a la nueva.
• Un agente que incluye a este en subagents.predefined_agents o workflows.predefined_agents conserva la versión que fijó, así que actualiza también ese agente.
• Para restringir una sesión que ya existe, actualiza las herramientas de esa sesión. La sesión debe estar idle, y la actualización reemplaza todo el arreglo tools. En una sesión multiagente, las nuevas listas allowed_domains y blocked_domains en las herramientas web del agente que ejecuta la sesión también se aplican a todos los demás agentes. Se aplican a partir del siguiente turno de cada agente. Las herramientas habilitadas y las políticas de permisos de esos agentes no cambian. Para cambiarlas, actualiza cada agente y luego inicia una sesión nueva.

Limita también los servidores MCP y las herramientas personalizadas a lo que el agente necesita:

• Servidores MCP: Un conjunto de herramientas MCP habilita de forma predeterminada todas las herramientas que expone el servidor. Establece default_config.enabled en false y habilita herramientas por nombre, para que las herramientas que un servidor añada más adelante permanezcan desactivadas. Elimina los servidores que el agente no usa. Consulta Conector MCP.
• Herramientas personalizadas: Las ejecuta tu aplicación, y las políticas de permisos no se aplican. Valida la entrada de cada llamada en tu aplicación y limita lo que la herramienta puede tocar.

Mantén la entrada no confiable lejos de las herramientas potentes

Comprueba qué herramientas y credenciales tiene un agente siempre que lea entrada no confiable, que es texto que puede escribir alguien ajeno a tu equipo. Esta sección usa dos términos:

• Entrada no confiable: Páginas web, resultados de búsqueda, tickets de soporte, correos electrónicos, archivos de repositorios, archivos subidos, resultados de servidores MCP y mensajes de usuarios finales que retransmites.
• Herramientas potentes: bash, write, edit, web_fetch, web_search, las herramientas MCP y las herramientas personalizadas que escriben o envían datos, y cualquier herramienta que use una credencial.

El texto de una entrada no confiable puede indicarle al agente que use una herramienta potente que tiene. El agente de soporte lee tickets, así que solo llega a tu API de pedidos a través de la herramienta personalizada lookup_order. Tu aplicación comprueba que el pedido pertenece al remitente del ticket.

En un entorno en la nube, leer un archivo con read también puede cargar archivos CLAUDE.md y AGENTS.md como instrucciones. Se cargan desde el directorio del archivo y sus directorios padre, hasta el directorio de trabajo del sandbox. Los archivos a los que hacen referencia con @ y una ruta, como @docs/setup.md, también se cargan, hasta cinco niveles de referencias. Una referencia puede apuntar a cualquier lugar del sandbox, por ejemplo @/etc/hosts. Ninguna opción desactiva esto salvo deshabilitar read, así que trata como entrada no confiable un repositorio, paquete o archivo comprimido que pueda escribir alguien ajeno a tu equipo.

Cuando un agente debe leer entrada no confiable y también actuar, esta guía recomienda uno de tres diseños:

• Separa la lectura de la acción. En una sesión multiagente, un agente principal asigna tareas a un agente de obtención, que lee la web, y a un agente de escritura, que modifica archivos o registros.
• Dale al agente una única herramienta personalizada acotada. Tu aplicación ejecuta la herramienta, comprueba su entrada y tiene la credencial. El agente de soporte usa este diseño, no la separación. Consulta Responder a llamadas a herramientas que pausan la sesión.
• Mantén a una persona en el proceso. Usa always_ask en la herramienta potente para que una persona apruebe cada llamada.

La separación usa tres agentes:

Los resultados del agente de obtención se construyen a partir de páginas no confiables, y el agente principal puede transmitir su texto al agente de escritura. Mantén auto o always_ask en las herramientas del agente de escritura. El agente de obtención aún puede enviar parte de lo que lee a los sitios de su lista de web_fetch, y al proveedor de búsqueda en sus consultas.

Los agentes de una misma sesión multiagente comparten el sandbox, sus archivos y las credenciales del vault, así que esta separación solo aísla sus herramientas y conversaciones. Para una separación más fuerte, usa dos sesiones con entornos y vaults separados. Haz que tu aplicación transmita entre las dos sesiones solo campos fijos, como un ID de pedido.

Establece límites y una forma de detenerlo

Establece un presupuesto al crear cada sesión y decide de antemano cómo detendrás a un agente.

Para detener un agente en ejecución, sigue estos pasos:

1. Envía user.interrupt por sí solo.
2. Para un agente programado, pausa también la implementación para que no se inicie ninguna nueva ejecución programada. Para finalizar la programación de forma permanente, archiva la implementación.
3. Si una clave podría estar expuesta, rótala en el servicio que la emitió.
4. Si el agente tiene ejecuciones de flujo de trabajo abiertas, envía también un user.message que le pida detenerlas, porque una interrupción no finaliza ninguna ejecución. Consulta Interrumpir una sesión con ejecuciones abiertas para ver las llamadas a herramientas que debes cancelar primero.
5. Espera a que la sesión pase a idle. Una sesión en ejecución no se puede archivar ni eliminar.
6. Archiva la sesión para conservar su historial. Elimínala cuando ya no necesites el historial.

Una interrupción no deshace lo que el agente ya hizo o envió. Archivar un agente no detiene sus sesiones en ejecución.

El max_list_cost.amount de un presupuesto es un número entero de centavos de dólar estadounidense escrito como cadena, así que "125" significa $1.25. Consulta Establecer un presupuesto al crear la sesión.

No puedes añadir un presupuesto a una sesión creada sin uno. Para cambiar o eliminar un tope, consulta Reanudar una sesión en su presupuesto. Después de eliminar el tope de una sesión, no puedes establecer uno nuevo.

Un presupuesto limita el gasto, pero no limita lo que hace el agente antes de alcanzar el tope. Para mantener separadas las cargas de trabajo con distintos niveles de confianza, usa espacios de trabajo separados. Dale a cada carga de trabajo una clave de API limitada a un solo espacio de trabajo, porque una clave que puede acceder a varios espacios de trabajo puede actuar en cualquiera de ellos.

Consulta Presupuestos de sesión, Operaciones de sesión e Implementaciones programadas.

Próximos pasos