Multi-Agenten-Handoff: Kontextübertragung zwischen Sub-Agenten

Der Recherche-Agent fand das Kundenkonto, bestätigte den Plan und zog die letzten vier Rechnungen. Er übergab an den Abrechnungs-Agenten nur eine einzeilige Zusammenfassung: „Kunde möchte eine Rückerstattung.“ Der Abrechnungs-Agent weiß nichts über Konto, Plan oder Rechnungen und fragt deshalb erneut nach der Konto-ID.

Apidog heute ausprobieren

Jede Tatsache, die der erste Agent gesammelt hatte, ging an der Schnittstelle verloren. Das Übergabeproblem kostet doppelt: durch wiederholte API-Aufrufe und durch Fehler, wenn der zweite Agent mit weniger Informationen arbeitet als der erste.

Dieser Leitfaden zeigt:

• welche Informationen eine Übergabe enthalten muss,
• welche drei Übergabemuster sich bewährt haben,
• warum Zusammenfassungen oft wichtige Details verlieren,
• wie man Übergaben mit Mocks und Grenztests prüft.

Warum Agenten in der Produktion ausfallen behandelt verlorene Zustände als eine zentrale Fehlerquelle. Hier betrachten wir dieselbe Herausforderung in Multi-Agent-Systemen.

Apidog kommt ins Spiel, weil die günstigste Lösung oft darin besteht, keine Nutzdaten zu übergeben, sondern Identifikatoren. Das funktioniert allerdings nur, wenn jeder Agent denselben Datensatz zuverlässig abrufen kann.

Was tatsächlich die Schnittstelle überqueren muss

Eine Übergabe sollte weder das gesamte Gespräch kopieren noch gar keine Informationen enthalten. Ein vollständiges Transkript belastet das Kontextfenster; eine leere Übergabe zwingt den nächsten Agenten, bereits erledigte Arbeit zu wiederholen.

Unterscheide vier Kategorien:

1. Identifikatoren

Konto-, Bestell-, Job- und Ticket-IDs sind klein, stabil und ermöglichen dem empfangenden Agenten, die benötigten Daten selbst abzurufen. Sie sind meist die wertvollsten Übergabedaten – und die, die am häufigsten fehlen.

2. Bereits getroffene Entscheidungen

Beispiel: „Der Kunde ist gemäß Richtlinie 3 für eine Rückerstattung berechtigt.“

Der empfangende Agent sollte diese Entscheidung nicht ohne neuen Grund neu verhandeln. Andernfalls können zwei Agenten innerhalb derselben Aufgabe widersprüchliche Entscheidungen treffen.

3. Einschränkungen

Dazu gehören:

• Budgetgrenzen,
• erteilte Genehmigungen,
• bereits ausgeführte Aktionen.

Fehlen diese Informationen, kann eine Aufgabe doppelt abgerechnet oder dieselbe Genehmigung erneut angefordert werden. Das steht in direktem Zusammenhang mit Idempotenz für KI-Agenten.

4. Offene Fragen

Dokumentiere ausdrücklich, was der erste Agent nicht klären konnte. So verhindert die Übergabe, dass der zweite Agent stillschweigend Annahmen trifft.

Nicht nötig sind normalerweise:

• rohe API-Antworten,
• das vollständige Begründungsprotokoll,
• Daten, die der empfangende Agent mit einem einzigen API-Aufruf abrufen kann.

Drei Wege zur Zustandsübergabe

Das gesamte Gespräch übergeben

Das ist für zwei Agenten und eine kurze Aufgabe unkompliziert. Bei langen Transkripten scheitert das Muster jedoch: Der empfangende Agent verbringt den Großteil seines Budgets mit dem Lesen der Historie, während relevante Fakten zwischen anderen Nachrichten verborgen sind.

Tool-Antworten aus dem Kontextfenster heraushalten erklärt, warum Modelle besonders in der Mitte langer Kontexte Informationen verlieren.

Eine Zusammenfassung übergeben

Der erste Agent schreibt eine Übergabenachricht, mit der der zweite Agent startet. Das ist in vielen Frameworks der Standard, aber verlustbehaftet: Modelle fassen eher erzählerisch als strukturiert zusammen.

Statt:

Konto 8812, Plan Pro, vier Rechnungen, Rückerstattung für Rechnung inv_44 genehmigt.

entsteht leicht:

Der Kunde ist seit zwei Jahren Abonnent und frustriert.

Ein strukturiertes Übergabeobjekt übergeben

Der erste Agent füllt ein Schema; der zweite liest Felder statt Prosa. Dieses Muster erfordert mehr Einrichtung, ist aber am zuverlässigsten:

