La mayoría de los tutoriales que prometen "un agente de IA en 100 líneas" entregan algo que no es un agente: una llamada al modelo, un prompt y un print. Eso es un chatbot de un turno. Un agente es otra cosa — un modelo que puede decidir llamar a funciones tuyas, leer lo que devolvieron y decidir otra vez, hasta que termina.
Esa diferencia es la que importa, y es la que vamos a construir aquí: un agente con herramientas reales, el loop visible, y las partes que se rompen cuando lo pones frente a usuarios.
Qué cambió en LangChain (y por qué el código viejo no corre)
Si vienes de un tutorial de 2023, el código que tienes ya no funciona. LangChain 1.0 salió en octubre de 2025 y reorganizó las piezas:
| Patrón viejo | Qué pasó | Qué usar hoy |
|---|---|---|
from langchain import LLMChain, OpenAI | Esa ruta de import desapareció | from langchain.agents import create_agent |
LLMChain(llm=...) | Deprecado en favor de LCEL y de agentes | create_agent(...) |
create_react_agent de langgraph.prebuilt | Deprecado en LangGraph 1.0 | create_agent de langchain.agents |
model_name="text-davinci-003" | OpenAI lo apagó en enero de 2024 | un modelo vigente, con prefijo de proveedor |
Ese último punto es el que más tutoriales rotos deja. text-davinci-003 no está deprecado: está apagado. Cualquier guía que lo mencione no corre desde hace dos años, y conviene desconfiar del resto de su contenido.
Las dos piezas
La API moderna se reduce a dos cosas: @tool para declarar lo que el agente puede hacer, y create_agent para armarlo.
Lo que hace a @tool elegante es que no escribes esquemas. LangChain deriva el contrato de la firma de Python: los type hints se vuelven el esquema de entrada y el docstring se vuelve la descripción que el modelo lee para decidir cuándo llamarla.
pip install langchain langchain-openai
export OPENAI_API_KEY="tu-clave"
El agente completo
Un agente que cotiza trabajo: busca precios en un catálogo y calcula el total con IVA. Dos herramientas, porque una sola no demuestra nada — lo interesante es que el modelo tiene que encadenarlas: primero averiguar el precio, luego usar ese resultado para el cálculo.
from langchain.agents import create_agent
from langchain.tools import tool
CATALOGO = {
"landing page": 18000,
"tienda en linea": 65000,
"app movil": 120000,
"integracion de api": 24000,
}
@tool
def buscar_precio(servicio: str) -> str:
"""Busca el precio base de un servicio en el catálogo, en pesos mexicanos.
Args:
servicio: nombre del servicio, por ejemplo "landing page" o "app movil"
"""
clave = servicio.lower().strip()
if clave in CATALOGO:
return f"{servicio}: ${CATALOGO[clave]:,} MXN"
disponibles = ", ".join(CATALOGO)
return f"No encontré '{servicio}'. Servicios disponibles: {disponibles}"
@tool
def calcular_total(subtotal: float, descuento_pct: float = 0.0) -> str:
"""Calcula el total de una cotización aplicando descuento e IVA del 16%.
Args:
subtotal: monto antes de descuento e impuestos, en pesos
descuento_pct: descuento a aplicar, de 0 a 100
"""
if not 0 <= descuento_pct <= 100:
return "El descuento debe estar entre 0 y 100."
con_descuento = subtotal * (1 - descuento_pct / 100)
iva = con_descuento * 0.16
return (
f"Subtotal: ${subtotal:,.2f}\n"
f"Descuento ({descuento_pct}%): -${subtotal - con_descuento:,.2f}\n"
f"IVA (16%): ${iva:,.2f}\n"
f"Total: ${con_descuento + iva:,.2f} MXN"
)
agent = create_agent(
"openai:gpt-5.5",
tools=[buscar_precio, calcular_total],
system_prompt=(
"Eres asistente de cotizaciones de una agencia de software en México. "
"Usa buscar_precio para obtener montos; nunca los inventes. "
"Usa calcular_total para cualquier aritmética. "
"Si un servicio no está en el catálogo, dilo y ofrece las alternativas."
),
)
if __name__ == "__main__":
pregunta = input("¿Qué necesitas cotizar? ")
resultado = agent.invoke({"messages": [{"role": "user", "content": pregunta}]})
print(resultado["messages"][-1].content)
Sesenta y pocas líneas, y es un agente de verdad. Con "cotiza una tienda en línea con 10% de descuento", el modelo llama buscar_precio, lee los $65,000, llama calcular_total con ese número y 10, y redacta la respuesta con el total. Nadie programó esa secuencia: la decidió él.
El primer argumento de create_agent lleva prefijo de proveedor — "openai:...", "anthropic:..." — y cambiar de proveedor es cambiar esa cadena. Verifica el nombre del modelo contra la lista vigente de tu proveedor: es la parte de este código que caduca más rápido.
Dos detalles que no son adorno. El system_prompt dice "nunca los inventes" y "usa calcular_total para cualquier aritmética" porque sin esas dos instrucciones el modelo a veces se salta las herramientas y responde de memoria — con un precio plausible y falso. Y las herramientas devuelven texto de error en lugar de lanzar excepciones: un return lo lee el modelo y puede corregir el rumbo; un raise tumba el proceso.
Ver el loop
Lo anterior imprime sólo la respuesta final, y por eso parece magia. Vale más la pena ver qué pasó:
resultado = agent.invoke({"messages": [{"role": "user", "content": pregunta}]})
for mensaje in resultado["messages"]:
tipo = mensaje.__class__.__name__
if getattr(mensaje, "tool_calls", None):
for llamada in mensaje.tool_calls:
print(f"[{tipo}] -> {llamada['name']}({llamada['args']})")
elif mensaje.content:
print(f"[{tipo}] {mensaje.content}")
Ahí se ve la traza completa: pregunta del usuario, decisión de llamar buscar_precio, resultado, decisión de llamar calcular_total, resultado, respuesta. Ese log es tu principal herramienta de depuración. Cuando un agente se porta mal, el 90% de las veces no es el modelo: es un docstring ambiguo, o una herramienta que devolvió algo que el modelo no supo leer.
¿Quieres llevar un agente de prototipo a producción?
En DevChefs construimos agentes con herramientas conectadas a sistemas reales, con límites de costo y trazas auditables. Cuéntanos qué quieres automatizar.
Lo que falta para producción
Estas 100 líneas son un prototipo honesto. Esto es lo que les falta, en orden de qué te va a morder primero:
Un límite de iteraciones. El loop puede ciclarse: el modelo llama una herramienta, no le gusta el resultado, la vuelve a llamar. Sin tope, eso es una factura abierta. Pon un máximo de pasos y decide qué responder cuando se alcance.
Control de costo. Cada iteración del loop es una llamada al modelo con el historial completo, que crece en cada paso. Una conversación de ocho turnos con tres herramientas cada uno no cuesta ocho llamadas: cuesta mucho más, porque el contexto se re-envía. Mide tokens por conversación desde el primer día, no cuando llegue el recibo.
Herramientas que no son idempotentes. buscar_precio sólo lee; si el modelo la llama dos veces no pasa nada. Pero el día que una herramienta tuya mande un correo, cobre una tarjeta o borre un registro, el agente puede llamarla dos veces. Esas operaciones necesitan una llave de idempotencia o confirmación humana explícita.
Permisos. El agente corre con los permisos de tu código, y su entrada la escribe un desconocido. Si una herramienta puede consultar la base de datos, asume que alguien va a intentar que consulte la tabla equivocada. Los permisos van en la herramienta, nunca en el prompt — las instrucciones del system_prompt son una sugerencia, no un control de acceso.
Memoria entre turnos. El ejemplo olvida todo al terminar. Para conversación real necesitas un checkpointer, que persiste el estado entre invocaciones.
Evaluación. "Funcionó cuando lo probé" no es una prueba. Arma un conjunto de 20 o 30 preguntas con la respuesta esperada y córrelo cada vez que cambies un prompt o una herramienta. Es la única forma de notar que ajustar un docstring rompió otros tres casos.
Cuándo no hacer un agente
Hay que decirlo porque el framework invita a usarlo en todo: si tú ya sabes el orden de los pasos, no necesitas un agente.
Si tu flujo es "extrae estos campos del documento, valídalos, guárdalos", escríbelo como funciones y una llamada al modelo para la extracción. Es más barato, más rápido, determinista y se depura con un stack trace normal. Un agente paga su sobrecosto cuando el orden de los pasos depende de lo que se descubra en el camino — cuando no puedes escribir el if por adelantado porque no sabes cuántos pasos habrá.
Cierre
La parte difícil de un agente nunca fue el código. Son 60 líneas, y hoy son más limpias que hace dos años.
La parte difícil son las herramientas: decidir cuáles expones, qué devuelven cuando fallan, qué pueden tocar y qué nunca, y cómo te das cuenta de que el modelo está usándolas mal. Ahí es donde se va el tiempo real, y ningún framework lo resuelve por ti.
Empieza con dos herramientas y un loop que puedas leer en consola. Cuando eso funcione y entiendas por qué, agrega la tercera.
