Agenten-Challenge

Praxisprojekt: Production-Ready Multi-Agent-System entwickeln

Inhaltsverzeichnis

Überblick Agenten-Challenge
Projektoptionen
Technische Anforderungen
Projekt-Setup
Bewertungskriterien
Abgabe
1. Abgabeformat
2. Checkliste vor Abgabe
Hilfreiche Ressourcen
FAQ
Beispiel-Architektur: Support-System

Überblick Agenten-Challenge

Die Agenten-Challenge dient als praktische Anwendung und Integration der in den Kursmodulen M01-M21 erlernten Konzepte. Ziel ist es, ein funktionsfähiges Multi-Agent-System zu entwickeln, das LangGraph State Machines, Human-in-the-Loop und Checkpointing kombiniert und einen praktischen Nutzen bietet. Die Module M22–M36 sind optional und eignen sich zur Vertiefung und Erweiterung des Projekts.

Lernziele

Integration von LangChain 1.0+ und LangGraph 1.0+ in einem Production-System
Implementierung komplexer Multi-Agent-Architekturen (Supervisor, Hierarchical, Collaborative)
Praktische Anwendung von State Machines und Conditional Routing
Human-in-the-Loop Workflows für kritische Entscheidungen
Deployment mit persistenter Session-Verwaltung
Präsentation und Dokumentation der eigenen Lösung

Voraussetzungen

Abschluss der Module M01-M21 (Tag 1-5); M22-M33 optional für Vertiefung
Kenntnisse in LangChain 1.0+ und LangGraph 1.0+
Zugriff auf API-Keys (OpenAI)
Grundlegende Vertrautheit mit Gradio für UI-Entwicklung
Verständnis von State Machines und Checkpointing

Umfang

Komplexität: Production-Ready Multi-Agent-System mit State Management
Eigenständigkeit: Freie Gestaltung innerhalb der gewählten Projektoption

Praxiseinblick: Von der State Machine zum Production-System

“Ein Agent ist kein Chatbot – der Unterschied ist verstanden.” — Modul M01 (Kursplan)

Die Agenten-Challenge bereitet Sie auf realistische Herausforderungen vor, die bei Production-Deployments von KI-Agenten auftreten:

Was unterscheidet einen einfachen Agent von einem Production-System?

Einfacher Agent	Production-System (Challenge-Ziel)
`create_agent()` mit Tools	LangGraph State Machine mit Kontrolle
Keine Session-Persistenz	Checkpointing (SQLite/PostgreSQL)
Keine Fehlerbehandlung	Graceful Error Handling + Retries
Linearer Flow	Conditional Routing, Verzweigungen
Kein Human-in-the-Loop	Interrupt/Resume für kritische Aktionen
Einzelner Agent	Multi-Agent-Koordination (Supervisor)
Keine Observability	LangSmith-Tracing + Monitoring

Learnings aus der Praxis

1. State Management ist Critical

Production-Agents müssen Sessions über Tage/Wochen persistieren
Ihr Projekt: Implementieren Sie SQLite-Checkpointer für alle Sessions
Takeaway: State ist die Foundation für Kontrolle

2. Human-in-the-Loop für kritische Entscheidungen

Agenten sollten bei unsicheren Entscheidungen Menschen fragen
Ihr Projekt: Mindestens 1 Interrupt-Point für Approval
Takeaway: Autonomie ≠ keine menschliche Kontrolle

3. Multi-Agent = Skalierung

Spezialisierte Worker-Agents > ein Generalist-Agent
Ihr Projekt: Mindestens Supervisor + 2 Worker implementieren
Takeaway: Arbeitsteilung macht Systeme robuster

4. Observability von Anfang an

LangSmith-Tracing ist nicht optional für Production
Ihr Projekt: Alle Agent-Entscheidungen nachvollziehbar machen
Takeaway: Debugging ohne Traces ist unmöglich

Empfehlung: Studieren Sie den LangGraph Einsteiger Guide für Production-Best-Practices.

