Übergaben: Orchestrierung mehrerer Agenten
Auf dieser Seite
Ü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.namezeigt an, welcher Agent letztendlich geantwortet hat.- Schützen Sie bidirektionale Übergaben mit
max_turns, um Schleifen zu verhindern.