Crear un agente IA paso a paso: tutorial completo (2026)

Un agente de IA no es un chatbot con más features. Es un sistema que planifica, ejecuta acciones en el mundo real y aprende de los resultados. La diferencia es la misma que entre un formulario web y un robot industrial: ambos procesan datos, pero solo uno actúa.

En 2026, crear un agente de IA está al alcance de cualquier desarrollador con conocimientos de Python. Los frameworks (LangGraph, CrewAI, Autogen) abstraen la complejidad de la orquestación. Los LLMs (Claude, GPT-4o, Qwen) son el cerebro. Las herramientas (APIs, bases de datos, MCP servers) son las manos. Lo que falta en la mayoría de tutoriales es el "cómo" completo: desde la arquitectura hasta la monitorización en producción.

Esta guía cubre el ciclo completo. No solo cómo escribir el código, sino cómo diseñar la arquitectura, elegir el framework, testear el agente y mantenerlo funcionando en producción.

Agente vs chatbot: la diferencia real

La confusión entre agente y chatbot es el origen de la mayoría de implementaciones fallidas. Un chatbot es una interfaz conversacional: recibe texto, genera texto. Un agente es un sistema autónomo que toma decisiones y ejecuta acciones.

Un chatbot:

• Recibe un mensaje del usuario
• Genera una respuesta basada en el prompt y el contexto
• No ejecuta acciones externas (salvo function calling básico)
• No mantiene memoria entre sesiones
• No planifica secuencias de pasos

Un agente:

• Recibe un objetivo (no necesariamente un mensaje)
• Descompone el objetivo en subtareas
• Decide qué herramientas usar y en qué orden
• Ejecuta acciones en sistemas externos (APIs, bases de datos, archivos, emails)
• Evalúa los resultados y decide si necesita más pasos
• Mantiene memoria entre ejecuciones
• Puede operar de forma autónoma o con aprobación humana (HITL)

Ejemplo concreto. Un chatbot de soporte responde "Para resetear tu contraseña, ve a Configuración > Seguridad > Cambiar contraseña." Un agente de soporte verifica la identidad del usuario, resetea la contraseña en el sistema, envía el email con las nuevas credenciales y registra el ticket en el CRM. Misma petición, resultado completamente diferente.

Arquitectura de un agente: planner + memory + tools

Todo agente de IA tiene tres componentes fundamentales. Independientemente del framework que uses, estos tres bloques deben existir.

Planner (cerebro). Es el LLM que toma decisiones. Recibe el objetivo, el contexto disponible, los resultados de acciones anteriores y el estado actual. Decide qué hacer a continuación: llamar a una herramienta, pedir más información, delegar en otro agente o dar la tarea por completada. El planner es el componente más crítico porque determina la calidad de las decisiones. Un planner débil (modelo pequeño, prompt vago) produce agentes erráticos.

Memory (contexto persistente). La memoria almacena información que el agente necesita recordar entre pasos y entre sesiones. Hay tres tipos de memoria relevantes:

• Working memory: el contexto de la ejecución actual. Resultados parciales, estado de las subtareas, decisiones tomadas. Se borra al terminar la ejecución.
• Short-term memory: información de la sesión o conversación actual. Se mantiene durante la sesión y se consolida o descarta al cerrar.
• Long-term memory: conocimiento persistente entre sesiones. Preferencias del usuario, resultados de ejecuciones anteriores, patrones aprendidos. Se almacena en base de datos (vector store o relacional).

Tools (capacidad de acción). Las herramientas son funciones que el agente puede ejecutar para interactuar con el mundo exterior. Cada herramienta tiene un nombre, una descripción (que el LLM lee para decidir cuándo usarla), parámetros de entrada y un output. Ejemplos: buscar en web, consultar base de datos, enviar email, crear ticket, analizar documento, generar gráfico.

La calidad de un agente depende más de cómo describes las herramientas que del modelo que uses como planner. Una herramienta con una descripción vaga ("busca información") produce peores resultados que una con una descripción precisa ("busca en la base de datos de clientes por nombre, email o ID. Devuelve los campos: id, nombre, email, plan, fecha_alta, ultimo_login. Máximo 10 resultados").

Implementación con LangGraph

LangGraph es el framework de referencia para agentes en producción en 2026. Define el agente como un grafo de estados: cada nodo es un paso de procesamiento, cada arista es una transición condicionada por el estado.

Conceptos clave de LangGraph:

• State: un diccionario tipado que contiene toda la información del agente en un momento dado. Mensajes, resultados parciales, decisiones tomadas, contadores de reintentos.
• Node: una función que recibe el estado, ejecuta lógica (llamada al LLM, ejecución de herramienta, validación) y devuelve el estado actualizado.
• Edge: una transición entre nodos. Puede ser incondicional (siempre va al siguiente) o condicional (va a un nodo u otro dependiendo del estado).
• Checkpointer: persiste el estado del grafo para poder reanudar ejecuciones interrumpidas, implementar HITL y hacer replay.