{
  "task_id": "task_2026_08_26_0031",
  "from_agent": "research",
  "to_agent": "billing",
  "entities": {
    "customer_id": "cus_8812",
    "invoice_ids": ["inv_41", "inv_42", "inv_43", "inv_44"],
    "subscription_id": "sub_119"
  },
  "decisions": [
    { "decision": "refund_eligible", "value": true, "basis": "policy 3.2, charged twice in one cycle" }
  ],
  "constraints": {
    "max_refund_cents": 4900,
    "human_approval_granted": false,
    "actions_taken": ["read_invoices"]
  },
  "open_questions": ["Customer has not confirmed which invoice to refund"],
  "summary": "Customer cus_8812 was double-charged in August. Refund of one invoice is approved under policy 3.2, up to 4900 cents. Awaiting the customer's choice of invoice."
}

Das Feld summary bleibt sinnvoll, weil Prosa Nuancen aufnehmen kann, die das Schema nicht abdeckt. Sie ergänzt die strukturierten Felder, ersetzt sie aber nicht.

Validiere das Objekt vor der Übergabe. Fehlt etwa customer_id, muss die Schnittstelle sofort fehlschlagen – nicht erst der zweite Agent nach drei weiteren Aufrufen.

Referenzen statt Nutzdaten übergeben

Die robusteste Variante übergibt fast keine Nutzdaten:

1. Der erste Agent übergibt IDs.
2. Der zweite Agent ruft die aktuellen Daten über die API ab.
3. Beide Agenten arbeiten mit derselben Quelle.

Das hat drei Vorteile:

• Der Zustand bleibt aktuell.
• Die Übergabe umfasst wenige Bytes statt vieler Tokens.
• Der Audit-Trail zeigt jeden Lesezugriff als API-Aufruf.

Die Voraussetzung: Jeder Agent muss dieselbe API mit passenden Berechtigungen erreichen können. Jeder Agent sollte eigene Zugangsdaten mit minimalen Rechten besitzen. Ein Abrechnungs-Agent mit einem schreibgeschützten Recherche-Token kann keine Rückerstattung ausführen. Ein Recherche-Agent mit einem mächtigen Abrechnungstoken vergrößert dagegen das mögliche Schadensausmaß.

Mehr dazu steht in API-Schlüssel mit geringsten Rechten für Agenten.

Wenn ein erneuter Abruf teuer oder langsam ist, kann der Orchestrator den Datensatz cachen. Übergib dann eine Referenz auf den Cache-Eintrag. Der empfangende Agent fordert die Daten weiterhin explizit an, während der zweite Lesezugriff günstig bleibt.

Wo Übergaben scheitern

Vier Fehlerklassen decken die meisten Vorfälle ab.

Verlorene Identifikatoren

Die Zusammenfassung nennt nur „den Kunden“. Der zweite Agent sucht nach Namen, findet mehrere Treffer und wählt den falschen Datensatz.

Gegenmaßnahme: Prüfe vor jeder Übergabe, ob alle erforderlichen Entitäts-IDs vorhanden sind.

Wiederholte Aktionen

Der erste Agent hat die E-Mail bereits gesendet, dokumentiert dies aber nicht. Der zweite Agent sendet sie erneut.

Gegenmaßnahmen:

• Führe actions_taken im Übergabeobjekt.
• Prüfe das Feld vor jedem Schreibvorgang.
• Verwende Idempotenzschlüssel, damit Wiederholungen harmlos bleiben.

Verlorene Genehmigungen

Ein Mensch hat während des ersten Agentenlaufs eine Rückerstattung genehmigt. Der zweite Agent weiß davon nichts und fragt erneut. Für die Nutzer wirkt das System, als würde es nicht zuhören.

Gegenmaßnahme: Übergib Genehmigungen als explizite Einschränkungen und binde sie an die Aufgabe, nicht an den Agenten.

Selbstbewusste Erfindungen

Der empfangende Agent benötigt einen Wert, den die Übergabe nicht enthält. Statt nachzufragen, erfindet er einen plausiblen Wert. Das ist besonders gefährlich, weil der Lauf erfolgreich aussehen kann.

Gegenmaßnahmen:

• Führe ein Feld open_questions.
• Weise den empfangenden Agenten ausdrücklich an: Fehlt ein erforderlicher Identifikator, muss er anhalten und fragen.

Schleifen verschärfen alle vier Probleme. Wenn Agent A an B und B anschließend an A übergibt, zerfällt der Zustand bei jedem Durchlauf wie bei einer Fotokopie einer Fotokopie.

Begrenze deshalb die Anzahl der Übergaben und führe dasselbe ursprüngliche Aufgabenobjekt durch den gesamten Lauf. Baue es nicht an jeder Grenze neu auf.

