CrewAI: Framework de Orquestación Multi-Agente para Python

1. ¿Qué es CrewAI?

CrewAI es un framework de código abierto en Python para orquestar agentes autónomos de IA que colaboran como un equipo. Creado por João Moura y lanzado a finales de 2023, modela sistemas multi-agente como equipos de especialistas con roles definidos -- cada agente tiene un rol, una meta y un trasfondo que moldea su comportamiento. Los agentes trabajan juntos en tareas organizadas en procesos secuenciales o jerárquicos, produciendo salidas estructuradas que fluyen a través del pipeline.

La filosofía de diseño central es colaboración basada en roles sobre programación rígida. En lugar de escribir flujo de control explícito para cada decisión, defines agentes con roles y metas en lenguaje natural, les asignas tareas con salidas esperadas y dejas que el framework orqueste su colaboración. Esto hace que CrewAI sea particularmente efectivo para automatización de trabajo intelectual: investigación, creación de contenido, análisis, planificación y cualquier flujo de trabajo donde múltiples especialistas contribuyen a un resultado compartido.

A junio 2026, CrewAI cruzó el hito 1.0 (v1.0.0 lanzada en octubre 2025; la versión actual es 1.14) y tiene más de 53,000 estrellas en GitHub, siendo uno de los frameworks multi-agente más adoptados en el ecosistema Python. El framework soporta cualquier proveedor de LLM (OpenAI, Anthropic Claude, Google Gemini, Ollama, Groq, Azure OpenAI y más), incluye un sistema de memoria integrado, se integra con servidores MCP y herramientas LangChain, y ofrece CrewAI+ -- una plataforma gestionada para despliegue en producción con monitoreo, testing y características empresariales.

3. Diseño de Agentes

El diseño de agentes es la parte más importante de construir crews efectivos. Cada agente se define por tres campos en lenguaje natural que moldean su comportamiento: role (qué es el agente), goal (qué está tratando de lograr) y backstory (contexto que da personalidad y experiencia al agente). Estos campos se inyectan en el prompt del sistema, así que elaborarlos bien es crítico para el rendimiento del agente.

Más allá de los campos de identidad centrales, los agentes aceptan configuración para asignación de LLM (parámetro llm), acceso a herramientas (lista tools), comportamiento de delegación (allow_delegation), límites máximos de iteración (max_iter), tiempo máximo de ejecución (max_execution_time) y configuración de memoria. Puedes asignar diferentes LLMs a diferentes agentes -- usa un modelo potente para tareas de razonamiento complejo y un modelo rápido y económico para extracción de datos simple.

from crewai import Agent, LLM

# Agent with specific LLM and configuration
analyst = Agent(
    role="Senior Financial Analyst",
    goal="Produce accurate financial analysis with actionable "
         "investment recommendations for {company}",
    backstory="You are a CFA charterholder with 20 years of experience "
              "in equity research. You specialize in technology sector "
              "analysis and are known for your rigorous, data-driven "
              "approach to valuation.",
    llm=LLM(model="anthropic/claude-sonnet-4-6", temperature=0.1),
    tools=[financial_data_tool, sec_filing_tool],
    allow_delegation=False,
    max_iter=15,
    max_execution_time=300,  # 5 minutes
    verbose=True
)

# YAML-based agent definition (config/agents.yaml)
# researcher:
#   role: "Senior Research Analyst"
#   goal: "Find comprehensive information on {topic}"
#   backstory: "Expert researcher with deep domain knowledge."
#   llm: openai/gpt-5.5
#   max_iter: 10

4. Definición de Tareas

Las tareas son las unidades de trabajo en CrewAI. Cada tarea tiene una description (qué hacer), un expected_output (cómo debe verse el resultado) y un agent (quién lo hace). La descripción y expected_output soportan interpolación {variable}, así que puedes parametrizar tareas en tiempo de ejecución vía crew.kickoff(inputs={...}).

El parámetro context crea dependencias de datos entre tareas. Cuando una tarea lista otras tareas en su contexto, recibe sus salidas como entrada adicional. Así es como la información fluye a través de un crew: la salida del investigador alimenta al escritor, la salida del escritor alimenta al editor. El contexto crea un DAG (grafo acíclico dirigido) de dependencias de tareas que CrewAI resuelve automáticamente.

from crewai import Task
from pydantic import BaseModel
from typing import List

# Structured output model
class ResearchReport(BaseModel):
    topic: str
    key_findings: List[str]
    recommendations: List[str]
    confidence_score: float

# Task with structured output and context
research_task = Task(
    description="Research {topic} and produce a structured analysis. "
                "Focus on: current state, key trends, major players, "
                "and technical challenges. Use available search tools.",
    expected_output="A structured research report with key findings, "
                    "actionable recommendations, and confidence score.",
    agent=researcher,
    output_pydantic=ResearchReport
)

