Configuración de red privada para el Servicio de Agente de Foundry

Foundry Agent Service ofrece una configuración estándar con un entorno de red privado. Esta configuración crea un entorno de red aislado que permite el acceso seguro a los datos al tiempo que mantiene el control total sobre la infraestructura de red.

De forma predeterminada, la configuración estándar con redes privadas garantiza:

• Sin salida pública: la infraestructura básica proporciona la autenticación y seguridad adecuadas para los agentes y las herramientas, sin necesidad de omitir servicios de confianza.
• Integración de subred: Usted proporciona una subred delegada de su red virtual. La plataforma conecta el cómputo del agente a esta subred, permitiendo la comunicación local con los recursos de Azure dentro de la misma red virtual.
• Acceso a recursos privados: si los recursos están marcados como privados y no detectables desde Internet, la red de la plataforma todavía puede acceder a ellos cuando estén en vigor las credenciales y la autorización necesarias.

Si no tiene una red virtual existente, la Configuración Estándar con flujo de red privada puede aprovisionar la infraestructura de red necesaria para usted.

Requisitos previos

• Una suscripción Azure: Crear una gratuita.

• Asegúrese de que la persona que crea la cuenta y el proyecto tenga el rol de Propietario de la cuenta de Foundry en el ámbito de la suscripción.

  Importante

  Recientemente se ha cambiado el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

• El usuario que crea esta configuración también debe tener permisos para asignar roles a los recursos necesarios (Azure Cosmos DB, Búsqueda de Azure AI, Azure Storage).

  • El rol integrado necesario es Administrador de acceso basado en roles.
  • Como alternativa, tener el rol Propietario en el nivel de suscripción también satisface este requisito.
  • El permiso de clave necesario es: Microsoft.Authorization/roleAssignments/write

• Python 3.9 o posterior

