Overview
En este tutorial, aprenderá a controlar el tráfico saliente de su agente declarando la política de salida de red en el archivo del agente y desplegándola. La salida de red le permite gestionar a qué servicios externos puede acceder el entorno de ejecución de su agente, de modo que este permanezca seguro a menos que usted habilite los destinos que necesita.
En el bloque sandboxes de su archivo de agente, define la política de salida para cada entorno aislado (sandbox). Para cada entorno aislado, declara los destinos en network.egress y, opcionalmente, configura el modo de salida mediante network.egress_mode. El despliegue aplica esta política a su espacio de trabajo en ejecución. Para inspeccionar la política desplegada, utilice el comando agentengine egress o la interfaz de usuario de acceso saliente del espacio de trabajo.
Para obtener más información sobre cómo funcionan las políticas de salida de red, consulte la guía "Administrar políticas de salida de red".
Requisitos previos
Antes de comenzar, asegúrese de cumplir con los siguientes requisitos previos:
Tienes instalada la versión 0.1.54-alpha o posterior de la interfaz de línea de comandos (CLI)
agentengine, y está disponible en tu variable de entornoPATH. Para obtener más información, consulta la guía de instalación y autenticación.Puedes autenticarte en la plataforma utilizando el comando
agentengine auth login.Usted tiene el rol de Propietario del Proyecto para implementar el agente y aplicar los cambios en la política de salida.
Para obtener más información sobre roles y permisos, consulte la sección Control de acceso basado en roles de la guía Administrar políticas de salida de red.
Para configurar los secretos que necesita su agente antes de implementarlo, consulte la guía Provision Cloud Secrets.
Configurar la salida en el archivo del agente.
Cada espacio de trabajo se inicia en modo deny_all, lo que restringe el agente a la política base de la plataforma. Antes de la primera implementación, declare una política de salida en el archivo agent.yaml. La implementación requiere que este archivo indique el modo de salida del agente. Siga el siguiente procedimiento para declarar la política de salida que necesita su agente y aplicarla.
Declara los destinos para cada entorno aislado.
Abra su archivo agent.yaml y agregue cada nombre de host al que su agente deba acceder en el campo network.egress del entorno aislado que lo llama, incluyendo el punto final de su proveedor LLM y cualquier API externa a la que llamen sus herramientas. De forma predeterminada, las herramientas se ejecutan en el entorno aislado del agente. Las herramientas que configure para ejecutarse en el entorno aislado de herramientas necesitan que sus hosts estén permitidos allí. El siguiente ejemplo permite un host para el entorno aislado del agente:
sandboxes: agent: network: egress: - fqdn: api.openai.com ports: [443]
El siguiente ejemplo ejecuta la herramienta fetch_github_object en el entorno aislado de la herramienta y permite que solo ese entorno aislado acceda a github.com. La lista tools se encuentra junto al bloque network:
sandboxes: agent: network: egress: - fqdn: api.openai.com ports: [443] tool: network: egress: - fqdn: github.com ports: [22] tools: - fetch_github_object
Si su agente utiliza servidores MCP, agregue también cada nombre de host MCP al campo network.egress del entorno aislado. Incluir un servidor en mcp.servers no habilita automáticamente el acceso saliente.
Establezca la postura de seguridad con network.egress_mode.
Opcionalmente, agregue la clave network.egress_mode a un entorno aislado para elegir cómo se aplican sus destinos. El siguiente ejemplo establece allow_list tanto para el entorno aislado del agente como para el entorno aislado de la herramienta:
sandboxes: agent: network: egress_mode: allow_list egress: - fqdn: api.openai.com ports: [443] tool: network: egress_mode: allow_list egress: - fqdn: api.openai.com ports: [443]
Si omite network.egress_mode, un entorno aislado con destinos utilizará automáticamente allow_list. Para obtener más información sobre los modos posibles, consulte la sección Modos en la guía Administrar políticas de salida de red.
Implementa tu agente.
Implemente el agente para que la política de salida del archivo surta efecto. Los cambios en el archivo del agente no afectarán al espacio de trabajo en ejecución hasta que implemente el agente actualizado. Si su espacio de trabajo tenía anteriormente un modo de salida diferente a través de otra ruta, la plataforma emitirá una advertencia y luego aplicará el archivo. Por ejemplo, si la política anterior está configurada como deny_all y la política actualizada como allow_list, la advertencia será similar a la siguiente:
agent.yaml network.egress_mode applied workspace tool mode: deny_all → allow_list
Verifique la política vigente.
Antes de probar su agente, ejecute el siguiente comando.
agentengine egress
Confirme que ambos entornos de pruebas muestren allow_list y que se incluyan todos los nombres de dominio completamente calificados (FQDN) esperados. Por ejemplo:
[agent] Mode: allow_list FQDN PORTS SOURCE api.openai.com 443 manifest [tool] Mode: allow_list FQDN PORTS SOURCE api.openai.com 443 manifest
Patrones comunes
Las siguientes secciones muestran configuraciones de salida comunes en el archivo del agente. Agregue la sección a su archivo agent.yaml y vuelva a implementar después de cada cambio.
Permitir una API LLM solo para el entorno aislado de herramientas
Agregue el nombre de host de LLM al campo network.egress del entorno aislado de la herramienta. Luego, configure el entorno aislado del agente en deny_all para que solo el entorno aislado de la herramienta pueda acceder a él:
sandboxes: agent: network: egress_mode: deny_all tool: network: egress_mode: allow_list egress: - fqdn: api.openai.com ports: [443]
Permitir una API externa para ambos entornos aislados (sandboxes).
Enumera el nombre de host en ambos entornos aislados para que tanto el entorno aislado del agente como el de la herramienta puedan acceder a él:
sandboxes: agent: network: egress: - fqdn: api.stripe.com ports: [443] tool: network: egress: - fqdn: api.stripe.com ports: [443]
Permitir todo el tráfico saliente
Establezca el valor network.egress_mode de un entorno aislado en allow_all para permitir el acceso saliente abierto para ese entorno aislado:
sandboxes: agent: network: egress_mode: allow_all tool: network: egress_mode: allow_all
No se puede combinar allow_all con una lista de destinos para el mismo entorno aislado.
Deje de permitir un destino
Para impedir el acceso a un destino saliente, elimine el nombre de host del campo network.egress del entorno aislado y vuelva a implementarlo. También puede editar el archivo mediante el comando agentengine agent egress remove, como se muestra en el siguiente ejemplo:
agentengine agent egress remove api.stripe.com
El cambio entrará en vigor en su próximo despliegue.
Bloquear el acceso de salida
Para bloquear toda la salida excepto la política base, configure el network.egress_mode de cada sandbox a deny_all y vuelva a implementar:
sandboxes: agent: network: egress_mode: deny_all tool: network: egress_mode: deny_all
Utilice la interfaz de línea de comandos (CLI) para agregar o eliminar destinos.
Los comandos agentengine agent egress add y agentengine agent egress remove son accesos directos que editan el bloque network.egress de cada entorno aislado en el archivo de agente local. El siguiente ejemplo añade un destino solo para el entorno aislado de la herramienta:
agentengine agent egress add --component tool api.openai.com:443
Estos comandos no actualizan la política en ejecución. Vuelva a implementar el agente para que los cambios surtan efecto.
Solución de problemas
Esta sección proporciona consejos para la resolución de problemas comunes relacionados con la configuración de la salida de red.
Mi agente no puede acceder a un host externo después de agregarlo.
Confirma que has desplegado el agente después de editar el archivo del agente. Los cambios en la política del archivo no se aplicarán hasta que se realice el despliegue.
Ejecute el comando
agentengine egressy confirme que el nombre de host aparece en la lista para el entorno aislado esperado en la política implementada.Confirme que el modo sea
allow_listoallow_all, nodeny_all.Tras la implementación, también puede revisar la configuración mediante la interfaz de usuario de acceso saliente.
El FQDN que quiero es rechazado.
Verifique que el FQDN que desea cumpla con los requisitos. Para obtener más información, consulte la sección Reglas de nombres de dominio completamente calificados (FQDN) de la guía Administrar políticas de salida de red.
Recibo una advertencia cuando agrego un nombre de host de Atlas.
La plataforma acepta nombres de host de clústeres Atlas, como *.mongodb.net, y la advertencia no es bloqueante. La advertencia indica que un destino de salida no configura el acceso a Atlas por sí solo. Para otorgar acceso a su agente a un clúster Atlas, utilice los comandos agentengine atlas o el bloque network.atlas_clusters en su archivo agent.yaml.
Recibo una advertencia cuando omito el puerto.
Un destino sin puerto, o con :*, permite el acceso a todos los puertos desde ese host. La plataforma guarda el destino y devuelve una advertencia no bloqueante. Para eliminar la advertencia, especifique los puertos que necesita el destino, hasta 10 puertos en el rango 1 a 65535.
El destino que indiqué no aparece.
Vuelva a implementar su agente. La plataforma lee los destinos de salida del archivo del agente en el momento de la implementación, no en tiempo de ejecución.