Módulo 2: Tools y Tool Calling

Introducción: Por qué los modelos necesitan herramientas

Siguiente →

Descripción

Los LLMs son impresionantes generando texto, pero eso es exactamente lo que son — generadores de texto. No pueden buscar en la web, no pueden hacer cálculos matemáticos confiables, no pueden consultar tu base de datos, no pueden llamar una API externa. Están atrapados dentro de su ventana de entrenamiento.

Las tools (herramientas) resuelven esta limitación. Con tool calling, un modelo puede decidir "necesito buscar el clima actual en Madrid" y tú ejecutas esa búsqueda por él. El modelo decide qué herramienta usar y con qué argumentos, tú ejecutas la herramienta, y el modelo integra el resultado en su respuesta final.

En este módulo aprenderás a crear tools, conectarlas a modelos, y ejecutar el flujo completo de tool calling. Al terminar, tus modelos podrán hacer cosas que el texto plano nunca permitiría.

¿Dónde estamos en la guía?

Este es el Módulo 2 de la guía LangChain & LangGraph: From Chains to Agents. Construye directamente sobre el Módulo 1 — ya sabes inicializar modelos, ejecutarlos con invoke/stream/batch, y obtener structured output. Ahora vas a darles manos para actuar en el mundo real.

La guía tiene 4 bloques progresivos:

Bloque 1: LangChain Core (Módulos 1-4)     ← ESTÁS AQUÍ (Módulo 2)
Bloque 2: LangGraph Fundamentals (Módulos 5-7)
Bloque 3: LangGraph Avanzado (Módulos 8-10)
Bloque 4: Producción (Módulos 11-12)

Tu progreso en el Bloque 1:

Módulo 1: Modelos y Proveedores           ✅ Completado
    │
    ▼
Módulo 2: Tools y Tool Calling            ← ESTÁS AQUÍ
    │
    ▼
Módulo 3: Agents (create_agent)           🔒 Siguiente
    │
    ▼
Módulo 4: Middleware y Customización      🔒 Después

En el Módulo 1 aprendiste a conectar con modelos y obtener respuestas. Pero esas respuestas están limitadas a lo que el modelo ya sabe. Con tools, el modelo puede acceder a información en tiempo real, ejecutar cálculos exactos, y interactuar con sistemas externos.

Por qué los modelos necesitan herramientas

El problema fundamental

Un LLM solo puede hacer una cosa: predecir el siguiente token basándose en su entrenamiento. Esto significa que tiene limitaciones fundamentales:

LimitaciónEjemploPor qué falla
Sin datos en tiempo real"¿Cuál es el clima ahora en CDMX?"Su conocimiento tiene una fecha de corte
Matemáticas poco confiables"¿Cuánto es 847 × 293?"Calcula "aproximadamente" en vez de exactamente
Sin acceso a tus datos"¿Cuántos usuarios tengo en mi DB?"No tiene conexión a tu base de datos
Sin acciones externas"Envía un email a soporte"Solo puede generar el texto del email
Sin contexto actualizado"¿Cuál es el precio actual de Bitcoin?"Responde con datos de su entrenamiento

El modelo es un cerebro poderoso sin manos. Puede razonar, planificar, y decidir qué hacer — pero no puede ejecutar nada por sí mismo.

Las herramientas desbloquean capacidades

Con tools, las mismas preguntas tienen respuestas reales:

PreguntaSin toolsCon tools
"¿Clima en CDMX?""Generalmente templado..." (genérico)"18°C, nublado, 65% humedad" (en tiempo real)
"¿847 × 293?""Aproximadamente 248,000" (incorrecto)"248,171" (exacto, vía calculadora)
"¿Cuántos usuarios activos?""No tengo acceso a tu DB""1,247 usuarios activos" (vía query SQL)
"Busca noticias de LangChain"Info de su entrenamientoResultados actualizados de búsqueda
"Envía un email a soporte"Genera el texto pero no envíaEnvía el email vía API de email

La diferencia es clara: sin tools, el modelo inventa o admite ignorancia. Con tools, obtiene datos reales y responde con información precisa.

Tipos de herramientas que puedes crear

Las tools se dividen en categorías según lo que hacen:

CategoríaEjemplosQué resuelve
Datos en tiempo realClima, precios, noticiasEl modelo accede a información actual
Cálculos exactosCalculadora, conversiones, estadísticasResultados matemáticos sin error
Consultas a datosSQL, APIs internas, búsquedasEl modelo accede a tus sistemas
AccionesEnviar emails, crear tickets, publicarEl modelo ejecuta tareas reales
ProcesamientoTraducción, formateo, extracciónOperaciones que requieren lógica específica

En este módulo cubrirás las primeras 3 categorías. Las acciones con side effects requieren más cuidado (validación, confirmación del usuario) y se profundizan en módulos posteriores con Human-in-the-Loop (Módulo 9).

