Ejemplos de CrewAI: crear y coordinar equipos de agentes

CrewAI es un framework Python para construir equipos de agentes de IA basado en un modelo de roles. En lugar de definir grafos complejos (como en LangGraph), simplemente describes quién forma tu equipo, qué hace cada uno y cómo colaboran. Es más intuitivo: piensas en roles y tareas, no en nodos y aristas.

João Moura desarrolló CrewAI en 2024 y rápidamente se consolidó como el framework multi-agente más accesible para principiantes. Está construido sobre LangChain, pero abstrae la complejidad innecesaria. Si quieres armar un equipo de agentes funcional sin aprender teoría de grafos, CrewAI es tu mejor opción.

En este tutorial te muestro tres ejemplos completos y prácticos: un equipo de creación de contenido, uno para revisión de código y otro para atención al cliente. Todos los ejemplos son ejecutables y puedes usarlos directamente como base para tus propios proyectos.

TL;DR: CrewAI en 90 segundos

La arquitectura de CrewAI: cómo funciona

El modelo de roles

CrewAI se basa en una idea simple pero poderosa: modeleas un equipo de agentes como un equipo real. Cada miembro tiene:

• Rol (Role): ¿Quién es el agente? “Senior Data Analyst”, “Tech Writer”, “Security Expert”
• Objetivo (Goal): ¿Qué quiere lograr el agente? “Encuentra todas las vulnerabilidades de seguridad en el código”
• Trasfondo (Backstory): ¿Qué experiencia y personalidad tiene el agente? “Eres un experto en seguridad con 15 años de experiencia en pruebas de penetración”
• Herramientas (Tools): ¿Qué instrumentos tiene disponibles? Búsqueda web, ejecución de código, acceso a archivos

El trasfondo es importante: influye en cómo el LLM “piensa” y responde. Un agente con el trasfondo “Eres un revisor exigente que no hace concesiones” responderá diferente a uno con “Eres un mentor servicial que apoya a los desarrolladores”.

El ciclo de vida de las tareas

Cuando ejecutas crew.kickoff(), ocurre lo siguiente:

1. Se determina el orden de tareas: Con Process.sequential se ejecutan en el orden definido. Con Process.hierarchical, un agente gerente decide el orden.
2. Selección del agente: Cada tarea tiene un parámetro agent. Se activa el agente correspondiente.
3. Llamada al LLM: El agente recibe su rol, objetivo, trasfondo, la tarea y los resultados de tareas previas como contexto.
4. Uso de herramientas: Si el agente tiene herramientas, puede invocarlas (búsqueda web, lectura de archivos, etc.).
5. Resultado: La salida del agente se pasa a la siguiente tarea.
6. Delegación: Si allow_delegation=True, un agente puede delegar tareas a otros.

Secuencial vs. jerárquico

Secuencial (por defecto): Las tareas se ejecutan una tras otra. La salida de la tarea 1 está automáticamente disponible como contexto en la tarea 2. Simple, predecible, ideal para flujos lineales.

Jerárquico: Un agente gerente recibe todas las tareas y decide qué agente hace qué y en qué orden. El gerente puede redistribuir tareas, reordenarlas y evaluar resultados. Útil para flujos complejos, pero más costoso (una llamada LLM adicional para el gerente).

Instalación y configuración

pip install crewai crewai-tools

API Keys:

export OPENAI_API_KEY="sk-..."
# Para búsqueda web con SerperDev:
export SERPER_API_KEY="..."

Modelos locales (gratuito para desarrollo):

# Instala Ollama y descarga un modelo
ollama pull llama3.1:8b

# Úsalo en CrewAI:
from langchain_community.llms import Ollama
llm = Ollama(model="llama3.1:8b")

Los 3 componentes clave: en detalle

1. Agent: el miembro del equipo

from crewai import Agent

researcher = Agent(
    role="Senior Research Analyst",
    goal="Encuentra información exhaustiva, actualizada y precisa sobre el tema dado",
    backstory="""Eres un analista de investigación experimentado con 10 años de trayectoria.
    Tienes acceso a bases de datos científicas y sabes cómo distinguir
    fuentes confiables de las poco confiables.
    Siempre estructuras tu investigación de forma clara y citas las fuentes.""",
    verbose=True,           # Registros detallados
    allow_delegation=False,  # Este agente no delega
    tools=[search_tool],    # Herramientas que puede usar
    llm=llm                  # Opcional: LLM propio para este agente
)

