Pular para o conteúdo
PTEN

O que é um agente de IA? Guia com exemplos reais

O que é um agente de IA, como ele difere de um chatbot e de uma automação, quais são suas partes e quando não usar, com exemplos de projetos reais.

Um agente de IA é um programa em que um modelo de linguagem decide, passo a passo, quais ferramentas chamar para cumprir um objetivo. Ele lê o pedido, escolhe uma ação (buscar um cliente, criar um orçamento, consultar uma base), olha o resultado e decide o próximo passo, até terminar ou parar num limite. A diferença para um chatbot é que o agente age em sistemas reais, e não só responde texto.

Eu construo agentes de IA em produção: um agente operacional dentro de um SaaS para empreiteiras, um agente de atendimento para WhatsApp e servidores MCP que dão dados a agentes. Este guia explica o que é um agente de IA, de que partes ele é feito e quando ele é a escolha errada.

O que é um agente de IA, na prática

Todo agente de IA tem quatro coisas:

  1. Um objetivo, que vem do pedido do usuário ("manda o orçamento do Smith").
  2. Um modelo de linguagem, que interpreta o pedido e decide o que fazer.
  3. Ferramentas, que são funções do seu sistema que o modelo pode pedir para executar.
  4. Um loop, que roda a ferramenta, devolve o resultado ao modelo e pergunta de novo o que fazer.

O modelo nunca executa nada sozinho. Ele devolve um pedido estruturado ("chame search_clients com name: Smith"), e o seu código decide se roda, roda e devolve o resultado. Esse mecanismo se chama tool calling (ou function calling). Um exemplo genérico do loop:

for (let i = 0; i < MAX_ITERATIONS; i++) {
  const response = await model.call({ messages, tools });
  const calls = response.toolCalls;
  if (calls.length === 0) return response.text; // terminou

  for (const call of calls) {
    const tool = tools.find((t) => t.name === call.name);
    const result = await tool.execute(ctx, call.arguments);
    messages.push({ role: "tool", id: call.id, content: truncate(result) });
  }
}
return "Parei no limite de passos.";

Quase tudo que importa num agente de IA mora em volta dessas linhas: quais ferramentas existem, o que elas podem fazer, quem é o usuário, quanto o loop pode rodar e o que fica registrado.

Agente de IA, chatbot e automação: qual a diferença

Muita gente chama estas quatro coisas pelo mesmo nome.

  • Chatbot com roteiro segue uma árvore de decisões desenhada antes. Mostra um menu, espera "1" ou "2". Se o cliente sai do roteiro, ele trava.
  • Chatbot com LLM conversa bem, mas só responde texto. Ele não consulta seu banco nem muda nada.
  • Automação de fluxo fixo executa sempre a mesma sequência: chegou um formulário, cria um registro, manda um e-mail. É previsível e barata, mas cada caminho novo precisa ser desenhado à mão.
  • Agente de IA escolhe a sequência em tempo de execução, entre as ações que você liberou. Duas perguntas parecidas podem gerar caminhos diferentes.

O ganho é flexibilidade. O custo é que a saída deixa de ser determinística, e por isso um agente precisa de mais controle em volta do que uma automação.

As partes de um agente de IA

O modelo

O modelo é a parte mais fácil de trocar. No LedgerJob, um SaaS para empresas de construção nos EUA, escrevi o loop do agente direto sobre a Responses API da OpenAI, com streaming da resposta via SSE. No DockPlus Atendimento, o modelo é configurável por agente, OpenAI ou Anthropic.

As ferramentas (tool calling)

As ferramentas definem o que o agente consegue fazer. Cada uma tem nome, descrição, parâmetros em JSON Schema e uma função que executa. A descrição é lida pelo modelo para decidir quando usar a ferramenta, então ela é instrução, não comentário.

O agente do LedgerJob tem 66 ferramentas: leads, orçamentos, projetos, faturas, agenda, contratos de serviço e QuickBooks. A mesma lista é exposta por um servidor MCP, então Claude Code ou outro cliente usa as mesmas ferramentas que o chat do app. Expliquei como isso funciona em o que é um servidor MCP.

Ferramenta também pode ser só leitura de dados. O Cape Cod Permits e o Achado de Leilão são servidores MCP que dão a um agente acesso a alvarás de obra de Massachusetts e a leilões oficiais no Brasil. Nos dois, as descrições orientam o agente, por exemplo a checar a cobertura de cada município antes de comparar números.

O loop e seus limites

Um loop sem teto pode chamar ferramentas para sempre e gastar tokens numa pergunta só. No LedgerJob o loop tem teto de 8 iterações por turno, e o resultado de cada ferramenta é cortado em 6.000 caracteres, com um aviso pedindo um filtro mais específico.