El flujo de tool calling

El tool calling sigue un flujo de 5 pasos claro:

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ 1. User  │────▶│ 2. Model │────▶│ 3. Tool  │────▶│ 4. Model │────▶│ 5. User  │
│ pregunta │     │ decide   │     │ ejecuta  │     │ integra  │     │ recibe   │
│          │     │ qué tool │     │ la tool  │     │ resultado│     │ respuesta│
└──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘

Paso a paso:

  1. El usuario envía una pregunta — "¿Qué clima hace en Madrid?"
  2. El modelo analiza y decide — "Necesito la tool get_weather con city='Madrid'"
  3. Tú ejecutas la tool — Llamas la función get_weather("Madrid") y obtienes el resultado
  4. El modelo integra — Recibe el resultado y genera una respuesta natural
  5. El usuario recibe la respuesta — "En Madrid hace 22°C, soleado"

Ejemplo concreto del flujo

Usuario: "¿Cuánto es 847 × 293 y cuál es la raíz cuadrada del resultado?"

Paso 2 — El modelo decide:
  → tool_call: multiply(a=847, b=293)

Paso 3 — Tú ejecutas:
  → multiply(847, 293) = 248171

Paso 4 — El modelo recibe 248171 y decide:
  → tool_call: square_root(n=248171)

Paso 3 (otra vez) — Tú ejecutas:
  → square_root(248171) = 498.17

Paso 4 — El modelo integra todo:

Paso 5 — Respuesta al usuario:
  "847 × 293 = 248,171. La raíz cuadrada de 248,171 es aproximadamente 498.17"

El modelo puede encadenar múltiples tool calls si necesita resultados intermedios. Este loop se repite hasta que el modelo tiene toda la información para responder.

Detalle importante: el modelo NO ejecuta tools

El modelo genera un JSON con el nombre de la tool y los argumentos. Es tu código el que ejecuta la función real. Esto te da control total:

  • ✅ Puedes validar los argumentos antes de ejecutar
  • ✅ Puedes decidir si una tool es segura de ejecutar
  • ✅ Puedes agregar logging, rate limiting, o timeout
  • ✅ Puedes manejar errores y darle feedback al modelo
  • ❌ El modelo nunca tiene acceso directo a tus sistemas

Lo que el modelo produce internamente es algo como:

{
  "tool_calls": [
    {
      "name": "get_weather",
      "args": {"city": "Madrid", "units": "celsius"},
      "id": "call_abc123"
    }
  ]
}

Tu código lee ese JSON, ejecuta get_weather(city="Madrid", units="celsius"), y le devuelve el resultado al modelo como un ToolMessage.

Analogía: el cerebro y las manos

Piensa en el modelo como un cerebro experto que puede analizar situaciones, razonar sobre qué hacer, y dar instrucciones precisas. Las tools son las manos que ejecutan esas instrucciones.

Un cirujano (cerebro) le dice a su equipo (manos): "necesito el bisturí #3, corte de 5cm en la incisión". El cirujano no agarra nada directamente — da instrucciones y el equipo ejecuta. Si algo no se puede hacer, el equipo reporta y el cirujano ajusta su plan.

Así funciona tool calling: el modelo da instrucciones, tu código ejecuta, y el modelo ajusta según los resultados.

¿Qué pasa si el modelo no necesita tools?

Si la pregunta no requiere herramientas, el modelo simplemente responde con texto normal. Tool calling es opcional por pregunta — el modelo decide si necesita una tool o no.

"¿Qué es Python?" → El modelo responde directamente (no necesita tools)
"¿Cuánto es 2+2?"  → El modelo puede responder directamente o usar calculadora
"¿Clima en Madrid?" → El modelo necesita la tool get_weather

El modelo evalúa cada pregunta y decide si alguna de las tools disponibles le ayudaría a dar una mejor respuesta.

Tool calling es un estándar de la industria

Tool calling no es exclusivo de LangChain. Los principales proveedores lo soportan nativamente:

  • ✅ OpenAI — Lo llaman "function calling" (desde GPT-3.5, mejorado en GPT-4.1)
  • ✅ Anthropic — Lo llaman "tool use" (desde Claude 3)
  • ✅ Google — Lo soportan en Gemini como "function calling"
  • ✅ Modelos locales — Llama 3.1+ y Mistral lo soportan

LangChain unifica todas estas implementaciones en una sola interfaz. Creas la tool una vez y funciona con cualquier proveedor que soporte tool calling — exactamente como init_chat_model unifica la inicialización de modelos.

Qué dominarás en este módulo

