Você precisa mesmo de um Agente?
   Este artigo aborda a discussão trazida pela inteligência artificial generativa sobre a necessidade de construir agentes de IA ou utilizar chamadas convencionais a modelos de linguagem, utilizando C# e .NET. (Gerado com ajuda da IA , ajustado e revisado por Macoratti)

A inteligência artificial generativa trouxe uma nova discussão para o desenvolvimento de software: precisamos construir agentes de IA para resolver nossos problemas ou podemos continuar utilizando chamadas convencionais a modelos de linguagem?

 

A resposta depende do problema que estamos tentando resolver.

Nos últimos anos, tornou-se comum chamar praticamente qualquer aplicação que utiliza um LLM de agente de IA. Uma aplicação que envia um prompt para um modelo e apresenta a resposta já é frequentemente descrita dessa forma. Outras aplicações disponibilizam ferramentas, consultam APIs, acessam bancos de dados e executam tarefas, recebendo a mesma denominação.

Entretanto, essas soluções não são necessariamente equivalentes.

Uma chamada convencional a um modelo de linguagem pode ser suficiente para resumir documentos, explicar um trecho de código, classificar informações ou responder a uma pergunta. Um agente passa a fazer sentido quando precisamos que o modelo participe da decisão sobre os próximos passos para alcançar um objetivo, utilizando as capacidades disponíveis e considerando os resultados obtidos durante a execução.

Neste artigo, vamos explorar essa diferença utilizando C# e a plataforma .NET. Primeiro, construiremos uma aplicação que conversa diretamente com um modelo de IA. Depois, adicionaremos ferramentas utilizando Microsoft.Extensions.AI e, finalmente, veremos como construir um agente com o Microsoft Agent Framework.

Para os exemplos, utilizaremos o modelo llama3.2, executado localmente pelo Ollama, com o pacote OllamaSharp como integração com o .NET.

O objetivo não é apenas demonstrar como implementar um agente, mas compreender quando precisamos realmente dele e quando uma solução mais simples é a melhor escolha.

Neste tutorial prático, vamos cobrir:
• 1. O que é um agente de IA?
• 2. Chamada direta, fluxo determinístico e agente
• 3. Preparando o ambiente .NET
• 4. Exemplo 1 — Conversando diretamente com o LLM
• 5. Exemplo 2 — Utilizando ferramentas com Microsoft.Extensions.AI
• 6. Exemplo 3 — Construindo um agente com Microsoft Agent Framework
• 7. Comparando as três abordagens
• 8. Cuidados importantes ao desenvolver agentes
• 9. Conclusão — Você precisa mesmo de um agente?

Vamos lá.

1. O que é um agente de IA?

Um agente de IA é um sistema que utiliza um modelo de inteligência artificial para interpretar um objetivo, tomar decisões sobre os próximos passos e executar ações permitidas para tentar alcançar esse objetivo.

Em sistemas baseados em modelos de linguagem, o LLM pode analisar uma solicitação, selecionar uma ferramenta, interpretar o resultado de sua execução e decidir se deve realizar outra ação ou apresentar a resposta final.

É importante distinguir três elementos:
• LLM: o modelo de linguagem que interpreta informações e gera respostas ou solicitações de ações.
• Aplicação: o software que fornece contexto, disponibiliza recursos e controla a execução.
• Agente: o sistema que utiliza o modelo e os recursos disponíveis para conduzir uma tarefa, participando das decisões sobre como prosseguir.

Um agente não é simplesmente um LLM com um prompt maior. Também não é definido exclusivamente pela presença de ferramentas.
A característica fundamental é a participação do modelo na decisão sobre como conduzir a tarefa.

Os principais componentes