Parámetros importantes:

• verbose=True: Muestra registros detallados de lo que piensa y hace el agente. Esencial para depuración.
• allow_delegation: Si es True, el agente puede delegar tareas a otros. Útil para gerentes o revisores, pero peligroso si hay demasiadas delegaciones (¡costo!).
• tools: Lista de herramientas de LangChain. Sin herramientas, el agente es solo un chatbot.
• llm: Puedes usar un LLM diferente para cada agente. Por ejemplo, GPT-4o para tareas complejas y GPT-4o-mini para simples.
• max_iter: Número máximo de iteraciones (por defecto 25). Protege contra bucles infinitos.
• memory: Si es True, el agente mantiene memoria entre múltiples tareas.

2. Task: la tarea

from crewai import Task

research_task = Task(
    description="""Investiga los últimos desarrollos en programación de IA en 2026.
    Considera nuevas herramientas, mejores prácticas y casos de uso prácticos.
    El informe debe incluir al menos 5 puntos principales.""",
    
    expected_output="""Un informe detallado con 5 puntos principales (2-3 oraciones cada uno),
    referencias de fuentes y un resumen al final.""",
    
    agent=researcher,
    output_file="output/research_report.md"  # Opcional: guardar resultado en archivo
)

Parámetros importantes:

• description: Sé específico: tareas vagas generan resultados vagos.
• expected_output: Describe exactamente cómo debe verse la salida. Este es el parámetro más importante. En lugar de “escribe un artículo” usa “escribe un artículo de 800 palabras en Markdown con introducción, 3 subtítulos y conclusión”.
• agent: ¿Qué agente debe ejecutar esta tarea?
• context: Lista de otras tareas cuyos resultados sirven como contexto.
• output_file: Guarda la salida en un archivo. Útil para depuración.

3. Crew — El equipo

from crewai import Crew, Process

crew = Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, write_task, edit_task],
    process=Process.sequential,  # o Process.hierarchical
    verbose=True,
    memory=True,       # Memoria entre múltiples ejecuciones
    cache=True,        # Cache para resultados de herramientas
    max_rpm=10         # Rate-limiting: solicitudes por minuto
)

result = crew.kickoff()

Qué hace kickoff(): valida los agentes y tareas, determina el orden de ejecución, ejecuta cada tarea (el agente recibe contexto + tarea → llamada LLM → resultado), y devuelve el resultado final.

Ejemplo 1: Content-Creation-Crew (Completo)

Un equipo con investigador, escritor y editor para artículos de blog, con herramientas reales, prompts detallados y archivos de salida.

import os
from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool, ScrapeWebsiteTool

# Inicializar herramientas
search_tool = SerperDevTool()
web_scraper = ScrapeWebsiteTool()

# --- AGENTS ---

researcher = Agent(
    role="Senior Content Researcher",
    goal="Recopila información fundamentada, actualizada y precisa sobre el tema",
    backstory="""Eres un experto en investigación con acceso a fuentes científicas 
    y blogs de tecnología. Sabes diferenciar entre fuentes confiables e 
    infiables. Siempre estructuras tu investigación de forma clara y 
    proporcionas todas las fuentes con URLs.""",
    tools=[search_tool, web_scraper],
    verbose=True,
    allow_delegation=False
)

writer = Agent(
    role="Tech Journalist",
    goal="Escribe un artículo atractivo, informativo y bien estructurado",
    backstory="""Eres un periodista de tecnología galardonado que explica temas 
    complejos de forma comprensible. Escribes para una audiencia técnica que 
    busca aplicabilidad práctica. Utilizas lenguaje activo, oraciones cortas 
    y ejemplos concretos.""",
    verbose=True,
    allow_delegation=False
)