Al completar las 8 cápsulas de este módulo, serás capaz de:

  • ✅ Crear herramientas con el decorador @tool y schemas Pydantic
  • ✅ Conectar tools a modelos con bind_tools() y controlar tool_choice
  • ✅ Implementar el tool execution loop completo (model → tool → model)
  • ✅ Manejar parallel tool calls (múltiples tools en una sola invocación)
  • ✅ Hacer streaming de tool call chunks
  • ✅ Usar tool calling como mecanismo de structured extraction
  • ✅ Implementar error handling robusto cuando una tool falla

Mapa del módulo

CápsulaTemaQué aprenderás
02Crear tools con @toolDecorador @tool, names y descriptions, argument schemas con Pydantic, tools async
03bind_tools y el flujo de tool callingmodel.bind_tools(), tool_choice, forzar tool calls, inspeccionar tool_calls en AIMessage
04Tool execution loopEjecutar tools manualmente, ToolMessage, loop completo, cuándo usar loop manual vs agent
05Parallel tool calls y streamingMúltiples tool calls simultáneos, streaming de chunks, acumular chunks
06Structured output con toolsTool calling como mecanismo de structured extraction, combinar tools + structured output
07Error handling y troubleshootingErrores comunes, retry logic, debugging, validación de schemas
08Proyecto: Asistente con herramientasAsistente con tools de weather, web search y calculator

Flujo de aprendizaje: Primero aprenderás a crear tools (02). Luego a conectarlas a modelos (03). Después a ejecutar el loop completo donde el modelo llama tools y usa sus resultados (04). Con eso dominado, avanzarás a parallel calls y streaming (05), structured extraction con tools (06), y error handling robusto (07). Al final, integrarás todo en un asistente funcional (08).

Conexión con el proyecto

Mini-Proyecto de este módulo: Asistente con Herramientas Externas

En la Cápsula 08 construirás un asistente conversacional que:

  1. Tiene 3 tools conectadas: clima (weather API), búsqueda web y calculadora
  2. El modelo decide autónomamente qué tool usar según la pregunta del usuario
  3. Maneja parallel tool calls — si el usuario pregunta "¿clima en Madrid y en Buenos Aires?", el modelo llama la tool dos veces simultáneamente
  4. Implementa error handling — si una tool falla, el modelo recibe el error y se recupera

Cada concepto que aprendes en las cápsulas 02-07 se aplica directamente en este proyecto.

Conexión con la guía completa

Las tools que creas aquí son la base de todo lo que viene:

  • Módulo 3: create_agent automatiza el tool execution loop — en vez de escribir el loop manualmente, el agent lo hace por ti. Es la diferencia entre conducir manual y automático.
  • Módulo 4: El middleware system te permite interceptar tool calls antes de que se ejecuten (logging, validación, rate limiting).
  • Módulos 5-7: En LangGraph, las tools se ejecutan como nodos en un grafo, lo que te da control granular sobre el flujo.
  • Módulos 8-10: En sistemas multi-agente, diferentes agentes tienen diferentes tools — un agente de datos tiene tools SQL, uno de comunicación tiene tools de email.

Límites: qué NO cubre este módulo

  • ❌ Agents (create_agent) — Se cubre en Módulo 3. Aquí aprendes el loop manual para entender qué pasa internamente.
  • ❌ Middleware y customización — Se cubre en Módulo 4. Interceptar y modificar tool calls antes/después de ejecutarlas.
  • ❌ LangGraph workflows — Se cubre en Módulos 5-7. Orquestar tools como nodos de un grafo.
  • ❌ MCP (Model Context Protocol) — Es un estándar para tools interoperables; se menciona brevemente pero no se profundiza.
  • ❌ Tools de terceros avanzadas — Cubrimos built-in tools como ejemplo, pero el foco es crear tus propias tools.

Setup técnico

Prerequisitos

Antes de continuar, verifica que tienes:

  • ✅ Módulo 1 completado — sabes usar init_chat_model, invoke, y structured output
  • ✅ Python 3.11+ instalado
  • ✅ Al menos una API key de un proveedor que soporte tool calling (OpenAI o Anthropic recomendado)
  • ✅ Familiaridad básica con Pydantic (modelos de datos Python)

Instalación

No necesitas paquetes nuevos más allá de los que instalaste en el Módulo 1:

# Si ya tienes el Módulo 1 instalado, no necesitas nada más
pip install langchain langchain-openai python-dotenv pydantic

# Opcional: para usar tools built-in de búsqueda
pip install duckduckgo-search

Verificar que todo funciona

from dotenv import load_dotenv
load_dotenv()

from langchain.chat_models import init_chat_model
from langchain_core.tools import tool

@tool
def greet(name: str) -> str:
    """Saluda a una persona por su nombre."""
    return f"¡Hola, {name}!"

print(greet.name)
# Output esperado: greet

print(greet.description)
# Output esperado: Saluda a una persona por su nombre.

