Criando seu primeiro Agente de IA

O que é o Microsoft Agent Framework

O Microsoft Agent Framework é um conjunto de bibliotecas .NET que reduz a complexidade de construir um agente de IA. A Microsoft projetou o framework para atender desde chatbots simples até sistemas com vários agentes, sempre com o mínimo de código boilerplate.

O framework nasce sobre tecnologias já consolidadas. O Semantic Kernel fornece orquestração robusta, o AutoGen traz a colaboração avançada entre múltiplos agentes e o Microsoft.Extensions.AI entrega os blocos de construção padronizados para IA em .NET.

Na prática, isso significa que você não precisa escolher entre os dois projetos anteriores. Em vez disso, ganha uma base única, com a mesma abstração para conversar com diferentes provedores de modelo.

Para uma visão mais ampla do framework, leia também o artigo sobre o Microsoft Agent Framework aqui no blog.

Conceitos fundamentais: agentes e workflows

Antes de escrever código, vale entender os dois blocos centrais do framework. Eles definem como você vai pensar a solução desde o início.

Pré-requisitos para criar um agente de IA

Para acompanhar os exemplos, você precisa do .NET 9 ou superior instalado na máquina. O .NET 10 oferece melhor integração com o Agent Framework, mas o .NET 8 e o .NET 9 também têm suporte.

Você também vai precisar de uma chave de API de um provedor compatível, como OpenAI ou Azure OpenAI. Neste artigo, os exemplos usam o cliente da OpenAI.

Por segurança, guarde a chave em uma variável de ambiente, e não no código. Nos exemplos, a leitura acontece com Environment.GetEnvironmentVariable("OPENAI_API_KEY").

Instalação dos pacotes

Primeiro, crie um projeto de console e entre na pasta dele.

dotnet new console -n MyFirstAgent
cd MyFirstAgent

Em seguida, adicione as dependências via NuGet. O artigo usa as versões de preview disponíveis na época da publicação.

dotnet add package Microsoft.Agents.AI.OpenAI --version 1.0.0-preview.251219.1
dotnet add package Microsoft.Extensions.AI.OpenAI --version 10.1.1-preview.1.25612.2
dotnet add package Azure.AI.OpenAI --version 2.1.0

Os pacotes Microsoft.Extensions.AI.OpenAI e Microsoft.Agents.AI.OpenAI estavam em preview nesse momento. Por isso, fixe as versões no arquivo de projeto para evitar quebras causadas por atualizações automáticas.

Criando o primeiro agente de IA

Com os pacotes instalados, o código para criar e executar um agente de IA fica direto. Veja o exemplo completo no Program.cs.

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;

// Lê a chave da API a partir de uma variável de ambiente
var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;

AIAgent agent = new OpenAIClient(apiKey)
    .GetChatClient("gpt-4o-mini")
    .AsIChatClient()
    .CreateAIAgent(instructions: "You help developers find accurate technical information.");

var response = await agent.RunAsync("What is C#?");
Console.WriteLine(response);

O método CreateAIAgent transforma um IChatClient em um agente pronto para uso. Portanto, qualquer provedor que exponha um IChatClient pode servir de base.

O parâmetro instructions define o comportamento e a personalidade do agente. Em outras palavras, ele equivale ao system prompt de uma conversa com o modelo.

Usando o Azure OpenAI como provedor

O pacote Azure.AI.OpenAI, instalado no início, permite trocar a OpenAI pelo Azure OpenAI com poucas mudanças. Nesse caso, você informa o endpoint do recurso e o nome do deployment do modelo.

using Azure;
using Azure.AI.OpenAI;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// Lê o endpoint e a chave do recurso a partir de variáveis de ambiente
var endpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!);
var key = new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY")!);

AIAgent agent = new AzureOpenAIClient(endpoint, key)
    .GetChatClient("gpt-4o-mini")
    .AsIChatClient()
    .CreateAIAgent(instructions: "You help developers find accurate technical information.");

Repare que apenas a criação do cliente mudou. Depois do AsIChatClient, o restante do código continua idêntico ao exemplo com a OpenAI.

No Azure, o valor passado para GetChatClient é o nome do deployment que você criou no recurso. Portanto, ele pode ser diferente do nome do modelo.

Essa troca simples mostra na prática o valor do IChatClient. Afinal, o seu agente de IA fica independente do provedor escolhido.

Execução sem streaming e com streaming

O framework oferece dois modos de execução do agente. A escolha depende de como você quer entregar a resposta ao usuário.

Para uma execução simples, sem streaming, use RunAsync. Nesse caso, o código espera a resposta completa antes de seguir.

var response = await agent.RunAsync("Explain what dependency injection is.");
Console.WriteLine(response);

Para streaming, que entrega o texto aos poucos à medida que o modelo o gera, use RunStreamingAsync.