Um sistema baseado em agente pode combinar os seguintes componentes:
• Modelo de IA: Interpreta a solicitação, analisa o contexto e produz respostas ou solicitações de ações.
• Instruções e contexto: Definem o objetivo, as orientações de comportamento e as informações relevantes para a execução.
• Ferramentas: Permitem consultar dados, acessar APIs, executar operações de negócio e utilizar recursos externos.
• Runtime e controle de execução: Coordena as interações, executa as ferramentas autorizadas, administra o estado e controla os limites da tarefa.

Memória persistente, múltiplos agentes e workflows complexos podem fazer parte de uma solução, mas não são requisitos obrigatórios para todo agente.

2. Chamada direta, fluxo determinístico e agente: qual é a diferença?

Antes de escrever código, precisamos distinguir três abordagens que podem utilizar exatamente o mesmo modelo de IA.

Abordagem 1 — Chamada direta ao LLM

A aplicação envia uma solicitação para o modelo e recebe uma resposta.
Por exemplo, podemos perguntar:  "Explique a diferença entre uma interface e uma classe abstrata em C#."
O modelo recebe a mensagem e gera uma resposta. O fluxo da aplicação é controlado pelo código que realizou a chamada.

Essa abordagem é adequada para tarefas como:
• Resumir um texto.
• Explicar código.
• Gerar documentação.
• Classificar informações.
• Responder a perguntas com base no contexto fornecido.

Não precisamos de um agente para realizar essas tarefas simplesmente porque estamos utilizando inteligência artificial.

Abordagem 2 — Fluxo determinístico com IA

Imagine uma aplicação que precisa gerar um relatório de vendas. A sequência é conhecida:
1. Consultar as vendas no banco de dados.
2. Calcular o total vendido.
3. Agrupar os resultados por categoria.
4. Enviar os dados para o modelo produzir uma explicação.
5. Apresentar o relatório.

A aplicação define antecipadamente a ordem das operações. A IA participa da geração do relatório, mas não precisa decidir quais etapas executar.
Esse é um fluxo determinístico que utiliza IA.

Abordagem 3 — Sistema baseado em agente

Agora considere uma aplicação que precisa investigar por que uma API está respondendo lentamente.

A tarefa pode exigir:
• Consultar métricas de desempenho.
• Examinar logs de erros.
• Verificar configurações.
• Comparar tempos de execução.
• Investigar hipóteses com base nos resultados encontrados.

Não sabemos antecipadamente qual investigação será necessária em todos os casos.
O modelo pode decidir consultar as métricas primeiro, interpretar o resultado e, dependendo das informações obtidas, solicitar uma consulta aos logs. Depois, pode verificar uma configuração específica ou concluir que já possui evidências suficientes.

Nesse cenário, delegar ao modelo parte da decisão sobre os próximos passos pode ser útil.
A distinção não é absoluta. Uma aplicação pode combinar etapas determinísticas com um agente responsável por uma parte específica da tarefa.

3. Preparando o ambiente .NET

Vamos utilizar um projeto Console para concentrar os exemplos e facilitar a comparação entre as abordagens.

Os requisitos são:
• .NET 10 SDK ou versão compatível com os pacotes escolhidos.
• Ollama instalado e em execução.
• Modelo llama3.2 disponível localmente.
• Pacotes OllamaSharp, Microsoft.Extensions.AI e Microsoft.Agents.AI.

Primeiro, baixe o modelo:

ollama pull llama3.2

Verifique se ele está disponível:

ollama list

Crie o projeto e instale os pacotes:

dotnet new console -n AgentesIA
cd AgentesIA
dotnet add package OllamaSharp
dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Agents.AI

O Ollama normalmente disponibiliza sua API local em http://localhost:11434.

O OllamaSharp implementa a abstração IChatClient do Microsoft.Extensions.AI, permitindo utilizar o mesmo modelo de programação sem acoplar o código de aplicação diretamente à API específica do Ollama.

A documentação do Microsoft Agent Framework pode apresentar APIs ou requisitos de versão diferentes conforme a versão instalada. Para reproduzir os exemplos, confira a compatibilidade entre o pacote e o SDK .NET utilizado.