model = init_chat_model("openai:gpt-4.1-mini")
model_with_tools = model.bind_tools([greet])

response = model_with_tools.invoke("Saluda a María")
print(response.tool_calls)
# Output esperado: [{'name': 'greet', 'args': {'name': 'María'}, 'id': '...'}]

Si ves la tool call en la respuesta, tu setup está listo para este módulo.

Si algo falla, los errores más comunes son:

ErrorCausaSolución
ImportError: cannot import name 'tool'Versión de langchain-core antiguapip install --upgrade langchain-core
NotImplementedError: ... does not support tool callingEl modelo no soporta tool callingUsa un modelo que lo soporte (GPT-4.1, Claude Sonnet)
ValidationError en args_schemaType hints inconsistentesVerifica que los tipos del schema coinciden con los de la función

Evidencia de éxito

Al terminar este módulo, sabrás que tuviste éxito si:

  • ✅ Puedes crear una tool con @tool y que el modelo la llame correctamente
  • ✅ Entiendes el flujo completo: user → model → tool → model → user
  • ✅ Sabes la diferencia entre que el modelo proponga una tool call y ejecutar la tool
  • ✅ Manejas parallel tool calls y errores de tools sin que el sistema se caiga
  • ✅ Tu asistente del proyecto final responde preguntas usando 3 tools diferentes

Vista previa: de tools manuales a agents automáticos

En este módulo vas a escribir el tool execution loop manualmente. Esto es intencional — necesitas entender qué pasa internamente antes de automatizarlo.

En el Módulo 3, aprenderás create_agent, que automatiza todo el loop:

# Módulo 2: loop manual (lo que aprenderás aquí)
response = model_with_tools.invoke(messages)
# → Verificar si hay tool_calls
# → Ejecutar cada tool
# → Agregar ToolMessage
# → Volver a llamar al modelo
# → Repetir hasta que no haya más tool_calls

# Módulo 3: loop automático con create_agent
from langchain.chat_models import init_chat_model
from langchain.agents import create_agent

model = init_chat_model("openai:gpt-4.1-mini")
agent = create_agent(model, tools=[greet, search, calculator])
response = agent.invoke({"messages": [{"role": "user", "content": "Saluda a María"}]})
# → El agent ejecuta todo el loop internamente

Aprender el loop manual primero te da superpoderes: cuando algo falla en un agent, sabes exactamente dónde buscar porque entiendes cada paso del flujo.

La relación es como aprender a conducir con transmisión manual antes de pasar a automática — entiendes lo que pasa debajo del capó, y eso te hace un mejor conductor incluso cuando usas automático.

¿Cuándo usar loop manual vs agent?

SituaciónRecomendación
Aprendiendo tool callingLoop manual (este módulo)
Prototipo rápido en produccióncreate_agent (Módulo 3)
Necesitas control total del flujoLoop manual o LangGraph (Módulos 5-7)
Debugging de un agentEntender el loop manual te ayuda a diagnosticar

Resumen

  • Los LLMs solo generan texto — no pueden buscar, calcular, ni interactuar con sistemas externos
  • Las tools extienden las capacidades del modelo: son funciones Python que el modelo puede solicitar ejecutar
  • El modelo nunca ejecuta tools directamente — decide qué tool llamar y con qué args, y tu código las ejecuta
  • El flujo es: user → model → tool → model → user (el modelo propone, tú ejecutas, el modelo integra)
  • El modelo puede encadenar múltiples tool calls cuando necesita resultados intermedios
  • Tool calling es opcional por pregunta — el modelo decide si necesita una tool o responde directo
  • Tool calling es un estándar de la industria soportado por OpenAI, Anthropic, Google y modelos locales
  • Las tools se dividen en categorías: datos en tiempo real, cálculos exactos, consultas a datos, acciones y procesamiento
  • Este módulo cubre el loop manual; el Módulo 3 (create_agent) lo automatiza
  • No necesitas paquetes nuevos — langchain y langchain-core incluyen todo lo necesario para tools
  • El proyecto integrador es un asistente con tools de clima, búsqueda y calculadora

Recursos adicionales

  1. LangChain Tools Documentation — Conceptos y guía oficial de tools
  2. How to create tools — Guía paso a paso para crear tools custom
  3. Tool Calling Conceptual Guide — Cómo funciona el tool calling internamente
  4. OpenAI Function Calling Guide — La especificación original de tool calling
  5. Anthropic Tool Use — Tool calling en Anthropic
  6. LangChain Built-in Tools — Catálogo de tools pre-construidas

Módulo 2 — LangChain & LangGraph: From Chains to Agents

Siguiente cápsula: Crear Tools con @tool — aprenderás a convertir cualquier función Python en una herramienta que los modelos pueden invocar.

← AnteriorProyecto: Chat Multi-Proveedor con FallbackSiguiente →Crear Tools con @tool