Tutorial: Construa uma aplicação web agente no Serviço de Aplicações do Azure com Microsoft Agent Framework ou Foundry Agent Service (.NET)

Este tutorial demonstra como adicionar capacidade de agente a um aplicativo ASP.NET Core CRUD controlado por dados existente. Faz isto usando duas abordagens diferentes: Microsoft Agent Framework e Foundry Agent Service.

Se a sua aplicação web já tem funcionalidades úteis, como compras, reservas de hotel ou gestão de dados, é relativamente simples adicionar funcionalidades de agente à sua aplicação web, envolvendo essas funcionalidades como ferramentas (para o Microsoft Agent Framework) ou como um endpoint OpenAPI (para o Foundry Agent Service). Neste tutorial, começas com uma aplicação de lista simples to-do. No final, você poderá criar, atualizar e gerenciar tarefas com um agente em um aplicativo do Serviço de Aplicativo.

Tanto o Microsoft Agent Framework como o Foundry Agent Service permitem-lhe construir aplicações web agentes com capacidades impulsionadas por IA. A tabela a seguir mostra algumas das considerações e compensações:

Neste tutorial, aprenderás como:

Prerequisites

• Uma conta do Azure com uma subscrição ativa - Crie uma conta gratuitamente.
• Conta do GitHub para usar o GitHub Codespaces - Saiba mais sobre o GitHub Codespaces.

Abra o exemplo com Codespaces

A maneira mais fácil de começar é usando o GitHub Codespaces, que fornece um ambiente de desenvolvimento completo com todas as ferramentas necessárias pré-instaladas.

1. Navegue até o repositório GitHub em https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent.

2. Selecione o botão Código , selecione a guia Espaços de código e selecione Criar espaço de código na principal.

3. Aguarde alguns instantes até que o Codespace seja inicializado. Quando estiver pronto, você verá um ambiente de desenvolvimento totalmente configurado em seu navegador.

4. Execute o aplicativo localmente:

   dotnet run
   

5. Quando vir que a sua aplicação em execução na porta 5280 está disponível, selecione Abrir no Browser e adicione algumas tarefas.

Revise o código do agente

Ambas as abordagens usam o mesmo padrão de implementação, onde o agente é inicializado como um serviço (em Program.cs) em um provedor e injetado no respetivo componente Blazor.

// Create IChatClient
IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deployment)
    .AsIChatClient();

// Get TaskCrudTool instance from service provider
var taskCrudTool = sp.GetRequiredService<TaskCrudTool>();

// Create agent with tools
var agent = chatClient.CreateAIAgent(
    instructions: @"You are an agent that manages tasks using CRUD operations. 
        Use the provided functions to create, read, update, and delete tasks. 
        Always call the appropriate function for any task management request.
        Don't try to handle any requests that are not related to task management.
        When handling requests, if you're missing any information, don't make it up but prompt the user for it instead.",
    tools:
    [
        AIFunctionFactory.Create(taskCrudTool.CreateTaskAsync),
        AIFunctionFactory.Create(taskCrudTool.ReadTasksAsync),
        AIFunctionFactory.Create(taskCrudTool.UpdateTaskAsync),
        AIFunctionFactory.Create(taskCrudTool.DeleteTaskAsync)
    ]);

// Create thread for this scoped instance (persists across navigation)
var thread = agent.GetNewThread();

return (agent, thread);

var response = await this.Agent.RunAsync(sentInput, this.agentThread);

// Create project client
var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());

// Get an existing agent from Microsoft Foundry
var agent = projectClient.Agents.GetAgent(agentName);

// Get conversations client for retrieving history
var conversationsClient = projectClient.OpenAI.Conversations;

// Create conversation for this browser session
var conversation = conversationsClient.CreateProjectConversation().Value;

// Get response client for this agent and conversation
var responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentName, conversation.Id);

return (responseClient, conversation, conversationsClient);

app.MapOpenApi();

app.MapGet("/api/tasks", async (TaskService taskService) =>
{
    return Results.Ok(await taskService.GetAllTasksAsync());
})
.WithDescription("Gets all tasks.")
.WithName("GetAllTasks");

#pragma warning disable OPENAI001
var response = await FoundryProvider.ResponseClient.CreateResponseAsync(sentInput);
#pragma warning restore OPENAI001

Implementar o exemplo de aplicação

O repositório de exemplo contém um modelo Azure Developer CLI (AZD), que cria uma aplicação de Serviços de Aplicação e implementa a sua aplicação de exemplo. A identidade gerida atribuída pelo sistema de App Service é mantida para chamadas de IA do Azure de saída. Uma identidade gerida separada atribuída pelo utilizador e uma credencial de identidade federada permitem que a autenticação de Serviços de Aplicações atue como a aplicação Microsoft Entra gerada sem um segredo do cliente.

1. No terminal, inicia sessão no Azure usando o Azure Developer CLI:

   azd auth login
   

   Siga as instruções para concluir o processo de autenticação.

2. Implemente a aplicação Serviço de Aplicações do Azure usando o modelo AZD:

   azd up
   