editor = Agent(
    role="Senior Editor",
    goal="Asegura calidad, corrección, legibilidad y optimización SEO",
    backstory="""Eres un editor riguroso con 20 años de experiencia. Revisas 
    gramática, estilo, corrección factual y palabras clave SEO. Das feedback 
    concreto y mejoras el artículo directamente. No aceptas declaraciones 
    imprecisas ni fuentes faltantes.""",
    verbose=True,
    allow_delegation=True  # El editor puede delegar en investigador o escritor
)

# --- TASKS ---

research_task = Task(
    description="""Investiga el tema 'Frameworks de Python 2026'.
    Encuentra los 5 mejores frameworks de Python para desarrollo web en 2026,
    con ventajas y desventajas, ejemplos prácticos y comparativas de rendimiento.
    Utiliza búsqueda web para información actualizada.""",
    expected_output="""Investigación estructurada con los 5 mejores frameworks,
    ventajas/desventajas por framework, al menos 3 fuentes por framework,
    y recomendación para 3 casos de uso (startup, empresa, prototipo).""",
    agent=researcher,
    output_file="output/research.md"
)

write_task = Task(
    description="""Escribe un artículo de blog (800-1200 palabras) basado 
    en la investigación. Estructura: introducción, cuerpo con subtítulos, 
    tabla comparativa, ejemplos prácticos, conclusión. Escribe en español, 
    dirige al lector de forma cercana, usa lenguaje activo.""",
    expected_output="""Artículo de blog completo en Markdown: 800-1200 palabras,
    estructura H1/H2, tabla comparativa, ejemplos de código, recomendación clara.""",
    agent=writer,
    output_file="output/article_draft.md"
)

edit_task = Task(
    description="""Revisa y mejora el artículo: gramática, estilo,
    corrección factual, SEO (meta-descripción, palabras clave, títulos),
    y aplicabilidad práctica. Mejora las declaraciones imprecisas.""",
    expected_output="""Artículo final corregido en Markdown con
    meta-descripción SEO, legibilidad mejorada, fuentes verificadas.""",
    agent=editor,
    output_file="output/article_final.md"
)

# --- CREW ---

content_crew = Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, write_task, edit_task],
    process=Process.sequential,
    verbose=True,
    memory=True
)

result = content_crew.kickoff()
print(result)

Lo que sucede aquí: el investigador usa búsqueda web, el escritor recibe la investigación como contexto y escribe el artículo, el editor revisa y mejora, puede delegar si hay dudas. Cada paso guarda archivos de salida para depuración. Costos con GPT-4o: aproximadamente 0.50-2.00$ por ejecución.

Ejemplo 2: Code-Review-Crew (Completo)

Un equipo para revisiones de código automatizadas con enfoque en seguridad.

from crewai import Agent, Task, Crew, Process
from crewai_tools import DirectoryReadTool, FileReadTool

file_reader = FileReadTool()
dir_reader = DirectoryReadTool(directory="src/")

# --- AGENTS ---

code_reviewer = Agent(
    role="Senior Security Code Reviewer",
    goal="Identifica bugs, problemas de seguridad, rendimiento y violaciones de mejores prácticas",
    backstory="""Eres un experto en seguridad con 15 años de experiencia. Conoces 
    OWASP Top 10, CWE-Top-25 y patrones de seguridad comunes. Revisas código 
    de forma sistemática: primero seguridad, luego bugs, luego estilo. Das a 
    cada problema un nivel de severidad (Critical/High/Medium/Low).""",
    tools=[file_reader, dir_reader],
    verbose=True
)

refactorer = Agent(
    role="Refactoring Specialist",
    goal="Mejora la calidad del código sin alterar su funcionalidad",
    backstory="""Estás especializado en Clean Code, principios SOLID y patrones 
    de diseño. Refactoreas de forma conservadora: cambios pequeños y seguros. 
    Nunca rompes funcionalidad existente. Explicas cada cambio.""",
    tools=[file_reader],
    verbose=True
)

doc_writer = Agent(
    role="Technical Writer",
    goal="Crea documentación clara y comprensible para el código mejorado",
    backstory="""Escribes documentación técnica comprensible para desarrolladores. 
    Usas ejemplos de código, diagramas y tablas. Documentas no solo QUÉ, 
    sino también POR QUÉ.""",
    verbose=True
)