await foreach (var update in agent.RunStreamingAsync("Explain what dependency injection is."))
{
    Console.Write(update);
}

O método RunStreamingAsync retorna um IAsyncEnumerable de atualizações. Com isso, a interface mostra o texto enquanto o modelo ainda responde, o que melhora bastante a percepção de velocidade.

Em geral, o streaming faz mais sentido em chats e interfaces interativas. Por outro lado, o RunAsync funciona melhor em processamentos em lote ou quando outra etapa precisa da resposta inteira.

Configurando o agente de IA com injeção de dependência

Em aplicações ASP.NET Core ou com IHostBuilder, o framework se integra ao contêiner de injeção de dependência. Para isso, ele usa as extensões do pacote Microsoft.Agents.AI.Hosting, que também estava em preview.

dotnet add package Microsoft.Agents.AI.Hosting --prerelease

Com o pacote instalado, registre o agente de IA no Program.cs com o método AddAIAgent.

// Program.cs
var builder = WebApplication.CreateBuilder(args);

var apiKey = builder.Configuration["OpenAI:ApiKey"]!;

IChatClient chatClient = new OpenAIClient(apiKey)
    .GetChatClient("gpt-4o-mini")
    .AsIChatClient();

builder.Services.AddAIAgent("assistant", (sp, key) =>
{
    return new ChatClientAgent(
        chatClient,
        name: key,
        instructions: "You are a technical assistant specialized in .NET."
    );
});

var app = builder.Build();

O AddAIAgent registra um agente nomeado no contêiner. Então, para receber essa instância em um serviço, use o atributo [FromKeyedServices] com o mesmo nome.

public class AssistantService
{
    private readonly AIAgent _agent;

    public AssistantService([FromKeyedServices("assistant")] AIAgent agent)
    {
        _agent = agent;
    }

    public async Task<string> AnswerAsync(string question)
    {
        AgentRunResponse response = await _agent.RunAsync(
            new ChatMessage(ChatRole.User, question)
        );
        return response.Text;
    }
}

Dessa forma, o agente segue as mesmas práticas que você já usa no restante da aplicação. Para revisar o funcionamento do contêiner, veja o artigo sobre dependency injection no ASP.NET Core.

Adicionando ferramentas ao agente de IA

Uma das capacidades mais importantes de um agente de IA é o uso de ferramentas externas. Sem elas, o modelo depende apenas do que aprendeu no treinamento.

No Microsoft Agent Framework, você registra as ferramentas diretamente no agente. Além disso, elas podem ser funções C# comuns, descritas com o atributo [Description].

using System.ComponentModel;

[Description("Returns the current temperature for a city.")]
static string GetTemperature(
    [Description("City name")] string city)
{
    // Simulação de chamada a uma API de clima
    return $"The temperature in {city} is 22°C.";
}

AIAgent agent = chatClient
    .CreateAIAgent(
        instructions: "You are a weather assistant.",
        tools: [AIFunctionFactory.Create(GetTemperature)]
    );

var response = await agent.RunAsync("What is the temperature in São Paulo?");
Console.WriteLine(response);

O AIFunctionFactory.Create lê a assinatura e as descrições da função para montar o esquema que o modelo recebe. Por isso, descrições claras ajudam o modelo a decidir quando chamar cada ferramenta.

O agente decide sozinho quando e como chamar a ferramenta, com base na intenção do usuário. Para explorar o assunto em mais detalhes, leia sobre tools no Microsoft Agent Framework.

Conversas com várias rodadas no agente de IA

Nos exemplos anteriores, cada chamada a RunAsync funciona de forma isolada. Ou seja, o agente de IA não lembra o que o usuário disse na mensagem anterior.

Para manter o histórico, o framework usa uma thread de conversa. Você cria a thread uma vez e a repassa em cada execução, como mostra o exemplo.

// Cria uma thread para guardar o histórico da conversa
AgentThread thread = agent.GetNewThread();

Console.WriteLine(await agent.RunAsync("My name is Ana.", thread));
Console.WriteLine(await agent.RunAsync("What is my name?", thread));

Na segunda chamada, o agente consegue responder o nome, porque a thread carrega as mensagens anteriores. Sem ela, o modelo não teria essa informação.

Esse recurso é a base de qualquer chat real. Para conhecer os detalhes, leia sobre conversas multi-turnos no Microsoft Agent Framework.

Boas práticas para as instruções do agente de IA

As instruções definem boa parte da qualidade de um agente de IA. Por isso, vale tratá-las com o mesmo cuidado que você dá ao código.

Primeiro, mantenha o agente focado em uma tarefa. Instruções curtas e específicas costumam gerar respostas mais previsíveis do que um texto que tenta cobrir tudo.

Em seguida, descreva o tom, o formato da resposta e os limites do agente. Por exemplo, deixe claro se ele deve responder apenas sobre .NET ou recusar perguntas fora do escopo.