Die Schnittstelle testen, nicht nur die Agenten

Übergaben sind Integrationspunkte. Teste sie daher wie jede andere Schnittstelle.

Übergabeobjekt prüfen

Führe den ersten Agenten in einem festen Szenario aus und prüfe sein Objekt:

• Sind alle erforderlichen IDs vorhanden?
• Sind Entscheidungen aufgezeichnet?
• Sind ausgeführte Aktionen enthalten?
• Sind offene Fragen explizit?

Diese Assertions sind deterministisch, auch wenn der Agent selbst nicht deterministisch arbeitet. Der allgemeine Ansatz wird in Testen nicht-deterministischer Agenten beschrieben.

Empfänger isoliert testen

Übergib dem Abrechnungs-Agenten zunächst ein gültiges, handgefertigtes Objekt. Prüfe anschließend ein absichtlich fehlerhaftes Objekt, aus dem customer_id entfernt wurde.

Der Test muss bestätigen, dass der Agent nachfragt, statt zu raten. Genau dieser Fall deckt Erfindungen auf.

Gegen Mocks testen

Ein Test, der echte Rückerstattungen ausführt, wird meist nur einmal ausgeführt. Richte beide Agenten stattdessen gegen Mock-Endpunkte und führe die Suite bei jeder Änderung aus. Siehe dazu Agenten gegen Mocks statt gegen die Produktion ausführen.

In Apidog stammen die Mocks aus derselben API-Definition, die beide Agenten verwenden. So driften Implementierung und Tests nicht auseinander.

Jede Übergabe protokollieren

Speichere das vollständige Objekt an jeder Grenze zusammen mit der Aufgaben-ID. Wenn ein Multi-Agent-Lauf fehlschlägt, zeigt das Protokoll, welcher Agent die Information noch hatte und an welcher Grenze sie verloren ging.

Tracing von Agenten-Tool-Aufrufen beschreibt, welche zusätzlichen Daten in diesen Audit-Trail gehören.

Was Frameworks bereitstellen

Die meisten Orchestrierungs-Frameworks besitzen ein Übergabeprimitiv. Entscheidend ist, was tatsächlich über die Grenze bewegt wird.

• Das OpenAI Agents SDK modelliert die Übergabe als Werkzeugaufruf. Das Modell entscheidet also, wann die Kontrolle übergeht. Kombiniere dieses flexible Muster mit einer Validierung beim Verlassen.
• Die LangGraph-Anleitung für Multi-Agent-Systeme verwendet ein explizites Graphobjekt, das jeder Knoten liest und schreibt. Das entspricht einer strukturierten Übergabe; du musst vor allem die Pflichtfelder definieren.
• Der Artikel von Anthropic über den Aufbau eines Multi-Agenten-Forschungssystems ist besonders für die operativen Details lesenswert, etwa für den Umfang der Anweisungen an Unteragenten.

Der rote Faden: Jedes Framework bewegt irgendeinen Zustand. Keines entscheidet für dich, welche Fakten tragend sind. Diese Liste musst du selbst definieren und testen.

Das Aufgabenobjekt außerhalb des Gesprächs halten

Eine strukturelle Änderung verhindert viele Übergabefehler: Speichere den Aufgabenstatus dauerhaft und lasse jeden Agenten dasselbe Objekt lesen und schreiben.

Das Gespräch ist ein schlechter Zustandsspeicher. Es wird zusammengefasst, gekürzt und umgeschrieben. Keine dieser Operationen weiß zuverlässig, welche Felder unverzichtbar sind. Eine Datenbankzeile kennt dieses Problem nicht.

Das Muster:

1. Der Agent lädt zu Beginn eines Zuges das Aufgabenobjekt.
2. Nach jeder Aktion ergänzt er actions_taken und speichert den Zustand.
3. Bei der Übergabe übergibt er nur die Aufgaben-ID.
4. Der nächste Agent lädt dasselbe Objekt.

Wichtige Informationen stehen damit nicht im Prompt und können nicht versehentlich wegzusammengefasst werden.

Das Aufgabenobjekt ist außerdem ein Wiederaufnahmepunkt. Bricht ein Lauf bei Schritt vier ab, bleiben die Ergebnisse der ersten drei Schritte erhalten. Ein erneuter Versuch beginnt dort statt bei null.

Wo die Plattform den Zustand halten kann

Laufen Agenten als CLI-Prozesse auf Entwicklerrechnern, musst du das dauerhafte Aufgabenobjekt selbst implementieren. Einige Plattformen modellieren diese Einheit bereits.

Sharkly ist ein Arbeitsverwaltungssystem für Menschen und Agenten. Eine Aufgabe enthält Ziel, Status, verantwortliche Person, zugewiesenen Agenten oder Crew, Kommentare sowie Ausführungszustand und Ergebnis.

