CrewAI Vortragskonzept fuer Claude Code

Dieses Projekt ist ein kleines Vortrags- und Workshop-Setup fuer CrewAI mit Claude/Anthropic. Die Beispiele starten bewusst lebensnah: Einkaufszettel, Wochenendplan, Abendessen, Tagesplanung und kleiner Umzug. Das letzte Beispiel ist eine kleine Dark-Factory fuer Software: mehrere Agents bauen gemeinsam einen Python-Taschenrechner.

Die Beispiele werden Schritt fuer Schritt anspruchsvoller und sind jeweils getrennt: eigene README, eigene Config und eigener Lernfokus. Ab Beispiel 07 kommen lebensnahe Flow-Beispiele hinzu: Morgenroutine, Wochenendplan, Einkaufsliste und Geburtstagsfeier.

Wichtig: Claude Code selbst ist kein CrewAI-Modell-Endpunkt. Claude Code kann dir beim Bearbeiten und Starten dieses Projekts helfen, aber CrewAI braucht zum Ausfuehren einen Anthropic API Key.

Voraussetzungen

• Python >=3.10 und <3.14
• Windows mit PowerShell oder Linux/macOS mit einer Shell wie Bash/Zsh
• Anthropic API Key in ANTHROPIC_API_KEY

Die Python-Abhaengigkeiten stehen in pyproject.toml:

• crewai[anthropic]
• pydantic
• PyYAML

Python installieren

Windows

Empfohlen ist eine normale Python-Installation von python.org oder ueber den Windows-Paketmanager winget.

Mit winget:

winget install Python.Python.3.12

Danach PowerShell neu oeffnen und pruefen:

python --version
pip --version

Falls python nicht gefunden wird, pruefe bei der Installation, ob Python zum PATH hinzugefuegt wurde. Alternativ funktioniert auf vielen Windows-Systemen auch der Python-Launcher:

py --version
py -m pip --version

Linux

Unter Debian/Ubuntu:

sudo apt update
sudo apt install python3 python3-venv python3-pip

Pruefen:

python3 --version
python3 -m pip --version

Unter anderen Distributionen installierst du entsprechend python3, venv und pip ueber den jeweiligen Paketmanager.

macOS

Mit Homebrew:

brew install python

Pruefen:

python3 --version
python3 -m pip --version

Was ist eine virtuelle Umgebung?

Eine virtuelle Umgebung ist ein lokaler Python-Arbeitsbereich fuer dieses Projekt. Die Abhaengigkeiten werden dann in .venv installiert und nicht global auf deinem System verteilt.

Dieses Projekt nutzt:

.venv/

Der Ordner muss nicht nach GitHub gepusht werden. Er kann jederzeit neu erstellt werden.

Installation ohne virtuelle Umgebung

Du kannst das Projekt auch ohne .venv installieren. Das ist fuer schnelle Server-Tests okay, aber weniger sauber, weil die Pakete dann in die aktuelle Python-Umgebung installiert werden.

Nutze diese Variante nur, wenn du weisst, welche Python-Umgebung aktiv ist, z. B. auf einem frischen Server oder in einem Wegwerf-Container.

Windows ohne venv

python -m pip install -e .

Mit Python-Launcher:

py -m pip install -e .

Start:

crewai-examples 01

Falls crewai-examples nicht gefunden wird, nutze direkt:

python -m examples.main 01

Linux/macOS ohne venv

python3 -m pip install -e .

Start:

crewai-examples 01

Falls crewai-examples nicht gefunden wird, nutze direkt:

python3 -m examples.main 01

Auf manchen Linux-Systemen verhindert Python globale Installationen und zeigt einen Hinweis wie externally-managed-environment. Dann nimm besser die .venv-Variante oder, nur wenn du es wirklich willst:

python3 -m pip install -e . --break-system-packages

Installation unter Windows

Im Projektordner in PowerShell ausfuehren:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

Falls du den Windows-Python-Launcher nutzt:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -e .

Was hier passiert:

• python -m venv .venv erstellt die virtuelle Umgebung.
• .\.venv\Scripts\Activate.ps1 aktiviert sie in der aktuellen PowerShell.
• pip install -e . liest pyproject.toml, installiert die Abhaengigkeiten und registriert den Befehl crewai-examples.

Danach den API Key fuer die aktuelle PowerShell setzen:

$env:ANTHROPIC_API_KEY="sk-ant-..."

Optional kannst du das Modell ueberschreiben:

$env:CREWAI_MODEL="anthropic/claude-sonnet-4-6"

Wenn CREWAI_MODEL nicht gesetzt ist, nutzt das Projekt anthropic/claude-sonnet-4-6.

Installation unter Linux/macOS

Im Projektordner in Bash oder Zsh ausfuehren:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Was hier passiert:

