Uma visão geral do Microsoft Agent Framework
O Microsoft Agent Framework é uma biblioteca open source da Microsoft para construir agentes de inteligência artificial, com suporte nativo a .NET e Python. Ele oferece abstrações para ferramentas, memória, conversas multi-turno, workflows e hospedagem em infraestrutura de produção.
Neste artigo, você vai percorrer cada uma dessas camadas com exemplos em C#. Além disso, vai entender onde o framework se encaixa no ecossistema de IA da Microsoft e quando faz sentido adotá-lo.
O que é o Microsoft Agent Framework
O Microsoft Agent Framework surgiu como uma evolução natural do Semantic Kernel, mas com foco específico na camada de agentes. Na prática, a documentação oficial o apresenta como sucessor direto do Semantic Kernel e do AutoGen, criado pelas mesmas equipes.
Enquanto o Semantic Kernel oferece as primitivas de integração com modelos de linguagem, o Agent Framework constrói sobre elas uma API de alto nível. Essa API serve para criar, compor e expor agentes autônomos.
Segundo a visão geral oficial do Agent Framework, o projeto combina as abstrações simples do AutoGen com recursos corporativos do Semantic Kernel. Entre esses recursos estão o estado baseado em sessões, a segurança de tipos, os middlewares e a telemetria.
Por fim, o framework acrescenta workflows baseados em grafos para orquestrar vários agentes de forma explícita. Esse é o ponto que mais o diferencia dos seus antecessores.
O papel do AIAgent
A unidade central do framework é o AIAgent. Ele encapsula um modelo de linguagem (LLM), as instruções de comportamento, as ferramentas disponíveis e a lógica de cada ciclo de raciocínio.
Dessa forma, qualquer agente, seja simples ou composto por um workflow inteiro, expõe a mesma interface para quem o consome. Essa uniformidade facilita bastante a troca de implementações.
Uma trilha de aprendizado progressiva
O framework segue uma abordagem progressiva, estruturada em etapas: primeiro agente, ferramentas, conversas multi-turno, memória e persistência, workflows e hospedagem. Cada etapa é independente e incremental.
Assim, o desenvolvedor absorve os conceitos em camadas, sem implementar toda a complexidade de uma vez. Este artigo segue exatamente essa ordem.
O suporte a provedores de LLM também é extensível. Os exemplos em C# deste artigo usam o Azure OpenAI, com os pacotes Azure.AI.OpenAI e Microsoft.Agents.AI.OpenAI.
Contudo, a documentação atual também lista conectores para Microsoft Foundry, OpenAI, Anthropic, Ollama e outros. Por isso, a escolha do provedor não prende o restante do código.
Criando o primeiro agente no Microsoft Agent Framework
Criar um agente no Microsoft Agent Framework exige poucos pacotes NuGet e poucas linhas de código. Os pacotes necessários são Azure.AI.OpenAI, Azure.Identity e Microsoft.Agents.AI.OpenAI.
Na época da publicação original, os pacotes do framework estavam em pré-lançamento, por isso os comandos usam --prerelease:
dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
A criação do agente parte de um AzureOpenAIClient. Em seguida, o código obtém um cliente de chat e o transforma em um AIAgent por meio do método de extensão AsAIAgent.
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
?? throw new InvalidOperationException("Set AZURE_OPENAI_ENDPOINT");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
.GetChatClient(deploymentName)
.AsAIAgent(instructions: "You are a friendly assistant. Keep your answers brief.", name: "HelloAgent");
O AzureCliCredential reaproveita o login feito com az login, o que simplifica o desenvolvimento local. Em produção, porém, a recomendação oficial é usar uma credencial específica, como ManagedIdentityCredential.
Invocação simples e streaming
O método RunAsync faz uma invocação simples e devolve a resposta completa do agente. Ao passar esse resultado para o Console.WriteLine, você imprime o texto gerado pelo modelo.
Para respostas em streaming, o método RunStreamingAsync devolve um fluxo assíncrono de atualizações. Com isso, você processa cada fragmento de texto à medida que o modelo o gera.
// Invocação simples
Console.WriteLine(await agent.RunAsync("What is the largest city in France?"));
// Streaming
await foreach (var update in agent.RunStreamingAsync("Tell me a one-sentence fun fact."))
{
Console.Write(update);
}
Essa simplicidade na API de entrada é intencional. O framework busca reduzir a fricção inicial para que o desenvolvedor foque na lógica de negócio do agente.
Se você ainda está dando os primeiros passos com o tema, vale ler antes o artigo sobre o que são agents. Ele explica o conceito antes de qualquer código.
Tools no Microsoft Agent Framework
As ferramentas (tools) são o mecanismo pelo qual um agente executa ações no mundo externo. Por exemplo, ele pode consultar APIs, acessar bancos de dados ou executar funções de negócio.
No Microsoft Agent Framework para C#, qualquer método pode virar uma ferramenta. Para isso, basta descrevê-lo com o atributo [Description] do namespace System.ComponentModel.
using System.ComponentModel;
[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location to get the weather for.")] string location)
=> $"The weather in {location} is cloudy with a high of 15°C.";
O framework usa o AIFunctionFactory.Create para criar um objeto de ferramenta a partir do método. Depois, você entrega esse objeto ao agente pelo parâmetro tools.
using Microsoft.Extensions.AI;
AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
.GetChatClient(deploymentName)
.AsAIAgent(
instructions: "You are a helpful assistant.",
tools: [AIFunctionFactory.Create(GetWeather)]
);
Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));
O agente decide sozinho quando invocar a ferramenta, com base no conteúdo da mensagem do usuário. Ou seja, você não escreve nenhum código de roteamento.
O framework cuida da detecção de intenção, da montagem do payload da chamada e da interpretação do resultado. As descrições que você escreve nos atributos são justamente o que o modelo lê para tomar essa decisão.
Para se aprofundar nesse recurso, o artigo utilizando tools no Microsoft Agent Framework traz mais cenários práticos.
Aprovação humana de ferramentas
A documentação também descreve o conceito de tool approval. Esse recurso exige confirmação humana antes que uma ferramenta execute, viabilizando o padrão human-in-the-loop em produção.
Na prática, você envolve a função em um ApprovalRequiredAIFunction. Então, em vez de executar a ferramenta, o agente devolve um pedido de aprovação dentro da resposta.
AIFunction weatherFunction = AIFunctionFactory.Create(GetWeather);
AIFunction approvalRequiredWeatherFunction = new ApprovalRequiredAIFunction(weatherFunction);
AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
.GetChatClient(deploymentName)
.AsAIAgent(
instructions: "You are a helpful assistant.",
tools: [approvalRequiredWeatherFunction]
);
O chamador procura instâncias de ToolApprovalRequestContent na resposta e mostra a chamada ao usuário. Em seguida, envia a decisão de volta ao agente, na mesma sessão, com CreateResponse(true) ou CreateResponse(false).
Esse fluxo é recomendado para ferramentas com efeitos colaterais, como estornos, compras ou exclusão de dados. Afinal, uma decisão errada do modelo nesses casos custa caro.
Conversas multi-turno com AgentSession
Por padrão, cada invocação de RunAsync é stateless, ou seja, o agente não retém memória das chamadas anteriores. Para manter o histórico entre interações, o Microsoft Agent Framework oferece o conceito de AgentSession.
Você cria uma sessão com o método CreateSessionAsync e a passa como parâmetro em cada chamada seguinte ao agente.
AgentSession session = await agent.CreateSessionAsync();
// Primeira interação
Console.WriteLine(await agent.RunAsync("My name is Alice and I love hiking.", session));
// Segunda interação: o agente recorda o nome e o hobby
Console.WriteLine(await agent.RunAsync("What do you remember about me?", session));
A sessão encapsula o histórico de mensagens trocadas. Dessa forma, cada nova invocação recebe o contexto completo da conversa.
Esse modelo atende bem assistentes conversacionais, chatbots e qualquer aplicação em que o contexto acumulado melhora a qualidade das respostas. Além disso, a mesma sessão viabiliza o fluxo de aprovação de ferramentas visto na seção anterior.
Internamente, o estado da sessão pode ficar em memória ou em provedores externos, como mostra a próxima seção. O artigo sobre conversas multi-turnos no Microsoft Agent Framework detalha esse tema.
Memória e persistência no Microsoft Agent Framework
O gerenciamento de memória no Microsoft Agent Framework distingue dois conceitos. De um lado fica o histórico de conversas (chat history), e do outro, o contexto persistente que provedores injetam no agente.
Agentes que usam o Azure OpenAI Chat Completion recebem automaticamente um InMemoryChatHistoryProvider. Isso acontece porque esse serviço não armazena o histórico do lado do servidor, então o framework o guarda em memória.
Quando o cenário exige outro armazenamento, o framework expõe a opção ChatHistoryProvider por meio do ChatClientAgentOptions:
AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
.GetChatClient(deploymentName)
.AsAIAgent(new ChatClientAgentOptions()
{
ChatOptions = new() { Instructions = "You are a helpful assistant." },
ChatHistoryProvider = new CustomChatHistoryProvider()
});
Neste exemplo, CustomChatHistoryProvider representa uma classe sua que herda de ChatHistoryProvider. Combinando esse provedor com sessões, você persiste o histórico em banco de dados, cache distribuído ou outro armazenamento de produção.
AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Hello! What's the square root of 9?", session));
Console.WriteLine(await agent.RunAsync("My name is Alice", session));
Console.WriteLine(await agent.RunAsync("What is my name?", session));
Compondo provedores de contexto
O framework também permite compor vários provedores em cenários avançados. Um exemplo comum separa o histórico ativo da conversa de um armazenamento de auditoria.
Essa separação de responsabilidades é um padrão recomendado quando rastreabilidade e compliance são requisitos. Assim, o histórico usado pelo modelo continua enxuto, enquanto a auditoria guarda tudo.
O artigo sobre memória, armazenamento e provedores de contexto aprofunda essa arquitetura.
Workflows no Microsoft Agent Framework
Workflows encadeiam múltiplos passos de processamento. Cada passo recebe uma entrada, executa uma operação e passa o resultado para o próximo nó.
A abstração central dos workflows é o Executor, que representa um nó de processamento dentro do grafo. Em C#, você pode criar um executor a partir de uma função comum ou de uma classe que herda de Executor<TInput, TOutput>.
using Microsoft.Agents.AI.Workflows;
// Passo 1: converte o texto para maiúsculas
Func<string, string> uppercaseFunc = s => s.ToUpperInvariant();
var uppercase = uppercaseFunc.BindAsExecutor("UppercaseExecutor");
// Passo 2: inverte a string
class ReverseTextExecutor() : Executor<string, string>("ReverseTextExecutor")
{
public override ValueTask<string> HandleAsync(
string message,
IWorkflowContext context,
CancellationToken cancellationToken = default)
{
return ValueTask.FromResult(string.Concat(message.Reverse()));
}
}
Depois, o WorkflowBuilder conecta os executores por meio de arestas (AddEdge) e indica de qual nó sai a saída final. Por fim, o InProcessExecution executa o grafo dentro do próprio processo.
ReverseTextExecutor reverse = new();
WorkflowBuilder builder = new(uppercase);
builder.AddEdge(uppercase, reverse).WithOutputFrom(reverse);
var workflow = builder.Build();
await using Run run = await InProcessExecution.RunAsync(workflow, "Hello, World!");
foreach (WorkflowEvent evt in run.NewEvents)
{
if (evt is ExecutorCompletedEvent executorComplete)
{
// Exibe o resultado de cada executor concluído
Console.WriteLine($"{executorComplete.ExecutorId}: {executorComplete.Data}");
}
}
Orquestração de vários agentes
Além de workflows sequenciais, o framework oferece workflows concorrentes. Nesse caso, a classe AgentWorkflowBuilder expõe métodos como BuildSequential e BuildConcurrent, que executam agentes em sequência ou em paralelo e agregam os resultados.
A capacidade de compor agentes em grafos abre caminho para arquiteturas multiagente sofisticadas. Nelas, cada agente se especializa em uma etapa do pipeline e os resultados fluem de forma controlada.
Os workflows também suportam aprovação humana. Quando um agente do grafo chama uma ferramenta com ApprovalRequiredAIFunction, o workflow pausa e emite um evento de solicitação até receber a resposta.
Se quiser ver orquestrações completas, o artigo sobre como orquestrar a execução de agentes com workflows cobre o assunto em detalhes.
Hospedagem de agentes no Microsoft Agent Framework
Hospedar um agente significa expô-lo para que outros sistemas e usuários interajam com ele por protocolos padronizados. O Microsoft Agent Framework oferece quatro opções principais de hospedagem, cada uma adequada a um cenário.
| Opção | Melhor para |
|---|---|
| A2A Protocol | Sistemas multiagente |
| OpenAI-Compatible Endpoints | Clientes compatíveis com OpenAI |
| Azure Functions (Durable) | Tarefas serverless de longa duração |
| AG-UI Protocol | Frontends web |
Para integração com ASP.NET, o pacote Microsoft.Agents.AI.Hosting fornece extensões para IHostApplicationBuilder. Essas extensões simplificam o registro e a configuração de agentes no container de injeção de dependência.
Registrando o IChatClient e o agente
O primeiro passo é registrar um IChatClient no container de DI. Os agentes vão usá-lo como provedor de modelo.
IChatClient chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
.GetChatClient(deploymentName)
.AsIChatClient();
builder.Services.AddSingleton(chatClient);
O método AddAIAgent registra um agente no container e devolve um IHostedAgentBuilder. Com ele, você configura ferramentas e o armazenamento de sessões de forma fluente.
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");
Por exemplo, os métodos WithAITool e WithInMemorySessionStore acrescentam uma ferramenta e um armazenamento de sessões em memória ao agente registrado.
Para workflows multiagente, o método AddWorkflow registra o grafo no container. Em seguida, o método AddAsAIAgent converte esse workflow em um AIAgent, que então pode usar os protocolos de integração.
Expondo o agente via A2A
A exposição pelo protocolo A2A exige apenas duas chamadas após o registro do agente:
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();
As bibliotecas de hospedagem funcionam como adaptadores de protocolo. Elas buscam o AIAgent registrado no container, traduzem as requisições de entrada e as respostas de saída e invocam o agente.
Essa arquitetura separa completamente a lógica do agente do protocolo de comunicação. Portanto, o agente fica agnóstico em relação ao canal que o acessa.
Vale notar que a especificação do protocolo A2A evolui rápido, e versões recentes dos pacotes separam o registro do servidor do mapeamento de cada binding. Por isso, confira sempre a documentação da versão que você instalou.
Para um passo a passo completo, veja o artigo sobre como publicar agents no ASP.NET.
Quando adotar o Microsoft Agent Framework
O Microsoft Agent Framework faz mais sentido quando o agente precisa de ferramentas, estado e orquestração. Para uma única chamada ao modelo, o IChatClient do Microsoft.Extensions.AI costuma bastar.
Por outro lado, times que já usam Semantic Kernel ou AutoGen têm um caminho de migração documentado. A Microsoft publica guias específicos para os dois projetos.
Segundo a Visual Studio Magazine, a versão 1.0 chegou em abril de 2026 com APIs estáveis para .NET e Python. Mesmo assim, alguns pacotes, como os de hospedagem, continuam em pré-lançamento, então revise as notas de versão antes de atualizar a produção.
Por fim, lembre que a responsabilidade pelas mitigações de IA responsável continua com você. A própria documentação recomenda filtros de conteúdo, testes e revisão cuidadosa de qualquer sistema de terceiros conectado ao agente.
Conclusão
O Microsoft Agent Framework representa uma abordagem madura e incremental para construir agentes de IA em .NET. A API reduz a complexidade inicial e cresce aos poucos, sem exigir domínio de todos os conceitos de uma vez.
As abstrações de tools, sessões, memória, workflows e hospedagem formam um conjunto coeso. Juntas, elas endereçam os principais desafios de sistemas baseados em agentes autônomos.
Além disso, a integração nativa com injeção de dependência, ASP.NET e Azure torna o framework uma escolha natural para equipes da stack Microsoft. Assim, incorporar IA generativa às aplicações existentes fica mais simples.
FAQ
O Microsoft Agent Framework é open source?
Sim. O código está no GitHub, no repositório microsoft/agent-framework, com exemplos para .NET e Python.
O framework suporta outros provedores além do Azure OpenAI?
Sim. A arquitetura aceita qualquer provedor que implemente o IChatClient do Microsoft.Extensions.AI, e a documentação lista conectores para Foundry, OpenAI, Anthropic e Ollama, entre outros.
É possível usar o Agent Framework sem ASP.NET?
Sim. Agentes, ferramentas, sessões e workflows funcionam em aplicações console, workers e qualquer host .NET, enquanto o ASP.NET só entra na hospedagem via protocolos.
O que é o protocolo A2A?
O A2A (Agent-to-Agent) é um protocolo aberto de comunicação entre agentes de IA. Com ele, agentes criados em frameworks diferentes se descobrem e conversam de forma padronizada.
Como funciona o tool approval?
Você envolve a função em um ApprovalRequiredAIFunction, e o agente passa a devolver um pedido de aprovação. Depois, o chamador responde com a decisão do usuário na mesma sessão.
O histórico de conversa persiste automaticamente?
Por padrão, o histórico fica em memória durante a execução. Para sobreviver a reinicializações, você implementa e registra um ChatHistoryProvider próprio.
É possível usar workflows com mais de dois agentes?
Sim. Os builders encadeiam quantos executores forem necessários, de forma sequencial ou concorrente, formando grafos complexos.