• Una vez configurado el entorno del agente, asegúrese de que cada miembro del equipo que quiera usar Agent Playground o el SDK para crear o editar agentes tenga asignado el Foundry Userrol integrado de RBAC para el proyecto.

  • El conjunto mínimo de permisos necesarios es: agents/*/read, agents/*/action, agents/*/delete

• Registrar proveedores. Los proveedores siguientes deben registrarse:

  • Microsoft.KeyVault
  • Microsoft.CognitiveServices
  • Microsoft.Storage
  • Microsoft.MachineLearningServices
  • Microsoft.Search
  • Microsoft.Network
  • Microsoft.App
  • Microsoft.ContainerService
  • Para usar la herramienta Bing Search: Microsoft.Bing

     az provider register --namespace 'Microsoft.KeyVault'
     az provider register --namespace 'Microsoft.CognitiveServices'
     az provider register --namespace 'Microsoft.Storage'
     az provider register --namespace 'Microsoft.MachineLearningServices'
     az provider register --namespace 'Microsoft.Search'
     az provider register --namespace 'Microsoft.Network'
     az provider register --namespace 'Microsoft.App'
     az provider register --namespace 'Microsoft.ContainerService'
     # only to use Grounding with Bing Search tool
     az provider register --namespace 'Microsoft.Bing'
  

Configuración de un entorno protegido por red

Puede crear esta configuración en el portal de Azure o implementarla mediante Bicep o Terraform.

En un nivel alto, la implementación implica estos pasos:

1. Elija la región de destino Azure para los recursos de Foundry.
2. Decida si debe traer su propia red virtual y subred o usar redes aprovisionadas automáticamente.
3. Si trae su propia red virtual, recopile los identificadores de recursos de red virtual y subred.
4. Cree la configuración en el portal de Azure o impleméntela mediante Bicep o Terraform.
5. Compruebe la implementación (consulte Comprobación de la implementación).

La configuración aprovisiona los siguientes recursos (a menos que traiga sus propios):

• Una cuenta de Foundry y un proyecto Foundry.
• Despliegue de modelo gpt-4o.
• Azure Storage, Azure Cosmos DB y Búsqueda de Azure AI para almacenar archivos, subprocesos y datos vectoriales.
• Estos recursos están conectados al proyecto.
• Las claves de cifrado administradas por Microsoft para la cuenta de almacenamiento y la cuenta cognitiva (Foundry) se usan de forma predeterminada.

Seleccione el método de implementación preferido mediante las siguientes pestañas:

Comprobación de la implementación

Una vez finalizada la implementación, compruebe que todos los recursos están configurados correctamente:

1. Confirmar delegación de subred: en Azure Portal, vaya a >Subredes de la red virtual y compruebe que la subred del agente muestra la delegación en Microsoft.App/environments.
2. Check public network access: Abra cada recurso (Foundry, Búsqueda de Azure AI, Azure Storage, Azure Cosmos DB) y confirme Public network access está establecido en Disabled.
3. Validar la resolución DNS del punto de conexión privado: desde una máquina conectada a la red virtual, ejecute nslookup en cada punto de conexión que se muestra en el resumen de configuraciones de zona DNS. Compruebe que cada nombre se resuelve en una dirección IP privada (10.x, 172.16-31.x o 192.168.x).
4. Conectividad del agente de prueba: acceda al proyecto foundry desde la red virtual (consulte Acceso a los agentes protegidos) y confirme que puede crear y ejecutar un agente.
5. Configurar asignaciones de roles: ejecute los siguientes comandos para asignar los roles necesarios. La primera concede al operador de identidad administrada la identidad administrada asignada por el usuario y la segunda concede a Colaborador de red en la red virtual remota el acceso entre inquilinos.

az role assignment create \
   --assignee <your-principal-id> \
   --role "Managed Identity Operator" \
   --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<id>"

 az role assignment create \
   --assignee <service-principal-object-id-in-remote-tenant> \
   --role "Network Contributor" \
   --scope "/subscriptions/<remote-subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>"

Limitaciones

• Limitación de direcciones IP de subred: ambas subredes deben tener intervalos IP dentro de intervalos IPv4 privados válidos RFC1918: 10.0.0.0/8, 172.16-31.0.0/12o 192.168.0.0/16. No se admiten intervalos 100.64.0.0100.127.255.255 de direcciones IP públicas y CGNAT.
• Exclusividad de subred del agente: La subred del agente no puede ser compartida por varios recursos de Foundry. Cada recurso Foundry debe usar una subred de agente dedicada.
• Tamaño de la subred del agente: El tamaño recomendado de la subred del agente delegado es /24 (256 direcciones) debido a la delegación de la subred a Microsoft.App/environments. Para obtener más información sobre el ajuste de tamaño de subred, consulte Configuración de redes virtuales para Azure Container Apps.
• Lista de permitidos del firewall de salida de subred del agente: si va a integrar una instancia de Azure Firewall con el agente estándar protegido de red privada, incluya en la lista de permitidos los nombres de dominio completo (FQDN) que aparecen en Identidad administrada en el artículo Integración con Azure Firewall o agregue la etiqueta de servicio AzureActiveDirectory.
  • Compruebe que no se produce ninguna inspección de TLS en el firewall que pueda agregar un certificado autofirmado. Durante las fallas, inspeccione si hay algún flujo de tráfico en el firewall y qué tráfico se está bloqueando.
• El recurso Foundry debe implementarse en la misma región que la red virtual (VNet). Otros recursos de Azure, como Azure Cosmos DB, Búsqueda de Azure AI y Azure Storage, se pueden implementar en diferentes regiones. Tenga en cuenta las implicaciones de costos de las implementaciones entre regiones.
• Disponibilidad de la región:
  • Para ver las regiones admitidas para las implementaciones de modelos, consulte: Compatibilidad de regiones del modelo Azure OpenAI.
  • Para el intervalo IP de red virtual, puede usar cualquier intervalo IP de clase privada A, B o C. Los intervalos de direcciones IP de clase privada A (10.x.x.x) solo se admiten en las siguientes regiones: Este de Australia, Sur de Brasil, Este de Canadá, Este de EE. UU., Este de EE. UU. 2, Centro de Francia, Centro-oeste de Alemania, Norte de Italia, Este de Japón, Norte de Sudáfrica, Centro de Sudáfrica, Centro de España, Norte de Emiratos Árabes Unidos, Sur de Reino Unido, Oeste de EE. UU. 3. Use rangos de clase B (172.16.x.x) o C (192.168.x.x) para otras regiones. No puede usar ningún otro intervalo IP que se superponga a la lista anterior o use intervalos IP públicos.
• Azure Blob Storage: no se admite el uso de archivos Azure Blob Storage con la herramienta Búsqueda de archivos.
• Limitaciones del archivo de intérprete de código: en una configuración de red privada (BYO), el intérprete de código solo funciona en escenarios que no implican cargas o descargas de archivos. La herramienta no puede recuperar archivos de la cuenta de almacenamiento en esta configuración. Si necesita utilizar archivos con Code Interpreter, debe usar el SDK para crear explícitamente un contenedor con los archivos necesarios y, a continuación, pasar el container_id a Code Interpreter. Esta solución alternativa solo está disponible a través del SDK; La interfaz de usuario del portal de Foundry no la admite.
• Conexión con Bing Search: solo se admiten las siguientes regiones: Oeste de Europa, Este de Canadá, Norte de Suiza, Centro de España, Norte de Emiratos Árabes Unidos, Centro de Corea, Centro de Polonia, Sudeste de Asia, Oeste de EE. UU., Oeste de EE. UU. 2, Oeste de EE. UU. 3, Este de EE. UU., Este de EE. UU. 2, Centro de EE. UU., Sur de la India, Este de Japón, Sur de Reino Unido, Centro de Francia, Este de Noruega, Este de Australia, Centro de Canadá, Centro de Suecia, Norte de Sudáfrica, Norte de Italia, Sur de Brasil
• Eliminar inyección de red: si desea eliminar su recurso de Foundry y el agente estándar con la configuración de red segura, elimine su recurso de Foundry y la red virtual en último lugar. Antes de eliminar la red virtual, elimine y purgue el recurso Foundry.
• Inyección de red virtual para agentes hospedados: en el caso de los agentes hospedados, la configuración de la red virtual (inyección de red) debe incluirse cuando se crea la cuenta de Foundry por primera vez. No se puede añadir la inyección de red a una cuenta de Foundry ya existente después de su creación en el caso de los agentes alojados.
• Registro de contenedor del agente hospedado detrás de una red privada: para los agentes hospedados, la compatibilidad con una Azure Container Registry (ACR) detrás de una red privada (punto de conexión privado con acceso a la red pública deshabilitada) depende de cuándo se creó el proyecto Foundry. Los proyectos creados después del 25 de junio de 2026 admiten un ACR privado. Los proyectos creados antes de esa fecha requieren que el ACR sea accesible a través de su punto de conexión público para que la plataforma pueda extraer la imagen. Los proyectos existentes no se ven afectados y siguen usando el acceso a la red pública.
• Superposición de IP: asegúrese de que los espacios de direcciones de la red virtual usada no se superpongan con ninguna red existente en el entorno de Azure o intervalos IP reservados como los siguientes: 169.254.0.0/16, , 172.30.0.0/16172.31.0.0/16192.0.2.0/240.0.0.0/8127.0.0.0/8100.100.0.0/17100.100.192.0/19, , . 100.100.224.0/19100.64.0.0/11 Esto incluye todos los espacios de direcciones que tiene en la red virtual, si tiene más de uno y redes virtuales emparejadas.

Diagrama de arquitectura

Revisión de los recursos de red aprovisionados

Los siguientes recursos se aprovisionan automáticamente cuando se usa el programa de instalación estándar con redes privadas, a menos que traiga sus propios recursos:

Infraestructura de red

• Una red virtual (192.168.0.0/16)
• Subred del agente (192.168.0.0/24): Aloja clientes del agente
• Subred del punto de conexión privado (192.168.1.0/24): Aloja puntos de conexión privados

Funcionalidades de red virtual

La red virtual controla qué puntos de conexión pueden realizar llamadas API a los recursos. El servicio Azure rechaza automáticamente las llamadas API desde dispositivos fuera de la red definida.

Reglas de red

Todas las cuentas y sus proyectos correspondientes están protegidas de forma predeterminada con la marca Acceso a la red pública Deshabilitada , lo que requiere una configuración explícita para permitir el acceso a través de puntos de conexión privados. Estas reglas se aplican a todos los protocolos, incluidos REST y WebSocket.

Resumen de configuraciones de zona DNS

Para crear un reenviador condicional en el servidor DNS al Azure DNS servidor virtual, use la lista de zonas mencionadas en la tabla anterior. La dirección IP del servidor virtual Azure DNS es 168.63.129.16.

Acceso a los agentes protegidos

Una vez completada la implementación, puede acceder al proyecto foundry detrás de una red virtual mediante uno de los métodos siguientes:

• Azure VPN Gateway: conecta redes locales a la red virtual a través de una conexión privada. La conexión se realiza a través de la red pública de Internet. Hay dos tipos de puertas de enlace de VPN que puede usar:
  • Punto a sitio: cada equipo cliente usa un cliente VPN para conectarse a la red virtual.
  • Sitio a sitio: un dispositivo VPN conecta la red virtual a la red local.
• ExpressRoute: conecta redes locales a la nube a través de una conexión privada. La conexión se realiza mediante un proveedor de conectividad.
• Azure Bastion: en este escenario, se crea una máquina virtual Azure (a veces denominada jump box) dentro de la red virtual. Después, se conecta a la máquina virtual mediante Azure Bastion. Bastion permite conectarse a la máquina virtual mediante una sesión RDP o SSH desde el explorador web local. Después, use el jumpbox como entorno de desarrollo. Puesto que está dentro de la red virtual, puede acceder directamente al área de trabajo.

Preguntas más frecuentes

¿Qué intervalo de direcciones debo usar para la red virtual global?

El intervalo de direcciones de red virtual puede ser cualquier intervalo IP privado que deje suficiente espacio de direcciones para la subred del agente delegado y la subred del punto de conexión privado.

¿Puedo usar redes virtuales emparejadas o colocar recursos en diferentes redes virtuales?

Se admiten redes virtuales emparejadas, pero los costos de transferencia de datos pueden aumentar.

¿Pueden varios recursos de Foundry reutilizar la misma red virtual y subred?

Sí, la misma red virtual, pero no la misma subred. Varios recursos de Foundry pueden reutilizar la misma red virtual. Sin embargo, cada recurso de Foundry requiere una subred dedicada exclusivamente al tiempo de ejecución del agente. La subred del agente no se puede compartir entre varios recursos de Foundry.

¿Es necesario que la red virtual esté en el mismo grupo de recursos que el recurso Foundry?

No. No es necesario que la red virtual y el recurso Foundry estén en el mismo grupo de recursos, pero deben estar en la misma región.

Guía de solución de problemas

Consulte esta guía para resolver errores durante o después de una implementación del agente estándar, tanto si ha usado el portal de Azure, Bicep o Terraform.

Errores de implementación

"CreateCapabilityHostRequestDto is invalid: Agents CapabilityHost supports a single, non empty value for vectorStoreConnections property."

"Agents CapabilityHost supports a single, non empty value for storageConnections property."

"Agents CapabilityHost supports a single, non empty value for threadStorageConnections property."

Solución: Para proporcionar todas las conexiones a los recursos "Bring-your-Own" (BYO), es necesario establecer conexiones con todos los recursos BYO. No se puede crear un agente estándar protegido en Foundry sin los tres recursos proporcionados.

"Provided subnet must be of the proper address space. Please provide a subnet which has address space in the range of 172 or 192."

Solución: no está usando un intervalo IP adecuado para la subred del agente delegado. Compruebe que usa un espacio de direcciones IP privada válido. Los intervalos de RFC1918 válidos incluyen 10.0.0.0/8, 172.16-31.0.0/12y 192.168.0.0/16. Es posible que el texto del mensaje de error no muestre todos los intervalos válidos.

"Subscripton is not registered with the required resource providers, please register with the resource providers Microsoft.App and Microsoft.ContainerService."

Solución: falta el registro de recursos correcto. Asegúrese de que los recursos necesarios están registrados en el inquilino.

"Failed to create Aml RP virtual workspace due to System.Exception: Failed async operation." o "The resource operation completed with terminal provisioning state 'Failed'. Capability host operation failed."

Solución: se trata de un error genérico. Cree una solicitud de incidencia de soporte técnico para investigar la configuración. Revise el host de capacidad en busca de un error.

"Subnet requires any of the following delegation(s) [Microsoft.App/environments] to reference service association link /subscriptions/11111-aaaaa-2222-bbbb-333333333/resourceGroups/agentRANGEChange/providers/Microsoft.Network/virtualNetworks/my-agent-vnet/subnets/agent-subnet/serviceAssociationLinks/legionservicelink."

Solution: este error aparece al intentar eliminar la configuración de la plantilla estándar protegida en Azure y no eliminó correctamente todos los recursos. Una solución consiste en ir a la página de recursos de Foundry en el portal de Azure y seleccionar Administrar recursos eliminados. Desde allí, purgue el recurso al que estaba asociado el agente para esta red virtual. La otra opción es ejecutar el deleteCaphost.sh script en la plantilla estándar protegida.

"Timeout of 60000ms exceeded" error when loading the Agent pages in the Foundry project

Solution: El proyecto Foundry tiene problemas para comunicarse con Azure Cosmos DB para crear agentes. Compruebe la conectividad con Azure Cosmos DB (punto de conexión privado y DNS).

Error en la resolución DNS del punto de conexión privado

Solución: si los recursos no son accesibles a través de puntos de conexión privados, compruebe que cada zona DNS privada esté vinculada a la red virtual. Confirme que los reenviadores condicionales apunten a la dirección IP del servidor virtual de Azure DNS 168.63.129.16. Desde una máquina conectada a la red virtual, ejecute nslookup <resource-fqdn> y compruebe que cada nombre se resuelve en una dirección IP privada.

Pasos siguientes

Ahora ha configurado correctamente una cuenta y un proyecto seguros de red. Use el inicio rápido para crear el primer agente.

Para más información sobre la configuración y las opciones de aislamiento de red, consulte Configuración del aislamiento de red.

Muchos entornos empresariales requieren que Foundry, el registro de contenedor y los servicios dependientes, como Application Insights y Storage, solo sean accesibles desde una red privada. En esta sección se explica cómo aprovisionar e implementar azd agentes hospedados cuyas dependencias se encuentran detrás de puntos de conexión privados en una red virtual (VNet).

La integración de la VNet se logra personalizando las plantillas de Bicep generadas infra/ y ejecutando azd desde dentro de la VNet o con acceso a ella.

Requisitos previos

• Un proyecto de agente alojado inicializado. Para crear uno, consulte Inicialización de un proyecto de agente hospedado con la CLI para desarrolladores de Azure.
• Se instalaron las extensiones Foundry de Azure Developer CLI.
• Una red virtual (nueva o existente) y permiso para crear puntos de conexión privados y zonas DNS privadas.
• Familiaridad con Bicep con estructura base generada. Consulte la infraestructura de agentes hospedados con la CLI para desarrolladores de Azure.

¿Qué significa la protección de red virtual para una implementación azd?

Un proyecto de agente hospedado aprovisiona varios recursos de Azure. Puede deshabilitar el acceso a la red pública en cada uno de ellos y colocar un punto de conexión privado en la red virtual.

Si necesita que el endpoint del agente sea privado, es una funcionalidad de la plataforma que actualmente queda fuera del alcance de esta extensión.

Qué hace y qué no hace la extensión

Decidir la topología

La mayoría de las implementaciones protegidas con red virtual se dividen en una de estas formas. Elija uno antes de editar Bicep:

• Greenfield, todo dentro de una nueva red virtual. Ejecute azd ai agent init, luego añada módulos de punto de conexión privado a la estructura generada infra/. Puede aprovisionar tanto la red virtual como los recursos en una sola ejecución de Bicep.
• Brownfield, conéctese a una red virtual existente. Igual que el enfoque de campo verde, pero se hace referencia a la red virtual existente a través de parámetros en lugar de crear una. Esto resulta útil cuando un equipo diferente posee redes.
• Reutilizar todos los recursos existentes. Un equipo de plataforma aprovisionó previamente la cuenta de Foundry, ACR y Application Insights en puntos de conexión privados. Solo tiene que aportar la definición del agente y hacer que las variables de entorno apunten a los recursos existentes. main.bicep crea solo lo que falta.

Las topologías 2 y 3 son las más comunes en las empresas reguladas. La topología 1 es adecuada para pilotos autónomos.

Personalización del Bicep con scaffolding

El directorio infra/ generado por azd ai agent init es Bicep estándar azd. Es suyo, y los cambios persisten entre despliegues. Las plantillas predeterminadas crean recursos públicos, por lo que debe reemplazarlos o aumentarlos para agregar puntos de conexión privados.

Adición de parámetros de red virtual y subred

Agregue parámetros a infra/main.bicep y guárdelos en infra/main.parameters.json:

// infra/main.bicep (excerpt)

@description('Resource ID of the existing virtual network. If empty, a new VNet is created.')
param vnetResourceId string = ''

@description('Name of the subnet hosting private endpoints.')
param privateEndpointSubnetName string = 'snet-pe'

@description('Disable public network access on data-plane resources.')
param disablePublicNetworkAccess bool = true

// infra/main.parameters.json (excerpt)
{
  "vnetResourceId":              { "value": "${AZURE_VNET_RESOURCE_ID=}" },
  "privateEndpointSubnetName":   { "value": "${AZURE_PE_SUBNET_NAME=snet-pe}" },
  "disablePublicNetworkAccess":  { "value": "${DISABLE_PUBLIC_NETWORK=true}" }
}

Establezca las variables de entorno antes de azd provision:

azd env set AZURE_VNET_RESOURCE_ID \
  /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>
azd env set AZURE_PE_SUBNET_NAME snet-pe
azd env set DISABLE_PUBLIC_NETWORK true

Bloqueo de cada recurso

Para cada recurso, las plantillas crean, establecen publicNetworkAccess: 'Disabled' y agregan un módulo de punto de conexión privado. El siguiente patrón es ilustrativo. Adapte los tipos de recursos y las zonas DNS al entorno.

// infra/core/ai/account.bicep (excerpt)
resource aiAccount 'Microsoft.CognitiveServices/accounts@2024-10-01' = {
  // ...existing properties...
  properties: {
    // ...existing properties...
    publicNetworkAccess: disablePublicNetworkAccess ? 'Disabled' : 'Enabled'
    networkAcls: {
      defaultAction: disablePublicNetworkAccess ? 'Deny' : 'Allow'
    }
  }
}

Agregue un módulo de punto de conexión privado que conecte la cuenta a la red virtual:

module aiAccountPrivateEndpoint '../network/private-endpoint.bicep' = if (disablePublicNetworkAccess) {
  name: 'pe-ai-account'
  params: {
    name: 'pe-${aiAccount.name}'
    location: location
    subnetId: '${vnetResourceId}/subnets/${privateEndpointSubnetName}'
    privateLinkServiceId: aiAccount.id
    groupId: 'account'
    privateDnsZoneId: privateDnsZones.cognitiveServices
  }
}

Repita este patrón para los recursos que desea que sean privados:

• Cuenta de AI Services: ID de grupo account. Las zonas DNS incluyen privatelink.cognitiveservices.azure.com, privatelink.openai.azure.comy privatelink.services.ai.azure.com, en función del plano de datos.
• Container Registry: ID de grupo registry. Zona DNSprivatelink.azurecr.io. Agrega un punto de conexión de datos por región.
• Application Insights: a través de un ámbito de Private Link de Azure Monitor. Las zonas DNS incluyen privatelink.monitor.azure.com, privatelink.ods.opinsights.azure.com, privatelink.oms.opinsights.azure.comy privatelink.agentsvc.azure-automation.net.
• Cuenta de almacenamiento: identificadores blobde grupo, file, queue, y table según sea necesario. Zonas DNS por servicio, por ejemplo privatelink.blob.core.windows.net.

El repositorio azd-ai-starter-basic, que la extensión del agente usa como plantilla, es una referencia útil de lo que se crea por defecto. Aumente esos módulos en lugar de reemplazarlos.

Aprovisionamiento de los recursos

azd provision

Después del aprovisionamiento, solo se puede acceder a cada dependencia de su lista a través de su punto de conexión privado. La resolución DNS pública sigue devolviendo el nombre de host público, pero las zonas DNS privadas lo sobrescriben dentro de la red virtual.

Ejecute azd up desde dentro de la red virtual.

Después de deshabilitar el acceso a la red pública, no se puede ejecutar azd up ni azd deploy desde una estación de trabajo pública de Internet. Se puede acceder al plano de control de ARM, pero las llamadas del plano de datos a Foundry y las operaciones push a ACR fallan con errores 403 o de conexión rechazada. Use uno de los siguientes patrones.

Ejecutor de Acciones de GitHub autohospedado

Aprovisione una máquina virtual del ejecutor o un ejecutor hospedado en AKS en una subred de la misma red virtual. Dirija el flujo de trabajo a ese ejecutor con runs-on: [self-hosted, agent-vnet]. Cada azd ai paso resuelve correctamente los nombres DNS privados y, a continuación, se enruta a través del punto de conexión privado.

jobs:
  deploy:
    runs-on: [self-hosted, agent-vnet]
    steps:
      - uses: actions/checkout@v4
      - uses: Azure/setup-azd@v2
      - run: azd ext install microsoft.foundry
      - run: azd auth login --client-id ${{ secrets.AZURE_CLIENT_ID }} \
          --federated-credential-provider github \
          --tenant-id ${{ secrets.AZURE_TENANT_ID }}
      - run: azd up --no-prompt

agente autohospedado de Azure DevOps

Use el mismo patrón para Azure DevOps. Instale el agente en una subred de una VNet y aplíquele la directiva pool: name: agent-vnet. La azd CLI y la extensión Foundry se ejecutan sin cambios.

Bastion o jump host para ejecuciones puntuales

En el caso de las ejecuciones ad hoc, como la respuesta manual a incidentes o una implementación fuera del ciclo, conéctese a través de Azure Bastion a un host de salto dentro de la red virtual, instale azd y las extensiones allí y ejecute azd desde ese host. Mantenga el servidor bastión al mínimo. La respuesta a largo plazo es CI.

Desarrolla localmente con un endpoint privado de Foundry

El desarrollo local (azd ai agent run y azd ai agent invoke) se comunica con el proceso del agente local mediante la interfaz de loopback y con el plano de datos de Foundry para herramientas, modelos y sesiones durante invoke. Cuando el punto de conexión de Foundry solo es accesible desde la red virtual, necesita tener conectividad de red desde el equipo de desarrollo. Entre las opciones se incluyen:

• Una VPN de punto a sitio o siempre activa que te sitúa en el entorno DNS de la VNet.
• Azure Bastion para una máquina virtual de desarrollo dentro de la red virtual. Ejecuta azd ai agent run en esa máquina virtual y redirige los puertos 8088 y 8087 para el inspector a través del túnel de Bastion.
• Una estación de trabajo de la red corporativa con una ruta de ExpressRoute o de VNet de concentrador a la red virtual periférica que aloja los puntos de conexión privados.

La FOUNDRY_PROJECT_ENDPOINT resolución no cambia. El valor sigue viniendo del entorno azd activo o de la configuración global. Lo que importa es que DNS resuelva el extremo a la dirección IP privada en lugar de a la pública.

Combinar con un ACR privado

Si tanto el punto de conexión de Foundry como el ACR están en puntos de conexión privados en la misma red virtual, haga lo siguiente:

1. Ejecute azd up desde dentro de la red virtual.
2. Configure AZURE_CONTAINER_REGISTRY_ENDPOINT y AZURE_CONTAINER_REGISTRY_RESOURCE_ID para que apunten al ACR privado existente, de modo que Bicep omita la creación de un nuevo ACR público.
3. Asegúrese de que la identidad del agente tenga asignado el rol AcrPull en el registro. azd deploy controla esto automáticamente después de crear la identidad del agente.

Para obtener detalles específicos del Registro, consulte Implementación de un agente hospedado con un Azure Container Registry privado.

Diagnóstico de problemas de red

• azd ai agent doctor ejecuta comprobaciones de disponibilidad de red en el plano de datos Foundry. Desde dentro de la red virtual, se pasan las comprobaciones. Desde fuera, fallan claramente. Use --local-only para omitir las comprobaciones remotas al depurar problemas que no son de red.
• azd ai agent invoke --output raw "ping" volca la respuesta HTTP completa. Un error de conexión rechazada o de host inexistente aquí es un problema de DNS o de enrutamiento, no un problema de autenticación.
• En el caso de los errores al hacer push en ACR, la CLI emite un comando az role assignment create listo para pegar cuando la causa es la falta de un rol y no un problema de red.

Restricciones conocidas

• No hay ninguna marca de la CLI de primera clase. Toda la configuración de la VNet requiere personalización manual en Bicep, además de disciplina operativa para la ubicación del runner, el DNS y el RBAC.
• El punto de conexión del agente permanece público en esta versión preliminar. El aislamiento de inquilinos en un punto de conexión público se realiza con claves de aislamiento, no con privacidad de red.
• Se aplican restricciones de región. Los agentes hospedados están disponibles en un conjunto fijo de regiones. La VNet, ACR y la cuenta de Foundry deben estar en una de esas regiones o tener emparejamiento con una de ellas. Ejecute azd ai agent doctor para validar.
• DNS es el modo de error más común. Confirme la resolución DNS privada de un extremo a otro, por ejemplo, con nslookup <endpoint> desde el ejecutor o la máquina virtual de desarrollo, antes de suponer que el problema es RBAC.

Contenido relacionado

• Implementación de un agente hospedado con un Azure Container Registry privado
• Pasar claves de aislamiento a un agente hospedado
• Infraestructura de agente hospedada con la CLI para desarrolladores de Azure
• Diagnostica un proyecto con agent doctor