Einführung

Was ist Multi-Agenten-Orchestrierung?

Ein einzelnes LLM kann Text generieren, Fragen beantworten und Code schreiben. Aber für strukturierte API-Interaktion — Dokument lesen, Daten extrahieren, Schema befüllen, HTTP-Call absetzen — braucht es mehrere spezialisierte Agenten, die arbeitsteilig zusammenwirken.

Multi-Agenten-Orchestrierung bedeutet: Jeder Agent hat genau eine Aufgabe, kennt nur seinen Verantwortungsbereich und kommuniziert über klar definierte Datenkontrakte. Das Ergebnis ist ein System, das modular, testbar und für beliebige APIs wiederverwendbar ist.

In diesem Artikel beschreiben wir ein bewährtes 3+1 Pattern: drei KI-Agenten (Operator, Extractor, Mapper) plus ein generischer HTTP-Client, der den eigentlichen API-Call ausführt.

Agent-Pipeline

Das 3+1 Agenten-Pattern

Vom User-Intent bis zum ausgeführten API-Call durchlaufen die Daten vier Stufen. Jede Stufe hat einen klaren Auftrag und liefert ein definiertes Ergebnis an die nächste.

Agent 1 · Operator
Intent Router
Erkennt den User-Intent und wählt die passende API-Operation aus der OpenAPI-Spec.
  • Parst die OpenAPI-Spec (Paths, Operations, Schemas)
  • Erkennt Intent via Tool-Use / Function Calling
  • Selektiert passende Operation (POST /orders, PUT /invoices…)
  • Orchestriert die Sub-Agenten mit klaren Aufträgen
↓ User Intent OpenAPI Spec → Operation + Schema
Schema + Extraktionsauftrag
Agent 2 · Extractor
Document Parser
Extrahiert strukturierte Rohdaten aus PDFs, Bildern oder Dokumenten. Keine Kenntnis der API — reine Datenextraktion.
  • Erhält Dokument (Base64) + Liste der zu extrahierenden Felder
  • Gibt Key-Value-Paare mit Confidence-Score zurück
  • Kennzeichnet Felder als confident / uncertain / missing
↓ PDF / Dokument Extraktionsauftrag → Raw JSON
Rohdaten + Body-Schema
Agent 3 · Mapper
Schema Filler
Mappt extrahierte Rohdaten auf das JSON-Schema der API. Transformiert Typen, ergänzt Defaults, validiert gegen die Spec.
  • Name-Matching und Typ-Casting (String → ISO-Date, Float…)
  • Füllt Pflichtfelder, ergänzt Defaults aus der Spec
  • Validiert Output gegen JSON Schema vor Rückgabe
  • Warnung bei fehlenden Pflichtfeldern
↓ Raw JSON JSON Schema → Valid Body
Valides Body-Objekt
Stufe 4 · Executor
HTTP Client
Führt den API-Call aus. Kein API-spezifisches Wissen nötig — Method, Path und Body kommen vollständig von den vorherigen Agenten.
  • Nimmt method, path, headers, body entgegen
  • Auth-Handling (Bearer, API-Key) via Konfiguration
  • Response wird zurück an den Operator gegeben
↓ Method + Path + Body → API Response
Datenkontrakte

Datenkontrakte zwischen Agenten

Klare Interfaces zwischen den Stufen machen das System testbar und austauschbar. Jeder Agent kennt nur seine Ein- und Ausgabe-Spezifikation.

Operator → Extractor

documentbase64 | url
fieldsToExtractstring[]
documentType"pdf" | "image"
hintsRecord<string,string>

Extractor → Mapper

extractedExtractedField[]
confidencenumber (0–1)
missingstring[]
raw_textstring (optional)

Mapper → HTTP Client

bodyRecord<string,unknown>
validboolean
warningsstring[]
auditLogMappingDecision[]

Beispiel: Extractor-Output

// Extractor Response { "extracted": { "customer_name": { value: "Acme GmbH", confidence: 0.97 }, "invoice_date": { value: "2024-03-01", confidence: 0.91 }, "total_amount": { value: "4250.00", confidence: 0.88 }, "vat_id": { value: null, confidence: 0.0, missing: true } } }