Eine Crew verbindet einen leitenden Agenten mit weiteren Agenten und Personen. Eine Aufgabe, die mehrere Spezialisten benötigt, wird dadurch einer wiederverwendbaren Gruppe zugewiesen, statt manuell per Prompt weitergereicht zu werden. Weil der Zustand an der Aufgabe und nicht am Gespräch hängt, ist die Übergabe nicht von einer guten Zusammenfassung abhängig.

Die Laufzeiten bleiben unverändert: Claude Code, Codex und andere Werkzeuge führen die Arbeit auf registrierten Computern aus. Die Plattform stellt Aufgabendatensatz, Zuweisung und Prüfzyklus bereit. Die Sharkly-Dokumentation ist eine Referenz für die Felder, die sich in einem solchen Modell als wichtig erweisen.

Checkliste für zuverlässige Übergaben

• [ ] Ein definiertes Übergabeschema existiert und wird an der Schnittstelle validiert.
• [ ] Entitätsidentifikatoren sind Pflichtfelder.
• [ ] Entscheidungen enthalten ihre Grundlage.
• [ ] Ausgeführte Aktionen werden protokolliert und vor Schreibvorgängen geprüft.
• [ ] Genehmigungen und Budgets gehören zur Aufgabe, nicht zum Agenten.
• [ ] Offene Fragen sind explizit; der Empfänger fragt statt zu raten.
• [ ] Daten werden per Referenz übergeben, wenn ein erneuter Abruf günstig ist.
• [ ] Die Anzahl der Übergaben ist begrenzt.
• [ ] Das ursprüngliche Aufgabenobjekt bleibt über alle Übergaben hinweg erhalten.
• [ ] Jede Übergabe wird mit der Aufgaben-ID protokolliert.
• [ ] Grenztests laufen in CI gegen Mocks, einschließlich einer absichtlich unvollständigen Übergabe.

Die meisten Multi-Agent-Fehler sind keine Denkfehler. Es handelt sich um eine Tatsache, die im ersten Agenten vorhanden war, aber den nächsten nicht erreicht hat. Behandle die Übergabe deshalb als echte Schnittstelle – mit Schema, Validierung und Tests.

Apidog herunterladen, um Mocks und Grenztests neben der API-Definition zu verwalten, von der beide Agenten abhängen.

Häufig gestellte Fragen

Lohnt sich eine strukturierte Übergabe für zwei Agenten?

Für zwei Agenten in einer kurzen Aufgabe reicht die Gesprächsübergabe meist aus. Ein strukturiertes Objekt lohnt sich ab drei Agenten, bei langen Aufgaben oder sobald eine Übergabe eine Prozess- oder Laufzeitgrenze überschreitet.

Sollte das Modell das Übergabeobjekt schreiben?

Wo möglich, sollte Code das Objekt erstellen. Identifikatoren, ausgeführte Aktionen und Genehmigungen sollten aus tatsächlich erfolgten Vorgängen stammen, nicht aus dem Gedächtnis des Modells.

Das Modell kann summary und offene Fragen formulieren. Kritische Felder sollten vom Orchestrator gesetzt und validiert werden.

Wie verhindere ich Kontextverlust in einer Schleife?

Führe ein einziges Aufgabenobjekt durch den gesamten Lauf und aktualisiere es, statt es an jeder Grenze neu zu generieren. Begrenze zusätzlich die Anzahl der Übergaben. Wenn eine Aufgabe mehr als eine Handvoll Übergaben benötigt, ist die Zerlegung wahrscheinlich zu kompliziert.

Was ist mit Frameworks mit integrierter Übergabe?

Nutze die integrierte Funktion, aber prüfe, was sie tatsächlich überträgt. Viele Frameworks übergeben nur den Nachrichtenverlauf. Dann überleben Identifikatoren nur, wenn sie zufällig im Text vorkommen.

Ergänze deshalb eine strukturierte Nutzlast neben dem Framework-Mechanismus.

Benötigen Unteragenten separate API-Zugangsdaten?

Ja. Zugangsdaten sollten auf die jeweilige Aufgabe zugeschnitten sein. Ein gemeinsam genutzter, mächtiger Schlüssel verhindert sowohl eine wirksame Schadensbegrenzung als auch eine eindeutige Zuordnung von API-Aufrufen.

Wie viel sollte das Feld summary enthalten?

Ein paar Sätze, die Absicht und Nuancen abdecken, die in den strukturierten Feldern fehlen. Sobald die Zusammenfassung IDs oder Beträge auflistet, gehören diese Informationen in validierbare strukturierte Felder.