4. Exemplo 1 — Conversando diretamente com o LLM

Vamos começar pela solução mais simples.

O objetivo é enviar uma pergunta para o modelo llama3.2 e apresentar a resposta no console.

using Microsoft.Extensions.AI;
using OllamaSharp;

IChatClient chatClient = new OllamaApiClient(new Uri("http://localhost:11434"), "llama3.2");

var resposta = await chatClient.GetResponseAsync(
    "Explique a diferença entre uma classe e uma interface em C#.");

Console.WriteLine(resposta.Text);

Observe a simplicidade da implementação.
Criamos um cliente de chat, enviamos uma pergunta e recebemos a resposta. Não precisamos implementar ferramentas, gerenciar um ciclo de decisões ou configurar um runtime de agentes.

Também não estamos limitados ao Ollama por causa do contrato utilizado. A aplicação depende da interface IChatClient, enquanto OllamaApiClient fornece a integração concreta com o provedor.

A abstração IChatClient é justamente uma das principais contribuições do Microsoft.Extensions.AI: padronizar a interação com diferentes provedores de IA.

Quando essa abordagem é suficiente?
Se o objetivo é explicar código, resumir informações ou responder a perguntas com base no conteúdo enviado, uma chamada direta pode resolver o problema.

Adicionar um agente a essa aplicação, sem existir necessidade de decisões sobre ações ou etapas, aumentaria a complexidade sem necessariamente trazer benefícios.

5. Exemplo 2 — Utilizando ferramentas com Microsoft.Extensions.AI

Agora vamos evoluir a aplicação.

Imagine que queremos construir um assistente capaz de responder perguntas sobre um projeto .NET. Para isso, disponibilizaremos duas ferramentas:

 • ObterInformacoesProjeto(): retorna informações sobre o projeto.
• ObterVersaoDotnet(): retorna a versão do .NET utilizada no ambiente.

O modelo poderá solicitar a execução dessas ferramentas quando considerar que elas são necessárias.

Aqui surge um conceito importante: tool calling não significa que o modelo executa diretamente o código C#.
O modelo recebe a descrição das ferramentas e pode produzir uma solicitação de chamada com argumentos. A aplicação ou o runtime executa a operação permitida e devolve o resultado para que o modelo continue a resposta.

Definindo as ferramentas
Crie uma classe chamada FerramentasProjeto.cs:

public sealed class FerramentasProjeto
{
    public string ObterInformacoesProjeto()
    {
        return """
            Nome: Sistema de Pedidos
            Plataforma: ASP.NET Core
            Persistência: Entity Framework Core
            Banco de dados: SQLite
            Arquitetura: Clean Architecture
            """;
    }

    public string ObterVersaoDotnet()
    {
        return Environment.Version.ToString();
    }
}

Esses métodos são operações comuns de C#. Eles não possuem inteligência artificial e não precisam conhecer o modelo.

Em uma aplicação real, poderiam consultar arquivos do projeto, APIs, bancos de dados ou serviços internos. Os exemplos retornam dados fixos ou informações do ambiente apenas para manter o foco no mecanismo de integração.

Registrando e executando as ferramentas

Agora, substitua o conteúdo de Program.cs pelo código abaixo:

using Microsoft.Extensions.AI;
using OllamaSharp;

var ferramentasProjeto = new FerramentasProjeto();

IChatClient chatClient = new OllamaApiClient(
    new Uri("http://localhost:11434"),
    "llama3.2");

chatClient = new ChatClientBuilder(chatClient)
    .UseFunctionInvocation()
    .Build();

var ferramentas = new List<AITool>
{
    AIFunctionFactory.Create(
        ferramentasProjeto.ObterInformacoesProjeto),
    AIFunctionFactory.Create(
        ferramentasProjeto.ObterVersaoDotnet)
};

var opcoes = new ChatOptions
{
    Tools = ferramentas
};

