Configurar a rede privada para o Serviço do Foundry Agent

Para obter informações detalhadas sobre a arquitetura de rede, o dimensionamento de sub-rede e o modelo de alocação de IP por trás dessas etapas, consulte Aprofundamento na rede do Serviço do Foundry Agent.

Este artigo descreve duas abordagens. Use a abordagem Portal ou modelos para provisionar um ambiente do Foundry protegido por rede com Bicep ou Terraform. Use a abordagem Azure Developer CLI para colocar as dependências de um projeto de agente azd hospedado atrás de pontos de extremidade privados. Escolha um método com o seletor.

O Serviço do Foundry Agent oferece uma Instalação Padrão com ambiente de rede privada . Essa configuração cria um ambiente de rede isolado que permite acesso seguro aos dados, mantendo o controle total sobre sua infraestrutura de rede.

Por padrão, a Instalação Padrão com rede privada garante:

  • Sem saída pública: a infraestrutura básica fornece a autenticação e a segurança adequadas para os agentes e as ferramentas, sem exigir o desvio de serviços confiáveis.
  • Integração de sub-rede: você fornece uma sub-rede delegada de sua rede virtual. A plataforma conecta a computação do agente a essa sub-rede, permitindo a comunicação local com seus recursos Azure na mesma rede virtual.
  • Acesso a recursos privados: se seus recursos forem marcados como privados e não verificáveis pela Internet, a rede da plataforma ainda poderá acessá-los quando as credenciais e a autorização necessárias estiverem em vigor.

Se você não tiver uma rede virtual existente, a Instalação Padrão com fluxo de rede privada poderá provisionar a infraestrutura de rede necessária para você.

