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

O AgentFrameworkProvider é inicializado em Serviços/AgentFrameworkProvider.cs. O código de inicialização faz o seguinte:

• Cria um IChatClient do OpenAI do Azure usando o AzureOpenAIClient.
• Obtém a instância TaskCrudTool que encapsula a funcionalidade do aplicativo CRUD (em Ferramentas/TaskCrudTool.cs). Os Description atributos nos métodos de ferramenta ajudam o agente a determinar como chamá-los.
• Cria um agente de IA usando o CreateAIAgent() com instruções e ferramentas registradas via AIFunctionFactory.Create().
• Cria um tópico para que o agente mantenha a conversa durante a navegação.

// 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);

Sempre que o usuário envia uma mensagem, o componente Blazor (em Components/Pages/AgentFrameworkAgent.razor) chama Agent.RunAsync() com a entrada do usuário e o thread do agente. O thread do agente mantém o controle do histórico de chat.

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

O provedor FoundryAgentProvider é inicializado em Services/FoundryAgentProvider.cs. O código de inicialização faz o seguinte:

• Cria um AIProjectClient usando um ponto de extremidade do projeto Foundry.
• Obtém um agente existente do Microsoft Foundry por nome.
• Cria uma conversa para a sessão do navegador.
• Obtém um ProjectResponsesClient para o agente e a conversa.

// 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);

Esse código de inicialização não define nenhuma funcionalidade para o agente, pois você normalmente compilaria o agente no portal do Foundry. Como parte do cenário de exemplo, ele também segue o padrão OpenAPI mostrado em Adicionar um aplicativo do Serviço de Aplicativo como uma ferramenta no Foundry Agent Service (.NET) e disponibiliza sua funcionalidade CRUD como um ponto de extremidade OpenAPI. Isso permite adicioná-lo ao agente posteriormente como uma ferramenta invocável.

O código OpenAPI é definido em Program.cs. Por exemplo, a API "obter tarefas" define a ID da operação com WithName(), conforme exigido pela ferramenta de especificação OpenAPI no Microsoft Foundry, e WithDescription() ajuda o agente a determinar como chamar a API:

app.MapOpenApi();

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

Sempre que o usuário envia uma mensagem, o componente Blazor (em Components/Pages/FoundryAgent.razor) chama ResponseClient.CreateResponseAsync() com a entrada do usuário. O cliente de resposta usa a ID da conversa para acompanhar o histórico de chat.

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

1. No Portal Foundry, verifique se o botão de rádio New Foundry superior está definido como ativo e crie um projeto.

2. Implante um modelo de sua escolha (consulte o Início Rápido do Microsoft Foundry: Criar recursos).

3. Na parte superior da área de testes do modelo, copie o nome do modelo.

4. A maneira mais fácil de obter o endpoint do Azure OpenAI ainda é através do portal clássico. Selecione o botão de opção Novo Foundry e, em seguida, OpenAI do Azure; depois, copie a URL no ponto de extremidade do OpenAI do Azure para uso posterior.

   

1. No portal do Foundry, verifique se o botão de opção Novo Foundry no topo está definido como ativo e crie um projeto.

2. Na home page, copie o Project endpoint para depois.

3. Selecione Iniciar a criação>do agente de criação e siga o prompt.

4. No ambiente de teste do novo agente, crie uma ferramenta OpenAPI para chamar seu aplicativo web selecionando Tools>Add>Custom>OpenAPI tool>Create. No painel Instalação , adicione uma ação com a ferramenta de especificação OpenAPI. Use o esquema OpenAPI que você obtém do aplicativo Web implantado e da autenticação anônima . Para obter etapas detalhadas, consulte Como usar a ferramenta de especificação OpenAPI.

   Seu código de aplicativo já está configurado para incluir o url e operationId do servidor, que são necessários para o agente. Para obter mais informações, consulte Connect to OpenAPI Specification.

5. Certifique-se de selecionar Salvar.

6. Selecione Experimentar no playground e teste seu agente do Foundry com prompts como "Mostrar-me todas as tarefas" e "Adicione uma tarefa".

   Se você receber uma resposta válida, o agente está fazendo chamadas de ferramenta para o ponto de extremidade OpenAPI no seu aplicativo Web implantado.

1. No menu superior do novo portal do Foundry, selecione Operar e, em seguida, selecione Administrador. Na linha do projeto foundry, você deverá ver dois links. O que está na coluna Nome é o recurso do projeto Foundry, e o que está na coluna Recurso pai é o recurso Foundry.

   

2. Selecione o recurso Foundry no recurso Pai e, em seguida, selecione Gerenciar esse recurso no portal do Azure. No portal do Azure, você pode atribuir acesso baseado em função para o recurso ao aplicativo Web implantado.

3. Adicione a seguinte função para a identidade gerenciada do aplicativo do Serviço de Aplicativos:

   Recurso de destino	Função necessária	Necessário para
   Fundição	Usuário dos Serviços Cognitivos OpenAI	O serviço de conclusão de chat no Microsoft Agent Framework.

   Para obter instruções, confira Atribuir funções do Azure usando o portal do Azure.

1. No menu superior do novo portal do Foundry, selecione Operar e, em seguida, selecione Administrador. Na linha do projeto foundry, você deverá ver dois links. O que está na coluna Nome é o Recurso do Projeto Foundry, e o da coluna Recurso Pai é o Recurso Foundry.

   

2. Selecione o recurso do projeto Foundry na coluna Nome e, em seguida, selecione Gerenciar esse recurso no portal do Azure. No portal do Azure, você pode atribuir acesso baseado em função para o recurso ao aplicativo Web implantado.

3. Adicione a seguinte função à identidade gerenciada do App Service:

   Recurso de destino	Função necessária	Necessário para
   Projeto de fundimento	Usuário de IA do Azure	Lendo e chamando o agente do Foundry.

   Para obter instruções, confira Atribuir funções do Azure usando o portal do Azure.