# --- TASKS ---

review_task = Task(
    description="""Revisa todo el código en el directorio src/.
    Verifica: OWASP Top 10, problemas de autenticación, secretos hardcodeados, 
    manejo de errores, rendimiento (consultas N+1), code smells. Usa 
    DirectoryReadTool y FileReadTool para leer todos los archivos.""",
    expected_output="""Informe de revisión de código con tabla de todos los problemas
    (archivo, línea, severidad, descripción), agrupados por severidad,
    con recomendación concreta para cada problema.""",
    agent=code_reviewer,
    output_file="output/code_review.md"
)

refactor_task = Task(
    description="""Refactoriza el código basándote en la revisión.
    Prioridad: 1. Soluciona problemas Critical/High, 2. Cierra brechas de seguridad,
    3. Reduce code smells. IMPORTANTE: no cambies funcionalidad.""",
    expected_output="""Código refactorizado con todos los cambios listados
    (archivo, qué cambió, por qué), comparativa antes/después para cambios críticos,
    justificación para cada refactoring.""",
    agent=refactorer,
    output_file="output/refactored_code.md"
)

doc_task = Task(
    description="""Documenta los cambios y el nuevo código.
    Crea CHANGELOG.md, documentación de funciones y checklist de seguridad.""",
    expected_output="""Documentación completa: CHANGELOG.md,
    documentación de módulos con descripción de funciones, ejemplos de código,
    checklist de seguridad para desarrollos futuros.""",
    agent=doc_writer,
    output_file="output/documentation.md"
)

# --- CREW ---

code_crew = Crew(
    agents=[code_reviewer, refactorer, doc_writer],
    tasks=[review_task, refactor_task, doc_task],
    process=Process.sequential,
    verbose=True
)

result = code_crew.kickoff()
print(result)

Por qué este setup funciona: el revisor lee código y encuentra problemas usando herramientas de archivo, el refactorer recibe la lista de problemas y mejora el código, el escritor documenta todo. Proceso secuencial: cada paso se construye sobre el anterior.

Ejemplo 3: Equipo de Soporte al Cliente (Jerárquico)

Un equipo para automatizar soporte al cliente con coordinación mediante un gestor.

from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool, FileReadTool

search_tool = SerperDevTool()
kb_reader = FileReadTool()

# --- AGENTS ---

triage_agent = Agent(
    role="Support Triage Specialist",
    goal="Kategorisiere y prioriza correctamente los tickets de soporte entrantes",
    backstory="""Analizas solicitudes de soporte en segundos. Identificas 
    severidad, categoría (Técnica, Facturación, Solicitud de Función) y 
    urgencia. Diriges cada ticket al agente correcto.""",
    verbose=True
)

solver_agent = Agent(
    role="Technical Support Engineer",
    goal="Resuelve problemas técnicos de los clientes rápida y correctamente",
    backstory="""Eres versátil en la resolución de problemas técnicos. 
    Conoces la base de conocimiento de memoria y puedes buscar en la documentación. 
    Si no conoces una solución, lo dices con honestidad y propones alternativas.""",
    tools=[search_tool, kb_reader],
    verbose=True
)

escalation_agent = Agent(
    role="Escalation Manager",
    goal="Escala problemas sin resolver al equipo correcto con contexto completo",
    backstory="""Decides cuándo derivar un problema a especialistas. 
    Te aseguras de que se transmita toda la información para que el especialista 
    no comience desde cero. Priorizas escalaciones según el impacto empresarial.""",
    verbose=True
)

# --- TASKS ---

triage_task = Task(
    description="""Analiza el ticket de soporte: 'Cliente no puede iniciar sesión. 
    Mensaje de error: Invalid token. Chrome en Windows 11.'
    Determina categoría, severidad, urgencia y agente recomendado.""",
    expected_output="""Reporte de clasificación con categoría, severidad más justificación,
    urgencia, agente recomendado e evaluación inicial (2-3 oraciones).""",
    agent=triage_agent
)

