CrewAI: guía práctica de crews multi-agente en Python con roles

CrewAI es el framework Python para crews de agentes con roles: defines quién hace qué (Agent con rol, objetivo y backstory), qué hay que entregar (Task con expected_output) y cómo colaboran (Crew secuencial o jerárquica). No es un grafo con estado como LangGraph. No es un SDK de agente único tipado como Pydantic AI. No es un canvas no-code como Dify. Es código Python donde la unidad de diseño es el equipo, no el nodo.

Esta guía cubre el recorte del hub Construir agentes que sí pegas en un repo hoy: versiones, scaffolding, primer crew, tools propias, memoria, y cuándo subir a Flows. El curso Instalar un agente cubre el harness de producto; aquí el contrato es el de crewai.

Versiones y arranque

PyPI publica crewai 1.15.20 (verificado 2026-09-07) con requires_python: >=3.10. No uses Python 3.9 “porque el resto del proyecto ya lo tiene”: el install falla y el error no es obvio.

Instalación mínima:

pip install crewai

Scaffold oficial con CLI (genera agents.yaml, tasks.yaml y estructura de crew):

crewai create crew mi-crew

El CLI es la vía recomendada para proyectos nuevos. Para un script rápido o un notebook, importar Agent, Task y Crew directo basta.

El modelo mental: roles, entregables, equipo

Todo en CrewAI cuelga de tres clases:

Pieza	Pregunta que responde	Campos clave
Agent	¿Quién lo hace?	role, goal, backstory, tools, llm, memory
Task	¿Qué hay que entregar?	description, expected_output, agent
Crew	¿Cómo colaboran?	agents, tasks, process, memory, planning

El error típico es escribir tasks vagas (“investiga el mercado”) sin expected_output. El expected_output es el contrato: qué formato, qué campos, qué longitud. Sin contrato, el crew entrega un ensayo cuando necesitabas una tabla.

Tu primer crew en 30 líneas

from crewai import Agent, Task, Crew

investigador = Agent(
    role="Investigador de mercado",
    goal="Encontrar datos verificables sobre precios de café en Guatemala",
    backstory="Analista con 10 años cubriendo commodities agrícolas.",
    tools=[],
    memory=True,
)

redactor = Agent(
    role="Redactor de reportes",
    goal="Convertir datos crudos en un resumen ejecutivo claro",
    backstory="Editor que odia el relleno y ama las tablas.",
    memory=True,
)

investigar = Task(
    description="Recopila 5 datos de precios de café con fuente y fecha.",
    expected_output="Tabla markdown con 5 filas: dato, fuente, fecha.",
    agent=investigador,
)

resumir = Task(
    description="Convierte la tabla en un resumen ejecutivo de 150 palabras.",
    expected_output="Resumen de 150 palabras con los 3 hallazgos clave.",
    agent=redactor,
)

crew = Crew(
    agents=[investigador, redactor],
    tasks=[investigar, resumir],
    process="sequential",
    memory=True,
)

resultado = crew.kickoff()

crew.kickoff() corre las tasks en orden y devuelve el output de la última. Eso es todo el “runtime”: sin servidores, sin YAML obligatorio, sin grafo que dibujar.

process: sequential vs hierarchical

El parámetro process decide quién manda:

• sequential (default): las tasks corren en el orden de la lista, cada una con su agente asignado. Predecible, barato, depurable. Empieza siempre aquí.
• hierarchical: un manager (un LLM aparte) delega tasks entre los agentes según su rol. Más flexible para problemas abiertos, pero gastas más tokens y el trazo es más difícil de seguir.

Regla práctica: si puedes escribir la lista de pasos por adelantado, sequential. Si el plan depende de lo que encuentren los agentes, hierarchical. La comparativa con grafos y SDKs mínimos vive en LangGraph vs CrewAI vs OpenAI Agents SDK.

Tools propias con @tool

Un agente sin tools solo opina. Una tool es una función Python con el decorador @tool:

from crewai.tools import tool

