.NET - Criando Agentes de IA com o Microsoft Agent Framework

Neste artigo veremos como criar Agentes de IA usando o Microsoft Agent Framework.

Continuando o artigo anterior, hoje vamos criar um projeto base de um Agente de IA focado em:
  - A Integração correta com IA
  - Uso consciente do Microsoft.Extensions.AI
  - Uso correto do Agent Framework
  - Separação mínima de responsabilidades
  - Código legível e ensinável

Visão geral do projeto

Vamos criar um projeto Console usando o .NET 10 que demonstra:

✔ Criação de um agente
✔ Uso de instructions (personalidade)
✔ Uso de threads (memória)
✔ Integração com OpenAI (facilmente trocável por Azure OpenAI ou Ollama)
✔ Registro de tools em C#
✔ Organização mínima correta

Você pode usar o Visual Studio ou aplicar estes comandos:

A seguir vamos instalar os seguintes pacotes: (A versão dos pacotes pode variar...)

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

Todos os pacotes ainda estão em preview em janeiro de 2026 , mas :

- O modelo mental não vai mudar
- A abstração Microsoft.Extensions.AI já é GA
- O Agent Framework é o caminho oficial da Microsoft

 Estrutura de pastas da aplicação:

AgentBaseDemo
│
├── Program.cs
│
├── Agents
│ └── TechnicalAssistantAgent.cs
│
├── Tools
│ └── DateTimeTools.cs
│
└── Configuration
└── AiSettings.cs 

Para usar a API da OpenAI você vai precisar criar uma API Key e definir o modelo gpt-4o-mini usado neste exemplo.

Criando a configuração : AiSettings

namespace AgentBaseDemo.Configuration;

/// <summary>
/// Centraliza configurações relacionadas à IA.
/// Em projetos reais, isso viria de appsettings.json ou Key Vault.
/// </summary>
public sealed class AiSettings
{
    public string ApiKey { get; init; } = string.Empty;
    public string Model { get; init; } = "gpt-4o-mini";
}

O AiSettings tem o papel de centralizar e isolar as configurações da IA, como chave de acesso e modelo utilizado, evitando que esses detalhes fiquem espalhados pelo código.

Ele separa configuração de comportamento, facilitando manutenção, testes e troca de providers (OpenAI, Azure OpenAI, Ollama).

Além disso, prepara o projeto para boas práticas de produção, como uso de appsettings.json, variáveis de ambiente ou Key Vault.

Didaticamente, deixa claro que o agente depende de configuração externa, não de valores “hardcoded”.

