LangChain ou sem framework: como montar um agente de IA

LangChain ou sem framework: como montar um agente de IA

Para o primeiro agente de IA de uma empresa, um laço simples com o SDK do provedor costuma bastar. O LangChain passa a compensar quando o fluxo cresce e a estrutura que ele traz economiza mais trabalho do que cria. A pergunta útil não é qual opção é melhor, e sim quem vai manter e depurar o agente daqui a alguns meses.

Principais pontos

• Um agente, no núcleo, é um laço: o modelo recebe contexto, decide se chama uma ferramenta, a ferramenta executa, o resultado volta ao modelo. Isso cabe em poucas dezenas de linhas com o SDK do provedor.
• Framework ajuda quando há muitas integrações, fluxos com estado e ramificações, ou várias pessoas precisando de um vocabulário comum. Não ajuda por si só a acertar o comportamento do agente.
• O custo escondido de um framework aparece na depuração: mais camadas entre você e o prompt real que foi enviado ao modelo.
• A decisão não é para sempre. Se o laço simples estiver bem separado (ferramentas, prompt, registro), migrar depois é viável. O contrário também.
• Limites, aprovação humana, logs e avaliação pesam mais no resultado do que a escolha da biblioteca.

O que é um agente, de fato, quando se tira o framework

A documentação da Anthropic sobre agentes descreve a diferença entre fluxos de trabalho, em que o código define o caminho, e agentes, em que o modelo decide o próximo passo usando ferramentas. Em ambos os casos o miolo é pequeno. Você monta uma lista de mensagens, envia ao modelo junto com a descrição das ferramentas disponíveis, lê a resposta e, se houver pedido de ferramenta, executa e devolve o resultado. Repete até o modelo responder sem pedir nada ou até um limite de passos ser atingido.

Quem enxerga esse laço com clareza decide melhor. Tudo o mais é decoração útil ou desnecessária: memória de conversa, busca em documentos, tentativas após falha, registro, aprovação humana. Cada item pode ser escrito à mão ou vir pronto de uma biblioteca. A escolha entre LangChain e nenhum framework é, na prática, a escolha sobre quais desses itens você quer receber prontos e a que preço de abstração.

Quando um framework ajuda de verdade

Há situações em que escrever tudo à mão vira retrabalho. As mais comuns:

• Muitas integrações: o agente precisa falar com vários provedores de modelo, bancos vetoriais e fontes de documentos, e você não quer manter cada conector.
• Fluxos com estado e ramificações: etapas que dependem de resultados anteriores, pausas para aprovação, retomada depois de uma interrupção. O ecossistema do LangChain tem o LangGraph justamente para modelar esse tipo de grafo de estados.
• Troca frequente de modelo: se a empresa quer comparar provedores sem reescrever a camada de chamada, uma interface comum reduz o atrito.
• Equipe maior ou rotativa: um vocabulário compartilhado (cadeias, ferramentas, recuperadores) ajuda quem chega a entender onde mexer.
• Observabilidade pronta: ferramentas de rastreamento ligadas ao framework mostram cada passo sem você instrumentar tudo.

Nesses casos, o framework é um acelerador legítimo. O ponto de atenção é que ele acelera o que já está claro. Se o processo de negócio ainda não foi mapeado, o framework só acelera a construção de algo mal definido.

Quando o SDK do provedor e um laço simples bastam

O guia da Anthropic sobre construção de agentes eficazes recomenda começar usando as APIs dos modelos diretamente, porque muitos padrões se resolvem em poucas linhas de código, e avisa que frameworks podem criar camadas extras que escondem prompts e respostas, tornando a depuração mais difícil. É uma observação de documentação oficial, não uma regra absoluta, mas descreve bem o risco.

O laço simples tende a bastar quando:

• O agente tem um objetivo estreito, como responder dúvidas de um catálogo ou preparar um rascunho de orçamento.
• Há poucas ferramentas, em geral entre uma e cinco, cada uma com entrada e saída bem definidas.
• Um único provedor de modelo atende, pelo menos no piloto.
• Quem mantém é uma pessoa ou uma equipe pequena que precisa ler o código inteiro em uma tarde.
• O fluxo é majoritariamente determinístico, com o modelo entrando apenas onde é preciso julgamento.