solve_task = Task(
    description="""Intenta resolver el problema. Busca en la base de conocimiento
    'Invalid token' y 'Login problems'. Busca en la web soluciones.
    Si es solucionable: instrucciones paso a paso. Si no: prepara escalación.""",
    expected_output="""Ya sea propuesta de solución con instrucciones paso a paso
    y referencia al artículo de KB, o reporte de escalación con toda la información
    y recomendación del equipo destinatario.""",
    agent=solver_agent
)

escalation_task = Task(
    description="""Si el problema no se resolvió, prepara una escalación profesional
    con descripción del problema, intentos de solución previos, sistema del cliente,
    impacto empresarial y recomendación.""",
    expected_output="""Ticket de escalación con resumen, todos los pasos anteriores,
    impacto empresarial evaluado y recomendación de prioridad.""",
    agent=escalation_agent
)

# --- CREW (JERÁRQUICO) ---

support_crew = Crew(
    agents=[triage_agent, solver_agent, escalation_agent],
    tasks=[triage_task, solve_task, escalation_task],
    process=Process.hierarchical,  # ¡El gestor decide el orden!
    verbose=True
)

result = support_crew.kickoff()
print(result)

¿Por qué jerárquico? En tickets de soporte no siempre está claro qué orden tiene sentido. A veces el especialista resuelve el problema directamente. A veces necesita escalarse de inmediato. El agente gestor decide dinámicamente. La desventaja es que el gestor realiza una llamada LLM adicional por cada decisión, lo que cuesta más, pero la flexibilidad lo justifica.

Herramientas personalizadas para CrewAI

Puedes crear herramientas propias cuando las integradas no son suficientes:

from crewai_tools import BaseTool

class DatabaseQueryTool(BaseTool):
    name: str = "Database Query Tool"
    description: str = "Ejecuta consultas SQL y devuelve resultados."
    
    def _run(self, query: str) -> str:
        import sqlite3
        conn = sqlite3.connect("database.db")
        cursor = conn.cursor()
        try:
            cursor.execute(query)
            results = cursor.fetchall()
            return str(results)
        except Exception as e:
            return f"Query failed: {str(e)}"
        finally:
            conn.close()

class APIRequestTool(BaseTool):
    name: str = "API Request Tool"
    description: str = "Realiza solicitudes HTTP a una API."
    
    def _run(self, url: str, method: str = "GET") -> str:
        import requests
        response = requests.request(method, url)
        return response.text

# Uso:
db_tool = DatabaseQueryTool()
api_tool = APIRequestTool()

analyst = Agent(
    role="Data Analyst",
    goal="Analiza datos de la base de datos",
    backstory="Eres experto en SQL.",
    tools=[db_tool, api_tool]
)

Lo importante en herramientas personalizadas:

• La description es crítica — el LLM decide si usar la herramienta basándose en ella
• El método _run debe devolver una cadena de texto (eso es lo que ve el LLM)
• Manejo de errores en la herramienta: devuelve siempre una cadena útil, nunca una excepción
• Seguridad: sanitiza las entradas. El LLM podría generar consultas SQL arbitrarias

Mejores prácticas de la experiencia

1. La biografía es más importante de lo que crees

La biografía determina el “carácter” del agente e influye enormemente en la calidad. “Eres un revisor exigente que respalda cada afirmación con fuentes” produce resultados dramáticamente diferentes a “Eres un revisor”.

2. El resultado esperado debe ser preciso

“Escribe un artículo” genera salida vaga. “Escribe un artículo de 800 palabras en Markdown con estructura H1/H2, 3 ejemplos de código y una tabla comparativa” produce salida precisa.

3. Las herramientas marcan la diferencia

Un agente sin herramientas es solo un chatbot. Con búsqueda web, acceso a archivos o conectividad API se vuelve realmente útil.

4. Controla los costos

Cada agente realiza al menos 1 llamada LLM. Con 3 agentes, delegación y gestor, rápidamente son 10+ llamadas. Usa GPT-4o-mini para tareas simples y GPT-4o solo para las complejas.

5. Aprovecha los archivos de salida

output_file por tarea guarda resultados intermedios. Es invaluable para depuración, ves exactamente qué produjo cada agente.

CrewAI vs. LangGraph ¿Cuál para cada caso?

