Compartilhar via

Tutorial: Invocar um aplicativo Web de um Serviço de Aplicativo por meio do Azure AI Foundry Agent Service

O Serviço do Azure AI Foundry Agent permite que você crie agentes de IA adaptados às suas necessidades por meio de instruções personalizadas e aumentadas por ferramentas avançadas, como interpretador de código e funções personalizadas. Agora você pode conectar seu Agente de IA do Azure a uma API externa usando uma ferramenta especificada do OpenAPI 3.0 , permitindo uma interoperabilidade escalonável com vários aplicativos.

O Serviço de Aplicativo do Azure é uma plataforma totalmente gerenciada para criar, implantar e dimensionar aplicativos Web e APIs. Se a API estiver hospedada no Serviço de Aplicativo do Azure, você poderá conectar seu Agente de IA à API usando a especificação OpenAPI. A especificação OpenAPI define a API e como interagir com ela. Em seguida, você pode usar o idioma natural para invocar a API por meio do agente de IA. Essa ferramenta é poderosa porque permite que você adicione recursos de agente de IA aos seus aplicativos existentes com alterações mínimas de código. Além disso, esse agente tem a capacidade de interagir diretamente com seu aplicativo. Não é necessário fazer alterações significativas no código ou trabalho de implementação, além de pequenas atualizações para interagir com o agente usando os SDKs disponíveis.

Neste tutorial, você está usando um Azure AI Foundry Agent para invocar uma API existente hospedada no Serviço de Aplicativo do Azure. Ao final deste tutorial, você terá um aplicativo de chat de assistente de moda em execução no Serviço de Aplicativo, usando um agente de IA do serviço Azure AI Foundry Agent.

Uma captura de tela mostrando um agente de IA em execução no Serviço de Aplicativo.

Pré-requisitos

  • Uma conta do GitHub. Você também pode obter um gratuitamente.
  • Uma conta do Azure com uma assinatura ativa. Se você não tiver uma conta do Azure, poderá criar uma gratuitamente.

1. Inspecionar o exemplo em codespaces do GitHub

Comece inspecionando o exemplo no GitHub:

  1. Entre em sua conta do GitHub e navegue até https://github.com/Azure-Samples/ai-agent-openai-web-app/fork.
  2. Selecione Criar fork.
  3. Selecione Código>Criar codespace no principal. O codespace leva alguns minutos para ser configurado.

O repositório de exemplo tem o seguinte conteúdo:

Conteúdo Descrição
src/webapp Um aplicativo .NET Blazor front-end.
infra Infraestrutura como código para implantar um aplicativo Web .NET nos recursos do Azure e do Azure AI Foundry para o Agente de IA. Confira Visão geral de criar modelos do Azure Developer CLI.
azure.yaml Configuração do Azure Developer CLI que implanta o aplicativo Blazor no Serviço de Aplicativo. Confira Visão geral de criar modelos do Azure Developer CLI.

2. Implantar a infraestrutura e o aplicativo do Azure

Para implantar a infraestrutura e o aplicativo do Azure:

  1. Entre em sua conta do Azure usando o comando azd auth login e seguindo o prompt:

    azd auth login

  2. Crie o aplicativo do Serviço de Aplicativo e implante o código usando o comando azd up:

    azd up

    O comando azd up pode levar alguns minutos para ser concluído. azd up usa os arquivos Bicep em seus projetos para criar um aplicativo do Serviço de Aplicativo no tipo de preço P0v3 e implanta o aplicativo .NET em src/webapp. O comando também cria o Azure AI Foundry e os recursos de suporte para o agente.

3. Criar o agente de IA

Para criar o agente de IA:

  1. No portal do Azure, navegue até o grupo de recursos que o modelo do azd cria. O nome do grupo de recursos está na saída do comando azd executado.

  2. Selecione o recurso de projeto de IA do Azure . O nome deve estar no formato ai-aiproject-<identifier>. Verifique se você selecionou o recurso do projeto e não os recursos de hub ou serviços de IA. Os agentes são criados a partir do recurso de projeto de IA do Azure.

  3. Selecione Iniciar estúdio para abrir o Estúdio do Azure AI Foundry.

  4. No menu à esquerda, em Compilar e personalizar, selecioneAgentes.

  5. Quando a página for carregada, na lista suspensa, selecione o recurso do Serviço OpenAI do Azure gerado automaticamente que é criado para você e, em seguida, selecione Vamos Lá.

  6. Selecione + Novo agente para criar um novo agente ou use o padrão se já estiver criado para você.

  7. Quando o agente for criado, adicione as instruções a seguir no menu à direita. Essas instruções garantem que seu agente responda apenas às perguntas e conclua tarefas relacionadas ao aplicativo da loja de moda.

     You are an agent for a fashion store that sells clothing. You have the ability to view inventory, update the customer's shopping cart, and answer questions about the clothing items that are in the inventory. You should not answer questions about topics that are unrelated to the fashion store. If a user asks an unrelated question, please respond by telling them that you can only talk about things that are related to the fashion store.

