Mi experiencia con el SDK LangChain.js V2 para agentes de IA

¡Hola a todos! Soy Nina de agntbox.com. Hoy quiero hablar sobre algo que ha estado dando vueltas en mi espacio de trabajo durante las últimas semanas: la nueva versión de LangChain.js. Específicamente, he estado profundizando en su SDK actualizado y cómo está facilitando mi vida como desarrolladora de agentes de IA, a veces un poco más frustrante, pero de una manera buena y de aprendizaje.

Si has estado siguiendo mis publicaciones, sabes que soy fanática de JavaScript por su versatilidad, y cuando se trata de orquestar grandes modelos de lenguaje, LangChain.js ha sido mi opción preferida. Pero seamos sinceros, los primeros días tuvieron sus peculiaridades. Configurar cadenas complejas, gestionar la memoria entre llamadas e integrar diversas herramientas a veces se sentía como intentar reunir gatos. Sin embargo, con las últimas actualizaciones del SDK, estoy viendo un cambio significativo hacia patrones más intuitivos y una mejor experiencia para el desarrollador. Y honestamente, ya era hora.

Así que, en lugar de un post genérico “¿qué es LangChain.js?”, (¡ya hemos hecho esos!), quiero compartir mi experiencia práctica con el nuevo SDK, centrándome en cómo simplifica el desarrollo de agentes, particularmente cuando buscas agentes que realmente puedan hacer cosas en el mundo real, no solo chatear.

Mis Dolores de Cabeza al Construir Agentes, Antes de la Actualización

Antes de entrar en los aspectos positivos, déjame dibujar un panorama de mis luchas anteriores. Estaba trabajando en un proyecto para un cliente, llamémosles “Acme Analytics”, que necesitaba un agente para realizar tareas de análisis de datos. Este agente debía ser capaz de:

• Acceder a una base de datos SQL para recuperar datos en bruto.
• Realizar cálculos estadísticos básicos (promedio, mediana, etc.).
• Generar gráficos simples utilizando una biblioteca de gráficos.
• Resumir hallazgos y presentarlos al usuario.

Suena sencillo, ¿verdad? Bueno, integrar todas estas “herramientas” con un LLM, gestionar la memoria conversacional y asegurar que el agente pudiera decidir correctamente qué herramienta usar en cada paso fue… un viaje. Pasé una buena parte de mi tiempo lidiando con la ingeniería de prompts para guiar al LLM, creando definiciones de herramientas personalizadas que encajaran con la estructura existente de LangChain, y depurando fugas de memoria que aparecían de la nada. Se sentía como si estuviera constantemente parcheando cosas en lugar de construir de forma elegante.

El Tango de la “Definición de Herramientas”

Uno de los mayores problemas fue definir herramientas. Tenías tu función, luego la envolvías en un objeto `Tool`, asegurándote de que tu descripción fuera absolutamente perfecta para que el LLM la entendiera. Si tu descripción se desviaba por una sola palabra, el LLM podía alucinar o simplemente ignorar tu herramienta. Era un delicado baile.

// Forma antigua (simplificada para el ejemplo)
import { Tool } from "langchain/tools";

const sqlQueryTool = new Tool({
 name: "SQL_Query_Executor",
 description: "Usa esta herramienta para ejecutar consultas SQL en la base de datos de Acme Analytics. La entrada debe ser una declaración SQL SELECT válida. Devuelve el resultado de la consulta.",
 func: async (query: string) => {
 // ... lógica para conectarse a la base de datos y ejecutar la consulta
 return "Resultados de la consulta...";
 },
});

Esto funcionó, pero era verboso, y cualquier cambio en la función subyacente a menudo significaba ajustar la descripción también. Se sentía como una capa de traducción muy manual.

La Nueva SDK de LangChain.js: ¿Un Respiro de Aire Fresco?

Cuando se empezó a lanzar el nuevo SDK, estaba cautelosamente optimista. “Mejores definiciones de herramientas”, decían. “Creación de agentes simplificada”, prometían. Mi escepticismo era alto, pero mi necesidad de un flujo de trabajo más fluido era aún mayor.

Decidí reconstruir una versión simplificada del agente de Acme Analytics utilizando los nuevos patrones del SDK, centrando mi atención en la integración de herramientas y la orquestación del agente. Y honestamente, me llevé una grata sorpresa.

Herramientas Modernas con Esquemas Zod

La mayor mejora, para mí, ha sido la forma en la que se definen las herramientas. El nuevo SDK se basa en gran medida en usar Zod para la validación de esquemas de entrada. Esto puede sonar como un cambio pequeño, pero es un gran avance por varias razones:

1. Seguridad de Tipos: Obtienes una verificación de tipos adecuada para las entradas de tu herramienta, lo que reduce significativamente los errores en tiempo de ejecución.
2. Descripciones Más Claras: Zod te permite agregar descripciones directamente a los campos de tu esquema, que LangChain puede usar para generar una descripción de herramienta más precisa y legible por máquina para el LLM. Esto significa menos ingeniería manual de prompts por tu parte.
3. Validación Integrada: Si el LLM intenta llamar a tu herramienta con argumentos no válidos, Zod lo detecta de inmediato, dándote mejores retroalimentaciones para depuración.

Veamos nuestra herramienta de consulta SQL con el nuevo enfoque:

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

const sqlQueryTool = new DynamicTool({
 name: "SQL_Query_Executor",
 description: "Ejecuta consultas SQL en la base de datos de Acme Analytics.",
 schema: z.object({
 query: z.string().describe("Una declaración SQL SELECT válida para ejecutar en la base de datos."),
 }),
 func: async ({ query }) => {
 try {
 // ... lógica para conectarse a la base de datos y ejecutar la consulta
 console.log(`Ejecutando consulta SQL: ${query}`);
 // Simular una llamada a la base de datos
 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: "Datos recuperados con éxito para la consulta: " + query }]);
 } catch (error) {
 return `Error al ejecutar la consulta: ${error.message}`;
 }
 },
});

¿Ves la diferencia? La propiedad `schema`, usando `z.object` y `z.string().describe()`, proporciona una forma mucho más estructurada y sólida de definir lo que tu herramienta espera. La `description` para la herramienta en sí sigue siendo importante, pero las descripciones detalladas dentro del esquema le dan al LLM un contexto mucho mejor para cada argumento. He encontrado que el LLM es significativamente mejor al generar llamadas a funciones correctas cuando tiene estos esquemas explícitos con los que trabajar.

Creación de Agentes Simplificada con `createOpenAIFunctionsAgent`

Otra área donde el nuevo SDK brilla es en la creación de agentes. Para cualquiera que use modelos de OpenAI (que, seamos realistas, somos muchos), la función `createOpenAIFunctionsAgent` ha sido una bendición. Se encarga de gran parte del trabajo inicial implicado en la configuración de un agente que puede usar las capacidades de llamada a funciones de OpenAI.

Antes, a menudo estaba construyendo manualmente objetos `RunnableSequence`, encadenando cuidadosamente un `ChatPromptTemplate`, el LLM y luego un `ToolExecutor`. Funciona, pero se sentía un poco como ensamblar muebles de IKEA sin todas las instrucciones.

Ahora, es mucho más directo:

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

// ... (definición de sqlQueryTool como antes)

const llm = new ChatOpenAI({
 model: "gpt-4-0125-preview", // O cualquier modelo actual que prefieras
 temperature: 0,
});

const prompt = ChatPromptTemplate.fromMessages([
 ["system", "Eres un asistente de IA útil que puede analizar datos. Usa las herramientas proporcionadas para responder preguntas sobre los datos de Acme Analytics."],
 ["human", "{input}"],
 ["placeholder", "{agent_scratchpad}"], // Importante para el proceso de pensamiento interno del agente
]);

const tools = [sqlQueryTool]; // Agrega más herramientas aquí según sea necesario

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

const agentExecutor = new AgentExecutor({
 agent,
 tools,
 verbose: true, // ¡Siempre es bueno saber qué está haciendo el agente!
});

// Vamos a probarlo
const result = await agentExecutor.invoke({
 input: "¿Puedes darme los nombres de todos los usuarios de la base de datos?",
});

console.log("Respuesta final del agente:", result.output);

¡Este fragmento de código es mucho más limpio! La `createOpenAIFunctionsAgent` maneja la lógica compleja de convertir las llamadas a funciones del LLM en ejecuciones reales de herramientas. Luego, el `AgentExecutor` orquesta todo el proceso, ejecutando el agente, comprobando si necesita usar una herramienta, ejecutando la herramienta y alimentando el resultado de nuevo al agente para un procesamiento adicional. La opción `verbose: true` es un salvavidas para la depuración, permitiéndote ver el proceso de pensamiento del agente paso a paso.

Mejora en la Gestión de Memoria (todavía es un área para crecer, ¡pero mejor!)

La memoria siempre ha sido un tema espinoso en la IA conversacional. Mantener un registro de las interacciones pasadas sin abrumar la ventana de contexto del LLM es un acto de equilibrio constante. El nuevo SDK no resuelve mágicamente todos los problemas de memoria, pero proporciona formas más eficientes de integrar diferentes tipos de memoria.

Para mi agente de Acme Analytics, necesitaba un simple búfer conversacional. Integrarlo con la nueva configuración del agente es bastante sencillo:

import { BufferWindowMemory } from "langchain/memory";

const memory = new BufferWindowMemory({
 k: 5, // Mantener los últimos 5 intercambios en memoria
 memoryKey: "chat_history", // Esto se pasará al prompt
 returnMessages: true,
});

// ... (resto de la configuración del agente)