# Async tasks that run in parallel
market_task = Task(
    description="Analyze market trends for {topic}.",
    expected_output="Market analysis with growth projections.",
    agent=market_analyst,
    async_execution=True
)

tech_task = Task(
    description="Analyze technical landscape for {topic}.",
    expected_output="Technical analysis with architecture comparisons.",
    agent=tech_analyst,
    async_execution=True
)

# Task with callback
def save_report(output):
    with open("report.md", "w") as f:
        f.write(output.raw)
    print(f"Report saved: {len(output.raw)} characters")

final_task = Task(
    description="Synthesize all research into a final report.",
    expected_output="A comprehensive report combining all analyses.",
    agent=writer,
    context=[market_task, tech_task],
    callback=save_report
)

5. Tipos de Proceso

El tipo de proceso determina cómo CrewAI orquesta la ejecución de tareas. CrewAI ofrece exactamente dos tipos de proceso -- secuencial y jerárquico. Elegir el correcto depende de las necesidades de coordinación de tu flujo de trabajo: pipelines predecibles usan secuencial, mientras que la delegación compleja y dinámica usa jerárquico.

from crewai import Crew, Process

# Sequential: tasks run in listed order
sequential_crew = Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, editing_task],
    process=Process.sequential,
    verbose=True
)

# Hierarchical: manager delegates to agents
hierarchical_crew = Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, editing_task],
    process=Process.hierarchical,
    manager_llm="openai/gpt-5.5",  # LLM for the auto-created manager
    verbose=True
)

# Hierarchical with custom manager
manager = Agent(
    role="Project Manager",
    goal="Coordinate the team to produce the highest quality output",
    backstory="Experienced PM who excels at delegating tasks to the "
              "right specialists and ensuring quality standards.",
    allow_delegation=True
)

custom_manager_crew = Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, editing_task],
    process=Process.hierarchical,
    manager_agent=manager,
    verbose=True
)

7. Sistema de Memoria

CrewAI incluye un sistema de memoria multicapa que da a los agentes la capacidad de aprender y retener información a través de tareas y ejecuciones del crew. La memoria está deshabilitada por defecto y se habilita con memory=True en el Crew. Cuando está habilitada, los agentes pueden recordar interacciones previas, construir conocimiento de entidades y mejorar su rendimiento con el tiempo.

from crewai import Crew

# Enable memory with default storage
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    memory=True,           # enables all memory layers
    verbose=True
)

# Custom memory configuration
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    memory=True,
    embedder={
        "provider": "openai",
        "config": {
            "model": "text-embedding-3-small"
        }
    },
    long_term_memory=LongTermMemory(
        storage=LTMSQLiteStorage(db_path="./crew_memory.db")
    ),
    short_term_memory=ShortTermMemory(
        storage=RAGStorage(
            embedder_config={
                "provider": "openai",
                "config": {"model": "text-embedding-3-small"}
            }
        )
    ),
    entity_memory=EntityMemory(
        storage=RAGStorage(
            embedder_config={
                "provider": "openai",
                "config": {"model": "text-embedding-3-small"}
            }
        )
    )
)

8. API de Flows

La API de Flows es la abstracción de nivel superior de CrewAI para construir flujos de trabajo con estado y dirigidos por eventos que coordinan múltiples crews y operaciones externas. Mientras los Crews manejan colaboración multi-agente en un conjunto de tareas, los Flows manejan la orquestación de múltiples crews, lógica condicional, gestión de estado e integración con sistemas externos en pipelines complejos.

Los Flows usan una sintaxis basada en decoradores: @start() marca el punto de entrada, @listen() conecta métodos que reaccionan a eventos (salidas de otros métodos) y @router() implementa ramificación condicional basada en estado o resultados. El Flow mantiene estado tipado a través de todos los pasos, facilitando construir flujos de trabajo complejos, multi-etapa con flujo de datos claro.

from crewai.flow.flow import Flow, listen, start, router
from pydantic import BaseModel

class ContentPipelineState(BaseModel):
    topic: str = ""
    research: str = ""
    draft: str = ""
    quality_score: float = 0.0
    final_content: str = ""

class ContentPipeline(Flow[ContentPipelineState]):

    @start()
    def gather_topic(self):
        self.state.topic = "Multi-Agent AI Orchestration"
        return self.state.topic

    @listen(gather_topic)
    def research_phase(self, topic):
        # Run a research crew
        research_crew = Crew(
            agents=[researcher],
            tasks=[research_task],
            verbose=True
        )
        result = research_crew.kickoff(inputs={"topic": topic})
        self.state.research = result.raw
        return result.raw

    @listen(research_phase)
    def writing_phase(self, research):
        # Run a writing crew
        writing_crew = Crew(
            agents=[writer, editor],
            tasks=[writing_task, editing_task],
            process=Process.sequential
        )
        result = writing_crew.kickoff(
            inputs={"research": research}
        )
        self.state.draft = result.raw
        return result.raw

    @router(writing_phase)
    def quality_check(self, draft):
        # Evaluate quality and decide next step
        score = evaluate_quality(draft)
        self.state.quality_score = score
        if score >= 0.8:
            return "publish"
        return "revise"

    @listen("publish")
    def publish(self):
        self.state.final_content = self.state.draft
        return f"Published: {len(self.state.final_content)} chars"

    @listen("revise")
    def revise(self):
        # Re-run writing with feedback
        return self.writing_phase(self.state.research)