var pergunta = """
    Analise as informações do projeto.
    Informe a arquitetura, o banco de dados e a versão do .NET.
    Utilize as ferramentas disponíveis quando necessário.
    """;

var resposta = await chatClient.GetResponseAsync(
    pergunta,
    opcoes);

Console.WriteLine(resposta.Text);

await chatClient.DisposeAsync();

A utilização de AIFunctionFactory.Create permite transformar métodos .NET em ferramentas que podem ser descritas ao modelo. Já UseFunctionInvocation() adiciona ao cliente o mecanismo de invocação automática dessa ferramenta.

O que acontece durante a execução?
1. A pergunta é enviada: O modelo recebe a pergunta e as descrições das ferramentas disponíveis.
2. O modelo solicita uma ferramenta: Por exemplo, solicita ObterInformacoesProjeto para descobrir os dados da aplicação.
3. O código C# é executado: O mecanismo de invocação chama o método e devolve seu resultado ao modelo.
4. A resposta é produzida: O modelo utiliza os resultados para compor a resposta final. Se necessário, pode solicitar outra ferramenta.

Repare que disponibilizamos duas ferramentas, mas não escrevemos uma sequência de if/else para determinar qual método deve ser executado. A escolha é delegada ao modelo, dentro das opções permitidas.

Isso não significa que a escolha será sempre correta. A seleção depende da qualidade do modelo, das descrições das ferramentas e do suporte do modelo e do provedor ao recurso de tool calling.

O llama3.2 deve ser testado no ambiente utilizado: o comportamento pode variar conforme a versão do modelo, o runtime e o suporte às chamadas de ferramentas. Se o modelo produzir uma resposta textual em vez de uma chamada de ferramenta, a aplicação não deve presumir que a operação foi executada.

Isso já é um agente?
Temos uma aplicação com IA, ferramentas e invocação dinâmica. Entretanto, o exemplo, por si só, demonstra principalmente o mecanismo de tool calling.
Para ensinar o conceito de agente com mais precisão, precisamos introduzir uma abstração que represente o agente e sua execução. É isso que faremos com o Microsoft Agent Framework.

6. Exemplo 3 — Construindo um agente com Microsoft Agent Framework

O Microsoft Agent Framework oferece abstrações específicas para construir agentes e coordenar sua execução.

Uma de suas vantagens é permitir que o desenvolvedor trabalhe com um contrato de agente, em vez de implementar manualmente toda a estrutura necessária para representar e executar essa abstração.

O framework oferece a classe abstrata AIAgent e implementações como ChatClientAgent, que utiliza um IChatClient para interagir com o modelo. Portanto, podemos continuar usando OllamaSharp como provedor, sem precisar trocar o modelo de IA.

Vamos utilizar as mesmas ferramentas do exemplo anterior.

Criando o agente
Substitua o conteúdo de Program.cs pelo seguinte código:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OllamaSharp;

var ferramentasProjeto = new FerramentasProjeto();

IChatClient chatClient = new OllamaApiClient(
    new Uri("http://localhost:11434"),
    "llama3.2");

var ferramentas = new List<AITool>
{
    AIFunctionFactory.Create(
        ferramentasProjeto.ObterInformacoesProjeto),
    AIFunctionFactory.Create(
        ferramentasProjeto.ObterVersaoDotnet)
};

AIAgent agente = chatClient.AsAIAgent(
    name: "AssistenteProjeto",
    instructions: """
        Você é um assistente especializado em projetos .NET.
        Utilize as ferramentas disponíveis para obter informações
        que não estejam presentes na conversa.
        Não invente dados sobre o projeto.
        Se não conseguir obter uma informação, informe essa limitação.
        """,
    tools: ferramentas);

var resposta = await agente.RunAsync("""
    Analise o projeto e informe sua arquitetura,
    o banco de dados utilizado e a versão do .NET.
    Explique brevemente o papel de cada tecnologia.
    """);

