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

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 o indivíduo que cria a conta e o projeto tem a função Proprietário da Conta do Azure AI no escopo da assinatura.

• 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 é Administrador de Acesso Baseado em Funções.
  • 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 do agente estiver configurado, verifique se cada membro da equipe que deseja usar o Agent Playground ou o SDK para criar ou editar agentes recebeu a função interna de Azure AI UserRBAC 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'
  

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:

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. Verifique se cada nome é resolvido para um endereço IP privado (10.x, 172.16-31.x ou 192.168.x).
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.

Limitações

• Limitação do endereço IP da sub-rede: ambas as sub-redes devem ter intervalos de IP dentro de intervalos IPv4 privados RFC1918 válidos: 10.0.0.0/8, 172.16-31.0.0/12ou 192.168.0.0/16. Não há suporte para intervalos de endereços IP públicos 100.64.0.0100.127.255.255 e CGNAT.
• 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 delegada é /24 (256 endereços) devido à delegação da sub-rede a 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.
• 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:
  • Para regiões com suporte para implantações de modelo, consulte: suporte de região para modelos do Azure OpenAI.
• 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.
• Grounding com a Pesquisa do Bing: somente as seguintes regiões são compatíveis: Europa Ocidental, Leste do Canadá, Norte da Suíça, Espanha Central, Norte dos EAU, Coreia Central, Polônia Central, Sudeste Asiático, EUA Oeste, Oeste dos EUA 2, Oeste dos EUA 3, Leste dos EUA, Leste dos EUA 2, EUA Central, 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 do agente hospedado atrás de uma rede privada: para agentes hospedados, o Registro de Contêiner do Azure (ACR) que armazena a imagem de contêiner do agente não pode ser colocado atrás de uma rede privada (ponto de extremidade privado com acesso à rede pública desabilitado). O ACR deve ser acessível em seu ponto de extremidade público para a plataforma realizar o pull da imagem.

Diagrama de arquitetura

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 aos 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 a flag Acesso à rede pública desabilitado, exigindo uma configuração explícita para permitir o acesso por meio de pontos de extremidade privados. Essas regras se aplicam a todos os protocolos, incluindo REST e WebSocket.

Resumo das configurações de zona DNS

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 o ambiente de trabalho diretamente.

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 sua própria sub-rede de agente de execução dedicado. 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: Para fornecer todas as conexões a todos os recursos BYO (Bring-your-Own), é necessário ter conexões com todos esses recursos. 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 sua sub-rede de 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. O texto da mensagem de erro pode não listar todos os intervalos válidos.

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

Solução: você não registrou o recurso correto. 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 uma solicitação de tíquete de suporte para investigar sua configuração. 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í, remova o recurso ao qual o agente foi 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 o 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 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.