4. Adicionar a Ferramenta Especificada do OpenAPI ao agente de IA

Para obter diretrizes detalhadas com capturas de tela e informações adicionais, consulte Adicionar ferramenta de especificação OpenAPI no portal do Azure AI Foundry. As etapas são resumidas nas instruções a seguir.

  1. Selecione + Adicionar ao lado de Ação.

  2. Selecione a ferramenta especificada OpenAPI 3.0.

  3. Dê um nome à sua ferramenta e a descrição a seguir. A descrição é usada pelo modelo para decidir quando e como usar a ferramenta.

     This tool is used to interact with and manage an online fashion store. The tool can add or remove items from a shopping cart as well as view inventory.

  4. Deixe o método de autenticação como anônimo. Não há autenticação no aplicativo Web. Se o aplicativo exigisse uma chave de API ou uma identidade gerenciada para acessá-la, esse local será onde você especificaria essas informações.

  5. Copie e cole a especificação OpenAPI na caixa de texto. A especificação OpenAPI é fornecida no Codespace no src/webapp diretório e é chamada swagger.json.

  6. Antes de concluir a criação da ferramenta, você precisa copiar e colar a URL do aplicativo na especificação OpenAPI. Substitua o espaço reservado <APP-SERVICE-URL> na linha 10 da especificação OpenAPI pela URL do aplicativo. O formato é https://<app-name>.azurewebsites.net.

    • Para localizar a URL do aplicativo, volte para o grupo de recursos e navegue até o Serviço de Aplicativo. A URL está na página Visão geral do Serviço de Aplicativo.

  7. Selecione Avançar, examine os detalhes fornecidos e selecione Criar Ferramenta.

5. Conectar seu Serviço de Aplicativo ao Agente de IA

Depois de configurar o Agente de IA e adicionar a Ferramenta Especificada do OpenAPI, você precisará configurar o Serviço de Aplicativo com as variáveis de ambiente apropriadas para que o aplicativo saiba a qual agente se conectar. O aplicativo já tem uma identidade gerenciada atribuída que lhe dá acesso ao Serviço do Agente de IA. Essa identidade gerenciada é necessária para que o aplicativo alcance o agente e é criada com o modelo azd.

  1. No painel Agentes em que você adicionou a ferramenta OpenAPI, observe a ID do agente. O formato é asst_<unique-identifier>.
  2. Selecione Visão geral no menu e anote a cadeia de conexão do projeto. O formato é <region>.api.azureml.ms;<subscription-id>;<resource-group-name>;<project-name>.
  3. No portal do Azure, navegue até o Serviço de Aplicativo.
  4. Selecione variáveis de ambiente no menu à esquerda.
  5. Na guia Configurações do aplicativo, selecione + Adicionar e adicione a seguinte configuração:
    • Nome: AzureAIAgent__ConnectionString
    • Valor: a cadeia de conexão que você anotou do serviço do Agente de IA
  6. Adicione outra configuração de aplicativo:
    • Nome: AzureAIAgent__AgentId
    • Valor: A ID do agente que você anotou ao criar seu agente
  7. Selecione Aplicar na parte inferior da página e confirme quando solicitado. O aplicativo é reiniciado com as novas configurações aplicadas.

6. Verificar o aplicativo em execução

Na saída do AZD, localize o URL do seu aplicativo e navegue até ele no navegador. A URL tem esta aparência na saída do azd:

Deploying services (azd deploy)

    (✓) Done: Deploying service web
    - Endpoint: https://<app-name>.azurewebsites.net/

Na janela de chat, faça perguntas ao agente, como:

  • O que há no meu carrinho?
  • Adicionar uma jaqueta jeans pequena ao meu carrinho
  • Temos algum blazer em estoque? Você também pode fazer perguntas gerais sobre os itens e o agente deve ser capaz de fornecer informações.
  • Fale-me sobre a camisa casual marcada do Red Slim Fit
  • O blazer está quente?