Console.WriteLine(resposta.Text);

await chatClient.DisposeAsync();

A extensão AsAIAgent cria um agente baseado no IChatClient existente, permitindo fornecer nome, instruções e ferramentas. A API atual documenta essa extensão no namespace Microsoft.Extensions.AI, com implementação no pacote Microsoft.Agents.AI.

Observe a mudança na estrutura.

No exemplo anterior, configuramos um IChatClient com invocação de ferramentas e passamos as opções para a chamada de chat. Agora, criamos explicitamente um agente, definimos suas instruções e disponibilizamos as ferramentas na configuração do agente.
A responsabilidade de conduzir a interação passa a ser representada pela abstração AIAgent.

O que mudou na prática?
• O modelo de IA continua sendo o mesmo: llama3.2.
• O provedor continua sendo o mesmo: Ollama, acessado por OllamaSharp.
• As ferramentas também continuam sendo métodos C#.
• O que mudou foi a abstração utilizada para organizar a solução.

Aspecto Microsoft.Extensions.AI Microsoft Agent Framework
Abstração principal IChatClient AIAgent
Objetivo Interagir com o modelo e compor capacidades Representar e executar agentes
Ferramentas AIFunction e FunctionInvokingChatClient Ferramentas associadas ao agente
Instruções do agente Podem ser fornecidas por mensagens ou opções do chat Podem ser definidas na configuração do agente
Conversas e estado Gerenciados pela aplicação e pelas abstrações utilizadas Possui abstrações específicas para sessões e histórico
Workflows e orquestração Podem ser implementados com código e componentes auxiliares Oferece recursos próprios para cenários de agentes e workflows

Essas bibliotecas não são concorrentes diretas. O Microsoft Agent Framework utiliza abstrações do Microsoft.Extensions.AI e pode trabalhar com qualquer provedor que implemente IChatClient, desde que os recursos necessários sejam compatíveis.

Uma observação importante: o Microsoft.Extensions.AI também possui recursos para invocação automática de ferramentas e construção de pipelines. Portanto, não seria correto afirmar que somente o Agent Framework permite executar chamadas de ferramentas ou implementar interações em várias etapas.
A diferença está principalmente no nível de abstração e nos recursos que cada biblioteca oferece para organizar a solução.

7. Comparando as três abordagens

Vamos consolidar o que vimos até agora.

• Chamada direta ao LLM: Quando a aplicação já sabe o que fazer. O código envia a pergunta e recebe uma resposta. É a opção mais simples para tarefas que não exigem execução de ações.
• Microsoft.Extensions.AI com ferramentas: Quando precisamos integrar o modelo às capacidades da aplicação. O modelo pode solicitar ferramentas, e a aplicação executa as operações permitidas. É possível construir fluxos de tool calling sem adotar necessariamente uma abstração de agente.
• Microsoft Agent Framework: Quando queremos organizar a solução em torno de agentes. Disponibiliza abstrações próprias para instruções, execução, sessões e composição de agentes e workflows.

A escolha não deve ser feita apenas com base na quantidade de código ou no framework mais recente. O importante é identificar a necessidade real da aplicação.

Quando utilizar cada abordagem?
Cenário Abordagem recomendada
Explicar um trecho de código C# Chamada direta ao LLM
Resumir um documento Chamada direta ao LLM
Consultar uma informação por meio de uma ferramenta conhecida Microsoft.Extensions.AI com tool calling
Executar um processo com etapas fixas Código determinístico, com IA quando necessário
Investigar um problema com várias hipóteses possíveis Considerar um agente
Delegar tarefas a agentes especializados e coordenar suas execuções Avaliar o Microsoft Agent Framework

Essas recomendações não são regras absolutas. Um agente pode ser utilizado em uma etapa de um workflow determinístico, e uma aplicação com ferramentas pode resolver um problema complexo sem precisar de um agente.

8. Cuidados importantes ao desenvolver agentes