Konkrete Tipps für Ihre Challenge

✅ Do’s:

StateGraph VOR Code zeichnen (Visualisierung hilft!)
Checkpointing von Anfang an einbauen (nicht nachträglich)
Klein starten: 2 Worker besser als 5 halbfertige
LangSmith-Tracing durchgängig nutzen
Human-in-the-Loop für kritische Pfade

❌ Don’ts:

Nicht create_agent() für Hauptlogik (nutze LangGraph!)
Kein Overengineering: Supervisor-Pattern reicht meist
Keine Hierarchical/Collaborative-Patterns ohne klaren Bedarf
Kein Production-Deployment ohne Error-Handling
Keine Sessions ohne Checkpointing

Projektoptionen

Zur Auswahl stehen vier verschiedene Multi-Agent-Architekturen, die jeweils unterschiedliche Aspekte von LangGraph betonen. Wählen Sie eine Option aus oder kombinieren Sie Elemente.

Multi-Agent Support-System

Beschreibung: Ein Support-System mit Supervisor-Agent, der Kundenanfragen an spezialisierte Worker-Agents delegiert (Technical, Billing, General Support).

Kernelemente:

Supervisor-Agent mit Routing-Logik
2-3 spezialisierte Worker-Agents
Conditional Routing basierend auf Anfragekategorie
Human-in-the-Loop für Eskalationen
Session-Management mit Checkpointing

Erwartete Module:

M03 (Erste Agenten)
M06 (Multi-Tool Agents)
M09 (StateGraph Basics)
M10 (Conditional Routing)
M16 (Checkpointing)
M17 (Human-in-the-Loop)
M20 (Supervisor-Pattern)

Erweiterte Module (optional):

M23 (Agent Security & Best Practices)
M28 (Gradio UI für Agenten)
M35 (Production Deployment)

Architektur:

graph TB
    USER([User Request]) --> SUP[Supervisor Agent]
    SUP --> TECH[Technical Worker]
    SUP --> BILL[Billing Worker]
    SUP --> GEN[General Worker]
    TECH -->|Needs Approval?| HITL[Human Approval]
    BILL -->|Needs Approval?| HITL
    HITL --> SUP
    SUP --> RESP([Response])

Erfolgskriterien:

✅ Supervisor routet korrekt zu 2+ Workers
✅ Sessions werden persistent gespeichert (SQLite)
✅ Mindestens 1 HITL-Interrupt implementiert
✅ LangSmith zeigt vollständigen Graph-Trace

Research-Team mit Hierarchical-Pattern

Beschreibung: Ein Research-Assistent mit hierarchischer Struktur: Main Supervisor → Research Lead + Writing Lead → Spezialisierte Worker.

Kernelemente:

Hierarchical Multi-Agent-Pattern (3 Ebenen)
Research-Agents (Web, Database, PDF)
Writing-Agents (Drafting, Editing, Formatting)
Subgraphs für Research und Writing
Streaming für Fortschrittsanzeige

Erwartete Module:

M07 (LCEL Chains)
M08-M11 (RAG)
M13-M14 (StateGraph, Routing)
M21-M22 (Multi-Agent Patterns)

Erweiterte Module (optional):

M26 (Agentic RAG)
M27 (Advanced RAG – Pipeline-Patterns)
M24 (Hierarchical Agent Teams)

Architektur:

graph TB
    MAIN[Main Supervisor] --> RLEAD[Research Lead]
    MAIN --> WLEAD[Writing Lead]

    RLEAD --> WEB[Web Researcher]
    RLEAD --> DB[Database Agent]
    RLEAD --> PDF[PDF Analyzer]

    WLEAD --> DRAFT[Drafting Agent]
    WLEAD --> EDIT[Editing Agent]

    WEB --> RLEAD
    DB --> RLEAD
    PDF --> RLEAD

    DRAFT --> WLEAD
    EDIT --> WLEAD

    RLEAD --> MAIN
    WLEAD --> MAIN

Erfolgskriterien:

✅ 3-Ebenen-Hierarchie funktioniert
✅ Research + Writing als Subgraphs implementiert
✅ Streaming zeigt Fortschritt in Echtzeit
✅ RAG-Integration für Wissensrecherche

Collaborative Code-Review-System

Beschreibung: Ein System mit 3 Peer-Agents (Code Analyzer, Security Reviewer, Performance Auditor), die kollaborativ Code reviewen und Konsens finden.

Kernelemente:

Collaborative Multi-Agent-Pattern
3 spezialisierte Review-Agents
Konsens-Mechanismus (Voting, Weighted Scoring)
Konflikt-Resolution durch Moderator-Agent
Structured Output für Review-Reports

Erwartete Module:

M03 (Erste Agenten)
M05 (Structured Output)
M06 (Multi-Tool Agents)
M21 (Multi-Agent Patterns - Collaborative)

Erweiterte Module (optional):

M19 (Agent Evaluation & Testing)

Architektur:

graph LR
    CODE[Code Input] --> ANA[Code Analyzer]
    CODE --> SEC[Security Reviewer]
    CODE --> PERF[Performance Auditor]

    ANA <-->|Peer Review| SEC
    SEC <-->|Peer Review| PERF
    PERF <-->|Peer Review| ANA

    ANA --> CON[Consensus Builder]
    SEC --> CON
    PERF --> CON

    CON -->|Konflikt?| MOD[Moderator Agent]
    MOD --> CON
    CON --> REPORT([Final Report])

Erfolgskriterien:

✅ 3 Peer-Agents kommunizieren miteinander
✅ Konsens-Mechanismus funktioniert
✅ Moderator löst Konflikte
✅ Structured Output (Pydantic) für Reports

Workflow-Automation mit Tool-Integration

Beschreibung: Ein Workflow-Agent, der komplexe Business-Prozesse automatisiert (z.B. Onboarding, Approval-Workflows, Data Processing).

Kernelemente:

LangGraph State Machine für Workflow-Steps
Tool-Nodes für externe Integrationen (APIs, Datenbanken)
Conditional Routing basierend auf Business-Logik
Human-in-the-Loop für kritische Genehmigungen
Checkpointing für langlebige Prozesse (Tage/Wochen)

Erwartete Module:

M02 (Tool Use)
M03 (Erste Agenten)
M13-M14 (StateGraph, Routing)
M16-M17 (Checkpointing, HITL)

Erweiterte Module (optional):

M20 (Agent Security & Best Practices)
M35 (Production Deployment)

Architektur:

stateDiagram-v2
    [*] --> Intake
    Intake --> Validation
    Validation --> Approved: Valid
    Validation --> Rejected: Invalid

    Approved --> DataProcessing
    DataProcessing --> QualityCheck

    QualityCheck --> HumanReview: Quality Issues
    QualityCheck --> Finalization: Pass

    HumanReview --> DataProcessing: Retry
    HumanReview --> Finalization: Override

    Finalization --> [*]
    Rejected --> [*]

Erfolgskriterien:

✅ Workflow läuft über mehrere Steps
✅ Conditional Routing entscheidet Pfade
✅ HITL-Interrupts für Genehmigungen
✅ Sessions persistent (können pausiert/resumed werden)

Technische Anforderungen

PFLICHT-Features (Must-Have)

Jedes Projekt MUSS folgende Features implementieren:

StateGraph mit TypedDict

from typing import TypedDict, Annotated
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages

class AgentState(TypedDict):
    """State-Definition (Type-Safe!)"""
    messages: Annotated[list, add_messages]
    current_agent: str | None
    session_id: str
    # Weitere Felder je nach Projekt

Checkpointing (SQLite)

from langgraph.checkpoint.sqlite import SqliteSaver

checkpointer = SqliteSaver.from_conn_string("agent_sessions.db")
graph = workflow.compile(checkpointer=checkpointer)

Human-in-the-Loop (mindestens 1 Interrupt-Point)

graph = workflow.compile(
    checkpointer=checkpointer,
    interrupt_before=["human_approval"]
)