O ganho principal é transparência. Você sabe exatamente o que foi enviado ao modelo, o que ele devolveu e por que a ferramenta foi chamada. Quando o agente responde algo estranho a um cliente no WhatsApp, esse é o dado que você precisa em minutos, não depois de navegar por camadas de abstração.

Manutenção e depuração: onde o custo aparece

A escolha parece técnica, mas o impacto é de operação. Três custos merecem atenção antes de decidir.

Primeiro, a atualização. Bibliotecas de agentes evoluem rápido e mudam interfaces. Isso é saudável para o ecossistema, mas significa que alguém da empresa precisa acompanhar versões, ler notas de mudança e testar. Com o SDK do provedor você também acompanha mudanças, só que em uma superfície menor.

Segundo, a depuração. Quando algo dá errado, a pergunta é sempre a mesma: qual foi o texto exato enviado, com quais ferramentas e qual foi a resposta bruta? Se o framework monta o prompt por você, é preciso saber extrair esse texto. Com ou sem framework, registre cada chamada ao modelo e cada chamada de ferramenta. As convenções semânticas do OpenTelemetry para IA generativa são uma boa referência de quais campos vale a pena guardar, e servem para os dois caminhos.

Terceiro, a transferência. Quem herda o sistema precisa entendê-lo. Um laço de cem linhas bem comentado é fácil de passar adiante. Um grafo grande com muitas abstrações pode ser igualmente claro, mas só se houver documentação interna e alguém que conheça o framework. Pergunte quem, na equipe do cliente ou na sua, dominará aquilo em um ano.

Nenhum desses custos é decisivo sozinho. Somados, indicam que a complexidade deve ser adotada quando comprada de propósito, não por padrão.

Guia de decisão em uma lista

Use as perguntas abaixo antes de escolher. Quanto mais respostas afirmativas em um bloco, mais você se inclina para ele.

Inclina para o laço simples com o SDK:

• Consigo descrever o fluxo do agente em um parágrafo?
• Tenho poucas ferramentas e todas com contrato claro?
• Vou usar um único provedor de modelo no piloto?
• Preciso ler e auditar cada prompt enviado?
• A equipe que vai manter é pequena?

Inclina para um framework:

• O fluxo tem muitas etapas com estado, pausas e retomadas?
• Vou integrar com muitas fontes de dados e provedores?
• Preciso trocar de modelo com frequência para comparar?
• Já existe na equipe alguém que domina o framework?
• O rastreamento pronto do ecossistema economiza trabalho real?

Se os dois blocos empatam, comece pelo laço simples, com ferramentas e prompt isolados em módulos próprios. Assim, adotar um framework depois vira uma troca da camada de orquestração, e não uma reescrita.

Cenário ilustrativo: agente de pós-venda

Imagine uma empresa de serviços que quer um agente para responder dúvidas de clientes sobre pedidos e abrir chamados para a equipe. Este é um cenário ilustrativo, sem relação com qualquer cliente real.

O agente precisa de três ferramentas: consultar o status de um pedido (somente leitura), buscar uma resposta na base de perguntas frequentes e abrir um chamado para uma pessoa. Ele não altera pedidos nem promete prazos fora da política. O fluxo é curto, o provedor de modelo é um só e a equipe técnica é de uma ou duas pessoas.

Nesse desenho, o laço com o SDK resolve. O código tem um prompt de sistema, três funções, um limite de passos por conversa e um registro de cada chamada. A transferência para humano é uma ferramenta como as outras. Se, meses depois, a empresa quiser adicionar aprovação em várias etapas, retomada de conversas longas e integração com vários sistemas, aí faz sentido reavaliar um framework de grafos, com o piloto anterior servindo de base de comparação.

Observe que as decisões importantes do cenário, como somente leitura, limite de passos e transferência para humano, não dependem da biblioteca. Dependem de desenho. Para o canal, vale ver o guia sobre como integrar IA no WhatsApp da empresa.

