Como publicar agents do Microsoft Agent Framework no ASP.NET
Hospedar o Microsoft Agent Framework no ASP.NET Core é o passo que transforma um agente de IA em um serviço acessível para outros sistemas. Com o framework, você cria agentes autônomos, orquestra fluxos multi-agente e os expõe por protocolos padronizados como A2A, AG-UI e endpoints compatíveis com OpenAI.
Este artigo percorre o processo completo de hospedagem de agents no ASP.NET Core. O caminho vai do registro via injeção de dependência até a exposição por protocolos modernos de comunicação entre agentes.
Os exemplos usam os pacotes de hospedagem na versão 1.0.0-preview.251110.2, de novembro de 2025. Como as bibliotecas ainda estão em preview, uma seção ao final resume o que mudou nas versões seguintes da integração A2A.
O que é o Microsoft Agent Framework
O Microsoft Agent Framework é um framework open source para construir agentes de IA de forma estruturada e extensível. Ele define o AIAgent como unidade fundamental, uma espécie de "wrapper de LLM" que processa entradas do usuário, toma decisões, chama ferramentas e gera respostas.
Diferente de soluções pontuais, o framework oferece suporte nativo à integração com APIs via OpenAPI. Além disso, ele permite colaboração entre runtimes com o protocolo Agent-to-Agent (A2A) e conexão dinâmica com ferramentas via MCP.
Se você ainda não conhece os conceitos básicos, a visão geral do Microsoft Agent Framework apresenta a arquitetura antes de chegarmos à hospedagem.
Opções de hospedagem do Agent Framework no ASP.NET
Antes de entrar na implementação, vale conhecer as quatro formas de expor agents com o Agent Framework no ASP.NET Core e em ambientes relacionados.
O protocolo A2A (Agent-to-Agent) é ideal para sistemas multi-agente, em que diferentes agents precisam se descobrir e se comunicar.
Os endpoints compatíveis com OpenAI, por sua vez, permitem que clientes OpenAI consumam os agents via Chat Completions ou Responses API.
Já o Azure Functions Durable atende cenários serverless com tarefas de longa duração.
Por fim, o protocolo AG-UI conecta agents a aplicações web. Ele funciona como a camada de interface entre o backend de IA e o frontend.
A biblioteca de hospedagem principal
A base para hospedar o Agent Framework no ASP.NET é o pacote Microsoft.Agents.AI.Hosting. Ele fornece extensões para IHostApplicationBuilder que simplificam o registro, a configuração e a exposição de agents por diferentes protocolos.
No ASP.NET Core, IHostApplicationBuilder representa o builder da aplicação hospedada e gerencia configuração, logging, ciclo de vida e muito mais. Assim, as bibliotecas de hospedagem se integram diretamente a esse ponto de extensão.
Segundo a documentação de hospedagem do Agent Framework, o pacote entrega quatro peças principais. São elas o AddAIAgent, o AddWorkflow com o encadeamento AddAsAIAgent, o IHostedAgentBuilder e um armazenamento opcional de sessões.
Vale um detalhe importante. O pacote de hospedagem não é um servidor HTTP, então a sua aplicação continua responsável pelo pipeline de middlewares, autenticação, autorização e armazenamento durável.
Registrando o IChatClient
Antes de registrar qualquer agent, você precisa configurar um IChatClient no contêiner de injeção de dependência. Esse client representa a conexão com o modelo de linguagem que alimenta os agents.
O exemplo abaixo usa Azure OpenAI com autenticação via DefaultAzureCredential:
// endpoint segue o formato https://<your-endpoint>.openai.azure.com/
// deploymentName indica o modelo, por exemplo gpt-4o-mini
IChatClient chatClient = new AzureOpenAIClient(
new Uri(endpoint),
new DefaultAzureCredential())
.GetChatClient(deploymentName)
.AsIChatClient();
builder.Services.AddSingleton(chatClient);
A variável endpoint segue o formato https://<your-endpoint>.openai.azure.com/. Já deploymentName indica o modelo a ser usado, como gpt-4o-mini.
A Microsoft faz um alerta sobre o DefaultAzureCredential. Ele é conveniente no desenvolvimento, mas em produção a recomendação é usar uma credencial específica, como ManagedIdentityCredential, para evitar latência e sondagens indesejadas de credenciais.
Registrando agents do Agent Framework no ASP.NET
Com o IChatClient configurado, o próximo passo do Agent Framework no ASP.NET é registrar o agent. O método AddAIAgent() retorna um IHostedAgentBuilder, que permite encadear configurações adicionais.
var pirateAgent = builder.AddAIAgent(
"pirate",
instructions: "You are a pirate. Speak like a pirate",
description: "An agent that speaks like a pirate.",
chatClientServiceKey: "chat-model");
Nesse código, o primeiro argumento é a chave pela qual o contêiner resolve o agent via IKeyedServiceProvider. As instructions definem o comportamento do agent, enquanto a description serve aos protocolos de descoberta, como o A2A.
O parâmetro chatClientServiceKey aponta para um IChatClient registrado com chave. Nesse caso, registre o client com builder.Services.AddKeyedSingleton("chat-model", chatClient) em vez do registro sem chave.
Adicionando ferramentas ao agent
Você adiciona ferramentas com o método WithAITool(). Qualquer tipo derivado de AITool pode entrar diretamente no builder do agent.
var pirateAgent = builder
.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate")
// MyTool é um tipo próprio derivado de AITool
.WithAITool(new MyTool());
Essa abordagem mantém as dependências do agent isoladas no mesmo contêiner e facilita o gerenciamento do ciclo de vida das ferramentas. Para entender como as ferramentas funcionam por dentro, veja o artigo sobre tools no Microsoft Agent Framework.
Session store do Agent Framework no ASP.NET
No Agent Framework no ASP.NET, o session store guarda o histórico de conversas por sessão. Para desenvolvimento ou testes, o armazenamento em memória é suficiente:
var pirateAgent = builder
.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate")
.WithInMemorySessionStore();
Em produção, porém, o ideal é substituir esse armazenamento por uma implementação persistente, como Redis ou um banco de dados relacional. Afinal, o estado em memória se perde quando a aplicação reinicia e não é compartilhado entre instâncias.
Orquestrando múltiplos agents com AddWorkflow
No Agent Framework no ASP.NET, um workflow é essencialmente um grafo em que cada nó representa um AIAgent. Os agents se comunicam seguindo a topologia definida no workflow.
Além disso, o framework oferece duas topologias nativas: sequencial e concorrente.
Workflow sequencial
No exemplo abaixo, o agent-1 processa primeiro a entrada do usuário e, em seguida, encaminha a resposta ao agent-2. A saída final é a resposta do último agent da cadeia.
builder.AddAIAgent("agent-1", instructions: "you are agent 1!");
builder.AddAIAgent("agent-2", instructions: "you are agent 2!");
var workflow = builder.AddWorkflow("my-workflow", (sp, key) =>
{
var agent1 = sp.GetRequiredKeyedService<AIAgent>("agent-1");
var agent2 = sp.GetRequiredKeyedService<AIAgent>("agent-2");
return AgentWorkflowBuilder.BuildSequential(key, [agent1, agent2]);
});
Assim, o método BuildSequential recebe a chave do workflow e a lista ordenada de agents. Para criar um fluxo concorrente, o método equivalente é BuildConcurrent.
Para cenários de orquestração mais elaborados, o artigo sobre workflows no Microsoft Agent Framework aprofunda o tema.
Expondo um workflow como AIAgent
As integrações de protocolo, como A2A e OpenAI, trabalham com instâncias de AIAgent, e não diretamente com workflows. Para contornar essa limitação, você converte o workflow em um agent autônomo com AddAsAIAgent().
var workflowAsAgent = builder
.AddWorkflow("science-workflow", (sp, key) => { ... })
.AddAsAIAgent();
Após essa conversão, você mapeia o workflow para qualquer protocolo suportado, exatamente como faria com um agent comum.
Expondo o Agent Framework no ASP.NET via A2A
O protocolo A2A define um padrão para que agents se descubram e troquem mensagens, independentemente da tecnologia em que foram construídos. Para expor o Agent Framework no ASP.NET via A2A, use o pacote Microsoft.Agents.AI.Hosting.A2A.AspNetCore.
Então, o fluxo básico envolve registrar o agent, adicionar o servidor A2A ao contêiner e mapear os endpoints na aplicação:
var pirateAgent = builder.AddAIAgent("pirate",
instructions: "You are a pirate. Speak like a pirate",
description: "An agent that speaks like a pirate.");
builder.Services.AddA2AServer();
var app = builder.Build();
app.MapA2AServer();
app.Run();
Nessa versão, o método MapA2AServer() registra os endpoints de descoberta (Agent Card) e de comunicação, seguindo a especificação A2A. Se você quer entender o protocolo em si, o artigo sobre comunicação entre agentes com o protocolo A2A explica o funcionamento.
Múltiplos agents do Agent Framework no ASP.NET
Com o Agent Framework no ASP.NET, você também pode mapear diferentes agents em endpoints distintos dentro da mesma aplicação. Basta garantir que os caminhos não colidam:
var mathAgent = builder.AddAIAgent("math", instructions: "You are a math expert.");
var scienceAgent = builder.AddAIAgent("science", instructions: "You are a science expert.");
app.MapA2A(mathAgent, "/a2a/math");
app.MapA2A(scienceAgent, "/a2a/science");
Na versão usada aqui, cada agent recebe o próprio Agent Card em GET /a2a/{name}/v1/card. Dessa forma, os clients descobrem as capacidades de cada agent de forma independente.
Agent Framework no ASP.NET com endpoints OpenAI
Além do A2A, o Agent Framework no ASP.NET conta com o pacote Microsoft.Agents.AI.Hosting.OpenAI, que expõe agents por endpoints compatíveis com as APIs da OpenAI. Com isso, qualquer cliente ou ferramenta que fale esse formato consegue conversar com o seu agent.
Na prática, o padrão segue a mesma lógica: registrar o protocolo no builder e mapear o agent na aplicação.
builder.AddOpenAIChatCompletions();
var pirateAgent = builder.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate.");
var app = builder.Build();
// expõe o agent pelo protocolo Chat Completions
app.MapOpenAIChatCompletions(pirateAgent);
app.Run();
Com essa configuração, o agent responde em POST /pirate/v1/chat/completions. Para a Responses API, os métodos equivalentes são AddOpenAIResponses() e MapOpenAIResponses(), e o caminho passa a ser /pirate/v1/responses.
A documentação recomenda a Responses API para aplicações novas. Por outro lado, a Chat Completions continua útil para integrações legadas e interações simples, sem estado no servidor.
Como as bibliotecas de hospedagem funcionam internamente
Por dentro, as bibliotecas do Agent Framework no ASP.NET atuam como adaptadores de protocolo entre a comunicação externa e a implementação interna de AIAgent.
Quando uma requisição chega, a biblioteca recupera o AIAgent registrado no contêiner de DI. Em seguida, ela envolve o agent com middleware específico do protocolo, traduz a requisição de entrada e a resposta de saída e invoca o agent para processar a mensagem.
Essa arquitetura mantém a implementação do agent completamente agnóstica ao protocolo. Portanto, o mesmo AIAgent pode ficar exposto ao mesmo tempo via A2A, OpenAI e AG-UI, sem qualquer modificação no código.
Esse desacoplamento entre agente e transporte também é o tema do artigo sobre channels no Microsoft Agent Framework, que mostra a evolução dessa ideia.
Pacotes NuGet do Agent Framework no ASP.NET
Para uma aplicação com o Agent Framework no ASP.NET Core, suporte a A2A e Azure OpenAI, o arquivo .csproj deve incluir as seguintes referências:
<ItemGroup>
<PackageReference Include="Microsoft.Agents.AI.Hosting.A2A.AspNetCore"
Version="1.0.0-preview.251110.2" />
<PackageReference Include="Azure.AI.OpenAI" Version="2.5.0-beta.1" />
<PackageReference Include="Azure.Identity" Version="1.17.0" />
<PackageReference Include="Microsoft.Extensions.AI" Version="9.10.2" />
<PackageReference Include="Microsoft.Extensions.AI.OpenAI"
Version="9.10.2-preview.1.25552.1" />
</ItemGroup>
Os pacotes Azure.Identity e Azure.AI.OpenAI cuidam da conexão com o Azure OpenAI. Já o Microsoft.Extensions.AI fornece as abstrações de IChatClient que o framework utiliza.
Os pacotes de integração de protocolo já referenciam o Microsoft.Agents.AI.Hosting. Por isso, você só precisa instalá-lo diretamente quando o host não usar nenhum pacote de protocolo.
Configuração via secrets e variáveis de ambiente
Para rodar o Agent Framework no ASP.NET com Azure OpenAI, a aplicação requer a configuração de AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_DEPLOYMENT_NAME. Em desenvolvimento, use o dotnet user-secrets para evitar credenciais no código ou em arquivos versionados.
dotnet user-secrets set "AZURE_OPENAI_ENDPOINT" "https://your-endpoint.openai.azure.com/"
dotnet user-secrets set "AZURE_OPENAI_DEPLOYMENT_NAME" "gpt-4o-mini"
No código, você recupera os valores normalmente via IConfiguration:
string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
Em produção, variáveis de ambiente ou um cofre de segredos substituem os user secrets, que existem apenas para a máquina do desenvolvedor.
Boas práticas para produção
Levar o Agent Framework no ASP.NET para produção exige alguns cuidados que o código de exemplo não mostra. Afinal, a documentação deixa claro que a aplicação continua dona da segurança e do armazenamento.
Primeiro, proteja os endpoints com autenticação e autorização, como faria com qualquer API. Além disso, valide as requisições e limite as opções de modelo que um cliente pode enviar.
Em seguida, troque todos os armazenamentos em memória por implementações duráveis. Isso vale para o session store e, nas versões mais novas do A2A, também para o armazenamento de tarefas.
Outro ponto envolve os identificadores de continuação, como os IDs de conversa e de resposta da API da OpenAI. A Microsoft orienta tratá-los como dados opacos, e não como credenciais, e verificar se o usuário autenticado é dono do ID antes de aceitá-lo.
Por fim, lembre que os pacotes de hospedagem .NET ainda são prerelease. Por isso, instale as versões prerelease de forma explícita e leia as notas de versão antes de atualizar um ambiente de produção.
O que mudou nas versões seguintes do A2A
Depois da versão usada neste artigo, a integração A2A do Agent Framework no ASP.NET migrou para o A2A SDK v1. Segundo o guia de migração oficial, trata-se de uma mudança incompatível.
Na prática, o registro do servidor virou uma etapa explícita, separada do mapeamento de endpoints. O MapA2A deu lugar ao AddA2AServer seguido de MapA2AHttpJson ou MapA2AJsonRpc.
var weatherAgentBuilder = builder.AddAIAgent("weather-agent",
instructions: "You are a helpful weather assistant.",
description: "A helpful weather assistant.");
// registra o servidor A2A para o agent
weatherAgentBuilder.AddA2AServer();
var app = builder.Build();
// mapeia os dois bindings do protocolo
app.MapA2AHttpJson(weatherAgentBuilder, "/a2a/weather-agent");
app.MapA2AJsonRpc(weatherAgentBuilder, "/a2a/weather-agent");
app.Run();
O Agent Card também saiu do mapeamento e ganhou uma chamada própria, MapWellKnownAgentCard, que publica o documento em /.well-known/agent-card.json. Contudo, apenas um Agent Card pode ser servido por host, então os demais agents ficam acessíveis diretamente pela URL.
Por fim, as opções A2AHostingOptions passaram a se chamar A2AServerRegistrationOptions. Se você parte do código deste artigo, revise esses pontos antes de atualizar os pacotes.
Conclusão
O Microsoft Agent Framework resolve um dos principais problemas ao publicar agents no ASP.NET Core: integrar a lógica de IA à infraestrutura da aplicação. Com AddAIAgent, AddWorkflow e os adaptadores de protocolo, você registra, configura e expõe agents de forma declarativa, aproveitando o contêiner de DI nativo do .NET.
A separação entre a implementação do agent e o protocolo de exposição é o ponto mais importante da arquitetura do Agent Framework no ASP.NET. Assim, você evolui e troca protocolos sem reescrever a lógica central dos agents, o que torna o sistema mais fácil de manter e de escalar.
FAQ
O Microsoft Agent Framework funciona sem Azure OpenAI?
Sim. Qualquer implementação de IChatClient pode entrar no contêiner, seja OpenAI direto, modelos locais ou outros provedores compatíveis com Microsoft.Extensions.AI.
É possível hospedar agents sem expor endpoints HTTP?
Sim. Os agents registrados via AddAIAgent ficam disponíveis no contêiner de DI e podem ser resolvidos e invocados no próprio código, sem rotas HTTP.
O que é o Agent Card no protocolo A2A?
É um documento JSON que descreve as capacidades e os endpoints de um agent. Outros agents e clients o utilizam para descobrir como interagir com ele.
Workflows podem ser compostos de outros workflows?
Sim, desde que cada workflow interno vire um AIAgent via AddAsAIAgent(). Isso permite hierarquias em que workflows de alto nível coordenam outros workflows.
Como persistir sessions em produção?
O WithInMemorySessionStore() serve apenas para desenvolvimento. Em produção, registre uma implementação durável, com Redis ou banco de dados relacional.
O protocolo AG-UI é diferente do A2A?
Sim. O A2A cuida da comunicação entre agents, enquanto o AG-UI padroniza a comunicação entre o agent e a interface do usuário, e os dois podem coexistir na mesma aplicação.