Aspecto	CrewAI	LangGraph
Enfoque	Basado en roles (metáfora de equipo)	Basado en grafo (teoría de grafos)
Tiempo de configuración	10 min para 3 agentes	30-60 min para el mismo flujo
Control	Menos granular	Muy granular (Conditional Edges)
Curva de aprendizaje	Plana, intuitiva	Pronunciada, conceptos de grafo necesarios
Ciclos/Bucles	Limitados (max_iter)	Nativos (Conditional Edges)
Human-in-the-Loop	Manual	Nativo (interrupt)
Delegación	Nativa (allow_delegation)	Manual
Agente gestor	Nativo (Process.hierarchical)	Manual como nodo
Idóneo para	Flujos estándar, prototipos	Flujos complejos condicionales, producción

Mi recomendación:

• CrewAI para: creación de contenido, revisión de código, soporte al cliente, equipos simples de 2-5 agentes
• LangGraph para: flujos de producción complejos con ciclos, condiciones, human-in-the-loop
• Ambos pueden coexistir, CrewAI para prototipos rápidos, LangGraph para la versión de producción

Problemas comunes y soluciones

Problema: El agente alucina fuentes

Solución: Proporciona al agente una herramienta de búsqueda web y escribe en la descripción de la tarea: “Todas las afirmaciones deben estar respaldadas por fuentes”.

Problema: El agente delega demasiado

Solución: Establece allow_delegation=False para agentes que deben trabajar de forma autónoma. Solo los gestores y revisores deberían poder delegar.

Problema: La ejecución de la crew tarda demasiado

Solución: Reduce max_iter, utiliza modelos más rápidos (GPT-4o-mini), disminuye el número de agentes, desactiva memory.

Problema: Los resultados son superficiales

Solución: Perfecciona expected_output con requisitos específicos (longitud, estructura, formato).

Puntos relevantes para el examen

• CrewAI: Framework multi-agente basado en roles, construido sobre LangChain
• 3 componentes principales: Agent (rol, objetivo, trasfondo, herramientas), Task (descripción, expected_output, agente), Crew (agentes + tareas + proceso)
• Tipos de proceso: Sequential (orden lineal) vs. Hierarchical (agente gestor coordina)
• Delegación: allow_delegation=True permite que los agentes asignen tareas a otros
• Herramientas: Built-in (SerperDev, ScrapeWebsite, FileRead, DirectoryRead) y herramientas personalizadas (BaseTool)
• Memory: memory=True para memoria entre contextos
• Output-Files: output_file por tarea para depuración y resultados intermedios
• Costos: Mínimo 1 llamada LLM por agente; el gestor y la delegación conllevan costos adicionales
• Comparación: CrewAI (rápido, intuitivo, control limitado) vs. LangGraph (complejo, granular, listo para producción)

Preguntas frecuentes

¿Puede CrewAI funcionar con modelos locales? Sí, mediante la integración de Ollama: from langchain_community.llms import Ollama; llm = Ollama(model="llama3.1:8b"). Puedes establecer llm por agente o globalmente en la crew. Los modelos locales son buenos para desarrollo, pero los modelos en la nube generalmente ofrecen mejores resultados.

¿Cuántos agentes debería tener una crew? 3-5 agentes son típicos y bien coordinables. Más de 8 se vuelve difícil de gestionar, los agentes delegan demasiado y los costos se disparan. Para requisitos complejos es mejor dividir en varias crews pequeñas.

¿Pueden comunicarse entre sí los agentes? Sí, con allow_delegation=True los agentes pueden asignar tareas a otros. Con Process.hierarchical, el agente gestor puede coordinar a todos los agentes y redistribuir tareas.

¿Cómo depuro una crew? Tres herramientas: 1) verbose=True para logs detallados. 2) output_file por tarea para resultados intermedios. 3) Tracing de LangSmith (variables de entorno: LANGCHAIN_TRACING_V2=true).

¿Cuánto cuesta ejecutar una crew con CrewAI? Con GPT-4o y 3 agentes: aprox. 0.50-2.00$ por ejecución. Con GPT-4o-mini: aprox. 0.05-0.20$. Con modelos locales (Ollama): 0$ pero más lento y menor calidad.

Lecturas recomendadas