Minha Experiência com o SDK LangChain.js V2 para Agentes de IA

Olá a todos, Nina aqui do agntbox.com! Hoje, quero falar sobre algo que tem agitado meu espaço de trabalho nas últimas semanas: a nova versão do LangChain.js. Especificamente, tenho analisado profundamente seu SDK atualizado e como ele está facilitando minha vida como desenvolvedor de agentes de IA – e, às vezes, um pouco mais frustrante, mas de um jeito bom, de aprendizado.

Se você tem acompanhado meus posts, sabe que sou uma grande fã de JavaScript pela sua versatilidade, e quando se trata de orquestrar grandes modelos de linguagem, LangChain.js tem sido minha escolha. Mas sejamos sinceros, os primeiros dias tinham suas peculiaridades. Configurar cadeias complexas, gerenciar a memória entre chamadas e integrar com várias ferramentas às vezes parecia como tentar reunir gatos. No entanto, com as últimas atualizações do SDK, estou vendo uma mudança significativa em direção a padrões mais intuitivos e uma melhor experiência para o desenvolvedor. E, sinceramente, já era hora.

Então, em vez de um post genérico sobre “o que é LangChain.js?” (já fizemos isso!), quero compartilhar minha experiência prática com o novo SDK, focando em como ele torna o desenvolvimento de agentes mais ágil, especialmente quando você está mirando em agentes que realmente podem fazer coisas no mundo real – não apenas conversar.

Minha Dor de Cabeça na Construção de Agentes, Antes da Atualização

Antes de explorarmos as coisas boas, deixe-me pintar um quadro das minhas lutas anteriores. Eu estava trabalhando em um projeto para um cliente – vamos chamá-los de “Acme Analytics” – que precisava de um agente para realizar tarefas de análise de dados. Este agente precisava ser capaz de:

• Acessar um banco de dados SQL para recuperar dados brutos.
• Executar cálculos estatísticos básicos (média, mediana, etc.).
• Gerar gráficos simples usando uma biblioteca de gráficos.
• Resumir as descobertas e apresentá-las ao usuário.

Parece simples, certo? Bem, integrar todas essas “ferramentas” com um LLM, gerenciar a memória conversacional e garantir que o agente pudesse decidir corretamente qual ferramenta usar em cada etapa foi… uma jornada. Passei uma boa parte do meu tempo lutando com a engenharia de prompts para guiar o LLM, elaborando definições de ferramentas personalizadas que se encaixavam na estrutura existente do LangChain, e depurando vazamentos de memória que surgiam do nada. Parecia que eu estava constantemente remendando as coisas em vez de construir de forma elegante.

O Tango da “Definição de Ferramenta”

Um dos maiores pontos críticos era definir ferramentas. Você teria a sua função, então a envolveria em um objeto `Tool`, garantindo que sua descrição fosse absolutamente perfeita para que o LLM entendesse. Se sua descrição estivesse errada por uma única palavra, o LLM poderia alucinar ou simplesmente ignorar sua ferramenta. Era uma dança delicada.

// Antiga forma (simplificada para exemplo)
import { Tool } from "langchain/tools";

const sqlQueryTool = new Tool({
 name: "SQL_Query_Executor",
 description: "Use esta ferramenta para executar consultas SQL no banco de dados da Acme Analytics. A entrada deve ser uma declaração SQL SELECT válida. Retorna o resultado da consulta.",
 func: async (query: string) => {
 // ... lógica para conectar ao DB e executar a consulta
 return "Resultados da consulta...";
 },
});

Isso funcionava, mas era verboso, e qualquer alteração na função subjacente muitas vezes significava ajustar a descrição também. Parecia uma camada de tradução muito manual.

Chegada do Novo SDK do LangChain.js: Um Sopro de Ar Fresco?

Quando o novo SDK começou a ser lançado, fiquei cautelosamente otimista. “Definições de ferramentas melhores,” disseram. “Criação de agentes simplificada,” prometeram. Meu ceticismo era alto, mas minha necessidade de um fluxo de trabalho mais suave era ainda maior.

Decidi reconstruir uma versão simplificada do agente Acme Analytics usando os novos padrões do SDK, focando na integração de ferramentas essenciais e na orquestração do agente. E, sinceramente, fiquei agradavelmente surpreendida.

Ferramentas Modernas com Esquemas Zod

A maior melhoria, para mim, tem sido a forma como as ferramentas são definidas. O novo SDK se apoia fortemente no uso de Zod para validação de esquemas de entrada. Isso pode parecer uma mudança pequena, mas é um grande passo à frente por várias razões:

1. Segurança de Tipo: Você obtém verificação de tipo adequada para as entradas da sua ferramenta, o que reduz significativamente erros em tempo de execução.
2. Descrições Mais Claras: O Zod permite que você adicione descrições diretamente aos campos do seu esquema, que o LangChain pode então usar para gerar uma descrição de ferramenta mais precisa e legível por máquina para o LLM. Isso significa menos engenharia de prompts manual da sua parte.
3. Validação Integrada: Se o LLM tentar chamar sua ferramenta com argumentos inválidos, o Zod detecta imediatamente, oferecendo um feedback de depuração melhor.