LangSmith-Tracing

import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_PROJECT"] = "agenten-challenge"
os.environ["LANGSMITH_ENDPOINT"] = "https://eu.api.smith.langchain.com"

Multi-Agent-Architektur

Minimum: 1 Supervisor + 2 Worker-Agents
Supervisor delegiert Aufgaben an Worker
Workers haben spezialisierte Tools oder Prompts

Empfohlene Features (Should-Have)

Conditional Routing

def route_by_category(state: AgentState) -> str:
    """Router-Funktion für Verzweigungen."""
    # Logik hier
    return "next_node_name"

workflow.add_conditional_edges(
    "supervisor",
    route_by_category,
    {
        "technical": "technical_worker",
        "billing": "billing_worker"
    }
)

Structured Output mit Pydantic

from pydantic import BaseModel, Field

class AgentDecision(BaseModel):
    reasoning: str = Field(description="Warum diese Entscheidung?")
    next_action: str = Field(description="Nächster Schritt")
    confidence: float = Field(description="Konfidenz 0-1", ge=0, le=1)

structured_llm = llm.with_structured_output(AgentDecision)

Gradio-UI mit Session-Management

import gradio as gr

def chat_handler(message, history, session_id):
    config = {"configurable": {"thread_id": session_id}}
    result = graph.invoke({"messages": [...]}, config=config)
    return result["messages"][-1].content

with gr.Blocks() as demo:
    session_id = gr.Textbox(label="Session ID")
    chatbot = gr.Chatbot()
    # ...

Optionale Features (Nice-to-Have)

Subgraphs für modulare Workflows
Streaming für Echtzeit-Fortschritt
Custom Middleware für Logging/Metrics
PostgreSQL-Checkpointer statt SQLite
Deployment auf Hugging Face Spaces
Advanced HITL mit Custom Approval-UI

Projekt-Setup

Environment Setup

# ═══════════════════════════════════════════════════
# 📦 INSTALLATION
# ═══════════════════════════════════════════════════

!pip install -q langchain>=1.1.0 langchain-openai>=1.0.0 langchain-community
!pip install -q langgraph>=1.0.0 langgraph-checkpoint-sqlite
!pip install -q tiktoken gradio

# Optional: genai_lib installieren
!uv pip install --system -q git+https://github.com/ralf-42/Agenten.git#subdirectory=04_modul

API-Keys Setup