Memória e contexto

O modelo não lembra de nada entre chamadas. Memória é o histórico que você manda de volta a cada passo, mais o que o agente consegue buscar.

No LedgerJob o histórico da conversa é persistido no banco, junto com o registro do consumo de tokens. No DockPlus Atendimento, o estado do grafo LangGraph é salvo no Postgres, e as dúvidas são respondidas com RAG sobre a base de conhecimento da empresa. Se o agente precisa responder sobre documentos, comece por o que é RAG.

Contexto também é o que o agente não pode escolher. No LedgerJob, tenant, usuário e papel vêm da sessão ou da API key, nunca de um argumento que o modelo preenche. O agente age com as permissões de quem pediu.

Limites e confirmação humana

Um agente que só lê dados erra e você corrige na próxima pergunta. Um agente que manda e-mail ou apaga um registro erra uma vez só.

No LedgerJob, 16 das 66 ferramentas exigem confirmação humana: as que mandam mensagem, gastam dinheiro com terceiros ou mudam dados de forma permanente. Elas não rodam dentro do loop. Viram um card que o usuário confirma, e o resultado volta ao histórico para o modelo não afirmar algo que não aconteceu. O passo a passo, com código, está em confirmação humana em agentes de IA.

Outro limite é saber parar. No DockPlus Atendimento, a passagem para um humano é um nó do grafo, com motivo registrado: cliente pediu atendente, sentimento negativo, agente não achou a resposta. Detalhei isso em agente de IA para WhatsApp.

Regra que tirei desses projetos: o limite que importa está no código ou no banco, não no prompt. O prompt pede; o código garante.

Observabilidade

Sem registro de cada passo, uma resposta errada não diz se a culpa foi do modelo, da ferramenta ou dos dados. No AgentLab, meu laboratório de estudos de arquitetura de agentes, um grafo LangGraph de 5 nós mostra no chat o log de execução de cada nó, com tempo, e manda o trace para o Langfuse. O mesmo grafo tem um nó de validação que pede nova resposta até 2 vezes se a primeira não passar. Na DockPlus uso o Langfuse para acompanhar latência, custo de tokens e qualidade das respostas.

Tipos de agentes de IA, com exemplos

Não existe uma taxonomia oficial. Estes são os formatos que construí:

  • Agente operacional dentro de um produto. O usuário opera o sistema conversando, como no LedgerJob: o agente cria orçamentos, busca faturas vencidas e agenda visitas.
  • Agente de atendimento. Responde clientes no WhatsApp, Telegram ou e-mail, agenda e passa para um humano quando precisa, como o DockPlus Atendimento.
  • Agente sobre dados. Um agente genérico (como o Claude) que ganha acesso a uma base específica por MCP. Exemplos: Cape Cod Permits e Achado de Leilão.
  • Agente de programação. Lê e edita código, roda comandos e testes. Eu desenvolvo com o Claude Code, que é um agente desse tipo: uso um agente para construir agentes.

Quando não usar um agente de IA

Agente não é a resposta padrão. Eu não usaria quando:

  • O caminho é sempre o mesmo. Se toda entrada segue os mesmos passos, uma automação de fluxo fixo ou uma função comum é mais barata, mais rápida e mais fácil de testar.
  • O erro não tem volta e não há quem revise. Se não dá para pôr confirmação humana e um erro custa caro, o agente não deve ter essa ferramenta.
  • A resposta exige um número exato. Cálculo de imposto ou fechamento de caixa é código, não modelo. O agente pode chamar a função que calcula, mas não deve calcular.

Como começar a construir um agente de IA

  1. Escreva o loop sem framework. Um modelo, duas ferramentas, um teto de iterações. Você entende o que LangGraph e afins fazem por você.
  2. Comece por ferramentas de leitura. Buscar e listar não estragam nada. Escrita vem depois.
  3. Classifique cada ferramenta. Leitura, escrita reversível, irreversível. A última pede confirmação humana.
  4. Ponha a regra de negócio no service. No LedgerJob, o assistente conseguiu agendar "das 18h às 17h" porque a validação estava só na rota HTTP. A regra foi para o service, com teste.
  5. Registre tudo. Cada chamada de modelo e de ferramenta, com tempo e tokens.

Se quiser entender o trabalho em volta disso, escrevi sobre o que faz um engenheiro de IA.

Resumo

Um agente de IA é um modelo que escolhe ferramentas num loop até cumprir um objetivo. O trabalho está nas ferramentas, nos limites do loop, na identidade, na confirmação humana e no registro de cada passo.

Os projetos citados estão em projetos, e minha trajetória em sobre. Se você quer um agente de IA agindo sobre os dados do seu sistema, fale comigo.

Todos os artigos