Pré-requisitos

  • Uma assinatura Azure – Criar uma gratuitamente.

  • Verifique se quem cria a conta e o projeto tem a função Responsável pela conta da Foundry no escopo da assinatura.

    Importante

    As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

  • O usuário que cria essa configuração também deve ter permissões para atribuir funções a recursos necessários (Azure Cosmos DB, Pesquisa de IA do Azure  Armazenamento do Azure).

    • A função interna necessária é o Administrador de Acesso Baseado em Função.
    • Como alternativa, ter a função Proprietário no nível da assinatura também atende a esse requisito.
    • A permissão de chave necessária é: Microsoft.Authorization/roleAssignments/write

  • Python 3.9 ou posterior

  • Depois que o ambiente de agente estiver configurado, verifique se a cada membro da equipe que deseja usar o Agent Playground ou o SDK para criar ou editar agentes foi atribuída a função interna de RBAC Usuário do Foundry para o projeto.

    • O conjunto mínimo de permissões necessário é: agents/*/read, agents/*/action, agents/*/delete

  • Registre provedores. Os seguintes provedores devem ser registrados:

    • Microsoft.KeyVault
    • Microsoft.CognitiveServices
    • Microsoft.Storage
    • Microsoft.MachineLearningServices
    • Microsoft.Search
    • Microsoft.Network
    • Microsoft.App
    • Microsoft.ContainerService
    • Para usar a ferramenta pesquisa do Bing: 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'

Importante

As configurações padrão exigem que você traga seus próprios recursos (BYO) para que todos os dados do agente permaneçam no seu locatário Azure.

Os recursos BYO incluem: Armazenamento do Azure, Pesquisa de IA do Azure  e Azure Cosmos DB.

Todos os dados processados pelo Serviço do Foundry Agent são armazenados automaticamente em repouso nesses recursos, ajudando você a atender aos requisitos de conformidade e aos padrões de segurança da empresa.

Configurar um ambiente protegido pela rede

Você pode criar essa configuração no portal Azure ou implantá-la usando Bicep ou Terraform.

Em um alto nível, a implantação envolve estas etapas:

  1. Escolha a região de destino Azure para seus recursos do Foundry.
  2. Decida se deseja trazer sua própria VNet e sub-rede ou utilizar a rede provisionada automaticamente.
  3. Se você trouxer sua própria VNet, reúna as IDs dos recursos da VNet e da sub-rede.
  4. Crie a configuração no portal Azure ou implante-a usando Bicep ou Terraform.
  5. Verifique a implantação (consulte Verificar a implantação).

A instalação provisiona os seguintes recursos (a menos que você traga seus próprios):

  • Uma conta do Foundry e um projeto do Foundry.
  • Uma implantação de modelo gpt-4o.
  • Armazenamento do Azure, Azure Cosmos DB e Pesquisa de IA do Azure  para armazenar arquivos, threads e dados de vetor.
  • Esses recursos estão conectados ao seu projeto.
  • Chaves de criptografia gerenciadas pela Microsoft para a Conta de Armazenamento e a Conta Cognitiva (Foundry) são usadas por padrão.

Selecione seu método de implantação preferencial usando as seguintes guias:

  1. No portal Azure, pesquise Foundry e selecione Criar um recurso.
  2. Depois de configurar a guia Noções básicas , selecione a guia Armazenamento e selecione Selecionar recursos no serviço agente.
    • Selecione ou crie uma conta de Armazenamento, um recurso do Pesquisa de IA do Azure  e um recurso do Azure Cosmos DB. Se você estiver usando a injeção de rede virtual, deverá trazer seus próprios recursos de Armazenamento, Pesquisa de IA do Azure  e Azure Cosmos DB para criar um Agente Standard com isolamento de rede virtual de ponta a ponta.
  3. Depois de configurar a guia Armazenamento , selecione a guia Rede e, em seguida, selecione a opção Desabilitada para acesso público.
  4. Na seção ponto de extremidade privado, selecione + Adicionar ponto de extremidade privado.
  5. Ao preencher os formulários para criar um ponto de extremidade privado, não se esqueça de:
    • No Básico, selecione a mesma Região que sua rede virtual.
    • No formulário Rede Virtual, selecione o virtual network e a sub-rede aos quais você deseja se conectar.

    Nota

    Na interface de usuário do portal, o destino para o qual você cria o ponto de extremidade privado deve ser rotulado como uma "conta". Selecione o recurso Foundry quando solicitado.

  6. Após configurar seu ponto de extremidade privado de entrada, um novo menu suspenso aparece para configurar a Injeção de rede virtual. Selecione sua rede virtual no primeiro menu suspenso e, em seguida, selecione sua sub-rede que está delegada a Microsoft.App/environments com um tamanho de sub-rede de /27 ou maior. Essa delegação e o tamanho da sub-rede são necessários para o processo de injeção.
  7. Continue através dos formulários para criar o projeto. Ao acessar a guia Examinar + criar , examine suas configurações e selecione Criar para criar o projeto.
  8. Continue com as verificações em Verificar a implantação.

Nota

Os pontos de extremidade privados para a Pesquisa de IA do Azure, o Armazenamento do Azure e o Azure Cosmos DB NÃO são criados automaticamente quando você implanta o recurso do Foundry. Certifique-se de criar endpoints privados para esses recursos separadamente em suas páginas de recursos no portal Azure.

Verificar a implantação

Após a conclusão da implantação, verifique se todos os recursos estão configurados corretamente:

  1. Confirme a delegação da sub-rede: no portal do Azure, navegue até suas >sub-redes VNet e verifique se a sub-rede do agente mostra delegação para Microsoft.App/environments.
  2. Verifique o acesso à rede pública: Abra cada recurso (Foundry, Pesquisa de IA do Azure , Armazenamento do Azure, Azure Cosmos DB) e confirme que o acesso à rede pública está configurado como Desativado.
  3. Valide a resolução DNS do ponto de extremidade privado: em uma máquina conectada à VNet, execute nslookup em cada ponto de extremidade listado no resumo das configurações de zona DNS.
  4. Conectividade do agente de teste: acesse o projeto foundry de dentro da VNet (consulte Acessar seus agentes protegidos) e confirme se você pode criar e executar um agente.
  5. Configurar atribuições de função: execute os seguintes comandos para atribuir as funções necessárias. A primeira concede a função de Operador de Identidade Gerenciada na identidade gerenciada atribuída ao usuário, e a segunda concede o papel de Colaborador de Rede na VNet remota para acesso entre locatários.
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>"

Limitações

  • Limitação de endereços IP da VNET e da sub-rede:
    • Sua sub-rede delegada do serviço de agente deve ter intervalos de IP dentro de intervalos IPv4 privados válidos RFC1918: 10.0.0.0/8, 172.16-31.0.0/12ou 192.168.0.0/16 também conhecidos como intervalos ip da classe A, classe B e Classe C.
    • Os intervalos de endereços IP da Classe A privada (10.0.0.0/8) só têm suporte em regiões específicas. Para obter a lista de regiões que dão suporte a intervalos de Classe A, consulte regiões com suporte. Use faixas de Classe B (172.16.x.x) ou Classe C (192.168.x.x) para implantar o serviço Agent em outras regiões.
    • Intervalos de IP públicos, como 44.x.x.x, e intervalos de endereços CGNAT 100.64.0.0–100.127.255.255 não têm suporte em sub-rede delegada para o serviço de agente.
    • Verifique se os espaços de endereço da VNET não se sobrepõem a nenhuma rede existente em seu ambiente Azure ou intervalos de IP reservados, como os seguintes: 169.254.0.0/16, , , 172.30.0.0/16, 172.31.0.0/16, 192.0.2.0/24, 0.0.0.0/8, 127.0.0.0/8, 100.100.0.0/17, 100.100.192.0/19, 100.100.224.0/19. 100.64.0.0/11 Este requisito inclui todos os espaços de endereço da sua VNET e, se você tiver mais de uma, também as VNETs emparelhadas.
  • Exclusividade da sub-rede do agente: a sub-rede do agente não pode ser compartilhada por vários recursos do Foundry. Cada recurso do Foundry deve usar uma sub-rede de agente dedicada.
  • Tamanho da sub-rede do Agente: o tamanho recomendado da sub-rede do Agente é /24 (256 endereços) devido à delegação da sub-rede para Microsoft.App/environments. Para obter mais informações sobre o dimensionamento de sub-rede, consulte Configurando redes virtuais para Aplicativos de Contêiner do Azure.
  • Lista de permissões de saída da sub-rede do agente: se você estiver integrando um Firewall do Azure ao seu agente padrão protegido por rede privada, inclua na lista de permissões os nomes de domínio totalmente qualificados (FQDNs) listados em Identidade gerenciada no artigo Integrar-se com o Firewall do Azure ou adicione a marca de serviço AzureActiveDirectory.
    • Verifique se nenhuma inspeção TLS ocorre no Firewall que pode adicionar um certificado autoassinado. Durante as falhas, inspecione se há algum tráfego aterrissando no Firewall e qual tráfego está sendo bloqueado.
    • Para implantações de agentes de código-fonte, permita também os endpoints de implantação listados em Requisitos de firewall para redes virtuais privadas.
  • O recurso Foundry deve ser implantado na mesma região que a VNet (rede virtual). Outros recursos Azure, como Azure Cosmos DB, Pesquisa de IA do Azure  e Armazenamento do Azure, podem ser implantados em regiões diferentes. Considere as implicações de custo das implantações entre regiões.
  • Disponibilidade da região:
  • Armazenamento de Blobs do Azure: não há suporte para o uso de arquivos Armazenamento de Blobs do Azure com a ferramenta pesquisa de arquivos.
  • Limitações de arquivo do Interpretador de Código: em uma configuração BYO (rede privada), o Interpretador de Código só funciona em cenários que não envolvem uploads ou downloads de arquivos. A ferramenta não pode recuperar arquivos da conta de armazenamento nesta configuração. Se você precisar usar arquivos com o Interpretador de Código, deverá usar o SDK para criar explicitamente um contêiner com os arquivos necessários e, em seguida, passar o container_id para o Interpretador de Código. Essa solução alternativa só está disponível por meio do SDK; A interface do usuário do portal do Foundry não dá suporte a ela.
  • Integração com a Pesquisa do Bing: somente as seguintes regiões são suportadas: Europa Ocidental, Canadá Oriental, Norte da Suíça, Centro da Espanha, Norte dos EAU, Coreia Central, Polônia Central, Sudeste da Ásia, Oeste dos EUA, Oeste dos EUA 2, Oeste dos EUA 3, Leste dos EUA, Leste dos EUA 2, Centro dos EUA, Sul da Índia, Leste do Japão, Sul do Reino Unido, França Central, Leste da Noruega, Leste da Austrália, Canadá Central, Suécia Central, Norte da África do Sul, Norte da Itália, Sul do Brasil
  • Excluir injeção de rede: se você quiser excluir o recurso do Foundry e o Agente Standard com a configuração de rede protegida, exclua o recurso do Foundry e a rede virtual por último. Antes de excluir a rede virtual, exclua e limpe o recurso foundry.
  • Injeção de rede virtual do agente hospedado: para agentes hospedados, a configuração de rede virtual (injeção de rede) deve ser incluída quando você cria a conta do Foundry pela primeira vez. Não há suporte para a adição de injeção de rede a uma conta do Foundry existente após a criação para agentes hospedados.
  • Registro de contêiner de agente hospedado atrás de uma rede privada: Para agentes hospedados, o suporte a um Registro de Contêiner do Azure (ACR) atrás de uma rede privada (ponto de extremidade privado com acesso à rede pública desativado) depende de quando o projeto Foundry foi criado. Os projetos criados após 25 de junho de 2026 dão suporte a um ACR privado. Projetos criados antes dessa data exigem que o ACR possa ser acessado por meio de seu ponto de extremidade público para que a plataforma possa extrair a imagem. Os projetos existentes não são afetados e continuam a usar o acesso à rede pública.

Diagrama de arquitetura

Diagrama mostrando a arquitetura de rede virtual para a rede privada do Foundry Agent Service, incluindo a sub-rede do agente, a sub-rede de endpoint privado e as zonas DNS privadas.

Examinar os recursos de rede provisionados

Os recursos a seguir são provisionados automaticamente quando você usa a Instalação Padrão com rede privada, a menos que você traga o seu próprio:

Infraestrutura de rede

  • Uma rede virtual (192.168.0.0/16)
  • Sub-rede do agente (192.168.0.0/24): hospeda o cliente do agente
  • Sub-rede do ponto de extremidade privado (192.168.1.0/24): hospeda os pontos de extremidade privados

Recursos de rede virtual

Sua rede virtual controla quais endpoints podem fazer chamadas de API para seus recursos. O serviço Azure rejeita automaticamente chamadas de API de dispositivos fora da rede definida.

Regras de rede

Todas as contas e seus projetos correspondentes são protegidos por padrão com o indicador Acesso à rede pública Desativado, exigindo uma configuração explícita para permitir o acesso por meio de endpoints privados. Essas regras se aplicam a todos os protocolos, incluindo REST e WebSocket.

Resumo das configurações de zona DNS

Tipo de recurso "Link Privado" Sub-recurso Nome da zona DNS privado Encaminhadores de zona DNS públicos
Foundry conta privatelink.cognitiveservices.azure.com
privatelink.openai.azure.com
privatelink.services.ai.azure.com		 cognitiveservices.azure.com
openai.azure.com
services.ai.azure.com
Pesquisa de IA do Azure  searchService privatelink.search.windows.net search.windows.net
Azure Cosmos DB Sql privatelink.documents.azure.com documents.azure.com
Armazenamento do Azure blob privatelink.blob.core.windows.net blob.core.windows.net

Para criar um encaminhador condicional no servidor DNS para o servidor virtual DNS do Azure, use a lista de zonas mencionadas na tabela acima. O endereço IP do servidor virtual DNS do Azure é 168.63.129.16.

Acessar seus agentes protegidos

Depois que a implantação for concluída, você poderá acessar seu projeto do Foundry por trás de uma rede virtual usando um dos seguintes métodos:

  • Gateway de VPN do Azure: conecta redes locais à rede virtual por meio de uma conexão privada. A conexão é feita pela Internet pública. Há dois tipos de gateways de VPN que você pode usar:
    • Ponto a site: cada computador cliente usa um cliente VPN para se conectar à rede virtual.
    • Site a site: um dispositivo VPN conecta a rede virtual à sua rede local.
  • ExpressRoute: conecta redes locais à nuvem por meio de uma conexão privada. A conexão é feita usando um provedor de conectividade.
  • Azure Bastion: nesse cenário, você cria uma máquina virtual Azure (às vezes chamada de jump box) dentro da rede virtual. Em seguida, você se conecta à VM usando Azure Bastion. O Bastion permite que você se conecte à VM usando uma sessão RDP ou SSH do navegador da Web local. Em seguida, utilize o jump box como ambiente de desenvolvimento. Como ele está dentro da rede virtual, ele pode acessar diretamente o espaço de trabalho.

perguntas frequentes

Qual intervalo de endereços devo usar para a rede virtual geral?

O intervalo de endereços de rede virtual pode ser qualquer intervalo de IP privado que deixe espaço de endereço suficiente para a sub-rede do agente delegado e a sub-rede do ponto de extremidade privado.

Posso usar redes virtuais emparelhadas ou colocar recursos em redes virtuais diferentes?

Há suporte para redes virtuais emparelhadas, mas os custos de transferência de dados podem aumentar.

Vários recursos do Foundry podem reutilizar a mesma rede virtual e sub-rede?

Sim, a mesma VNET, mas não a mesma sub-rede. Vários recursos do Foundry podem reutilizar a mesma rede virtual. No entanto, cada recurso do Foundry requer uma sub-rede exclusiva para tempo de execução do agente. A sub-rede do agente não pode ser compartilhada entre vários recursos do Foundry.

A rede virtual precisa estar no mesmo grupo de recursos que o recurso Foundry?

Não. A rede virtual e o recurso Foundry não precisam estar no mesmo grupo de recursos, mas devem estar na mesma região.

Guia de solução de problemas

Consulte este guia para resolver erros durante ou após uma implantação do Standard Agent, se você usou o portal Azure, Bicep ou Terraform.

Erros de implantação

"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."

Solução: Fornecer todas as conexões a todos os recursos "Traga seu próprio equipamento" (BYO, na sigla em inglês) requer conexões a todos os recursos BYO. Você não pode criar um agente padrão seguro no Foundry sem os três recursos fornecidos.

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

Solução: você não está usando um intervalo de IP adequado para a sub-rede do agente delegado. Verifique se você está usando um espaço de endereço IP privado válido. Os intervalos de RFC1918 válidos incluem 10.0.0.0/8, 172.16-31.0.0/12e 192.168.0.0/16. Mais detalhes estão em limitações acima.

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

Solução: você está deixando de fazer o correto registro do recurso. Verifique se os recursos necessários estão registrados em seu locatário.

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

Solução: este é um erro abrangente. Crie um chamado de suporte para investigar seu sistema. Verifique o host de capacidade para o erro.

"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: esse erro aparece quando você tenta excluir a configuração de modelo padrão protegida no Azure e não excluiu corretamente todos os recursos. Uma solução é navegar até a página de recursos do Foundry no portal do Azure e selecionar Manage recursos excluídos. A partir daí, limpe o recurso ao qual o agente estava associado para essa rede virtual. A outra opção é executar o deleteCaphost.sh script no modelo padrão protegido.

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

Solução: O projeto Foundry tem problemas para se comunicar com Azure Cosmos DB para criar Agentes. Verifique a conectividade com o Azure Cosmos DB (endpoint privado e DNS).

Falha na resolução de DNS do ponto de extremidade privado

Solução: se os recursos não estiverem acessíveis por meio de pontos de extremidade privados, verifique se cada zona DNS privada está vinculada à sua rede virtual. Confirme se os encaminhadores condicionais apontam para o endereço IP do servidor virtual DNS do Azure 168.63.129.16. Em uma máquina conectada à VNet, execute nslookup <resource-fqdn> e verifique se cada nome se resolve para um endereço IP privado.

Próximas etapas

Agora você configurou com êxito uma conta e um projeto seguros de rede. Use o início rápido para criar seu primeiro agente.

Para obter mais informações sobre a configuração e as opções de isolamento de rede, consulte Configurar o isolamento de rede.

Muitos ambientes empresariais exigem que o Foundry, o registro de contêiner e os serviços dependentes, como Application Insights e Armazenamento, sejam acessíveis somente de uma rede privada. Esta seção explica como provisionar e implantar agentes hospedados azd cujas dependências estão por trás de endpoints privados em uma rede virtual (VNet).

A integração com a VNet é obtida personalizando os modelos Bicep com scaffold infra/ e executando azd de dentro da VNet (ou com acesso a ela).

Pré-requisitos

O que a proteção de VNet significa para uma implantação do azd

Um projeto de agente hospedado provisiona vários recursos Azure. Você pode desabilitar o acesso à rede pública em cada um deles e colocar um ponto de extremidade privado em sua VNet.

Resource Pode ser protegido por VNet? O que significa o modo privado
Conta dos Serviços de IA Yes A conta do Foundry é acessível somente por meio de um endpoint privado, tanto para chamadas do plano de dados quanto para chamadas do ARM.
Projeto de fundição Sim, com a conta Herda a postura de rede da conta.
Registro de Contêiner do Azure Yes publicNetworkAccess: Disabled. A compilação, o push e o pull ocorrem por meio do endpoint privado.
Application Insights Sim, por meio de um Azure Monitor Link Privado Scope As rotas de ingestão de telemetria passam pelo escopo de link privado.
Armazenamento do Azure Yes Os serviços Blob, File e Queue estão por trás de endpoints privados.
O ponto de extremidade do agente em si Não, nesta versão prévia A URL do ponto de extremidade do agente implantado permanece acessível publicamente. As sessões de cada usuário são isoladas por sua identidade. Consulte Isolar sessões de agente hospedado por usuário.

Se você precisar que o endpoint do agente em si seja privado, isso é uma funcionalidade da plataforma e, no momento, está fora do escopo desta extensão.

O que a extensão faz e não faz

Capability Status
Opção da CLI que habilita a integração de VNet Sem suporte. Nenhuma flag --vnet nem --private-endpoint vem por padrão.
Reutilização de um ACR privado existente Com suporte via AZURE_CONTAINER_REGISTRY_RESOURCE_ID e AZURE_CONTAINER_REGISTRY_ENDPOINT. Consulte Implantar um agente hospedado com um Registro de Contêiner do Azure privado.
Reutilização de uma conta do Foundry existente Com suporte via AZURE_AI_ACCOUNT_NAME e USE_EXISTING_AI_PROJECT=true.
Módulos de Bicep personalizados em infra/ Totalmente com suporte. O diretório infra/ é o Bicep azd padrão que pertence a você.
azd ai agent doctor de dentro da rede virtual (VNet) Funciona. As verificações remotas exigem a resolução de DNS do endpoint do plano de dados do Foundry. Use --local-only para ignorá-los.
Executores de GitHub auto-hospedados ou agentes do Azure DevOps na VNet Padrão recomendado. A CI provisiona recursos e realiza a implantação a partir de dentro da rede.

Escolha sua topologia

A maioria das implantações protegidas por VNet se enquadra em uma dessas formas. Escolha um antes de editar Bicep:

  • Greenfield, tudo dentro de uma nova VNet. Execute azd ai agent init, depois adicione módulos de ponto de extremidade privado à estrutura com scaffold infra/. Você provisiona tanto a VNet quanto os recursos em uma única execução do Bicep.
  • Brownfield, anexe-se a uma VNet existente. Assim como na abordagem de greenfield, você referencia a VNet existente por meio de parâmetros, em vez de criar uma. Isso é útil quando uma equipe diferente possui rede.
  • Reutilize todos os recursos existentes. Uma equipe de plataforma pré-provisionou a conta do Foundry, o ACR e o Application Insights em pontos de extremidade privados. Você traz apenas a definição do agente e aponta as variáveis de ambiente para os recursos existentes. main.bicep cria apenas o que está faltando.

Topologias 2 e 3 são as mais comuns em empresas regulamentadas. A topologia 1 é adequada para pilotos autônomos.

Personalizar o Bicep com scaffold

O diretório infra/ gerado por azd ai agent init é Bicep azd padrão. Você tem o controle, e as alterações persistem entre as implantações. Os modelos padrão criam recursos públicos, por isso é necessário substituí-los ou complementá-los para adicionar endpoints privados.

Adicionar parâmetros de VNet e sub-rede

Adicionar parâmetros a infra/main.bicep e vinculá-los em 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}" }
}

Defina as variáveis de ambiente antes 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

Bloquear cada recurso

Para cada recurso que os modelos criarem, defina publicNetworkAccess: 'Disabled' e adicione um módulo de ponto de extremidade privado. O padrão a seguir é ilustrativo. Adapte os tipos de recursos e as zonas DNS ao seu ambiente.

// 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'
    }
  }
}

Adicione um módulo de ponto de extremidade privado que conecta a conta à VNet:

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 esse padrão para os recursos que você deseja tornar privados:

  • Conta de Serviços de IA: ID account do grupo. As zonas DNS incluem privatelink.cognitiveservices.azure.com, privatelink.openai.azure.come privatelink.services.ai.azure.com, dependendo do plano de dados.
  • Registro de contêiner: ID do grupo registry. Zona DNS privatelink.azurecr.io. Adiciona um endpoint de dados por região.
  • Application Insights: por meio de um escopo de link privado do Azure Monitor. As zonas DNS incluem privatelink.monitor.azure.com, privatelink.ods.opinsights.azure.come privatelink.oms.opinsights.azure.comprivatelink.agentsvc.azure-automation.net.
  • Conta de armazenamento: IDs de grupo blob, file, queue e table, conforme necessário. Zonas DNS por serviço, por exemplo privatelink.blob.core.windows.net.

O repositório azd-ai-starter-basic, a partir do qual a extensão de agente faz scaffold, é uma referência útil para o que é criado por padrão. Aumente esses módulos em vez de substituí-los.

Provisionar os recursos

azd provision

Após o provisionamento, cada dependência da sua lista fica acessível apenas por meio do seu endpoint privado. A resolução DNS pública ainda retorna o nome do host público, mas as zonas DNS privadas a substituem dentro da VNet.

Executar azd up de dentro da VNet

Depois de desabilitar o acesso à rede pública, você não poderá executar azd up ou azd deploy de uma estação de trabalho da Internet pública. O plano de controle do ARM pode ser acessado, mas as chamadas ao plano de dados para o Foundry e o envio por push ao ACR falham com erros 403 ou de conexão recusada. Use um dos seguintes padrões.

Executor do GitHub Actions auto-hospedado

Provisione uma VM executora ou um executor hospedado pelo AKS em uma sub-rede da mesma VNet. Aponte seu fluxo de trabalho para esse executor com runs-on: [self-hosted, agent-vnet]. Cada etapa azd ai resolve corretamente os nomes DNS privados e passa pelo ponto de extremidade 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 auto-hospedado do Azure DevOps

Use o mesmo padrão para Azure DevOps. Instale o agente em uma sub-rede VNet e direcione-o com a pool: name: agent-vnet diretiva. A azd CLI e a extensão Foundry são executadas inalteradas.

Bastion ou jump host para execuções pontuais

Para execuções ad hoc, como resposta a incidentes manuais ou uma implantação fora do ciclo, conecte-se por meio de Azure Bastion a um host de salto dentro da VNet, instale azd e as extensões lá e execute azd a partir desse host. Mantenha o jump host o mais enxuto possível. A resposta a longo prazo é CI.

Desenvolva localmente usando um endpoint privado do Foundry

O desenvolvimento local (azd ai agent run e azd ai agent invoke) se comunica com o processo do agente local via loopback e com o plano de dados do Foundry para ferramentas, modelos e sessões durante invoke. Quando o endpoint do Foundry é acessível apenas por VNet, você precisa de conectividade de rede a partir da sua máquina de desenvolvimento. As opções incluem:

  • Uma VPN ponto a site ou sempre ativa que coloca você no escopo de DNS da VNet.
  • Azure Bastion para uma VM de desenvolvimento dentro da VNet. Execute azd ai agent run nessa VM e encaminhe as portas 8088 e 8087 para o inspetor, por meio do túnel Bastion.
  • Uma estação de trabalho na rede corporativa com um caminho via ExpressRoute ou hub-VNet para o spoke que hospeda os pontos de extremidade privados.

A FOUNDRY_PROJECT_ENDPOINT resolução não muda. O valor ainda vem do ambiente ativo azd ou da configuração global. O que importa é que o DNS resolve o endpoint para o endereço IP privado, em vez do público.

Integrar com um ACR privado

Se tanto o endpoint do Foundry quanto o ACR estiverem em endpoints privados na mesma VNet, faça o seguinte:

  1. Execute azd up de dentro da rede virtual.
  2. Defina AZURE_CONTAINER_REGISTRY_ENDPOINT e AZURE_CONTAINER_REGISTRY_RESOURCE_ID para apontarem para o ACR privado existente, para que o Bicep não crie um novo ACR público.
  3. Verifique se a identidade do agente tem a função AcrPull no registro. azd deploy trata isso automaticamente depois de criar a identidade do agente.

Para obter detalhes específicos do Registro, consulte Implantar um agente hospedado com uma Registro de Contêiner do Azure privada.

Diagnosticar problemas de rede

  • azd ai agent doctor executa verificações de acessibilidade de rede em relação ao plano de dados do Foundry. Dentro da VNet, as verificações são aprovadas. De fora, eles falham claramente. Use --local-only para ignorar verificações remotas quando você depurar problemas que não são de rede.
  • azd ai agent invoke --output raw "ping" despeja a resposta HTTP completa. Um erro de conexão recusada ou de host inexistente aqui é um problema de DNS ou roteamento, não um problema de autenticação.
  • Para falhas ao enviar para o ACR, a CLI emite um comando az role assignment create pronto para colar quando a causa é a ausência de uma função, e não um problema de rede.

Limitações conhecidas

  • Nenhum sinalizador da CLI de primeira classe. Toda a configuração da VNet é feita por meio de personalização manual no Bicep, além de disciplina operacional para o posicionamento do executor, DNS e RBAC.
  • O ponto de extremidade do agente permanece público nesta versão prévia. O isolamento de locatário em um ponto de extremidade público é feito por isolamento de sessões por usuário, não por privacidade de rede.
  • As restrições de região se aplicam. Os agentes hospedados estão disponíveis em um conjunto fixo de regiões. A VNet, o ACR e a conta do Foundry devem estar em uma dessas regiões ou emparelhados com uma delas. Para saber mais sobre o requisito de mesma região entre o recurso Foundry e sua rede virtual, consulte o suporte regional para rede privada. Execute azd ai agent doctor para validar.
  • O DNS é o modo de falha mais comum. Confirme a resolução privada de DNS de ponta a ponta, por exemplo, com nslookup <endpoint> a partir do executor ou da VM de desenvolvimento, antes de presumir que o problema é de RBAC.

Conteúdo relacionado

  • Last updated on