Lección 4 de 20 · Lectura y práctica
Práctica: Construye un agente básico que use una API
Concepto claveEn LangGraph, un agente es un sistema de IA que toma decisiones secuenciales usando herramientas externas y mantiene contexto a través de ciclos de conversación. Piensa en él como un asistente virtual que, en lugar.
Del concepto a la práctica
Taller de esta lección
La práctica debe aislar la frontera entre el agente y una API. En vez de depender de una red, modela la respuesta externa con un adaptador local; así puedes probar estados de éxito y error con los mismos datos. El agente solo debe continuar cuando la respuesta tenga el contrato esperado.
Ejemplo resuelto
def api_local(ciudad):
return {"ciudad": ciudad, "temperatura": 18, "unidad": "C"}
def resumir(s, respuesta=None):
r = api_local(s["ciudad"]) if respuesta is None else respuesta
if (not isinstance(r, dict) or
r.get("ciudad") != s["ciudad"] or r.get("unidad") != "C" or
type(r.get("temperatura")) not in (int, float)):
return {"ruta": "error_datos", "resumen": None}
return {"ruta": "resumen", "resumen":
f'{r["ciudad"]}: {r["temperatura"]} °{r["unidad"]}'}
print(resumir({"ciudad": "Lima"})["resumen"])
# Lima: 18 °CEl dato18°C es un fixture, no el clima real de Lima. Prueba resumir({"ciudad":"Lima"}, {"ciudad":"Lima","unidad":"C"}) para obtener error_datos sin KeyError; un adaptador real añade timeout, límites y manejo de HTTP. Al envolver resumir en un nodo usa su estado y devuelve un update, mientras la arista selecciona ruta con el campo validado.
Pruébalo
Define la entrada
ciudad.Simula una respuesta válida y otra con error.
Valida temperatura y unidad antes de formatear.
Dirige el error a una salida segura.
Un error frecuente es leer claves anidadas sin comprobarlas. Corrígelo validando primero la forma de la respuesta y conservando el mensaje original para diagnóstico.
Comprueba tu resultado
Para Lima, la salida exacta es Lima: 18 °C. Para una respuesta sin temperatura, la ruta debe ser error_datos, no un texto inventado.

