Tutorial: Criar um aplicativo Web agente no Serviço de Aplicativo do Azure com o Microsoft Agent Framework ou o Foundry Agent Service (.NET)

Este tutorial demonstra como adicionar capacidade agente a um aplicativo CRUD de núcleo de ASP.NET baseado em dados existente. Ele faz isso usando duas abordagens diferentes: Microsoft Agent Framework e Foundry Agent Service.

Se seu aplicativo Web já tiver recursos úteis, como compras, reservas de hotéis ou gerenciamento de dados, é relativamente simples adicionar funcionalidade de agente ao seu aplicativo Web encapsulando essas funcionalidades como ferramentas (para o Microsoft Agent Framework) ou como um ponto de extremidade OpenAPI (para o Serviço do Foundry Agent). Neste tutorial, você começa com um simples aplicativo de lista to-do. Ao final, você poderá criar, atualizar e gerenciar tarefas com um agente em um aplicativo do Serviço de Aplicativo.

O Microsoft Agent Framework e o Foundry Agent Service permitem criar aplicativos Web agente com funcionalidades controladas por IA. A tabela a seguir mostra algumas das considerações e compensações:

Neste tutorial, você aprenderá como:

Prerequisites

• Uma conta do Azure com uma assinatura ativa – crie uma conta gratuitamente.
• Conta do GitHub para usar os Codespaces do GitHub – saiba mais sobre os codespaces do GitHub.

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 Codespaces e selecione Criar codespace no principal.

3. Aguarde alguns instantes para que o codespace seja inicializado. Quando estiver pronto, você verá um ambiente de desenvolvimento totalmente configurado no navegador.

4. Execute o aplicativo localmente:

   dotnet run
   

5. Quando você vir que seu aplicativo em execução na porta 5280 está disponível, selecione Abrir no Navegador e adicione algumas tarefas.

Revisar o código do agente

Ambas as abordagens usam o mesmo padrão de implementação, em que o agente é inicializado como um serviço (em Program.cs) em um provedor e injetado no respectivo 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

Implantar o aplicativo de exemplo

O repositório de exemplo contém um template de CLI para Desenvolvedores do Azure (AZD), que cria um aplicativo de Serviço de Aplicativos e implanta sua aplicação de exemplo. A identidade gerenciada atribuída ao sistema de App Service é mantida para chamadas de IA do Azure de saída. Uma identidade gerenciada separada atribuída pelo usuário e uma credencial federada permitem que a autenticação do App Service atue como a aplicação Microsoft Entra gerada sem um segredo cliente.

1. No terminal, faça login no Azure usando o Azure Developer CLI:

   azd auth login
   

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

2. Implante o aplicativo Serviço de Aplicativo do Azure usando o modelo AZD:

   azd up
   

3. Quando solicitado, dê as seguintes respostas:

   Question	Answer
   Insira um novo nome de ambiente:	Digite um nome exclusivo.
   Selecione uma Assinatura do Azure para usar:	Selecione a assinatura.
   Escolha um grupo de recursos a ser usado:	Selecione Criar um 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 do AZD, localize a URL do seu aplicativo e navegue até ela no navegador. Também copie o valor do público da identidade gerenciada do Foundry OpenAPI para usar mais tarde. A saída tem esta aparência:

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

5. Quando a Microsoft solicitar, faça login usando uma conta no tenant de implantação e verifique se a lista de tarefas está carregada.

6. No mesmo navegador autenticado, anexe /openapi/v1.json ao endpoint do App Service. Copie ou salve o esquema OpenAPI gerado para depois.

   Note

   A autenticação por App Service retorna um redirecionamento HTTP 302 para requisições de navegador não autenticadas. Este exemplo contém tanto uma interface de navegador quanto APIs, então o redirecionamento oferece uma experiência de login utilizável. Aplicativos apenas de API geralmente usam HTTP 401.

Criar e configurar 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 copiados anteriormente do portal do Foundry, configure as seguintes variáveis:

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

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

   Note

   Para manter o tutorial simples, você usará essas variáveis em appsettings.json em vez de substituí-las com configurações de 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 com configurações de aplicativo no Serviço de Aplicativo.

2. Entre no Azure com a CLI do Azure:

   az login
   

   Isso permite que a biblioteca de clientes da Identidade do Azure 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 você vir Seu aplicativo em execução na porta 5280 está disponível, selecione Abrir no Navegador.

5. Valide ambos os pivôs separadamente:

   • Microsoft Agent Framework: Selecione Microsoft Agent Framework Agent e peça ao agente 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 para criar uma tarefa. O agente Foundry remoto chama o endpoint implantado e protegido /api/tasks usando identidade gerenciada.

   A tarefa criada pelo agente Foundry aparece na instância do App Service implantada, não no banco de dados local em memória. A ferramenta OpenAPI do Foundry sempre utiliza a URL do servidor embutida no esquema OpenAPI.

6. De volta ao codespace do GitHub, implante as alterações do aplicativo.

   azd up
   

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

Perguntas frequentes

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

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

Esta instrução se aplica ao caminho Foundry Agent Service neste tutorial. Ele não altera as implementações do LangGraph, Kernel semântico ou Microsoft Agent Framework mostradas na outra aba.

Crie ou selecione uma base de conhecimento do Foundry IQ e, em seguida, conecte a base de conhecimento ao agente do serviço de agente do Foundry. A conexão é exposta ao agente como uma ferramenta de conhecimento gerenciada do MCP.

O código do App Service continua a invocar o mesmo agente pelo nome através de seu cliente existente no Foundry e agent_reference. O aplicativo 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 exibir fontes, processe as anotações de citação retornadas pelo agente.

Limpar os 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, exclua o recurso do Foundry se você o criou separadamente.

Mais recursos

• Integrar a IA aos aplicativos do Serviço de Aplicativo do Azure
• O que é o Serviço de Agente da Fábrica?
• Documentação do Microsoft Agent Framework