Wichtig: LangSmith-Account und LangSmith-API-Key im EU-Workspace anlegen (https://eu.smith.langchain.com/) und für LANGSMITH_ENDPOINT den EU-API-Endpoint setzen: https://eu.api.smith.langchain.com

# ═══════════════════════════════════════════════════
# 🔑 API-KEYS
# ═══════════════════════════════════════════════════

import os
from google.colab import userdata

# OpenAI API
os.environ["OPENAI_API_KEY"] = userdata.get('OPENAI_API_KEY')

# LangSmith (PFLICHT für Challenge!)
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_PROJECT"] = "agenten-challenge-your-name"
os.environ["LANGSMITH_API_KEY"] = userdata.get('LANGSMITH_API_KEY')
os.environ["LANGSMITH_ENDPOINT"] = "https://eu.api.smith.langchain.com"

LangGraph Basis-Template

# ═══════════════════════════════════════════════════
# 🎯 LANGGRAPH BASIS-SETUP
# ═══════════════════════════════════════════════════

from typing import TypedDict, Annotated, Literal
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.checkpoint.sqlite import SqliteSaver
from langchain.chat_models import init_chat_model

# 1. State definieren
class MultiAgentState(TypedDict):
    messages: Annotated[list, add_messages]
    current_agent: str | None
    session_id: str
    approved: bool

# 2. LLM initialisieren
llm = init_chat_model("openai:gpt-4o-mini", temperature=0.0)

# 3. Checkpointer erstellen
checkpointer = SqliteSaver.from_conn_string("challenge_sessions.db")

# 4. StateGraph erstellen
workflow = StateGraph(MultiAgentState)

# 5. Nodes hinzufügen (Beispiel)
def supervisor_node(state: MultiAgentState) -> MultiAgentState:
    """Supervisor entscheidet nächsten Agent."""
    # Ihre Logik hier
    return state

workflow.add_node("supervisor", supervisor_node)
# ... weitere Nodes

# 6. Graph kompilieren
graph = workflow.compile(
    checkpointer=checkpointer,
    interrupt_before=["human_approval"]  # HITL
)

Bewertungskriterien

Kategorie	Punkte	Kriterien
Multi-Agent-Architektur	25	Supervisor + 2+ Worker, klare Delegation, Routing-Logik
State Management	20	TypedDict State, Checkpointing, Sessions persistent
Human-in-the-Loop	15	Interrupt/Resume funktioniert, sinnvoller Einsatz
Code-Qualität	15	Sauber, dokumentiert, Error-Handling, Best Practices
Funktionalität	10	End-to-End-Flow funktioniert, Use Case gelöst
Deployment & UI	10	Gradio-UI vorhanden, lauffähig, benutzerfreundlich
Dokumentation	5	README.md, Architektur-Diagramm, Setup-Anleitung
Gesamt	100

Bestanden: ≥ 60 Punkte

Abgabe

Abgabeformat

Pflicht-Dateien:

Jupyter Notebook (Agenten_Challenge.ipynb)
- Vollständig ausführbar von oben bis unten
- Kommentierte Code-Zellen
- Mermaid-Diagramme für Architektur
SQLite-Datenbank (challenge_sessions.db) mit Beispiel-Sessions
README.md mit:
- Kurzbeschreibung des Projekts
- Architektur-Übersicht (Mermaid-Diagramm)
- Setup-Anleitung (API-Keys, Dependencies)
- Screenshot der Gradio-UI
- LangSmith-Project-Link (public)
Optional: Demo-Video (max. 5 Min.)

Einreichung:

Als Colab-Link (öffentlich freigegeben)
ODER als ZIP-Archiv mit .ipynb + DB
ODER als Git-Repository-Link (GitHub/GitLab)

Checkliste vor Abgabe

Code & Funktionalität

Notebook läuft von oben bis unten fehlerfrei durch
Alle API-Keys sind über Colab Secrets eingebunden (nicht hardcodiert!)
StateGraph verwendet TypedDict (PFLICHT!)
Checkpointing funktioniert (Sessions können geladen werden)
Mindestens 1 HITL-Interrupt implementiert
Multi-Agent-System funktioniert (Supervisor + 2+ Workers)
LangSmith-Tracing aktiviert, Projekt öffentlich

Dokumentation

README.md erklärt Projekt, Architektur und Setup
Mermaid-Diagramm der Multi-Agent-Architektur vorhanden
Code-Kommentare an kritischen Stellen
Error-Handling implementiert

UI & Deployment

Gradio-UI läuft und erstellt share-Link
Session-Management in UI funktioniert
UI ist benutzerfreundlich (nicht nur technisch)

Hilfreiche Ressourcen

Dokumentation

LangGraph:

Projekt-Ressourcen:

Code-Beispiele

Referenz-Notebooks:

M13_StateGraph_Basics.ipynb - StateGraph Einführung
M14_Conditional_Routing_Tool_Loop.ipynb - Routing
M22_Supervisor_Pattern.ipynb - Multi-Agent-Beispiel
M23_Multi_Agent_Projekt.ipynb - Vollständiges Projekt

Troubleshooting

Problem	Ursache	Lösung
`END is not defined`	Falscher Import	`from langgraph.graph import END`
Sessions nicht persistent	Kein Checkpointer	`checkpointer=SqliteSaver(...)`
Graph stoppt nicht bei HITL	Falscher Interrupt	`interrupt_before=["node_name"]`
Supervisor routet nicht	Conditional Edge fehlt	`add_conditional_edges()` verwenden
LangSmith zeigt nichts	Tracing nicht aktiviert oder falscher Endpoint	`LANGSMITH_TRACING="true"` und `LANGSMITH_ENDPOINT="https://eu.api.smith.langchain.com"` setzen

FAQ

Q: Muss ich alle 4 Projektoptionen implementieren? A: Nein! Wählen Sie eine Option, die Sie vollständig implementieren. Qualität > Quantität.

Q: Kann ich create_agent() statt LangGraph verwenden? A: Nein! LangGraph ist PFLICHT für die Challenge. create_agent() reicht nicht für die Bewertungskriterien.

Q: Wie viele Worker-Agents brauche ich mindestens? A: Minimum 2 Worker + 1 Supervisor. Für Bonuspunkte: 3-4 Worker.

Q: Muss ich SQLite oder kann ich PostgreSQL nutzen? A: SQLite reicht für die Challenge. PostgreSQL ist optional (Bonuspunkte).

Q: Wie lange sollen Sessions persistent bleiben? A: Mindestens über Notebook-Neustart hinweg. Test: Notebook schließen, neu öffnen, Session laden.

Q: Mein Graph hat Endlos-Loops – was tun? A: Fügen Sie recursion_limit=20 bei compile() hinzu. Prüfen Sie, ob Supervisor-Router immer zu END führen kann.

Q: Brauche ich wirklich eine UI? A: Ja! Gradio-UI ist Teil der Bewertung (10 Punkte). Zeigt, dass System nutzbar ist.

Q: Kann ich die Challenge lokal statt in Colab machen? A: Ja! Verwenden Sie dann:

Lokales Jupyter Notebook/Lab
from dotenv import load_dotenv für API-Keys
SQLite funktioniert identisch

Q: Unterschied zur RAG_Workshop.md? A:

RAG Workshop: Fokus auf LangChain, RAG, Retrieval, Embeddings
Kursnavigator Workshop: Fokus auf LangGraph, Routing, State und kleine Kursanwendung
Agenten Challenge: Production-Ready System mit allen 7 LangGraph Must-Haves

Beispiel-Architektur: Support-System

Hier ein vollständiges Beispiel für Option 2.1 (Multi-Agent Support-System) als Inspiration:

flowchart TB
    START([User Request]) --> PARSE[Parse & Categorize]
    PARSE --> SUP[Supervisor Agent]

    SUP --> ROUTE{Category?}

    ROUTE -->|Technical| TECH[Technical Worker]
    ROUTE -->|Billing| BILL[Billing Worker]
    ROUTE -->|General| GEN[General Worker]

    TECH -->|Tools| TOOLS1[Server Check<br/>Service Restart<br/>Log Analysis]
    BILL -->|Tools| TOOLS2[Invoice Query<br/>Payment Status]
    GEN -->|RAG| KB[Knowledge Base]

    TOOLS1 --> TECH
    TOOLS2 --> BILL
    KB --> GEN

    TECH --> APPROVAL{Critical<br/>Action?}
    BILL --> APPROVAL
    GEN --> SUP

    APPROVAL -->|Yes| HITL[👤 Human Review]
    APPROVAL -->|No| SUP

    HITL -->|Approved| SUP
    HITL -->|Rejected| REJECT[Send Rejection Notice]

    SUP -->|Complete?| CHECK{All Steps<br/>Done?}
    CHECK -->|No| ROUTE
    CHECK -->|Yes| FINISH([Response to User])

    REJECT --> FINISH

    style SUP fill:#FFD700
    style TECH fill:#87CEEB
    style BILL fill:#90EE90
    style GEN fill:#FFB6C1
    style HITL fill:#FFA500

State-Definition:

class SupportState(TypedDict):
    messages: Annotated[list, add_messages]
    category: Literal["technical", "billing", "general"] | None
    current_worker: str | None
    requires_approval: bool
    approved: bool
    session_id: str
    tool_results: list[dict]

Version: 1.1
Stand: März 2026
Kurs: KI-Agenten. Verstehen. Anwenden. Gestalten.