Criando a Tool do agente (função C# chamável pela IA)

using System.ComponentModel; using Microsoft.Extensions.AI; namespace AgentBaseDemo.Tools; /// <summary> /// Tools são métodos C# normais que o agente pode invocar. /// O Agent Framework decide QUANDO chamá-los. /// </summary> public sealed class DateTimeTools { [Description("Retorna a data e hora atual do sistema")] public string GetCurrentDateTime() { return DateTime.Now.ToString("dd/MM/yyyy HH:mm:ss"); } }

 

A Tool do agente é um método C# exposto para que a IA possa executar ações no mundo externo, indo além de apenas gerar texto.

Ela permite que o agente consuma lógica da aplicação, dados ou serviços reais (data/hora, banco, APIs).

O papel dela é estender as capacidades do agente de forma controlada e segura.
Assim, o agente decide quando usar a tool, mas o como é sempre código .NET.

Destacando que :

- Você não escreve lógica de decisão
- O modelo escolhe quando chamar
- O método só precisa ser claro e bem descrito

Definindo o Agente

Na pasta Agents vamos criar a classe TechnicalAssistantAgent.cs

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using AgentBaseDemo.Tools;

namespace AgentBaseDemo.Agents;

/// <summary>
/// Encapsula a criação do agente.
/// Isso evita espalhar detalhes de IA pelo código.
/// </summary>
public static class TechnicalAssistantAgent
{
    public static AIAgent Create(IChatClient chatClient)
    {
        return chatClient.CreateAIAgent(
            name: "TechnicalAssistant",
            

            // Instructions definem o comportamento permanente do agente
            instructions: """
            Você é um assistente técnico especializado em .NET e C#.
            Responda de forma objetiva, técnica e didática.
            Quando não souber algo, diga explicitamente.
            """,

            // Registro das tools disponíveis para o agente
            tools: [
                AIFunctionFactory.Create(new DateTimeTools().GetCurrentDateTime)
            ]
        );
    }
}

Neste código está o coração do Agent Framework :
    instructions = identidade do agente
    tools = capacidades externas
    O agente não é stateless (isso vem via thread)

Juntando todas as partes no arquivo Program:

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

// ===============================
// CONFIGURAÇÃO BÁSICA
// ===============================

var settings = new AiSettings
{
    ApiKey = "SUA_API_KEY_AQUI"
};

// ===============================
// CRIAÇÃO DO CLIENTE DE IA
// ===============================

/*
 * Microsoft.Extensions.AI define a abstração IChatClient.
 * Isso permite trocar OpenAI, Azure OpenAI ou Ollama
 * sem alterar o código do agente.
 */
IChatClient chatClient =
    new OpenAIClient(settings.ApiKey)
        .GetChatClient(settings.Model)
        .AsIChatClient();

// ===============================
// CRIAÇÃO DO AGENTE
// ===============================

AIAgent agent = TechnicalAssistantAgent.Create(chatClient);

// ===============================
// THREAD = MEMÓRIA DO AGENTE
// ===============================

/*
 * A thread mantém o histórico da conversa.
 * Sem thread -> agente stateless.
 */
AgentThread thread = agent.GetNewThread();

// ===============================
// LOOP DE CONVERSA
// ===============================

Console.WriteLine("Agente iniciado. Digite uma pergunta ou 'sair'.\n");

while (true)
{
    Console.Write("> ");
    var input = Console.ReadLine();

    if (string.IsNullOrWhiteSpace(input))
        continue;

    if (input.Equals("sair", StringComparison.OrdinalIgnoreCase))
        break;

    // O agente executa considerando:
    // - Instructions
    // - Histórico da thread
    // - Tools disponíveis
    var response = await agent.RunAsync(input, thread);

    Console.WriteLine($"\nAgente: {response}\n");
}

O que este projeto prova na prática

✔ O código funciona
✔ Está alinhado com a arquitetura oficial da Microsoft
✔ Usa Agent Framework corretamente

O que NÃO foi feito de propósito :

❌ Não usamos appsettings.json (menos ruído)
❌ Não usamos DI ainda (entra no próximo módulo)
❌ Não usamos persistência de threads (entra depois)
❌ Não misturamos RAG aqui (responsabilidade separada)

Neste artigo, construímos do zero um agente de IA na plataforma .NET utilizando o Microsoft Agent Framework (MAF), aplicando as abstrações oficiais da Microsoft para criação de agentes com identidade, memória e capacidade de ação. Vimos que um agente não é apenas um prompt, mas uma composição clara de instructions (comportamento), threads (estado e memória) e tools (integração com código C# e o mundo externo).

Ao utilizar o Microsoft.Extensions.AI como camada de abstração, garantimos que o agente não fique acoplado a um provedor específico de IA, permitindo trocar OpenAI, Azure OpenAI ou Ollama sem impacto na lógica do agente. Já o MAF entra como a camada responsável pelo comportamento agentic: orquestração, uso de ferramentas, manutenção de contexto e evolução para cenários mais avançados, como múltiplos agentes e fluxos condicionais.

Embora o Agent Framework ainda esteja em preview, a arquitetura apresentada segue as premissas corretas para aplicações .NET modernas, sendo didática, extensível e alinhada com o caminho oficial da plataforma. Este projeto base serve tanto como ponto de partida para aplicações reais quanto como material sólido para ensino, permitindo evoluções naturais para Web APIs, RAG, agentes especializados e cenários multi-agente.

Em resumo, o Microsoft Agent Framework representa o modelo futuro de desenvolvimento de agentes de IA em .NET, e compreender seus fundamentos agora coloca o desenvolvedor em uma posição estratégica para construir soluções inteligentes, sustentáveis e preparadas para produção.

E estamos conversados...  

"Como, pois, recebestes o Senhor Jesus Cristo, assim também andai nele,Enraizados e edificados nele, e confirmados na fé, assim como fostes ensinados, nela abundando em ação de graças"
Colossenses 2:6,7