@tool("Consultar inventario")
def consultar_inventario(sku: str) -> str:
    """Devuelve el stock actual de un SKU."""
    fila = db.query("SELECT stock FROM inventario WHERE sku = %s", (sku,))
    return f"Stock de {sku}: {fila['stock']}" if fila else f"SKU {sku} no existe."

Puntos que sí importan en producción:

1. El docstring es el contrato: el modelo decide cuándo llamar la tool leyendo el docstring. Docstring vago = llamadas inventadas.
2. Devuelve strings cortos, no objetos gigantes. El output de la tool entra al contexto del agente; si devuelves 200 filas, quemas la ventana y pagas el precio (ver truncar tool results).
3. Una tool, un verbo. consultar_inventario sí; gestionar_todo_el_erp no.

CrewAI también trae integraciones listas (búsqueda, scraping, bases de datos) y conexión con servidores MCP documentada en las docs oficiales. Empieza con tus propias tools antes de enchufar diez integraciones.

Memoria: qué recuerda el crew

memory=True en el Crew activa tres capas:

• Short-term: lo que pasó en esta ejecución.
• Long-term: aprendizajes entre ejecuciones (qué funcionó, qué no).
• Entity memory: personas, SKUs, proyectos que aparecen seguido.

La memoria larga persiste en disco (por defecto un store local). Para producción seria, apunta el storage a tu propia base y define política de borrado: un crew que recuerda PII de clientes sin TTL es un incidente esperando fecha. El patrón de permisos y frescura por tenant aplica igual aquí que en un RAG.

Cuándo subir a Flows

Cuando el proceso deja de ser “lista de pasos” y pasa a ser “máquina de estados” (reintentos condicionales, ramas según el resultado, loops con límite), el Crew plano se queda corto. Ahí entran los Flows: métodos decorados con @start y @listen que orquestan crews como pasos de un flujo con estado.

from crewai.flow import Flow, start, listen

class PipelineReporte(Flow):
    @start()
    def recolectar(self):
        return self.crew_investigacion.kickoff()

    @listen(recolectar)
    def redactar(self, datos):
        return self.crew_redaccion.kickoff(inputs={"datos": datos})

Regla: un crew resuelve una colaboración; un flow resuelve un proceso. Si tu Crew empieza a necesitar “si esto falla, vuelve al paso 2”, ya no quieres más tasks: quieres un Flow. Para ejecuciones largas con checkpoints y resume, el patrón es el mismo que en orquestación multi-agente.

Checklist de producción

• Python 3.10+ y crewai pineado en requirements.txt (crewai==1.15.20, no >= flotante en prod).
• Cada Task con expected_output medible (formato + longitud + campos).
• process="sequential" salvo que el plan sea genuinamente abierto.
• Tools con docstring-contrato y outputs recortados.
• OPENAI_API_KEY (o la key de tu proveedor) en entorno, nunca en el repo ni en el prompt.
• Memoria larga con storage propio y política de borrado si hay datos de clientes.
• Tracing activado (las docs listan integraciones: Langfuse, Phoenix, Braintrust, entre otras) antes del primer deploy.
• kickoff() envuelto en timeout y reintento con backoff en tu capa de llamada, no dentro del framework.

FAQ

¿CrewAI o LangGraph? Crews de roles con handoffs en lenguaje natural: CrewAI. Control exacto del flujo, ramas y estado tipado: LangGraph. La tabla de decisión completa está en la comparativa.

¿CrewAI o Pydantic AI? Un equipo colaborando (investigador + redactor + revisor): CrewAI. Un agente único con tipos estrictos y validación de outputs: Pydantic AI.

¿Necesito Flows desde el día uno? No. Empieza con un Crew secuencial y dos agentes. Cuando aparezcan ramas condicionales o reintentos entre pasos, migra a Flows.

¿Qué modelo uso? CrewAI acepta cualquier proveedor vía el parámetro llm del agente. Empieza con el que ya pagas; cambia cuando el costo por ejecución duela, no antes.

¿Dónde pongo los prompts del sistema? El backstory + goal del agente ES tu system prompt (ver system prompts para agentes). Escríbelos como fichas de puesto: rol, criterio de calidad y qué nunca debe hacer.