Como criar um agente de IA do zero: o guia do operador

A palavra "agente" virou marketing. Quase tudo que se vende como agente é um chatbot com nome bonito. A diferença importa, porque um chatbot responde e um agente age: ele decide, usa ferramentas, executa passos e entrega um resultado.

Este guia é pra quem constrói. Mostra o que de fato compõe um agente, como montar a arquitetura, e onde eles costumam quebrar quando saem da demo e encaram a produção. É o que eu aplico construindo na FM Solutions e em colaborações técnicas.

A ideia em 1 minuto

Um agente de IA é um modelo de linguagem com três coisas que um chatbot não tem: ferramentas pra agir no mundo, memória pra não recomeçar do zero, e um laço de decisão que escolhe o próximo passo até cumprir o objetivo.

A forma mais simples de enxergar:

• Chatbot: você pergunta, ele responde. Fim.
• Agente: você dá um objetivo, ele planeja, chama ferramentas (buscar dado, criar registro, enviar mensagem), avalia o resultado e repete até terminar.

A peça que transforma um no outro são as tools (ferramentas que o modelo pode chamar) e o laço (deixar o modelo decidir e agir mais de uma vez). Se você só faz uma chamada e mostra o texto, é chatbot. Se o modelo chama funções e itera, é agente.

As peças de um agente

Antes de codar, entenda o que precisa existir. Um agente de produção tem cinco componentes.

1. O modelo (o cérebro)

   O LLM que raciocina e decide. Use o mais capaz que couber no seu custo para as decisões difíceis, e um mais barato para tarefas simples. Misturar modelos por tarefa é o que mantém a conta sob controle.

2. As tools (as mãos)

   Funções que o modelo pode chamar: consultar o banco, criar um pedido, enviar um e-mail, buscar na web. Cada tool tem um nome, uma descrição e parâmetros. A qualidade da descrição decide se o modelo usa a ferramenta certa.

3. A memória (o histórico)

   Curto prazo (a conversa atual) e longo prazo (o que ele aprendeu sobre o usuário e o negócio). Sem memória, o agente reexplica tudo a cada interação e parece amnésico.

4. O contexto (quem ele é)

   As instruções de sistema: o papel, as regras, o que nunca fazer, o tom. É o que alinha o comportamento ao seu negócio.

5. O laço de controle (a vontade)

   A lógica que deixa o modelo agir, ver o resultado e decidir o próximo passo, com um limite de iterações pra não rodar pra sempre.

A arquitetura mínima que funciona

Não precisa de framework gigante pra começar. O laço de um agente cabe em poucas linhas de pseudocódigo, e entender isso evita que você se perca em abstração.

objetivo = "qualificar este lead e agendar uma call"
historico = [instrucoes_de_sistema, objetivo]

repita ate concluir ou atingir limite:
    resposta = modelo(historico, tools_disponiveis)

    se resposta pede pra usar uma tool:
        resultado = executa_tool(resposta.tool, resposta.args)
        historico.adiciona(resultado)
    senao:
        retorna resposta   # o agente terminou

É isso. O modelo olha o histórico e as ferramentas, decide se age ou responde, você executa a ferramenta e devolve o resultado pro histórico, e repete. Toda a "inteligência" do agente está em dar boas ferramentas e bom contexto, não em código esperto.

Tools: onde os agentes ganham ou perdem

A diferença entre um agente que funciona e um que alucina está quase toda nas ferramentas. Três regras que mudam o jogo.

1. Descreva a tool como se explicasse pra um estagiário

   O modelo escolhe a ferramenta pela descrição. "busca_cliente: encontra um cliente pelo email ou telefone, retorna nome, histórico e status" funciona. "busca_cliente: busca cliente" não.

2. Valide a entrada e a saída

   O modelo às vezes manda parâmetro errado. Valide antes de executar e devolva um erro claro que ele consiga corrigir, em vez de quebrar.

3. Dê poucas ferramentas boas, não muitas

   Vinte ferramentas confundem o modelo. Comece com as 3 ou 4 essenciais pro objetivo. Você adiciona conforme a necessidade real aparece.

Onde os agentes quebram em produção

A demo sempre funciona. A produção é que separa o brinquedo do produto. Estes são os pontos de falha mais comuns.

Observabilidade: você não pode consertar o que não vê

Agente em produção sem log é uma caixa preta. Registre cada decisão: qual tool foi chamada, com quais argumentos, qual resultado voltou. Quando algo der errado (e vai dar), você lê o rastro e entende onde a decisão furou, em vez de adivinhar.

Um roteiro de 4 passos pra sua primeira versão

1. Escolha um objetivo estreito

   Não "um agente que faz tudo". Algo como "qualificar lead e agendar". Estreito é o que você consegue terminar e medir.

2. Liste as 3 tools que esse objetivo exige

   Pro exemplo: buscar cliente, checar agenda, criar agendamento. Só isso.

3. Escreva o contexto e monte o laço na mão

   Instruções de sistema claras + o laço simples lá de cima. Rode no terminal antes de pensar em interface.

4. Teste com casos reais e adicione guarda-corpos

   Jogue conversas de verdade, veja onde quebra, e adicione validação, limite e confirmação humana onde for sensível.

Construir é uma coisa. Colocar pra rodar no negócio é outra

Montar o agente é a parte divertida. O que costuma travar é integrar com os sistemas reais da empresa (WhatsApp, banco de dados, agenda) e mantê-lo confiável em produção. É exatamente o tipo de trabalho que a FM Solutions faz em projetos sob medida e advisory técnico.

Se você tem um projeto de agente em mente e quer acelerar a parte difícil, a FM Solutions faz um diagnóstico gratuito.

Agende seu diagnóstico em fmsolutions.ai