A capacidade de escolher ferramentas dinamicamente também introduz riscos que não existem da mesma forma em uma sequência totalmente determinística.

• Controle de permissões: disponibilize somente as ferramentas necessárias. Um agente que consulta dados não precisa receber automaticamente permissão para excluir registros.
• Validação de argumentos: nunca considere os argumentos produzidos pelo modelo confiáveis apenas porque foram gerados por IA.
• Limites de execução: defina limites para iterações, tempo de execução e consumo de recursos.
• Tratamento de erros: uma ferramenta pode falhar, retornar dados incompletos ou ficar indisponível. O sistema precisa lidar com essas situações.
• Avaliação do modelo: teste se o modelo realmente seleciona as ferramentas apropriadas e interpreta corretamente seus resultados. Não presuma que todo modelo oferece suporte confiável a tool calling.
• Custos e desempenho: múltiplas interações com o modelo podem aumentar a latência e o consumo de recursos. Um processo determinístico pode ser mais rápido, previsível e econômico.

Esses cuidados são especialmente importantes quando as ferramentas acessam sistemas corporativos, dados sensíveis ou operações que produzem efeitos externos.

Resumo

• Abordagem Direta: Ideal para resumos, explicações e respostas baseadas no contexto sem execução de ações.

• Tool Calling: Permite que o modelo solicite a execução de métodos .NET através do Microsoft.Extensions.AI.

• Microsoft Agent Framework: Oferece abstrações robustas para gerenciamento de agentes, sessões e fluxos complexos.

• Arquitetura Consciente: Comece sempre pela solução mais simples e introduza agentes apenas quando houver necessidade real de tomada de decisão dinâmica.

9. Conclusão — Você precisa mesmo de um agente?

A resposta é: depende do problema que você precisa resolver.

Se sua aplicação precisa receber uma pergunta, enviar um prompt e apresentar uma resposta, uma chamada direta ao LLM pode ser suficiente.

Se precisa consultar uma API, obter dados de um banco ou executar métodos C# escolhidos com base na solicitação do usuário, o Microsoft.Extensions.AI oferece abstrações para integrar o modelo às ferramentas disponíveis.

Se a aplicação precisa conduzir tarefas nas quais o modelo participa da decisão sobre os próximos passos, interpretar resultados e coordenar ações, o Microsoft Agent Framework pode oferecer uma estrutura mais adequada.

O ponto fundamental é que nem toda aplicação com IA precisa ser um agente, e nem toda aplicação que utiliza ferramentas precisa adotar um framework de agentes.

Como desenvolvedores .NET, devemos escolher a arquitetura que melhor atende aos requisitos de previsibilidade, segurança, manutenção, custo e complexidade do problema.

Comece pela solução mais simples que atende aos requisitos. Introduza um agente quando a necessidade de decisões dinâmicas e condução de tarefas justificar essa complexidade.

Afinal, a qualidade de uma solução não é determinada pela quantidade de inteligência artificial que ela utiliza, mas pela capacidade de resolver o problema de maneira confiável, segura e sustentável.

Referências técnicas
• Microsoft.Extensions.AI — documentação oficial
• Usando IChatClient — Microsoft Learn
• Chamadas de ferramentas em .NET — Microsoft Learn
• Conceitos de agentes — Microsoft Agent Framework
• OllamaSharp — repositório oficial

Nota sobre os exemplos: o código ilustra as APIs e os padrões de integração descritos. Antes de utilizá-lo em um curso ou projeto, valide a compilação com as versões efetivamente instaladas e teste o suporte a chamadas de ferramentas do llama3.2 no ambiente Ollama utilizado.

E estamos conversados..

"Ninguém pode servir a dois senhores; porque ou há de odiar um e amar o outro, ou se dedicará a um e desprezará o outro. Não podeis servir a Deus e a Mamom."
Mateus 6:24a

Referências:

José Carlos Macoratti