# Run the flow
flow = ContentPipeline()
result = flow.kickoff()

11. Comparación de Frameworks

El panorama de frameworks multi-agente en 2026 incluye varios jugadores principales. Cada framework hace diferentes compromisos entre nivel de abstracción, flexibilidad y preparación para producción. La elección correcta depende de la complejidad de tu flujo de trabajo, experiencia del equipo y requisitos de despliegue.

CrewAI sobresale cuando necesitas colaboración de equipo estructurada con roles claros -- tiene el nivel de abstracción más alto, haciendo que sea el más rápido para prototipar flujos de trabajo multi-agente. AutoGen (Microsoft) es más fuerte para patrones conversacionales multi-turno donde los agentes debaten y refinan salidas. LangGraph ofrece el mayor control con máquinas de estado basadas en grafos explícitos, ideal para flujos de trabajo complejos que necesitan checkpointing y depuración con viaje en el tiempo. Claude Agent SDK tiene el acceso más profundo al sistema con herramientas integradas de archivos y shell. OpenAI Agents SDK proporciona el camino más simple a multi-agente con abstracciones mínimas y ejecución en sandbox.

12. Despliegue en Producción

Llevar CrewAI de prototipo a producción requiere abordar confiabilidad, monitoreo, manejo de errores, control de costos y escalamiento. CrewAI+ (la plataforma gestionada) maneja muchas de estas preocupaciones, pero despliegues auto-hospedados necesitan infraestructura explícita alrededor del framework.

# Production deployment with error handling and monitoring
import logging
from crewai import Crew
from tenacity import retry, stop_after_attempt, wait_exponential

logger = logging.getLogger("crewai_production")

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=60)
)
def run_crew_with_retries(crew, inputs):
    try:
        result = crew.kickoff(inputs=inputs)
        logger.info(
            f"Crew completed: {result.token_usage}"
        )
        return result
    except Exception as e:
        logger.error(f"Crew execution failed: {e}")
        raise

# Deploy as API endpoint (FastAPI example)
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()

@app.post("/api/analyze")
async def analyze(topic: str, background_tasks: BackgroundTasks):
    crew = Crew(
        agents=[researcher, analyst, writer],
        tasks=[research_task, analysis_task, report_task],
        process=Process.sequential,
        memory=True,
        max_rpm=30  # rate limit across all agents
    )
    background_tasks.add_task(
        run_crew_with_retries, crew, {"topic": topic}
    )
    return {"status": "processing", "topic": topic}

# CLI deployment with CrewAI+
# crewai deploy    -- deploys to CrewAI+ platform
# crewai monitor   -- real-time crew monitoring
# crewai logs      -- view execution logs

Primeros Pasos

CrewAI requiere Python 3.10 a 3.13 (3.14 aún no está soportado). Instala con pip y crea tu primer crew en minutos.

# Install CrewAI and tools
pip install crewai crewai-tools

# Create a new project with the CLI
crewai create crew my_project
cd my_project

# Configure agents in config/agents.yaml
# Configure tasks in config/tasks.yaml
# Run the crew
crewai run

# Minimal crew -- your first multi-agent workflow
from crewai import Agent, Task, Crew

researcher = Agent(
    role="Researcher",
    goal="Find accurate information on {topic}",
    backstory="Expert research analyst."
)

writer = Agent(
    role="Writer",
    goal="Write clear, engaging content based on research",
    backstory="Skilled technical writer."
)

research = Task(
    description="Research {topic} thoroughly.",
    expected_output="Comprehensive research brief.",
    agent=researcher
)

article = Task(
    description="Write an article based on the research.",
    expected_output="A polished 1000-word article.",
    agent=writer,
    context=[research]
)

crew = Crew(agents=[researcher, writer], tasks=[research, article])
result = crew.kickoff(inputs={"topic": "CrewAI multi-agent orchestration"})
print(result)

Para uso en producción, configura tus claves de API de LLM como variables de entorno, habilita memoria para aprendizaje entre ejecuciones y usa la API de Flows para orquestación multi-crew compleja. La documentación oficial en docs.crewai.com cubre todos los conceptos, integraciones y patrones avanzados en profundidad.