Estructura típica de un agente LangGraph:

El grafo tiene un nodo de entrada que recibe el objetivo del usuario. Un nodo "planner" que decide qué herramienta llamar. Un nodo "executor" que ejecuta la herramienta. Un nodo "evaluator" que decide si el resultado es suficiente o necesita más pasos. Y un nodo de salida que formatea la respuesta final.

La ventaja de LangGraph sobre otros frameworks es el control total. Puedes implementar lógica de negocio arbitraria en cada nodo, gestionar errores con granularidad, implementar circuit breakers, timeouts y HITL en puntos específicos del flujo. El coste es mayor complejidad inicial, pero la ganancia es un agente predecible y debuggable.

Para tutoriales detallados de LangGraph, consulta nuestra guía de LangChain en español.

Implementación con CrewAI

CrewAI toma un enfoque diferente: defines agentes como "personas" con roles, objetivos y herramientas, y la orquestación se gestiona automáticamente.

Conceptos clave de CrewAI:

• Agent: un personaje con rol ("Senior Research Analyst"), objetivo ("Find and synthesize market data"), backstory (contexto) y un conjunto de herramientas disponibles.
• Task: una tarea específica asignada a un agente con descripción, contexto esperado y criterio de completitud.
• Crew: un equipo de agentes con tareas asignadas y un modo de ejecución (secuencial o jerárquico).
• Process: cómo se ejecutan las tareas. Secuencial (una tras otra) o jerárquico (un agente manager coordina a los demás).

Cuándo usar CrewAI vs LangGraph:

• Prototipo rápido: CrewAI (puedes tener un agente funcional en 30 minutos)
• Lógica de negocio compleja: LangGraph (control total sobre el flujo)
• Multi-agente con roles claros: CrewAI (el paradigma de "equipo" es natural)
• Producción con requisitos de fiabilidad: LangGraph (checkpointing, HITL, observabilidad)
• Integración con sistemas existentes: LangGraph (más flexible en I/O)

Ejemplo práctico: agente de investigación

Vamos a diseñar un agente de investigación que recibe un tema, busca información en múltiples fuentes, sintetiza los hallazgos y produce un informe estructurado. Este es uno de los patrones más útiles y transferibles a otros dominios.

Objetivo del agente: dado un tema de investigación, producir un informe de 1.000-1.500 palabras con fuentes verificadas, datos cuantitativos cuando estén disponibles y una sección de conclusiones accionables.

Herramientas disponibles:

• web_search: busca en la web y devuelve los 10 primeros resultados con título, URL y snippet
• web_scrape: extrae el contenido completo de una URL en formato markdown
• document_search: busca en una base de conocimiento interna (vector store)
• write_report: genera el informe final con las secciones requeridas

Flujo del agente:

1. Plan: el planner analiza el tema y genera 3-5 preguntas de investigación que debe responder
2. Search: para cada pregunta, ejecuta web_search y selecciona las 3 fuentes más relevantes
3. Extract: usa web_scrape para extraer el contenido de las fuentes seleccionadas
4. Internal check: busca en la base de conocimiento interna información complementaria
5. Synthesize: el planner sintetiza toda la información recopilada, identifica consensos, contradicciones y gaps
6. Write: genera el informe final con la estructura definida
7. Validate: revisa que el informe tenga fuentes, datos cuantitativos y que las conclusiones estén soportadas por la evidencia

Este flujo tiene entre 15 y 30 llamadas al LLM y entre 10 y 20 llamadas a herramientas por ejecución. El coste por informe usando Claude Sonnet como planner es de aproximadamente 0,10-0,30 EUR. Con un modelo self-hosted como Qwen 3.5, el coste marginal es cercano a cero (solo el coste fijo de la GPU).

MCP como capa de herramientas

El Model Context Protocol (MCP) es el estándar que está transformando cómo los agentes se conectan con herramientas externas. En lugar de implementar cada integración como una función custom, MCP define un protocolo estándar para que los agentes descubran y usen herramientas de forma uniforme.

Por qué MCP es relevante para agentes. Sin MCP, cada herramienta es una integración custom: escribes el código de la función, defines el schema de input/output, manejas errores y documentas la herramienta para que el LLM la entienda. Con MCP, conectas un servidor MCP y el agente descubre automáticamente las herramientas disponibles, sus schemas y sus descripciones. Para una explicación detallada de MCP, consulta nuestro artículo qué es MCP en inteligencia artificial.

Arquitectura con MCP:

• Tu agente (LangGraph o CrewAI) actúa como MCP client
• Cada servicio externo expone sus capacidades como MCP server
• El agente descubre herramientas disponibles al inicio de la sesión
• Cuando el planner decide usar una herramienta, la llama a través del protocolo MCP
• El resultado vuelve al agente en formato estándar

La ventaja es composabilidad: puedes añadir y quitar herramientas sin cambiar el código del agente. Si mañana quieres que tu agente de investigación también consulte una base de datos de patentes, conectas el MCP server de patentes y el agente lo descubre automáticamente.

Deployment y escalado

Desplegar un agente en producción es diferente a desplegarlo en desarrollo. En desarrollo, el agente corre en tu máquina, con tu API key, y si falla, lo reinicias manualmente. En producción, necesitas fiabilidad, escalado y gestión de costes.

Opciones de deployment:

• Docker + servidor dedicado: la opción más común. El agente corre como un servicio Docker con un endpoint HTTP o WebSocket. Hetzner o cualquier VPS con suficiente RAM (4-8GB para la aplicación, más si usas modelos locales).
• Serverless (Cloudflare Workers, AWS Lambda): para agentes con ejecuciones cortas (menos de 30 segundos). No es viable para agentes que hacen múltiples llamadas a herramientas.
• LangGraph Cloud: hosting gestionado por LangChain. Incluye checkpointing, HITL y observabilidad out of the box. Más caro pero con menos operaciones.

Gestión de errores en producción:

• Circuit breakers: si una herramienta falla 3 veces seguidas, deja de llamarla y notifica
• Timeouts: cada llamada a herramienta tiene un timeout configurable (30s por defecto)
• Max iterations: el agente tiene un límite de pasos (10-20) para evitar loops infinitos
• Fallbacks: si el LLM principal no responde, fallback a un modelo más pequeño o a una respuesta estática
• Dead letter queue: las ejecuciones fallidas se almacenan para análisis posterior

Testing de agentes

Testear agentes es fundamentalmente diferente a testear software tradicional. El output de un LLM no es determinístico: el mismo input puede producir outputs diferentes. Necesitas una estrategia de testing adaptada.

Unit tests de herramientas. Cada herramienta se testea de forma aislada con inputs conocidos y outputs esperados. Esto es testing tradicional: dado este input, espero este output (o un error específico). Las herramientas son determinísticas y se testean como cualquier función.

Eval datasets. Un conjunto de pares (input, output esperado) que representan casos de uso del agente. El agente procesa cada input y un evaluador (otro LLM o un humano) compara el output con el esperado. La métrica es accuracy: porcentaje de respuestas correctas. El umbral mínimo para producción depende del caso de uso: 90%+ para agentes de soporte, 95%+ para agentes financieros, 80%+ para agentes creativos.

Tests de integración. Verifican que el agente llama a las herramientas correctas en el orden correcto. No evalúan el contenido del output, sino el flujo de ejecución. "Dado este objetivo, el agente debería llamar a web_search, luego a web_scrape, luego a write_report."

Tests adversariales. Inputs diseñados para romper al agente: prompt injection, inputs malformados, peticiones fuera de scope, instrucciones contradictorias. El agente debe manejar estos casos sin ejecutar acciones no autorizadas y sin exponer información sensible.

Monitorización en producción

Un agente en producción sin monitorización es una bomba de relojería. No sabes si funciona correctamente, cuánto cuesta cada ejecución, ni cuándo empieza a degradarse.

Métricas esenciales:

• Latencia por ejecución: tiempo total desde input hasta output. Incluye tiempo de LLM + tiempo de herramientas + overhead.
• Tokens consumidos: input tokens + output tokens por ejecución. Directamente proporcional al coste si usas APIs.
• Tasa de éxito: porcentaje de ejecuciones que completan sin error. Si baja del 95%, hay un problema.
• Número de pasos por ejecución: cuántas llamadas a LLM y herramientas necesita. Si sube, el agente está siendo ineficiente o está en un loop.
• Coste por ejecución: EUR por task completada. Fundamental para unit economics.

Herramientas de observabilidad:

• Langfuse (OSS): trazas completas de ejecución, métricas de tokens y latencia, dashboard de costes. Se despliega en tu infraestructura.
• OpenTelemetry: estándar de trazas que se integra con Grafana, Jaeger o cualquier backend de observabilidad.
• LangSmith: observabilidad gestionada por LangChain. Trazas, evals, datasets de testing integrados.

Alertas recomendadas:

• Tasa de éxito < 95% en los últimos 100 ejecuciones
• Latencia P95 > 2x la media histórica
• Coste diario > presupuesto definido
• Ejecución individual > max_iterations (loop detectado)
• Herramienta específica con error rate > 10%

Preguntas frecuentes