Como montar o primeiro agente sem framework, passo a passo

Se o seu caso se parece com o cenário acima, este roteiro serve de ponto de partida:

• Passo 1: escreva o objetivo do agente em uma frase e liste o que ele nunca deve fazer.
• Passo 2: defina as ferramentas com nome claro, parâmetros simples e descrição objetiva. A Anthropic tem um texto específico sobre como escrever boas ferramentas para agentes, e a qualidade dessas descrições pesa muito no comportamento.
• Passo 3: escreva o laço: enviar mensagens e ferramentas ao modelo, executar o pedido de ferramenta, devolver o resultado, repetir até a resposta final ou até o limite de passos.
• Passo 4: trate falhas de forma explícita. Tempo esgotado, limite de taxa e queda do provedor precisam de comportamento definido, como descrito em rate limit e queda de API de LLM.
• Passo 5: adicione validações na entrada, na saída e antes de qualquer ação com efeito, conforme guardrails para agentes de IA.
• Passo 6: registre cada chamada ao modelo e à ferramenta, com identificador de conversa, para poder reconstruir qualquer atendimento.
• Passo 7: monte um conjunto pequeno de casos reais de teste e rode a cada mudança de prompt ou de modelo. O guia da Anthropic sobre avaliações de agentes ajuda a pensar nisso.
• Passo 8: coloque aprovação humana nas ações que mudam dinheiro, contrato ou dados pessoais, e confirme o tratamento desses dados à luz da LGPD.

Note que a lista inteira cabe tanto num laço próprio quanto num framework. A diferença é quanto de cada passo você escreve e quanto herda.

Como o método se aplica: mapear, limitar, pilotar, transferir

A escolha de ferramenta vem depois do processo. Primeiro mapeamos o fluxo atual e o ponto de partida: quem atende, com que informação, onde há retrabalho. Depois limitamos dados e ações, definindo o que o agente lê, o que pode fazer e quando passa para uma pessoa. Então pilotamos um fluxo real, com logs e uma métrica de sucesso combinada de antemão. Para isso, o texto sobre como medir um piloto de automação com IA traz critérios de decisão.

Por fim, transferimos: documentação, acessos e decisão de expandir, ajustar ou parar. Esse último passo é onde a simplicidade rende. Uma base de código que a equipe do cliente consegue ler e operar tem mais chance de sobreviver ao fim do projeto do que uma que exige especialista permanente. Quando um framework é a melhor resposta para o fluxo, usamos, mas com essa pergunta de manutenção feita antes.

Perguntas frequentes

LangChain é obrigatório para criar um agente de IA? Não. Um agente pode ser feito com o SDK do provedor do modelo e um laço que executa ferramentas. O framework é uma opção para quando integrações, estado e equipe justificam a camada extra.

Dá para começar sem framework e migrar depois? Dá, desde que você mantenha prompt, ferramentas e registro em módulos separados da orquestração. Nesse caso a migração troca principalmente o laço central. O que costuma tornar a mudança cara é misturar regras de negócio com o código de chamada ao modelo.

O framework deixa o agente mais seguro ou mais preciso? Não por si só. Segurança e precisão vêm de ferramentas bem descritas, permissões restritas, validação de saídas, avaliação com casos reais e aprovação humana. A OWASP mantém uma lista dos principais riscos de aplicações com modelos de linguagem que vale consultar, independentemente da biblioteca escolhida.

Como decidir se minha equipe pequena deve usar framework? Verifique se alguém consegue ler e depurar o código inteiro com calma e se o fluxo cabe em poucas ferramentas. Se sim, o laço simples tende a ser mais barato de manter. Se o fluxo exige estado, pausas e muitas integrações, avalie um framework com um piloto curto antes de se comprometer.

Fontes

• Anthropic: Building effective agents
• Anthropic: Writing effective tools for agents
• Anthropic: Demystifying evals for AI agents
• OpenTelemetry: semantic conventions for generative AI