Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Übergaben: Orchestrierung mehrerer Agenten

Lektion 12 von 25 Aktualisiert am 29. Juli 2026 Entwickler
Auf dieser Seite
  1. Übergaben: Orchestrierung mehrerer Agenten
  2. Das Konzept der Übergabe
  3. Anpassung der Übergabebeschreibung
  4. Übergaben mit Kontext
  5. Muster: Dreistufige Triage
  6. Bidirektionale Übergaben
  7. Verfolgung von Übergaben
  8. Kernaussagen

Übergaben: Orchestrierung mehrerer Agenten

Ein einzelner Agent kann nicht alles erledigen. Je mehr Domänen Sie in eine einzige Anweisungsmenge packen, desto mehr widersprechen sich die Richtlinien gegenseitig und desto weniger präzise werden die Antworten. Übergaben (Handoffs) ermöglichen es einem Agenten, die Konversation an einen anderen spezialisierten Agenten zu delegieren. Dies ist der Schlüsselmechanismus für die Erstellung mehragentiger Systeme, in denen jeder Agent in seiner eigenen Domäne exzellent ist.

Das Konzept der Übergabe

Eine Übergabe ist eine Übertragung der Kontrolle von einem Agenten auf einen anderen. Wenn Agent A an Agent B übergibt, übernimmt Agent B die Kontrolle und generiert die Antwort. Der Runner übernimmt diesen Übergang automatisch: Sie müssen keine explizite Routing-Logik schreiben oder den zweiten Agenten manuell aufrufen. Im folgenden Beispiel erhält der Triage-Agent eine Beschwerde über einen Rechnungsbetrag, erkennt den Bereich und reicht den Ballon weiter. Der Kunde sieht hingegen nur eine durchgehende Konversation.

from agents import Agent, Runner

billing_agent = Agent(
    name="Billing Agent",
    instructions="""Sie bearbeiten Abrechnungsfragen: Rechnungen, Zahlungen,
    Rückerstattungen, Abonnements. Antworten Sie präzise und professionell.""",
    model="gpt-5.6-terra",
)

technical_agent = Agent(
    name="Technical Agent",
    instructions="""Sie bearbeiten technischen Support: Fehler, Konfiguration,
    Installation, Fehlerbehebung. Geben Sie schrittweise Anweisungen.""",
    model="gpt-5.6-terra",
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="""Sie sind der erste Anlaufpunkt.
    Analysieren Sie die Anfrage des Kunden und leiten Sie sie an den zuständigen Agenten weiter.
    - Abrechnungsfragen → Billing Agent
    - Technische Fragen → Technical Agent""",
    handoffs=[billing_agent, technical_agent],
    model="gpt-5.6-terra",
)

result = Runner.run_sync(
    triage_agent,
    "Meine letzte Rechnung scheint falsch zu sein; der Betrag ist zu hoch."
)
# Der Triage-Agent übergibt an den Billing-Agenten
print(f"Beantwortet von: {result.last_agent.name}")
print(result.final_output)

Anpassung der Übergabebeschreibung

Standardmäßig verwendet eine Übergabe den Namen und die Anweisungen des Zielagenten. Dies funktioniert gut, solange die Namen deskriptiv sind, wird aber riskant, wenn zwei Agenten ähnlich aussehen. In solchen Fällen können Sie die Beschreibung anpassen, um das Routing zu steuern, indem Sie die spezifischen Szenarien auflisten, die jede Weiterleitung auslösen sollten.

from agents import Handoff

triage_agent = Agent(
    name="Triage Agent",
    instructions="Leiten Sie die Anfrage an den spezialisierten Agenten weiter.",
    handoffs=[
        Handoff(
            agent=billing_agent,
            description="Weiterleitung für Zahlungsfragen, Rechnungen, Rückerstattungen und Abonnements.",
        ),
        Handoff(
            agent=technical_agent,
            description="Weiterleitung für technische Probleme, Fehler und Anfragen zur Konfigurationshilfe.",
        ),
    ],
)

Übergaben mit Kontext

Eine Übergabe ist nur dann nützlich, wenn der übernehmende Agent weiß, worum es geht. Wenn ein Agent eine Übergabe vornimmt, wird die Konversationsverlaufshistorie an den Zielagenten übergeben: Der neue Agent hat Zugriff auf alles, was bisher gesagt wurde, sodass der Kunde sein Problem nicht wiederholen muss. Darüber hinaus trägt der typisierte Kontext strukturierte Sitzungsdaten – Kunden-ID, abonniertes Paket, frühere Tickets – und bleibt für die Werkzeuge des eingehenden Agenten zugänglich.

from dataclasses import dataclass
from agents import Agent, Runner, RunContextWrapper, function_tool

@dataclass
class CustomerContext:
    client_id: str
    plan: str
    ticket_history: list[str]

@function_tool
def view_invoice(ctx: RunContextWrapper[CustomerContext], month: str) -> str:
    """Zeigt die Rechnung für einen bestimmten Monat für den aktuellen Kunden an."""
    client_id = ctx.context.client_id
    return f"Rechnung für {month} für {client_id}: €149,99 (Paket {ctx.context.plan})"