Vamos revisitar nossa ferramenta de consulta SQL com a nova abordagem:

// Nova forma com Zod
import { DynamicTool } from "@langchain/core/tools";
import { z } from "zod";

const sqlQueryTool = new DynamicTool({
 name: "SQL_Query_Executor",
 description: "Executa consultas SQL no banco de dados da Acme Analytics.",
 schema: z.object({
 query: z.string().describe("Uma declaração SQL SELECT válida para executar no banco de dados."),
 }),
 func: async ({ query }) => {
 try {
 // ... lógica para conectar ao DB e executar a consulta
 console.log(`Executando a consulta SQL: ${query}`);
 // Simula uma chamada ao banco de dados
 await new Promise(resolve => setTimeout(resolve, 500)); 
 if (query.includes("SELECT * FROM users")) {
 return JSON.stringify([{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]);
 }
 return JSON.stringify([{ result: "Dados recuperados com sucesso para a consulta: " + query }]);
 } catch (error) {
 return `Erro ao executar a consulta: ${error.message}`;
 }
 },
});

Viu a diferença? A propriedade `schema`, usando `z.object` e `z.string().describe()`, fornece uma maneira muito mais estruturada e sólida de definir o que sua ferramenta espera. A `description` da ferramenta em si ainda é importante, mas as descrições detalhadas dentro do esquema dão ao LLM muito mais contexto para cada argumento. Descobri que o LLM é significativamente melhor em gerar chamadas de função corretas quando possui esses esquemas explícitos para trabalhar.

Criação de Agentes Simplificada com `createOpenAIFunctionsAgent`

Outra área onde o novo SDK brilha é na criação de agentes. Para quem está usando modelos da OpenAI (que, sejamos sinceros, é muitos de nós), a função `createOpenAIFunctionsAgent` tem sido uma bênção. Ela cuida de muita da estrutura necessária para configurar um agente que pode usar as capacidades de chamadas de função da OpenAI.

Antes, eu costumava construir manualmente objetos `RunnableSequence`, encadeando cuidadosamente um `ChatPromptTemplate`, o LLM e depois um `ToolExecutor`. Funcionava, mas parecia um pouco como montar móveis do IKEA sem todas as instruções.

Agora, é muito mais direto:

import { ChatOpenAI } from "@langchain/openai";
import { createOpenAIFunctionsAgent, AgentExecutor } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";

// ... (definição de sqlQueryTool como acima)

const llm = new ChatOpenAI({
 model: "gpt-4-0125-preview", // Ou qualquer modelo atual que você preferir
 temperature: 0,
});

const prompt = ChatPromptTemplate.fromMessages([
 ["system", "Você é um assistente de IA útil que pode analisar dados. Use as ferramentas fornecidas para responder perguntas sobre os dados da Acme Analytics."],
 ["human", "{input}"],
 ["placeholder", "{agent_scratchpad}"], // Importante para o processo de pensamento interno do agente
]);

const tools = [sqlQueryTool]; // Adicione mais ferramentas aqui conforme necessário

const agent = await createOpenAIFunctionsAgent({
 llm,
 tools,
 prompt,
});

const agentExecutor = new AgentExecutor({
 agent,
 tools,
 verbose: true, // Sempre bom ver o que o agente está fazendo!
});

// Vamos testar!
const result = await agentExecutor.invoke({
 input: "Você pode me passar os nomes de todos os usuários do banco de dados?",
});

console.log("Resposta final do agente:", result.output);

Este trecho de código é muito mais limpo! O `createOpenAIFunctionsAgent` lida com a lógica complexa de transformar as chamadas de função do LLM em execuções reais de ferramentas. O `AgentExecutor` orquestra todo o processo, rodando o agente, verificando se precisa usar uma ferramenta, executando a ferramenta e alimentando o resultado de volta para o agente para um processamento adicional. A opção `verbose: true` é uma salvação para depuração, permitindo que você veja o processo de pensamento do agente passo a passo.

Gerenciamento de Memória Aprimorado (Ainda uma Área de Crescimento, mas Melhor!)

A memória sempre foi um problema espinhoso na IA conversacional. Manter o controle das interações passadas sem sobrecarregar a janela de contexto do LLM é uma constante atuação de equilíbrio. O novo SDK não resolve magicamente todos os problemas de memória, mas fornece maneiras mais simplificadas de integrar diferentes tipos de memória.

Para meu agente Acme Analytics, eu precisava de um buffer conversacional simples. Integrá-lo com a nova configuração do agente é bem direto:

import { BufferWindowMemory } from "langchain/memory";

const memory = new BufferWindowMemory({
 k: 5, // Mantenha as últimas 5 interações na memória
 memoryKey: "chat_history", // Isso será passado para o prompt
 returnMessages: true,
});

// ... (restante da configuração do agente)

// Modifique o prompt para incluir o histórico de chat
const promptWithMemory = ChatPromptTemplate.fromMessages([
 ["system", "Você é um assistente de IA útil que pode analisar dados. Use as ferramentas fornecidas para responder a perguntas sobre os dados da Acme Analytics."],
 new MessagesPlaceholder("chat_history"), // Placeholder para a memória
 ["human", "{input}"],
 ["placeholder", "{agent_scratchpad}"],
]);

const agentWithMemory = await createOpenAIFunctionsAgent({
 llm,
 tools,
 prompt: promptWithMemory,
});

const agentExecutorWithMemory = new AgentExecutor({
 agent: agentWithMemory,
 tools,
 memory, // Passe a memória aqui
 verbose: true,
});

// Interação de exemplo
await agentExecutorWithMemory.invoke({
 input: "Oi, o que você pode fazer?",
});

await agentExecutorWithMemory.invoke({
 input: "Você pode me dar os nomes de todos os usuários do banco de dados?",
});

// A memória agora manterá a troca "Oi, o que você pode fazer?"

O `MessagesPlaceholder` no prompt é crucial, permitindo que o `AgentExecutor` injete o `chat_history` da `BufferWindowMemory` diretamente no prompt. Embora os limites do contexto ainda sejam uma realidade, essa integração torna a gestão desse histórico muito mais limpa do que antes.

Principais Aprendizados para Seu Próximo Projeto de IA

Então, após passar um bom tempo com o novo SDK LangChain.js, aqui está o que eu aprendi e o que recomendo se você estiver explorando o desenvolvimento de agentes:

1. Adote o Zod para Definições de Ferramentas:

   Sério, essa é uma mudança significativa. Isso torna suas ferramentas mais sólidas, mais fáceis de entender para o LLM e oferece uma melhor segurança de tipo. Invista tempo no início para definir corretamente os esquemas das suas ferramentas.

   
   // Sempre defina um esquema claro para suas ferramentas
   const myNewTool = new DynamicTool({
    name: "WeatherDataFetcher",
    description: "Busca dados de clima atuais para uma cidade específica.",
    schema: z.object({
    city: z.string().describe("O nome da cidade para buscar o clima."),
    unit: z.enum(["celsius", "fahrenheit"]).default("celsius").describe("A unidade de temperatura a ser retornada."),
    }),
    func: async ({ city, unit }) => {
    // ... lógica da chamada da API de clima
    return `O clima em ${city} é de 25 graus ${unit}.`;
    },
   });
    

2. Comece com `createOpenAIFunctionsAgent` (se estiver usando OpenAI):

   A menos que você tenha razões muito específicas para não fazê-lo, essa função simplifica imensamente a criação de agentes. Ela lida com as complexidades da API de chamada de funções da OpenAI, permitindo que você se concentre em suas ferramentas e prompts.

3. Mantenha Seus Prompts Focados e Claros:

   Mesmo com melhores definições de ferramentas, o prompt do sistema ainda é a estrela-guia para o seu agente. Defina claramente seu papel, capacidades e quaisquer restrições. Use o placeholder `agent_scratchpad` para o monólogo interno do agente.

4. Use `verbose: true` para Depuração:

   Quando as coisas derem errado (e elas vão!), `verbose: true` no seu `AgentExecutor` é seu melhor amigo. Ele imprime o processo de pensamento do LLM, qual ferramenta está tentando chamar e os resultados, ajudando você a identificar problemas rapidamente.

5. Gerencie a Memória de Forma Consciente:

   Embora a integração seja melhor, lembre-se de que a memória custa tokens. Escolha o tipo de memória certo para o seu caso de uso (por exemplo, `BufferWindowMemory` para chat de curto prazo, ou uma sumarização mais sofisticada se o comprimento do contexto for uma grande preocupação). Sempre inclua o `MessagesPlaceholder` em seu prompt ao usar memória.

6. Teste de Forma Iterativa:

   Construa uma ferramenta, teste-a. Integre-a com o agente, teste-a. Adicione outra ferramenta, teste novamente. O desenvolvimento de agentes de IA é inerentemente iterativo. Testes pequenos e focados vão te salvar de dores de cabeça mais adiante.

O novo SDK LangChain.js parece ser um passo significativo em direção a tornar o desenvolvimento de agentes de IA mais acessível e menos propenso a erros obscuros. Não é perfeito, e sempre há uma curva de aprendizado com novos padrões, mas as melhorias na definição das ferramentas e na orquestração do agente estão realmente tornando meus projetos mais suaves. Se você estava em dúvida sobre explorar o LangChain.js, ou se teve uma experiência menos que estelar com versões anteriores, agora é um ótimo momento para dar uma nova olhada no SDK atualizado.

Quais são suas experiências com o novo SDK LangChain.js? Alguma dica legal ou desafios que você encontrou? Deixe-me saber nos comentários abaixo! Boa codificação!

🕒 Published: April 3, 2026