Também vale explicar quando usar cada ferramenta. Embora o modelo leia as descrições das funções, uma orientação nas instruções reduz chamadas desnecessárias.

Por fim, teste as instruções com perguntas reais e ajuste aos poucos. Como o comportamento do modelo pode variar, pequenos ajustes no texto costumam trazer ganhos visíveis.

Integração com MCP

O Microsoft Agent Framework também se integra a servidores MCP. Com isso, os agentes consomem ferramentas externas publicadas pelo Model Context Protocol.

Esse recurso amplia bastante o alcance do agente. Afinal, ele passa a interagir com sistemas como GitHub, bancos de dados, APIs empresariais e qualquer servidor MCP compatível.

A vantagem é que a mesma lógica de ferramentas continua valendo. Em vez de escrever cada integração à mão, você aponta o agente para um servidor que já expõe essas capacidades.

Para entender o protocolo, confira o artigo o que é MCP.

Observabilidade com OpenTelemetry

Em produção, saber o que o agente fez é tão importante quanto a resposta final. Por isso, o framework oferece suporte nativo ao OpenTelemetry.

Essa integração permite rastreamento distribuído, monitoramento e depuração do comportamento dos agentes. Segundo a documentação de observabilidade do Agent Framework, o framework segue as convenções semânticas de GenAI do OpenTelemetry.

Para habilitar, adicione os pacotes do OpenTelemetry ao projeto.

dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Exporter.Console

Em seguida, instrumente o agente e configure o provedor de traces com o mesmo nome de fonte.

using OpenTelemetry;
using OpenTelemetry.Trace;

const string SourceName = "MyFirstAgent";

// Instrumenta o agente com OpenTelemetry
agent = agent.AsBuilder()
    .UseOpenTelemetry(sourceName: SourceName)
    .Build();

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(SourceName)
    .AddConsoleExporter()
    .Build();

O nome passado em AddSource precisa bater com o nome usado na instrumentação. Caso contrário, o provedor não recebe nenhum trace do agente de IA.

Além disso, evite registrar dados sensíveis em produção, porque prompts, respostas e argumentos de ferramentas podem conter informações dos usuários.

Para ir além, veja o artigo sobre observabilidade de agentes e workflows.

Considerações importantes sobre o preview

O Microsoft Agent Framework estava em preview no momento da publicação deste artigo. Por isso, nomes de métodos e tipos podem mudar entre as versões.

Fixe as versões dos pacotes no arquivo de projeto e acompanhe as notas de versão. Assim, você se prepara para possíveis breaking changes antes de atualizar.

Também vale isolar o código do agente em poucos pontos da aplicação, como um serviço dedicado. Dessa forma, uma mudança de API no framework afeta apenas um lugar, e não o projeto inteiro.

Outro cuidado envolve os custos. Cada chamada ao modelo consome tokens, então monitore o uso desde os primeiros testes, principalmente quando o agente de IA chama ferramentas em sequência.

A Microsoft mantém a documentação oficial em learn.microsoft.com/en-us/agent-framework. Além disso, o repositório Agent Framework Samples cobre desde o primeiro agente até sistemas com vários agentes, RAG e workflows baseados em grafos.

Conclusão

O Microsoft Agent Framework representa uma mudança concreta na forma de construir aplicações com IA em .NET. Com poucas linhas, você cria um agente de IA, executa com ou sem streaming e adiciona ferramentas.

A abstração sobre IChatClient e a integração com injeção de dependência, ferramentas e observabilidade tornam esse desenvolvimento acessível. Ao mesmo tempo, você mantém as práticas já estabelecidas no ecossistema .NET.

Para equipes que já trabalham com ASP.NET Core e Microsoft.Extensions.AI, a curva de aprendizado é pequena. Portanto, o primeiro agente de IA pode sair do papel ainda hoje.

FAQ

Qual versão do .NET preciso para usar o Agent Framework?

O artigo usa o .NET 9 ou superior. O .NET 10 oferece melhor integração, mas o .NET 8 e o .NET 9 também têm suporte.

Posso usar outro provedor além da OpenAI?

Sim. Como o agente se apoia no IChatClient, qualquer provedor que exponha essa interface pode servir de base, como o Azure OpenAI.

Qual a diferença entre RunAsync e RunStreamingAsync?

O RunAsync devolve a resposta completa de uma vez. Já o RunStreamingAsync entrega o texto aos poucos, enquanto o modelo gera a resposta.

Como o agente sabe quando usar uma ferramenta?

O modelo analisa a intenção do usuário e as descrições das funções registradas. Por isso, descrições claras com [Description] fazem diferença.

Posso usar o Agent Framework em produção?

No momento da publicação, os pacotes estavam em preview. Fixe as versões e acompanhe as notas de lançamento antes de adotar em produção.