billing_agent = Agent(
    name="Billing Agent",
    instructions="Sie bearbeiten Abrechnungen. Nutzen Sie den Kundenkontext.",
    tools=[view_invoice],
    model="gpt-5.6-terra",
)

triage_agent = Agent(
    name="Triage",
    instructions="Leiten Sie an den richtigen Agenten weiter.",
    handoffs=[billing_agent],
    model="gpt-5.6-terra",
)

context = CustomerContext(
    client_id="cli_456",
    plan="Pro",
    ticket_history=["Ticket #001: Langsame Verbindung"]
)

result = Runner.run_sync(
    triage_agent,
    "Können Sie meine Rechnung für März prüfen?",
    context=context,
)

Muster: Dreistufige Triage

Übergaben beschränken sich nicht auf horizontales Routing. Sie replizieren auch die Eskalationsstruktur eines echten Supportdienstes. Hier ist ein Produktionsmuster mit drei Ebenen: L1 behandelt Routineanfragen, leitet fortgeschrittene Konfigurationsprobleme an L2 weiter, und L2 eskaliert Architekturthemen an L3. Beachten Sie, dass Ebene 3 auf einem leistungsfähigeren Modell basiert, da sie nur Fälle sieht, die von den beiden vorhergehenden Ebenen bereits gefiltert wurden.

level3_agent = Agent(
    name="L3 Technical Expert",
    instructions="""Sie sind ein technischer Experte der Ebene 3.
    Sie bearbeiten komplexe Architektur- und Infrastrukturprobleme.
    Wenn Sie das Problem nicht lösen können, weisen Sie darauf hin, dass eine menschliche Eskalation notwendig ist.""",
    model="gpt-5.6-sol",  # Das leistungsfähigste Modell für komplexe Fälle
)

level2_agent = Agent(
    name="L2 Technical Support",
    instructions="""Sie sind ein Techniker der Ebene 2.
    Sie bearbeiten fortgeschrittene Konfigurationsprobleme.
    Wenn das Problem zu komplex ist, leiten Sie an Ebene 3 weiter.""",
    handoffs=[level3_agent],
    model="gpt-5.6-terra",
)

level1_agent = Agent(
    name="L1 Customer Support",
    instructions="""Sie sind der erste Anlaufpunkt für den Kundensupport.
    Behandeln Sie einfache Fragen (Passwort, Konto, Navigation).
    Leiten Sie technische Probleme an Ebene 2 weiter.""",
    handoffs=[level2_agent],
    model="gpt-5.6-terra",
)

Bidirektionale Übergaben

Die Kette kann auch kreisförmig sein: Zwei Agenten können die Kontrolle hin und her übertragen. Dies ist typisch, wenn ein Interessent während eines Verkaufsgesprächs eine technische Frage stellt und sich nach der Beruhigung wieder der Preisfrage zuwendet.

sales_agent = Agent(
    name="Sales Agent",
    instructions="""Sie verkaufen Produkte. Wenn der Kunde nach
    technischem Support fragt, leiten Sie an den technischen Agenten weiter.""",
)

support_agent = Agent(
    name="Support Agent",
    instructions="""Sie bieten technischen Support an. Wenn der Kunde
    etwas kaufen möchte, leiten Sie an den Verkaufsagenten weiter.""",
)

# Bidirektionale Übergaben
sales_agent.handoffs = [support_agent]
support_agent.handoffs = [sales_agent]

Achten Sie auf unendliche Schleifen: Eine Sicherung oder max_turns wird empfohlen. Ohne diese Begrenzung kann eine mehrdeutige Anfrage die Konversation von einem Agenten zum anderen hin und her werfen, bis Ihr Kontingent erschöpft ist.

Verfolgung von Übergaben

Schließlich müssen Sie wissen, wer die Antwort tatsächlich gegeben hat – sowohl zur Überprüfung Ihres Routings als auch für Ihre Supportstatistiken. RunResult sagt Ihnen, welcher Agent letztlich die Antwort generiert hat.

result = Runner.run_sync(triage_agent, "Ich habe einen kritischen Fehler")

print(f"Initialer Agent: triage_agent")
print(f"Finaler Agent: {result.last_agent.name}")
# Druckt "Technical Agent", wenn die Triage korrekt funktioniert hat

Machen Sie es zur Gewohnheit, diesen Wert zu protokollieren: Wenn ein Triage-Agent Anfragen behält, die er hätte weiterleiten sollen, wird die Verteilung von last_agent das Problem lange vor Kundenfeedback aufdecken.

Kernaussagen

  • Übergaben ermöglichen es Ihnen, die Konversation an einen spezialisierten Agenten zu delegieren.
  • Der Konversationsverlauf wird an den Zielagenten übergeben.
  • Verwenden Sie Handoff(agent=..., description=...), um das Routing zu steuern.
  • Geteilter Kontext (RunContextWrapper) ist für alle Agenten zugänglich.
  • result.last_agent.name zeigt an, welcher Agent letztendlich geantwortet hat.
  • Schützen Sie bidirektionale Übergaben mit max_turns, um Schleifen zu verhindern.