# CrewAI Multi-Agenten-Framework

## Überblick

[CrewAI](https://github.com/crewAIInc/crewAI) ist ein hochmodernes Framework zur Orchestrierung **rollenbasierter autonomer KI-Agenten**, mit **44K+ GitHub-Sternen**. Im Gegensatz zu Ein-Agenten-Systemen ermöglicht CrewAI die Definition spezialisierter Agenten (Researcher, Writer, Coder, Analyst...), die als "Crew" zusammenarbeiten, um komplexe Aufgaben zu erfüllen — jeder Agent mit eigener Rolle, Zielsetzung, Hintergrundgeschichte und Werkzeugkasten.

An **Clore.ai**, CrewAI kann in einer dockerisierten Umgebung für nur **0,05–0,20 $/Std.**. Während CrewAI selbst CPU-gebunden ist (es orchestriert API-Aufrufe), erhalten Sie in Kombination mit einem lokalen Ollama- oder vLLM-Server auf demselben GPU-Knoten ein vollständig privates, offline-fähiges Multi-Agenten-System.

**Wesentliche Funktionen:**

* 👥 **Multi-Agenten-Crews** — definieren Sie Agenten-Personas mit Rollen, Zielen und Hintergrundgeschichten
* 🎯 **Aufgabendelegation** — Manager-Agent weist Aufgaben automatisch dem passenden Spezialisten zu
* 🛠️ **Tool-Ökosystem** — Websuche, Datei-I/O, Code-Ausführung, Datenbankzugriff, benutzerdefinierte Tools
* 🔁 **Sequenziell & Parallel** — führe Aufgaben nacheinander aus oder lasse unabhängige Aufgaben gleichzeitig laufen
* 🧠 **Agenten-Speicher** — Kurzzeit-, Langzeit-, Entitäts- und Kontextspeicher-Typen
* 🔌 **LLM-agnostisch** — funktioniert mit OpenAI, Anthropic, Google, Ollama, Groq, Azure und mehr
* 📊 **CrewAI Studio** — visuelle Oberfläche zum Erstellen von Crews ohne Code (Enterprise)
* 🚀 **Pipelines** — verknüpfe mehrere Crews für komplexe mehrstufige Workflows

***

## Anforderungen

CrewAI ist eine Python-Bibliothek. Sie läuft auf der CPU und benötigt nur eine System-Python-Umgebung 3.10+ oder Docker. GPU ist optional, ermöglicht jedoch leistungsstarke lokale Modell-Inferenz.

| Konfiguration                  | GPU             | VRAM  | System-RAM | Festplatte | Clore.ai-Preis      |
| ------------------------------ | --------------- | ----- | ---------- | ---------- | ------------------- |
| **Minimal** (Cloud-APIs)       | Keine / CPU     | —     | 2 GB       | 10 GB      | \~0,03 $/Std. (CPU) |
| **Standard**                   | Keine / CPU     | —     | 4 GB       | 20 GB      | \~0,05 $/Std.       |
| **+ Lokales LLM (klein)**      | RTX 3080        | 10 GB | 8 GB       | 40 GB      | \~0,15 $/Std.       |
| **+ Lokales LLM (groß)**       | RTX 3090 / 4090 | 24 GB | 16 GB      | 60 GB      | 0,20–0,35 $/Std.    |
| **+ Hochwertiges lokales LLM** | A100 40 GB      | 40 GB | 32 GB      | 100 GB     | \~0,80 $/Std.       |

### API-Schlüssel

CrewAI funktioniert mit den meisten großen LLM-Anbietern. Sie benötigen mindestens einen:

* **OpenAI** — GPT-4o (beste Reasoning-Fähigkeiten für komplexe Aufgaben)
* **Anthropic** — Claude 3.5 Sonnet (ausgezeichnet für schreibintensive Crews)
* **Groq** — Kostenloser Tarif, schnelle Inferenz (Llama 3 70B)
* **Ollama** — Vollständig lokal, kein API-Schlüssel erforderlich (siehe [GPU-Beschleunigung](#gpu-acceleration))

***

## Schnellstart

### 1. Miete einen Clore.ai-Server

Melde dich an bei [clore.ai](https://clore.ai):

* **Nur CPU** bei Nutzung von Cloud-LLM-APIs
* **RTX 3090/4090** für lokale Ollama-Inferenz
* SSH-Zugriff aktiviert
* Keine speziellen Portanforderungen für CLI-Nutzung (Ports nur für Web-UIs öffnen)

### 2. Verbinden und vorbereiten

```bash
ssh root@<clore-server-ip> -p <ssh-port>

# System aktualisieren
apt-get update && apt-get upgrade -y

# Installiere Python 3.11 (falls nicht vorhanden)
apt-get install -y python3.11 python3.11-venv python3-pip
python3 --version   # Sollte 3.10+ sein

# Docker verifizieren
docker --version
```

### 3. Option A — Direkte pip-Installation (am schnellsten)

```bash
# Erstelle eine virtuelle Umgebung
python3 -m venv crewai-env
source crewai-env/bin/activate

# Installiere CrewAI mit allen Tools
pip install crewai crewai-tools

# Installation überprüfen
python -c "import crewai; print(crewai.__version__)"
crewai --version
```

### 4. Option B — Docker-Container (empfohlen für Reproduzierbarkeit)

```bash
# Projektverzeichnis erstellen
mkdir my-crew && cd my-crew

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

# Systemabhängigkeiten installieren
RUN apt-get update && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# Arbeitsverzeichnis setzen
WORKDIR /app

# CrewAI und gängige Tools installieren
RUN pip install --no-cache-dir \
    crewai \
    crewai-tools \
    langchain-openai \
    langchain-anthropic \
    python-dotenv

# Anwendungs-Code kopieren
COPY . .

# Standardbefehl
CMD ["python", "main.py"]
EOF

# Image bauen
docker build -t my-crewai-app .
```

### 5. Erstelle deine erste Crew

```bash
# Initialisiere ein neues CrewAI-Projekt mit dem CLI
source crewai-env/bin/activate
crewai create crew my-research-crew
cd my-research-crew

# API-Schlüssel konfigurieren
cat > .env << 'EOF'
OPENAI_API_KEY=sk-...
# Oder für Anthropic:
# ANTHROPIC_API_KEY=sk-ant-...
# Oder für Ollama (kein Schlüssel nötig):
# OPENAI_API_BASE=http://localhost:11434/v1
# OPENAI_API_KEY=ollama
EOF

# Projektabhängigkeiten installieren
crewai install

# Die Crew ausführen
crewai run
```

***

## Konfiguration

### Projektstruktur (von `crewai create`)

```
my-research-crew/
├── .env                    # API-Schlüssel und Einstellungen
├── pyproject.toml          # Abhängigkeiten
├── src/
│   └── my_research_crew/
│       ├── config/
│       │   ├── agents.yaml   # Agenten-Definitionen
│       │   └── tasks.yaml    # Aufgaben-Definitionen
│       ├── tools/
│       │   └── custom_tool.py  # Deine benutzerdefinierten Tools
│       ├── crew.py           # Crew-Zusammenstellung
│       └── main.py           # Einstiegspunkt
```

### agents.yaml — Definiere deine Agenten

```yaml
researcher:
  role: >
    Senior Research Analyst
  goal: >
    Entdecke bahnbrechende Entwicklungen in {topic} und fasse umsetzbare Erkenntnisse zusammen
  backstory: >
    Du bist ein erfahrener Forscher mit Talent dafür, Informationen zu finden und zu verknüpfen
    aus diversen Quellen. Du hast ein gutes Gespür für Glaubwürdigkeit und Relevanz.
  tools:
    - SerperDevTool
    - ScrapeWebsiteTool
  llm: gpt-4o                # Kann pro Agent gesetzt werden
  verbose: true
  max_iter: 15               # Maximale Reasoning-Iterationen
  memory: true               # Agentenspeicher aktivieren

writer:
  role: >
    Expert Technical Writer
  goal: >
    Transformiere komplexe Forschung in klaren, überzeugenden und präzisen Inhalt
  backstory: >
    Du verfasst Erklärungen, die komplexe Themen zugänglich machen, ohne an Tiefe zu verlieren.
    Du zitierst Quellen und strukturierst Inhalte für maximale Lesbarkeit.
  llm: claude-3-5-sonnet-20241022
  verbose: true
```

### tasks.yaml — Definiere Aufgaben

```yaml
research_task:
  description: >
    Recherchiere die neuesten Entwicklungen zu {topic} der letzten 6 Monate.
    Identifiziere wichtige Trends, Durchbrüche und Implikationen.
    Stelle mindestens 10 glaubwürdige Quellen zusammen.
  expected_output: >
    Ein detaillierter Forschungsbericht mit nach Themen geordneten Erkenntnissen,
    inklusive Quellen-URLs und Veröffentlichungsdaten.
  agent: researcher

writing_task:
  description: >
    Nutze den Forschungsbericht, um einen umfassenden Blogbeitrag über {topic} zu schreiben.
    Zielumfang: 1500–2000 Wörter. Füge Titel, Einführung, Hauptabschnitte
    und einen Schluss mit Ausblick hinzu.
  expected_output: >
    Ein veröffentlichungsfertiger Blogbeitrag im Markdown-Format.
  agent: writer
  context:
    - research_task    # Schreibaufgabe erhält die Ausgabe des Forschers
  output_file: output/blog_post.md
```

### crew\.py — Stelle die Crew zusammen

```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():
    """Forschungs- und Schreibcrew"""
    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,  # oder Process.hierarchical
            verbose=True,
            memory=True,
            max_rpm=10   # Rate-Limit für API-Aufrufe
        )
```

### Ausführen mit Docker Compose (mit 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
# Stack starten
docker compose up -d ollama

# Ziehe dein Modell
docker compose exec ollama ollama pull llama3.1:70b

# Starte deine Crew
docker compose run --rm crewai python src/my_research_crew/main.py
```

***

## GPU-Beschleunigung

CrewAI selbst nutzt die GPU nicht — das aufgerufene LLM jedoch. Führe Ollama oder vLLM auf demselben Clore-Server aus für GPU-beschleunigte lokale Inferenz.

### Ollama-Setup (empfohlen wegen Benutzerfreundlichkeit)

```bash
# Installiere Ollama auf dem Host
curl -fsSL https://ollama.com/install.sh | sh

# GPU-Erkennung verifizieren
nvidia-smi
ollama run llama3:8b "Test"   # Sollte die GPU verwenden

# Ziehe Modelle für unterschiedliche Agentenbedürfnisse
ollama pull llama3.1:8b          # Schnelles, leichtgewichtiges Reasoning
ollama pull llama3.1:70b         # Komplexes Reasoning (benötigt A100+)
ollama pull codestral:latest     # Spezialisiert für Code-Agenten
ollama pull nomic-embed-text     # Für Memory/RAG-Embeddings

# CrewAI so konfigurieren, dass Ollama verwendet wird
export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
export OPENAI_MODEL_NAME=llama3.1:8b
```

### CrewAI-LLM pro Agent konfigurieren

```python
from crewai import Agent, LLM

# Verwende Ollama für einen bestimmten Agenten
local_llm = LLM(
    model="ollama/llama3.1:8b",
    base_url="http://localhost:11434"
)

# Verwende Cloud-API für einen anderen Agenten (z. B. komplexes Reasoning)
cloud_llm = LLM(
    model="gpt-4o",
    api_key="sk-..."
)

researcher = Agent(
    role="Researcher",
    goal="Informationen finden",
    backstory="Expertenforscher",
    llm=local_llm    # Verwendet lokale GPU
)

strategist = Agent(
    role="Strategist",
    goal="Aktionen planen",
    backstory="Strategischer Denker",
    llm=cloud_llm    # Verwendet Cloud-API
)
```

### Modellempfehlungen für Agentenaufgaben

| Aufgabentyp             | Empfohlenes Modell | VRAM   | Hinweise                  |
| ----------------------- | ------------------ | ------ | ------------------------- |
| Recherche + Websuche    | Llama 3.1 70B      | 40 GB  | Bestes lokales Reasoning  |
| Code-Generierung        | Codestral 22B      | 13 GB  | Code-spezialisiert        |
| Schreiben               | Llama 3.1 8B       | 6 GB   | Schnell, gute Qualität    |
| Komplexe Orchestrierung | GPT-4o (API)       | —      | Insgesamt am besten       |
| Embeddings/Speicher     | nomic-embed-text   | < 1 GB | Erforderlich für Speicher |

> Siehe [Ollama auf Clore.ai](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/ollama) und [vLLM auf Clore.ai](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/vllm) für vollständige Inferenz-Setup-Anleitungen.

***

## Tipps & bewährte Methoden

### Kostenoptimierung

```bash
# Verfolge LLM-API-Kosten mit CrewAIs integriertem Nutzungs-Tracking
# Zum Hinzufügen zu deiner Crew:
result = crew.kickoff(inputs={"topic": "AI agents"})
print(f"Total tokens used: {result.token_usage}")

# Verwende günstigere Modelle für einfache Aufgaben, Premium für komplexe
# Llama 3.1 8B auf Ollama = $0 API-Kosten
# GPT-4o = ~0,005 $/1K Input-Token

# Setze max_iter, um entgleiste Agenten zu verhindern
Agent(max_iter=10, max_execution_time=120)  # 2-Minuten-Timeout

# Cache LLM-Antworten während der Entwicklung
os.environ["CREWAI_DISABLE_CACHE"] = "false"
```

### Crews als persistenten Dienst ausführen

```bash
# Crews über einen FastAPI-Endpunkt bereitstellen
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

# Server starten
uvicorn server:app --host 0.0.0.0 --port 8080 &

# Einen Crew-Lauf auslösen
curl -X POST http://<clore-ip>:8080/run/quantum-computing
```

### Nützliche eingebaute CrewAI-Tools

```python
from crewai_tools import (
    SerperDevTool,        # Google-Suche über Serper API
    ScrapeWebsiteTool,    # Web-Scraping
    FileReadTool,         # Lokale Dateien lesen
    FileWriterTool,       # Dateien schreiben
    DirectoryReadTool,    # Verzeichnisinhalte auflisten
    CodeInterpreterTool,  # Python-Code ausführen
    GithubSearchTool,     # GitHub-Repositories durchsuchen
    YoutubeVideoSearchTool, # YouTube durchsuchen
    PGSearchTool,         # PostgreSQL abfragen
)
```

### Implementierung Human-in-the-Loop

```python
# Frage bei einer bestimmten Aufgabe nach menschlichem Input
task = Task(
    description="Research {topic}",
    expected_output="Forschungsbericht",
    agent=researcher,
    human_input=True    # Pausiert und fordert den Benutzer zur Rückmeldung auf
)
```

***

## Fehlerbehebung

### "openai.AuthenticationError" selbst bei gültigem Schlüssel

```bash
# Prüfe, ob dein API-Schlüssel geladen ist
python3 -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('OPENAI_API_KEY')[:10])"

# Wenn du Ollama nutzt, stelle sicher, dass diese gesetzt sind:
export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
export OPENAI_MODEL_NAME=llama3.1:8b

# Verifiziere, dass Ollama erreichbar ist
curl http://localhost:11434/v1/models
```

### Agent in Reasoning-Schleife festgefahren

```bash
# Setze eine harte Begrenzung für Iterationen
Agent(
    max_iter=10,            # Maximale Reasoning-Schritte
    max_execution_time=300  # 5-minütiges hartes Timeout
)

# Aktiviere verbose, um zu sehen, wo es sich wiederholt
Agent(verbose=True)

# Prüfe, ob das Modell Tool-Calling unterstützt
# Einige kleinere Modelle tun dies nicht; verwende llama3.1 oder mistral-nemo
```

### CrewAI-Tools schlagen fehl (SerperDevTool 403)

```bash
# SerperDevTool benötigt einen kostenlosen API-Schlüssel von serper.dev
export SERPER_API_KEY=dein-serper-key

# Alternative: Verwende DuckDuckGo (kein API-Schlüssel erforderlich)
from langchain_community.tools import DuckDuckGoSearchRun
from crewai import tool

@tool("DuckDuckGo Search")
def ddg_search(query: str) -> str:
    """Durchsuche das Web mit DuckDuckGo."""
    return DuckDuckGoSearchRun().run(query)
```

### Speicherfehler (ChromaDB / Embeddings)

```bash
# CrewAI-Speicher verwendet ChromaDB für Vektor-Speicherung
# Wenn es fehlschlägt, überprüfe Festplattenspeicher und Berechtigungen
df -h
ls -la ~/.local/share/crewai/

# Korrumpierten Speicher löschen
rm -rf ~/.local/share/crewai/

# Oder Speicher deaktivieren, wenn nicht benötigt
Crew(memory=False)

# Wenn Ollama-Embeddings verwendet werden, stelle sicher, dass das Modell gezogen wurde
docker exec ollama ollama pull nomic-embed-text
```

### Docker-Build scheitert wegen ARM/x86-Unterschied

```bash
# Clore.ai-Server sind x86_64; gib die Plattform explizit an:
docker build --platform linux/amd64 -t my-crewai-app .

# Oder in docker-compose.yml:
services:
  crewai:
    platform: linux/amd64
    build: .
```

### Rate-Limiting durch LLM-APIs

```bash
# Reduziere Anfragen pro Minute
Crew(max_rpm=5)   # 5 Anfragen pro Minute

# Füge Retry-Logik in der LLM-Konfiguration hinzu
LLM(
    model="gpt-4o",
    max_retries=3,
    timeout=60
)
```

***

## Weiterführende Lektüre

* [Offizielle CrewAI-Dokumentation](https://docs.crewai.com)
* [CrewAI GitHub-Repository](https://github.com/crewAIInc/crewAI)
* [CrewAI Tools-Dokumentation](https://docs.crewai.com/concepts/tools)
* [CrewAI Beispiele-Repository](https://github.com/crewAIInc/crewAI-examples)
* [Ollama auf Clore.ai ausführen](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/ollama)
* [vLLM auf Clore.ai ausführen](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/vllm)
* [Clore.ai GPU-Vergleich](https://docs.clore.ai/guides/guides_v2-de/erste-schritte/gpu-comparison)
* [CrewAI Community Discord](https://discord.com/invite/X4JWnZnxPb)