Limpar os recursos

Quando terminar esse aplicativo, execute o seguinte para excluir o grupo de recursos com todos os recursos criados durante este tutorial.

azd down

Resolução de problemas

Problemas comuns

  1. Chat não está funcionando
    • Verifique se as variáveis de ambiente (AzureAIAgent__ConnectionString e AzureAIAgent__AgentId) estão definidas corretamente nas variáveis de ambiente do Serviço de Aplicativo.
    • Verifique se o Agente de IA foi criado e configurado corretamente com a ferramenta OpenAPI correta.
    • Verifique se a URL de especificação do OpenAPI está acessível no Serviço do Agente do Azure AI Foundry.
    • Verifique se o URL do Serviço de Aplicativo está atualizada no swagger.json fornecido à Ferramenta Especificada do OpenAPI.
  2. Problemas de permissão
    • Se você encontrar erros de autenticação, verifique se a identidade gerenciada do Serviço de Aplicativo tem permissões adequadas para acessar o Serviço do Agente do Azure AI Foundry. A identidade gerenciada precisa, pelo menos, da Microsoft.MachineLearningServices/workspaces/agents/action permissão para interagir com o Agente. A "função de Desenvolvedor de IA do Azure" fornecida tem essa permissão e deve ser suficiente. Se você decidir alterar essa função, certifique-se de que ela tenha a permissão necessária.
  3. Problemas de API
    • Se o agente não puder executar ações no inventário ou carrinho, verifique as rotas de API na especificação OpenAPI.
    • Verifique se os endpoints da API estão respondendo corretamente testando-os diretamente na Swagger UI em /api/docs.

Exibir logs

Para exibir os logs do Serviço de Aplicativo:

  1. No portal do Azure, navegue até o Serviço de Aplicativo.
  2. No menu à esquerda, selecione Monitoramento>Fluxo de Log para exibir logs em tempo real.
  3. Esses logs revelam todos os problemas de aplicativo que talvez seja necessário resolver.

Noções básicas sobre os recursos de API

A especificação OpenAPI fornece ao agente de IA informações sobre pontos de extremidade disponíveis:

Pontos de extremidade da API do carrinho

  • GET /api/Cart: recupera o conteúdo do carrinho de compras atual e o custo total
  • DELETE /api/Cart: limpa todos os itens do carrinho
  • POST /api/Cart/add: adiciona um item ao carrinho de compras
  • PUT /api/Cart/{productId}/size/{size}: atualiza a quantidade de um item específico
  • DELETE /api/Cart/{productId}/size/{size}: remove um item específico do carrinho

Pontos de extremidade da API de inventário

  • GET /api/Inventory: lista todos os itens de inventário disponíveis
  • GET /api/Inventory/{id}: obtém detalhes sobre um produto específico
  • GET /api/Inventory/{id}/size/{size}: verifica o inventário de um tamanho específico do produto
  • GET /api/Inventory/sizes: obtém todos os tamanhos disponíveis no inventário

Interações avançadas do agente

Além das interações básicas, o agente de IA pode lidar com cenários mais complexos:

  • Recomendações personalizadas: "Preciso de uma roupa casual de negócios para uma reunião"
  • Diretrizes de tamanho: "Que tamanho de blazer caberia em alguém que tem 1,80 m e 180 quilos?"
  • Coordenação de Roupas: "O que iria bem com a jaqueta jeans preta?"
  • Gerenciamento do Carrinho de Compras: "Remova a camisa grande e adicione um meio em vez disso"
  • Verificações de inventário: "Você tem camisas vermelhas no meio?"
  • Consultas de preço: "Qual é a faixa de preço para blazers?"

Considerações de segurança

  • O aplicativo usa identidades gerenciadas do Azure para autenticação segura no Serviço de Agent Foundry de IA do Azure em ambientes de produção.
  • Você pode proteger ainda mais seu aplicativo e agente usando qualquer uma das práticas padrão e recursos do Azure. Para obter modelos seguros de infraestrutura do Agente de IA do Azure, consulte o repositório de exemplos do azureai.

Conteúdo relacionado

Agora que você aprendeu a conectar seu Agente de IA a uma API no Serviço de Aplicativo do Azure, você pode explorar as outras integrações de IA disponíveis com o Serviço de Aplicativo:

  • Last updated on