3. Quando solicitado, forneça as seguintes respostas:

   Question	Answer
   Insira um novo nome de ambiente:	Escreva um nome exclusivo.
   Selecione uma Assinatura do Azure para usar:	Selecione uma subscrição.
   Escolha um grupo de recursos para usar:	Selecione Criar um novo grupo de recursos.
   Selecione um local para criar o grupo de recursos em:	Selecione Suécia Central.
   Insira um nome para o novo grupo de recursos:	Digite Enter.

4. Na saída AZD, localize a URL do seu aplicativo e navegue até ela no navegador. Copie também o valor da audiência da identidade gerida do Foundry OpenAPI para utilizar mais tarde. O resultado tem o seguinte aspeto:

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: <URL>
   
    Foundry OpenAPI managed identity audience:
        api://<generated-client-id>
    

5. Quando a Microsoft te pedir, inicia sessão usando uma conta no tenant de implementação e verifica se a lista de tarefas está carregada.

6. No mesmo navegador autenticado, anexe /openapi/v1.json ao endpoint do Serviço de Aplicações. Copie ou guarde o esquema OpenAPI gerado para mais tarde.

   Note

   A autenticação do App Service devolve um redirecionamento HTTP 302 para pedidos de navegador não autenticados. Este exemplo contém tanto uma interface de navegador como APIs, pelo que o redirecionamento proporciona uma experiência de login utilizável. As aplicações só de API normalmente usam antes o HTTP 401.

Crie e configure o recurso Microsoft Foundry

Atribuir permissões necessárias

Configurar variáveis de conexão em seu aplicativo de exemplo

1. Abra appsettings.json. Usando os valores que copiou anteriormente do portal Foundry, configure as seguintes variáveis:

   • Estrutura do Microsoft Agent
   • Serviço de Agente Foundry

   Variable	Description
   AzureOpenAIEndpoint	Azure OpenAI endpoint (copiado da página inicial do portal Foundry).
   ModelDeployment	Nome do modelo na implementação (copiado da área de testes do modelo no novo portal da Foundry).

   Note

   Para manter o tutorial simples, você usará essas variáveis em appsettings.json em vez de substituí-las pelas configurações do aplicativo no Serviço de Aplicativo.

   Note

   Para manter o tutorial simples, você usará essas variáveis em appsettings.json em vez de substituí-las pelas configurações do aplicativo no Serviço de Aplicativo.

2. Entre no Azure com a CLI do Azure:

   az login
   

   Isso permite que a biblioteca de cliente do Azure Identity no código de exemplo receba um token de autenticação para o usuário conectado. Lembre-se de que você adicionou a função necessária para esse usuário anteriormente.

3. Execute o aplicativo localmente:

   dotnet run
   

4. Quando vir que a sua aplicação em execução na porta 5280 está disponível, selecione Abrir no Browser.

5. Valide ambos os pivôs separadamente:

   • Microsoft Agent Framework: Selecione Microsoft Agent Framework Agent e peça-lhe para criar uma tarefa. O Microsoft Agent Framework chama a ferramenta de tarefas em processo.
   • Foundry Agent Service: Selecione Foundry Agent Service e peça ao agente que crie uma tarefa. O agente Foundry remoto invoca o endpoint /api/tasks implementado e protegido, utilizando a identidade gerida.

   A tarefa que o agente Foundry cria aparece na instância do Serviço de Aplicação implementado, e não na base de dados local em memória. A ferramenta Foundry OpenAPI utiliza sempre a URL do servidor embutida no esquema OpenAPI.

6. De volta ao espaço de código do GitHub, implante as alterações do seu aplicativo.

   azd up
   

7. Navegue até o aplicativo implantado novamente e teste os agentes de chat.

Perguntas mais frequentes

• Como posso adicionar geração aumentada de recuperação (RAG) ao agente da Foundry?

Como posso adicionar geração aumentada de recuperação (RAG) ao agente da Foundry?

Esta orientação aplica-se ao caminho Foundry Agent Service neste tutorial. Não altera as implementações do LangGraph, Kernel Semântico ou Microsoft Agent Framework mostradas no outro separador.

Crie ou selecione uma base de conhecimento Foundry IQ e depois ligue essa base ao agente do Serviço de Agentes da Foundry. A conexão é disponibilizada ao agente como uma ferramenta de conhecimento gerida do MCP.

O código do App Service continua a invocar o mesmo agente pelo respetivo nome através do cliente Foundry existente e agent_reference. A aplicação web não precisa de uma integração direta com Pesquisa de IA do Azure nem de um cliente MCP próprio. Se a interface mostrar as fontes, processe as anotações de citação devolvidas pelo agente.

Limpeza de recursos

Quando terminar de usar o aplicativo, você poderá excluir os recursos do Serviço de Aplicativo para evitar incorrer em custos adicionais:

azd down --purge

Depois, apaga o recurso Foundry se o criaste separadamente.

Mais recursos

• Integre a IA em seus aplicativos do Serviço de Aplicativo do Azure
• O que é o Foundry Agent Service?
• Documentação do Microsoft Agent Framework