// Modificar el prompt para incluir el historial de chat
const promptWithMemory = ChatPromptTemplate.fromMessages([
 ["system", "Eres un asistente de IA útil que puede analizar datos. Usa las herramientas proporcionadas para responder preguntas sobre los datos de Acme Analytics."],
 new MessagesPlaceholder("chat_history"), // Marcador de posición para la memoria
 ["human", "{input}"],
 ["placeholder", "{agent_scratchpad}"],
]);

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

const agentExecutorWithMemory = new AgentExecutor({
 agent: agentWithMemory,
 tools,
 memory, // Pasar la memoria aquí
 verbose: true,
});

// Ejemplo de interacción
await agentExecutorWithMemory.invoke({
 input: "Hola, ¿qué puedes hacer?",
});

await agentExecutorWithMemory.invoke({
 input: "¿Puedes darme los nombres de todos los usuarios de la base de datos?",
});

// La memoria ahora llevará el intercambio "Hola, ¿qué puedes hacer?"

El `MessagesPlaceholder` en el prompt es crucial, permitiendo que el `AgentExecutor` inyecte el `chat_history` desde el `BufferWindowMemory` directamente en el prompt. Si bien los límites de la ventana de contexto siguen siendo una realidad, esta integración facilita la gestión de ese historial mucho más que antes.

Recomendaciones Accionables para Tu Próximo Proyecto de IA

Después de pasar un buen tiempo con el nuevo SDK de LangChain.js, aquí’s lo que he aprendido y lo que recomiendo si te adentras en el desarrollo de agentes:

1. Adopta Zod para Definiciones de Herramientas:

   De verdad, este es un cambio significativo. Hace que tus herramientas sean más claras, más fáciles de entender para el LLM y te brinda una mejor seguridad de tipos. Invierte tiempo al principio para definir adecuadamente los esquemas de tus herramientas.

   
   // Siempre define un esquema claro para tus herramientas
   const myNewTool = new DynamicTool({
    name: "WeatherDataFetcher",
    description: "Obtiene los datos climáticos actuales para una ciudad dada.",
    schema: z.object({
    city: z.string().describe("El nombre de la ciudad para la que se obtendrán los datos del clima."),
    unit: z.enum(["celsius", "fahrenheit"]).default("celsius").describe("La unidad de temperatura a devolver."),
    }),
    func: async ({ city, unit }) => {
    // ... lógica de llamada a la API del clima
    return `El clima en ${city} es de 25 grados ${unit}.`;
    },
   });
   

2. Comienza con `createOpenAIFunctionsAgent` (si usas OpenAI):

   A menos que tengas razones muy específicas para no hacerlo, esta función simplifica enormemente la creación de agentes. Maneja las complejidades de la API de llamadas de función de OpenAI, permitiéndote concentrarte en tus herramientas y prompts.

3. Mantén Tus Prompts Enfocados y Claros:

   Aunque tengas mejores definiciones de herramientas, el prompt del sistema sigue siendo la estrella guía para tu agente. Define claramente su rol, capacidades y cualquier restricción. Usa el marcador de posición `agent_scratchpad` para el monólogo interno del agente.

4. Usa `verbose: true` para Depurar:

   Cuando las cosas salgan mal (y lo harán), `verbose: true` en tu `AgentExecutor` es tu mejor amigo. Imprime el proceso de pensamiento del LLM, qué herramienta está intentando llamar y los resultados, ayudándote a identificar problemas rápidamente.

5. Administra la Memoria de Manera Reflexiva:

   Aunque la integración es mejor, recuerda que la memoria consume tokens. Escoge el tipo de memoria correcto para tu caso de uso (por ejemplo, `BufferWindowMemory` para chat a corto plazo, o una resumisión más sofisticada si la longitud del contexto es una gran preocupación). Siempre incluye el `MessagesPlaceholder` en tu prompt al usar memoria.

6. Prueba de Manera Iterativa:

   Crea una herramienta, pruébala. Intégrala con el agente, pruébala. Agrega otra herramienta, pruébala de nuevo. El desarrollo de agentes de IA es inherentemente iterativo. Pruebas pequeñas y enfocadas te ahorran dolores de cabeza a futuro.

El nuevo SDK de LangChain.js se siente como un paso significativo hacia la accesibilidad del desarrollo de agentes de IA y menos propenso a errores ocultos. No es perfecto, y siempre hay una curva de aprendizaje con nuevos patrones, pero las mejoras en la definición de herramientas y la orquestación de agentes realmente están haciendo que mis proyectos sean más fluidos. Si has estado indeciso sobre adentrarte en LangChain.js, o si has tenido una experiencia menos que estelar con versiones anteriores, ahora es un gran momento para darle una nueva mirada al SDK actualizado.

¿Cuáles son tus experiencias con el nuevo SDK de LangChain.js? ¿Algún truco interesante o desafíos que hayas encontrado? ¡Déjame saber en los comentarios a continuación! ¡Feliz codificación!

🕒 Published: March 26, 2026