Mapa de prácticaUn agente mantiene un estado y utiliza herramientas dentro de límites definidos. El resultado de cada herramienta actualiza ese estado para decidir el siguiente paso. Las acciones de alto impacto deben pasar por una revisión humana antes de ejecutarse.
Ver la infografía en tamaño completo ↗Concepto clave
En LangGraph, un agente es un sistema de IA que toma decisiones secuenciales usando herramientas externas y mantiene contexto a través de ciclos de conversación. Piensa en él como un asistente virtual que, en lugar de solo responder preguntas, puede ejecutar acciones como consultar APIs, procesar datos y recordar interacciones previas para ofrecer respuestas contextualizadas.
La arquitectura se basa en grafos dirigidos donde los nodos representan estados o acciones, y las aristas definen transiciones condicionales. Esto permite modelar flujos complejos donde el agente decide qué hacer a continuación basado en el estado actual, similar a cómo un conductor navega usando señales de tráfico y mapas en tiempo real.
Cómo funciona en la práctica
Para construir un agente básico que use una API, sigue estos pasos:
- Define el estado del grafo con variables como
messages(historial) ynext(siguiente acción). - Crea nodos para funciones clave:
call_api(llamada a la API),process_response(análisis de datos), ydecide_next(decisión condicional). - Conecta los nodos con aristas que evalúen condiciones, por ejemplo, si la API devuelve un error, redirige a un nodo de manejo de fallos.
- Implementa herramientas usando decoradores de LangGraph para integrar APIs externas, asegurando que el agente pueda acceder a datos en tiempo real.
Ejemplo de un flujo simplificado:
from langgraph.graph import StateGraph, END
# 1. Definir estado
class AgentState(TypedDict):
query: str
api_response: Optional[dict]
next_step: str
# 2. Crear nodos
def call_api(state):
# Lógica para llamar a la API
return {"api_response": data}
# 3. Construir grafo
graph = StateGraph(AgentState)
graph.add_node("call_api", call_api)
graph.add_edge("call_api", END)
graph.set_entry_point("call_api")
app = graph.compile()Caso de estudio
Imagina un agente para un sistema de recomendación de películas que use la API de TMDB (The Movie Database). El agente recibe una consulta como "recomiéndame películas de acción recientes", y ejecuta:
- Llama a la API de TMDB con parámetros de género y fecha.
- Procesa la respuesta para extraer títulos, calificaciones y enlaces.
- Decide si mostrar resultados o pedir más detalles al usuario, basado en la completitud de los datos.
- Almacena la interacción en memoria para refinar futuras recomendaciones.
Datos de ejemplo de la API:
| Película | Género | Calificación | Año |
|---|---|---|---|
| Mad Max: Fury Road | Acción | 8.1 | 2015 |
| John Wick | Acción | 7.4 | 2014 |
En producción, este agente reduciría el tiempo de respuesta de 30 segundos (manual) a 2 segundos (automático), mejorando la experiencia del usuario.
Errores comunes
- No manejar errores de API: Si la API falla, el agente puede bloquearse. Solución: Implementa reintentos y nodos de fallback en el grafo.
- Estado sobredimensionado: Incluir demasiadas variables en el estado ralentiza el agente. Solución: Usa solo campos esenciales como
messagesytools. - Falta de condiciones claras: Aristas sin lógica condicional llevan a bucles infinitos. Solución: Define reglas explícitas, por ejemplo,
if response.status == 200: proceed else: retry. - Ignorar la memoria: Sin historial, el agente no contextualiza. Solución: Integra un nodo que actualice
memorydespués de cada interacción. - Tool mal configurada: APIs con parámetros incorrectos devuelven datos erróneos. Solución: Valida esquemas de entrada y usa tipos de datos estrictos.
Checklist de dominio
- ¿Puedes definir un grafo en LangGraph con al menos 3 nodos y aristas condicionales?
- ¿Integraste una API externa usando herramientas de LangGraph, manejando autenticación y parámetros?
- ¿Implementaste memoria que persista entre ciclos de conversación?
- ¿Diseñaste condiciones que dirijan el flujo basado en respuestas de API (éxito/error)?
- ¿Probaste el agente con consultas reales y mediste latencia?
- ¿Documentaste el flujo del grafo y las dependencias de herramientas?
- ¿Optimizaste el estado para evitar redundancias y mejorar rendimiento?
Construye un agente de clima con la API de OpenWeatherMap
En este ejercicio, crearás un agente que consulta el clima actual usando LangGraph y la API de OpenWeatherMap. Sigue estos pasos:
- Regístrate en OpenWeatherMap para obtener una API key gratuita (límite de 60 llamadas/minuto).
- Define un estado de agente con campos:
city(string),weather_data(dict), ynext_action(string). - Crea un nodo
fetch_weatherque llame a la API de OpenWeatherMap con la ciudad del estado. Usa el endpoint:https://api.openweathermap.org/data/2.5/weather?q={city}&appid={API_KEY}&units=metric. - Añade un nodo
parse_responseque extraiga temperatura, humedad y descripción del JSON de respuesta. - Conecta los nodos: de
fetch_weatheraparse_responsesi la API responde con código 200, o a un nodohandle_errorsi hay error. - Implementa memoria almacenando la última consulta en el estado para referencias futuras.
- Prueba el agente con ciudades como "Madrid" o "Bogotá" y verifica que devuelva datos estructurados.
Entrega: Código en Python con el grafo compilado y una captura de salida de ejemplo.
Pistas
- Usa la librería requests para llamadas HTTP en el nodo fetch_weather, manejando excepciones con try-except.
- En parse_response, accede a los datos con claves como 'main.temp' y 'weather[0].description' del JSON.
- Para memoria, añade un campo 'history' al estado que acumule consultas previas.
Evalua tu comprension
Completa el quiz interactivo de arriba para ganar XP.
Sigue con LangGraph para Automatización: Memoria, Estado y Decisiones
Esta lección forma parte de un curso de Cursalo. Revisa su programa y elige entre la compra individual o el acceso a toda la escuela.
Si ya tenías acceso a este curso, entra con tu cuenta: tus derechos y tu progreso se conservan. No necesitas comprarlo de nuevo.