Beispiel: Mapper-Output

// Mapper Response → valides Body-Objekt { "body": { "customerName": "Acme GmbH", // mapped + validated "invoiceDate": "2024-03-01", // ISO 8601 cast "amount": 4250.00, // string → float "currency": "EUR", // default from spec "vatId": null // optional, missing }, "warnings": ["vatId missing, field is optional"] }
System-Prompt

System-Prompt Pattern (Operator)

Der Operator-Agent erhält die vollständige OpenAPI-Spec als Kontext. Sein System-Prompt definiert den Ablauf und die Delegation an die Sub-Agenten.

SYSTEM: Du bist ein API-Operator. Dir liegt folgende OpenAPI-Spec vor: {spec_json} ABLAUF: 1. Erkenne den Intent des Users und wähle die passende Operation aus der Spec 2. Rufe select_api_operation(operationId, method, path, bodySchema) auf 3. Beauftrage Extractor: “Extrahiere aus dem Dokument: {required_fields}” 4. Beauftrage Mapper: “Mappe {extractor_output} auf Schema {bodySchema}” 5. Sende den finalen Body via HTTP-Client WICHTIG: Validiere das finale Body-Objekt gegen die Spec bevor du den Call absetzt. Fehlende Pflichtfelder → frage den User nach, sende keinen invaliden Request.

Tool-Definition (Function Calling)

// Operator: Tool-Definition für Intent-Routing tools: [{ "name": "select_api_operation", "description": "Maps user intent to OpenAPI operationId", "input_schema": { "operationId": string, // e.g. "createOrder" "method": string, // POST | PUT | GET "path": string, // /api/v1/orders "bodySchema": object // JSON Schema from spec } }]

HTTP Client (Executor)

// Generic HTTP Client async function executeApiCall({ method, path, body, headers }: ApiCallParams) { const res = await fetch(baseUrl + path, { method, headers: { "Content-Type": "application/json", ...headers }, body: JSON.stringify(body) }); return res.json(); }
Vorteile

Warum 3+1 statt ein einzelner Agent?

  • Austauschbarkeit: Jede REST-API mit OpenAPI-Spec funktioniert — ohne Code-Änderungen an den Agenten.
  • Testbarkeit: Jeder Agent kann isoliert getestet werden — mit festen Ein- und Ausgaben.
  • Wiederverwendbarkeit: Extractor und Mapper sind domänenunabhängig — sie funktionieren für Rechnungen genauso wie für Bestellungen.
  • Erweiterbarkeit: Ein vierter KI-Agent für Validierung oder Review lässt sich nahtlos einfügen.
  • Fehlereingrenzung: Wenn ein Feld falsch extrahiert wird, ist klar ob Extractor oder Mapper verantwortlich ist.
  • Verantwortungstrennung: Jeder Agent hat genau eine Aufgabe — Separation of Concerns auf Agent-Ebene.
FAQ

Häufige Fragen

Brauche ich für jeden Agenten ein eigenes LLM?
Nein. Alle drei KI-Agenten können dasselbe Sprachmodell nutzen — der Unterschied liegt im System-Prompt und den bereitgestellten Tools. In der Praxis verwendet man häufig ein größeres Modell für den Operator (Reasoning) und ein schnelleres für Extractor und Mapper (Structured Output).
Funktioniert das Pattern auch ohne OpenAPI-Spec?
Prinzipiell ja — die OpenAPI-Spec macht es aber deutlich robuster, weil der Operator automatisch die richtige Operation und das Request-Schema findet. Ohne Spec muss das Schema-Wissen manuell in den Prompt eingebaut werden.
Wie gehe ich mit fehlenden Pflichtfeldern um?
Der Mapper erkennt fehlende Pflichtfelder und gibt eine Warnung zurück. Der Operator kann dann den User nach den fehlenden Informationen fragen, statt einen invaliden API-Call abzusetzen. Das ist ein bewusster Design-Entscheid: Kein Agent sendet unvollständige Requests.