• python3 -m venv .venv erstellt die virtuelle Umgebung.
• source .venv/bin/activate aktiviert sie in der aktuellen Shell.
• pip install -e . liest pyproject.toml, installiert die Abhaengigkeiten und registriert den Befehl crewai-examples.

Danach den API Key fuer die aktuelle Shell setzen:

export ANTHROPIC_API_KEY="sk-ant-..."

Optional kannst du das Modell ueberschreiben:

export CREWAI_MODEL="anthropic/claude-sonnet-4-6"

Wenn CREWAI_MODEL nicht gesetzt ist, nutzt das Projekt anthropic/claude-sonnet-4-6.

pyproject.toml starten und verstehen

pyproject.toml ist die Projektbeschreibung fuer Python. Darin stehen Name, Python-Version, Abhaengigkeiten und der Startbefehl:

[project.scripts]
crewai-examples = "examples.main:main"

Das bedeutet: Nach pip install -e . kannst du das Projekt mit crewai-examples starten. Intern ruft Python dann die Funktion main() aus examples/main.py auf.

Typischer Ablauf:

pyproject.toml -> pip install -e . -> crewai-examples -> examples.main:main

Wenn du das Projekt ohne installierten Script-Befehl starten willst, geht auch:

python -m examples.main 01

oder unter Linux/macOS:

python3 -m examples.main 01

Beispiele starten unter Windows

crewai-examples 01
crewai-examples 02
crewai-examples 03
crewai-examples 04
crewai-examples 05
crewai-examples 06
crewai-examples 07
crewai-examples 08
crewai-examples 09
crewai-examples 10

Aliases funktionieren ebenfalls:

crewai-examples basic
crewai-examples review
crewai-examples cooking
crewai-examples weekend
crewai-examples moving
crewai-examples coder
crewai-examples calculator
crewai-examples morgenroutine
crewai-examples wochenendplan
crewai-examples einkaufsliste
crewai-examples geburtstag

Alternativ geht der Start direkt als Python-Modul:

python -m examples.main 01

Beispiele starten unter Linux/macOS

crewai-examples 01
crewai-examples 02
crewai-examples 03
crewai-examples 04
crewai-examples 05
crewai-examples 06
crewai-examples 07
crewai-examples 08
crewai-examples 09
crewai-examples 10

Aliases funktionieren ebenfalls:

crewai-examples basic
crewai-examples review
crewai-examples cooking
crewai-examples weekend
crewai-examples moving
crewai-examples coder
crewai-examples calculator
crewai-examples morgenroutine
crewai-examples wochenendplan
crewai-examples einkaufsliste
crewai-examples geburtstag

Alternativ geht der Start direkt als Python-Modul:

python3 -m examples.main 01

Vortragsdramaturgie

0. 00_config_erklaerung: erklaert alle Config-Felder, die spaeter vorkommen.
1. 01_single_agent_no_tool: ein Agent, eine Task, keine Tools.
2. 02_two_agents_no_tools: zwei Agents, zwei Tasks, keine Tools.
3. 03_one_agent_one_tool: ein Agent, eine Task, ein Tool.
4. 04_one_agent_multiple_tools: ein Agent, mehrere Tools.
5. 05_multi_agent_with_tools: mehrere Agents, Tools und Task-Kontext.
6. 06_dark_factory_calculator: Dark-Factory mit Produktdesigner, Coder, Tester, QA-Checker, echter Coder-Tester-Schleife, echten Unit-Tests, echtem Linting sowie unterschiedlichen Modellen und Temperaturen pro Agent.
7. 07_morgenroutine_flow: morgens puenktlich loskommen, mit State als Notizzettel.
8. 08_wochenendplan_branching: Samstag planen, mit Abzweigung nach Regen und Budget.
9. 09_einkaufsliste_validation_loop: Einkaufsliste wiederholen, bis sie ins Budget passt.
10. 10_geburtstagsfeier_flow_crews: Kindergeburtstag planen, mit Flow als Rahmen um Planung, Pruefung und Elternnachricht.

Die Idee: Erst Rollen und Tasks verstehen, dann Zusammenarbeit, danach Tools, danach mehrere Tools, danach mehrere Agents mit Kontext, zuletzt eine kleine Software-Dark-Factory mit agentenspezifischem Modell-Setup. Danach wird der Blick groesser: Lebensnahe Flows zeigen, wie man Crews, Tools und normalen Python-Code zu robusteren Workflows verbindet.

Projektstruktur

