# Framework multiagente CrewAI

## Resumen

[CrewAI](https://github.com/crewAIInc/crewAI) es un marco de vanguardia para orquestar **agentes autónomos de IA que interpretan roles**, con **44K+ estrellas en GitHub**. A diferencia de los sistemas de un solo agente, CrewAI te permite definir agentes especializados (Investigador, Redactor, Programador, Analista...) que colaboran como una "tripulación" para completar tareas complejas — cada agente con su propio rol, objetivo, historia de fondo y conjunto de herramientas.

En **Clore.ai**, CrewAI puede desplegarse en un entorno Dockerizado por tan solo **$0.05–0.20/h**. Aunque CrewAI en sí está limitado por CPU (orquesta llamadas a APIs), combinarlo con un servidor local Ollama o vLLM en el mismo nodo GPU te da un sistema multiagente totalmente privado y capaz de funcionar sin conexión.

**Capacidades clave:**

* 👥 **Tripulaciones multiagente** — define las personalidades de los agentes con roles, objetivos e historias de fondo
* 🎯 **Delegación de tareas** — el agente gestor asigna automáticamente tareas al especialista adecuado
* 🛠️ **Ecosistema de herramientas** — búsqueda web, E/S de archivos, ejecución de código, acceso a bases de datos, herramientas personalizadas
* 🔁 **Secuencial y Paralelo** — ejecuta tareas en orden o ejecuta tareas independientes simultáneamente
* 🧠 **Memoria de agente** — tipos de memoria a corto plazo, largo plazo, de entidades y contextual
* 🔌 **Independiente de LLM** — funciona con OpenAI, Anthropic, Google, Ollama, Groq, Azure y más
* 📊 **CrewAI Studio** — interfaz visual para construir tripulaciones sin código (empresarial)
* 🚀 **Pipelines** — encadena múltiples tripulaciones para flujos de trabajo complejos en varias etapas

***

## Requisitos

CrewAI es una biblioteca de Python. Se ejecuta en CPU y solo requiere un entorno Python 3.10+ del sistema o Docker. La GPU es opcional pero desbloquea una inferencia local potente.

| Configuración                   | GPU                | VRAM  | RAM del sistema | Disco  | Precio de Clore.ai |
| ------------------------------- | ------------------ | ----- | --------------- | ------ | ------------------ |
| **Mínima** (APIs en la nube)    | Ninguno / Solo CPU | —     | 2 GB            | 10 GB  | \~$0.03/h (CPU)    |
| **Estándar**                    | Ninguno / Solo CPU | —     | 4 GB            | 20 GB  | \~$0.05/h          |
| **+ LLM local (pequeño)**       | RTX 3080           | 10 GB | 8 GB            | 40 GB  | \~$0.15/h          |
| **+ LLM local (grande)**        | RTX 3090 / 4090    | 24 GB | 16 GB           | 60 GB  | $0.20–0.35/h       |
| **+ LLM local de alta calidad** | A100 40 GB         | 40 GB | 32 GB           | 100 GB | \~$0.80/h          |

### Claves de API

CrewAI funciona con la mayoría de los principales proveedores de LLM. Necesitas al menos una:

* **OpenAI** — GPT-4o (mejor razonamiento para tareas complejas)
* **Anthropic** — Claude 3.5 Sonnet (excelente para tripulaciones centradas en redacción)
* **Groq** — Nivel gratuito, inferencia rápida (Llama 3 70B)
* **Ollama** — Totalmente local, no se necesita clave API (ver [Aceleración por GPU](#gpu-acceleration))

***

## Inicio rápido

### 1. Alquila un servidor Clore.ai

Inicia sesión en [clore.ai](https://clore.ai):

* **Solo CPU** si usas APIs de LLM en la nube
* **RTX 3090/4090** para inferencia local con Ollama
* Acceso SSH habilitado
* No hay requisitos especiales de puertos para el uso por CLI (expón puertos solo para interfaces web)

### 2. Conectar y preparar

```bash
ssh root@<ip-servidor-clore> -p <puerto-ssh>

# Actualizar el sistema
apt-get update && apt-get upgrade -y

# Instalar Python 3.11 (si no está presente)
apt-get install -y python3.11 python3.11-venv python3-pip
python3 --version   # Debe ser 3.10+

# Verificar Docker
docker --version
```

### 3. Opción A — instalación directa con pip (más rápida)

```bash
# Crear un entorno virtual
python3 -m venv crewai-env
source crewai-env/bin/activate

# Instalar CrewAI con todas las herramientas
pip install crewai crewai-tools

# Verificar la instalación
python -c "import crewai; print(crewai.__version__)"
crewai --version
```

### 4. Opción B — contenedor Docker (recomendado para reproducibilidad)

```bash
# Crear directorio del proyecto
mkdir my-crew && cd my-crew

# Escribir Dockerfile
cat > Dockerfile << 'EOF'
FROM python:3.11-slim

# Instalar dependencias del sistema
RUN apt-get update && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# Establecer directorio de trabajo
WORKDIR /app

# Instalar CrewAI y herramientas comunes
RUN pip install --no-cache-dir \
    crewai \
    crewai-tools \
    langchain-openai \
    langchain-anthropic \
    python-dotenv

# Copiar el código de la aplicación
COPY . .

# Comando predeterminado
CMD ["python", "main.py"]
EOF

# Construir la imagen
docker build -t my-crewai-app .
```

### 5. Crea tu primera tripulación

```bash
# Inicializa un nuevo proyecto CrewAI usando la CLI
source crewai-env/bin/activate
crewai create crew my-research-crew
cd my-research-crew

# Configurar claves de API
cat > .env << 'EOF'
OPENAI_API_KEY=sk-...
# O para Anthropic:
# ANTHROPIC_API_KEY=sk-ant-...
# O para Ollama (no se necesita clave):
# OPENAI_API_BASE=http://localhost:11434/v1
# OPENAI_API_KEY=ollama
EOF

# Instalar dependencias del proyecto
crewai install

# Ejecutar la tripulación
crewai run
```

***

## Configuración

### Estructura del proyecto (desde `crewai create`)

```
my-research-crew/
├── .env                    # Claves de API y configuraciones
├── pyproject.toml          # Dependencias
├── src/
│   └── my_research_crew/
│       ├── config/
│       │   ├── agents.yaml   # Definiciones de agentes
│       │   └── tasks.yaml    # Definiciones de tareas
│       ├── tools/
│       │   └── custom_tool.py  # Tus herramientas personalizadas
│       ├── crew.py           # Ensamblaje de la tripulación
│       └── main.py           # Punto de entrada
```

### agents.yaml — Define tus agentes

```yaml
researcher:
  role: >
    Analista de Investigación Senior
  goal: >
    Descubrir desarrollos de vanguardia en {topic} y sintetizar ideas accionables
  backstory: >
    Eres un investigador experto con talento para encontrar y conectar información
    de fuentes diversas. Tienes un ojo agudo para la credibilidad y la relevancia.
  tools:
    - SerperDevTool
    - ScrapeWebsiteTool
  llm: gpt-4o                # Puede establecerse por agente
  verbose: true
  max_iter: 15               # Máximo de iteraciones de razonamiento
  memory: true               # Habilitar memoria del agente

writer:
  role: >
    Escritor Técnico Experto
  goal: >
    Transforma investigación compleja en contenido claro, atractivo y preciso
  backstory: >
    Redactas explicaciones que hacen accesibles temas complejos sin sacrificar profundidad.
    Citas fuentes y estructuras el contenido para máxima legibilidad.
  llm: claude-3-5-sonnet-20241022
  verbose: true
```

### tasks.yaml — Define tareas

```yaml
research_task:
  description: >
    Investiga los últimos desarrollos en {topic} de los últimos 6 meses.
    Identifica tendencias clave, avances e implicaciones.
    Compila al menos 10 fuentes creíbles.
  expected_output: >
    Un informe de investigación detallado con hallazgos organizados por tema,
    incluyendo URLs de las fuentes y fechas de publicación.
  agent: researcher

writing_task:
  description: >
    Usando el informe de investigación, escribe una publicación de blog completa sobre {topic}.
    Longitud objetivo: 1500-2000 palabras. Incluye un título, introducción, secciones principales,
    y una conclusión con perspectivas futuras.
  expected_output: >
    Una publicación lista para publicar en formato Markdown.
  agent: writer
  context:
    - research_task    # La tarea de redacción recibe la salida del investigador
  output_file: output/blog_post.md
```

### crew\.py — Ensamblar la tripulación

```python
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool, ScrapeWebsiteTool

@CrewBase
class MyResearchCrew():
    """Tripulación de investigación y redacción"""
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

    @agent
    def researcher(self) -> Agent:
        return Agent(
            config=self.agents_config['researcher'],
            tools=[SerperDevTool(), ScrapeWebsiteTool()],
            verbose=True
        )

    @agent
    def writer(self) -> Agent:
        return Agent(
            config=self.agents_config['writer'],
            verbose=True
        )

    @task
    def research_task(self) -> Task:
        return Task(config=self.tasks_config['research_task'])

    @task
    def writing_task(self) -> Task:
        return Task(
            config=self.tasks_config['writing_task'],
            output_file='output/blog_post.md'
        )

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,  # o Process.hierarchical
            verbose=True,
            memory=True,
            max_rpm=10   # Limitar la tasa de llamadas a la API
        )
```

### Ejecutando con Docker Compose (con Ollama)

```yaml
# docker-compose.yml
version: "3.8"

services:
  crewai:
    build: .
    volumes:
      - ./src:/app/src
      - ./output:/app/output
    environment:
      - OPENAI_API_BASE=http://ollama:11434/v1
      - OPENAI_API_KEY=ollama
      - OPENAI_MODEL_NAME=llama3.1:70b
      - SERPER_API_KEY=${SERPER_API_KEY}
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    volumes:
      - ollama_data:/root/.ollama
    ports:
      - "11434:11434"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama_data:
```

```bash
# Iniciar la pila
docker compose up -d ollama

# Descargar tu modelo
docker compose exec ollama ollama pull llama3.1:70b

# Ejecutar tu tripulación
docker compose run --rm crewai python src/my_research_crew/main.py
```

***

## Aceleración por GPU

CrewAI en sí no usa la GPU — pero el LLM al que llama sí. Ejecuta Ollama o vLLM en el mismo servidor Clore para inferencia local acelerada por GPU.

### Configuración de Ollama (recomendada por facilidad)

```bash
# Instalar Ollama en el host
curl -fsSL https://ollama.com/install.sh | sh

# Verificar la detección de GPU
nvidia-smi
ollama run llama3:8b "Test"   # Debería usar GPU

# Descargar modelos para diferentes necesidades de agentes
ollama pull llama3.1:8b          # Razonamiento rápido y ligero
ollama pull llama3.1:70b         # Razonamiento complejo (requiere A100+)
ollama pull codestral:latest     # Especializado para agentes de código
ollama pull nomic-embed-text     # Para embeddings de memoria/RAG

# Configurar CrewAI para usar Ollama
export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
export OPENAI_MODEL_NAME=llama3.1:8b
```

### Configurar LLM de CrewAI por agente

```python
from crewai import Agent, LLM

# Usar Ollama para un agente específico
local_llm = LLM(
    model="ollama/llama3.1:8b",
    base_url="http://localhost:11434"
)

# Usar API en la nube para otro agente (por ejemplo, razonamiento complejo)
cloud_llm = LLM(
    model="gpt-4o",
    api_key="sk-..."
)

researcher = Agent(
    role="Investigador",
    goal="Encontrar información",
    backstory="Investigador experto",
    llm=local_llm    # Usa GPU local
)

strategist = Agent(
    role="Estratega",
    goal="Planear acciones",
    backstory="Pensador estratégico",
    llm=cloud_llm    # Usa API en la nube
)
```

### Recomendaciones de modelos para tareas de agentes

| Tipo de tarea                | Modelo recomendado | VRAM   | Notas                     |
| ---------------------------- | ------------------ | ------ | ------------------------- |
| Investigación + búsqueda web | Llama 3.1 70B      | 40 GB  | Mejor razonamiento local  |
| Generación de código         | Codestral 22B      | 13 GB  | Especializado en código   |
| Redacción                    | Llama 3.1 8B       | 6 GB   | Rápido, buena calidad     |
| Orquestación compleja        | GPT-4o (API)       | —      | Mejor en general          |
| Embeddings/memoria           | nomic-embed-text   | < 1 GB | Requerido para la memoria |

> Ver [Ollama en Clore.ai](/guides/guides_v2-es/modelos-de-lenguaje/ollama.md) y [vLLM en Clore.ai](/guides/guides_v2-es/modelos-de-lenguaje/vllm.md) para guías completas de configuración de inferencia.

***

## Consejos y mejores prácticas

### Optimización de costos

```bash
# Rastrea los costos de API de LLM con el seguimiento de uso incorporado de CrewAI
# Agrega a tu tripulación:
result = crew.kickoff(inputs={"topic": "agentes de IA"})
print(f"Total de tokens usados: {result.token_usage}")

# Usa modelos más baratos para tareas simples, premium para las complejas
# Llama 3.1 8B en Ollama = $0 de costo API
# GPT-4o = ~$0.005/1K tokens de entrada

# Establece max_iter para evitar agentes descontrolados
Agent(max_iter=10, max_execution_time=120)  # Tiempo de espera de 2 minutos

# Cachea las respuestas del LLM durante el desarrollo
os.environ["CREWAI_DISABLE_CACHE"] = "false"
```

### Ejecutando tripulaciones como un servicio persistente

```bash
# Servir tripulaciones vía un endpoint FastAPI
pip install fastapi uvicorn

cat > server.py << 'EOF'
from fastapi import FastAPI, BackgroundTasks
from my_research_crew.crew import MyResearchCrew
import asyncio

app = FastAPI()
results = {}

@app.post("/run/{topic}")
async def run_crew(topic: str, background_tasks: BackgroundTasks):
    job_id = f"job-{topic}-{len(results)}"
    background_tasks.add_task(execute_crew, job_id, topic)
    return {"job_id": job_id, "status": "started"}

async def execute_crew(job_id: str, topic: str):
    crew = MyResearchCrew().crew()
    result = crew.kickoff(inputs={"topic": topic})
    results[job_id] = str(result)

@app.get("/result/{job_id}")
async def get_result(job_id: str):
    return {"result": results.get(job_id, "pending")}

EOF

# Ejecutar el servidor
uvicorn server:app --host 0.0.0.0 --port 8080 &

# Activar una ejecución de tripulación
curl -X POST http://<clore-ip>:8080/run/quantum-computing
```

### Herramientas útiles incorporadas en CrewAI

```python
from crewai_tools import (
    SerperDevTool,        # Búsqueda en Google vía la API de Serper
    ScrapeWebsiteTool,    # Scraping web
    FileReadTool,         # Leer archivos locales
    FileWriterTool,       # Escribir archivos
    DirectoryReadTool,    # Listar contenidos de un directorio
    CodeInterpreterTool,  # Ejecutar código Python
    GithubSearchTool,     # Buscar repositorios en GitHub
    YoutubeVideoSearchTool, # Buscar en YouTube
    PGSearchTool,         # Consultar PostgreSQL
)
```

### Implementando humano-en-el-bucle

```python
# Pedir entrada humana en una tarea específica
task = Task(
    description="Investigar {topic}",
    expected_output="Informe de investigación",
    agent=researcher,
    human_input=True    # Pausa y solicita retroalimentación del usuario
)
```

***

## Solución de problemas

### "openai.AuthenticationError" incluso con clave válida

```bash
# Verifica que tu clave API esté cargada
python3 -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('OPENAI_API_KEY')[:10])"

# Si usas Ollama, asegúrate de que estos estén configurados:
export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
export OPENAI_MODEL_NAME=llama3.1:8b

# Verifica que Ollama sea accesible
curl http://localhost:11434/v1/models
```

### Agente atascado en bucle de razonamiento

```bash
# Establece un límite estricto de iteraciones
Agent(
    max_iter=10,            # Máx. pasos de razonamiento
    max_execution_time=300  # Tiempo de espera rígido de 5 minutos
)

# Habilita verbose para ver dónde está el bucle
Agent(verbose=True)

# Comprueba si el modelo soporta llamadas a herramientas
# Algunos modelos más pequeños no lo hacen; usa llama3.1 o mistral-nemo
```

### Las herramientas de CrewAI fallan (SerperDevTool 403)

```bash
# SerperDevTool requiere una clave API gratuita de serper.dev
export SERPER_API_KEY=tu-serper-key

# Alternativa: usa DuckDuckGo (no necesita clave API)
from langchain_community.tools import DuckDuckGoSearchRun
from crewai import tool

@tool("DuckDuckGo Search")
def ddg_search(query: str) -> str:
    """Buscar en la web usando DuckDuckGo."""
    return DuckDuckGoSearchRun().run(query)
```

### Errores de memoria (ChromaDB / embeddings)

```bash
# La memoria de CrewAI usa ChromaDB para el almacenamiento vectorial
# Si falla, verifica espacio en disco y permisos
df -h
ls -la ~/.local/share/crewai/

# Borrar memoria corrupta
rm -rf ~/.local/share/crewai/

# O deshabilitar la memoria si no es necesaria
Crew(memory=False)

# Si usas embeddings de Ollama, asegura que el modelo esté descargado
docker exec ollama ollama pull nomic-embed-text
```

### Fallo en la compilación de Docker por incompatibilidad ARM/x86

```bash
# Los servidores Clore.ai son x86_64; especifica la plataforma explícitamente:
docker build --platform linux/amd64 -t my-crewai-app .

# O en docker-compose.yml:
services:
  crewai:
    platform: linux/amd64
    build: .
```

### Limitación de tasa por las APIs de LLM

```bash
# Reduce las solicitudes por minuto
Crew(max_rpm=5)   # 5 solicitudes por minuto

# Agrega lógica de reintento en la configuración del LLM
LLM(
    model="gpt-4o",
    max_retries=3,
    timeout=60
)
```

***

## Lecturas adicionales

* [Documentación oficial de CrewAI](https://docs.crewai.com)
* [Repositorio de GitHub de CrewAI](https://github.com/crewAIInc/crewAI)
* [Documentación de herramientas de CrewAI](https://docs.crewai.com/concepts/tools)
* [Repositorio de ejemplos de CrewAI](https://github.com/crewAIInc/crewAI-examples)
* [Ejecutando Ollama en Clore.ai](/guides/guides_v2-es/modelos-de-lenguaje/ollama.md)
* [Ejecutando vLLM en Clore.ai](/guides/guides_v2-es/modelos-de-lenguaje/vllm.md)
* [Comparativa de GPU de Clore.ai](/guides/guides_v2-es/primeros-pasos/gpu-comparison.md)
* [Discord de la comunidad de CrewAI](https://discord.com/invite/X4JWnZnxPb)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-es/plataformas-y-agentes-de-ia/crewai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.