README.md
pyproject.toml
examples/
  main.py
  tools.py
  00_config_erklaerung/
    README.md
    config/
      agents.yaml
      tasks.yaml
  01_single_agent_no_tool/
    README.md
    config/
      agents.yaml
      tasks.yaml
  02_two_agents_no_tools/
    README.md
    config/
      agents.yaml
      tasks.yaml
  03_one_agent_one_tool/
    README.md
    config/
      agents.yaml
      tasks.yaml
  04_one_agent_multiple_tools/
    README.md
    config/
      agents.yaml
      tasks.yaml
  05_multi_agent_with_tools/
    README.md
    config/
      agents.yaml
      tasks.yaml
  06_dark_factory_calculator/
    README.md
    config/
      agents.yaml
      tasks.yaml
  07_morgenroutine_flow/
    README.md
    config/
      agents.yaml
      tasks.yaml
      flow.yaml
  08_wochenendplan_branching/
    README.md
    config/
      agents.yaml
      tasks.yaml
      flow.yaml
  09_einkaufsliste_validation_loop/
    README.md
    config/
      agents.yaml
      tasks.yaml
      flow.yaml
  10_geburtstagsfeier_flow_crews/
    README.md
    config/
      agents.yaml
      tasks.yaml
      flow.yaml

Was wo passiert

• examples/main.py ist der Runner. Er nimmt das CLI-Argument entgegen, laedt die passende YAML-Config und startet die Crew.
• examples/flow_examples.py enthaelt die didaktischen Flow-Beispiele ab 07. Sie zeigen State, Branching, Loops und Flow-Orchestrierung an alltagsnahen Situationen ohne zusaetzliche Modellaufrufe, damit der Ablauf selbst im Vordergrund steht.
• examples/tools.py enthaelt alle eigenen Tools. Tools sind Python-Code, weil sie echte Logik ausfuehren. Viele Tools erzeugen Lauf-IDs, Uhrzeiten, Zufallswerte oder kleine Berechnungen, damit im Vortrag sichtbar wird, dass wirklich Python-Code ausgefuehrt wurde.
• Beispiel 06 nutzt zusaetzlich unit_tests_ausfuehren und linting_ausfuehren. Ausserdem gibt es bash_befehl_ausfuehren, womit die technischen Agents echte Bash-Kommandos starten koennen, z. B. python --version, pip install ... oder Testbefehle. Der Runner fuehrt die Pflichtpruefungen zwischen Coder und Tester wirklich aus und wiederholt die Coder-Runde, bis Tests und Linting gruen sind oder CREWAI_DARK_FACTORY_MAX_RUNS erreicht ist.
• Wichtig: bash_befehl_ausfuehren ist absichtlich sehr maechtig. Nutze es nur in einer Umgebung, in der ein Agent Befehle ausfuehren darf. Auf Windows wird dafuer Git Bash oder WSL benoetigt.
• agents.yaml beschreibt Rollen, Ziele, Backstories und erlaubte Tools.
• Im letzten Beispiel beschreibt agents.yaml zusaetzlich pro Agent ein eigenes llm-Profil mit Modell, Temperatur und Tokenlimit.
• tasks.yaml beschreibt Aufgaben, erwartete Ergebnisse und optionalen Task-Kontext.
• flow.yaml beschreibt ab Beispiel 07 den Flow-Fokus der Lerneinheit: Schritte, Branches, Validatoren oder Orchestrierung.
• Jede Beispiel-README erklaert Lernziel, Besonderheiten und Takeaways.

Eigene Beispiele anlegen

1. Einen neuen Ordner unter examples/ anlegen, z. B. 07_mein_beispiel.
2. Darin README.md, config/agents.yaml und config/tasks.yaml erstellen.
3. Falls neue Tools noetig sind, diese in examples/tools.py implementieren.
4. Die Tools in TOOL_REGISTRY in examples/main.py registrieren.
5. Das neue Beispiel in EXAMPLES in examples/main.py eintragen.

Typische Fehler

• ANTHROPIC_API_KEY fehlt: Der Crew-Run kann kein Claude-Modell aufrufen.
• Virtuelle Umgebung ist nicht aktiv: crewai-examples wird nicht gefunden.
• Neues Tool steht in YAML, aber nicht in TOOL_REGISTRY: Der Runner kennt den Tool-Namen nicht.
• Task-Kontext verweist auf eine Task, die in tasks.yaml erst spaeter definiert ist: Kontext-Tasks muessen vor der nutzenden Task stehen.

Was der Vortrag vermitteln soll

• CrewAI trennt Rollen, Aufgaben, Tools und Ablauf.
• YAML ist gut fuer Prompts, Rollen und Aufgaben geeignet.
• Python bleibt der richtige Ort fuer Tool-Logik und Orchestrierung.
• Tools sind nicht nur Datenquellen, sondern koennen auch Guardrails sein.
• Mehrere Agents lohnen sich erst, wenn sie unterschiedliche Rollen oder Denkmodi abbilden.