Warum kommt ein AI Agent nicht ohne JSON aus? Vollständige Datenflussanalyse von Tool Calling, Function Calling bis MCP

Symptom: Ihr Agent erzeugt gültiges JSON, ruft aber das falsche Tool auf, verliert die Zuordnung zum Ergebnis oder liefert MCP-Daten, die der nächste Dienst nicht verarbeiten kann.
Schnellste Lösung: Prüfen Sie nicht nur die JSON-Syntax, sondern nacheinander Schema, Tool-Auswahl, Berechtigung, Aufruf-ID, Protokollantwort und fachliche Validierung.

Für wen lohnt sich diese Analyse?

Dieser Beitrag ist für Sie relevant, wenn Sie als Agent-Entwickler die Rolle von JSON innerhalb einer Tool-Kette verstehen müssen. Auch für Fehleranalyse- und Betriebsteams ist er gedacht, wenn Parameter, Nachrichtenstatus oder MCP-Ergebnisse sporadisch fehlschlagen.

Plattformarchitekten erhalten außerdem ein Modell für einheitliche Ereignisprotokolle, Schema-Versionen und reproduzierbare Tests. Wenn Sie lediglich eine einzelne fehlerhafte Endausgabe reparieren möchten, ist eine Anleitung zur Fehlersuche bei ungültigem Agent-JSON möglicherweise der kürzere Einstieg.

Ein AI Agent nutzt JSON jedoch nicht, weil JSON die eigentliche Schlussfolgerung erzeugt. JSON ist die maschinenlesbare Übergabeform zwischen Modell, Orchestrator, Tool, API und Geschäftssystem. Ein stabiler AI Agent JSON Datenfluss prüft deshalb mindestens fünf getrennte Zustände:

Ist die Nachricht syntaktisch gültig?
Entspricht sie dem erwarteten JSON Schema?
Wurde das richtige Tool für den Kontext ausgewählt?
Darf der Aufruf tatsächlich ausgeführt werden?
Kann das Ergebnis über ID, Verlauf und Ausgabeformat wieder korrekt zugeordnet werden?

Wer nur JSON.parse() erfolgreich ausführt, hat höchstens die erste Schicht geprüft.

Der Datenfluss beginnt nicht beim API-Aufruf

Ein typischer Fehlerfall sieht zunächst harmlos aus: Der Benutzer bittet den Agenten, den Status eines Builds zu prüfen. Das Modell erzeugt einen Tool-Aufruf mit einem Namen und einem JSON-Objekt als Parametern. Der Orchestrator akzeptiert die Nachricht, führt den Dienst aus und erhält eine Antwort. Trotzdem endet der Dialog mit „Der Status konnte nicht ermittelt werden“.

Die Ursache kann an mehreren Stellen liegen:

Das JSON ist syntaktisch korrekt, aber ein Pflichtfeld fehlt.
Das Modell wählt ein ähnliches, jedoch fachlich falsches Tool.
Der API-Schlüssel ist gültig, besitzt aber keine Berechtigung für die Ressource.
Die Antwort wird mit einer anderen call_id in den Gesprächsverlauf geschrieben.
Das Tool liefert structuredContent, der Client erwartet aber ausschließlich Text.
Das Ergebnis ist technisch korrekt, enthält jedoch eine veraltete oder nicht mehr aktive Ressource.

Die Verantwortung darf deshalb nicht pauschal dem Modell zugeschoben werden. Das Modell generiert eine beabsichtigte Aktion. Die Anwendung entscheidet, ob sie diese Aktion akzeptiert und ausführt. Das Protokoll transportiert Nachrichten. Die Geschäftslogik entscheidet, ob das Resultat fachlich verwendbar ist.

Achtung: Ein engeres Feldschema löst keinen Fehler bei falscher Tool-Auswahl. Wenn der Agent das falsche Werkzeug auswählt, müssen Sie Beschreibung, Namen, Kandidatenmenge und Kontext verbessern.

Die vier Verantwortungsgrenzen

Für die Praxis hilft diese Zuordnung:

Modell: erzeugt Tool-Namen, Argumente und gegebenenfalls die nächste Antwort.
Orchestrator: validiert, begrenzt, protokolliert und entscheidet über die Ausführung.
Tool oder API-Adapter: führt die Aktion aus und meldet Erfolg oder Fehler strukturiert zurück.
Geschäftssystem: prüft Ressourcenstatus, fachliche Regeln und Folgewirkungen.

Diese Trennung ist für Tool Calling und Function Calling entscheidend. Die offiziellen Funktionsaufruf-Abläufe beschreiben ausdrücklich, dass das Modell nicht selbst den Funktionscode ausführt. Die Anwendung muss Namen und Argumente extrahieren, die Funktion ausführen und das Ergebnis anschließend wieder an das Modell senden. Offizielle Dokumentation zum Function Calling Außerdem beschreibt die offizielle Anleitung zu Tool-Aufrufen denselben Verantwortungsübergang zwischen Modell und Anwendung.

Warum bleibt ein Agent trotz gültigem JSON erfolglos?

1. Syntax gültig, Schema nicht erfüllt

JSON-Syntax beantwortet nur die Frage, ob sich eine Nachricht technisch lesen lässt. Ein Objekt wie dieses ist syntaktisch gültig:

{
  "project": "build-42",
  "retry": "yes"
}

Es kann dennoch gegen das erwartete Schema verstoßen, wenn retry ein Boolean sein muss oder das Pflichtfeld environment fehlt. Auch zusätzliche Felder können problematisch sein, wenn der Adapter unbekannte Eigenschaften ablehnt oder sie stillschweigend ignoriert.

JSON Schema beschreibt Datentypen, Pflichtfelder und weitere Einschränkungen. Die offizielle Referenz unterscheidet deshalb klar zwischen einem JSON-Dokument und einem Schema, das Struktur und zulässige Werte festlegt. Grundlagen von JSON Schema

Für die Fehlerdiagnose sollten Sie drei Ergebnisse getrennt protokollieren:

syntax_valid: Kann der Parser die Nachricht lesen?
schema_valid: Entspricht die Nachricht dem vereinbarten Schema?
schema_errors: Welche Pfade und Regeln wurden verletzt?

Ein Plattformvergleich ist nur sinnvoll, wenn Sie die jeweiligen Schema-Einschränkungen berücksichtigen. Tool Calling, Function Calling und MCP verwenden ähnliche Konzepte, aber nicht automatisch identische Feldnamen, Dialekte oder unterstützte Schema-Untergruppen. Ein Schema, das in einer Umgebung akzeptiert wird, muss daher nicht unverändert in einer anderen funktionieren.

Die aktuelle JSON-Schema-Spezifikation ist 2020-12. Trotzdem hängt die tatsächlich nutzbare Teilmenge vom jeweiligen SDK, Modell-Endpoint und Validierer ab. Offizielle JSON-Schema-Spezifikation

2. Schema erfüllt, Tool falsch gewählt

Nehmen wir an, das Modell sendet:

{
  "repository": "mobile-app",
  "branch": "main"
}

Das Objekt kann vollständig gültig sein. Wenn es aber an get_deployment_logs statt an get_build_status gesendet wird, hilft die perfekte Typprüfung nicht weiter.

Verbessern Sie in diesem Fall nicht zuerst die Feldtypen. Prüfen Sie stattdessen:

Sind die Tool-Namen eindeutig und handlungsorientiert?
Beschreibt die Dokumentation den Anwendungsfall oder nur die interne Implementierung?
Werden ähnliche Tools gleichzeitig angeboten?
Enthält der Kontext die Ressource, Umgebung und gewünschte Aktion?
Gibt es eine erlaubte Kandidatenliste statt eines unbeschränkten Werkzeugkatalogs?

Eine Beschreibung wie „Verarbeitet Projektdaten“ ist für ein Modell zu unscharf. Besser ist: „Liest den zuletzt abgeschlossenen Build eines Projekts. Startet keinen neuen Build und verändert keine Daten.“ Solche Grenzen reduzieren Mehrdeutigkeit und machen spätere Berechtigungsentscheidungen nachvollziehbarer.

3. Parameter korrekt, API-Ausführung abgelehnt

Wenn Name und Parameter stimmen, verschiebt sich die Fehlersuche in die Ausführungsschicht. Häufige Ursachen sind:

fehlende oder abgelaufene Authentifizierung,
gültige Identität ohne erforderliche Berechtigung,
gesperrte oder gelöschte Ressource,
falsche Umgebung,
Netzwerk- oder DNS-Fehler,
Rate-Limit oder temporäre Dienststörung,
fachliche Regel, etwa ein bereits abgeschlossener Vorgang.

Der Tool-Adapter sollte niemals nur null, eine leere Zeichenkette oder einen allgemeinen HTTP-Fehler an das Modell zurückgeben. Er benötigt eine strukturierte Fehlerantwort mit mindestens einer stabilen Fehlerklasse, einer menschenlesbaren Erklärung und einer Information darüber, ob ein erneuter Versuch zulässig ist.

Beispiel:

{
  "ok": false,
  "error": {
    "code": "permission_denied",
    "message": "Die Ressource ist vorhanden, aber für diese Identität nicht freigegeben.",
    "retryable": false
  }
}

Das Modell kann mit einer solchen Antwort sinnvoll reagieren: Es kann eine fehlende Freigabe melden, statt einen nicht existierenden Build zu erfinden. Bei Datenschutz und DSGVO sollten Sie außerdem vermeiden, geheime Token, vollständige Authorization-Header oder personenbezogene Antwortdaten in den Agentenverlauf zu schreiben. Hinweise zum Umgang mit Daten und Protokollen finden Sie in der Datenschutzerklärung von Kvmzen.

4. Ausführung erfolgreich, Zuordnung verloren

Der Aufruf-ID-Fehler ist besonders schwer zu erkennen, weil die API selbst erfolgreich gewesen sein kann. Bei parallelen Tool-Aufrufen darf das Ergebnis nicht nur über Position oder Tool-Namen zugeordnet werden. Verwenden Sie eine stabile ID pro Aufruf und bewahren Sie sie vom Modellereignis bis zur Ergebnisnachricht auf.

Ein sicherer Ereignissatz enthält beispielsweise:

{
  "conversation_id": "conversation-abc",
  "interaction_id": "interaction-17",
  "tool_call_id": "call-93",
  "tool_name": "get_build_status",
  "schema_version": "build-status.v3",
  "status": "executed"
}

Die konkrete Benennung unterscheidet sich je nach Plattform. Übernehmen Sie daher nicht blind call_id, tool_call_id, id oder toolUseId aus einer fremden Dokumentation. Semantisch erfüllen diese Felder eine ähnliche Aufgabe, sind aber nicht austauschbar.

Fehlt die Zuordnung, entstehen typische Folgeschäden:

Ein Ergebnis wird dem falschen Tool-Aufruf zugeordnet.
Ein bereits ausgeführter Vorgang wird erneut gestartet.
Der Agent wartet auf ein Resultat, das im Verlauf nicht existiert.
Eine Schleife bricht ab, weil die vorherige Interaktion nicht fortgesetzt werden kann.
Bei parallelen Aufrufen werden Ergebnisse in zufälliger Reihenfolge verarbeitet.

Bei zustandslosen Interaktionen muss der Client den vollständigen relevanten Verlauf erneut übergeben. Die offizielle Dokumentation weist dabei ausdrücklich auf die Notwendigkeit hin, die vom Modell erzeugten Schritte und das Function Result vollständig zu erhalten.

Wie gibt MCP ein Tool-Ergebnis zurück?

Das Model Context Protocol trennt zwischen unstrukturiertem Inhalt und strukturierten Ergebnissen. Ein Tool-Ergebnis kann Text, Bilder, Ressourcenlinks oder andere Inhaltsblöcke in content enthalten. Zusätzlich kann structuredContent ein maschinenlesbares Ergebnis tragen. Ein optionales outputSchema beschreibt dabei die erwartete Form dieses strukturierten Inhalts. MCP-Spezifikation für Tools und Ergebnisse

Ein kompatibles Ergebnis kann beispielsweise so aussehen:

{
  "content": [
    {
      "type": "text",
      "text": "{\"status\":\"passed\",\"duration_seconds\":84}"
    }
  ],
  "structuredContent": {
    "status": "passed",
    "duration_seconds": 84
  },
  "isError": false
}

Der Textanteil ist nicht bloß Dekoration. Die MCP-Dokumentation empfiehlt bei strukturierten Ergebnissen zusätzlich serialisierten JSON-Text, damit auch ältere oder eingeschränkte Clients die Antwort verarbeiten können. Der Client sollte structuredContent validieren, aber nicht voraussetzen, dass jeder Verbraucher dieselben Felder unterstützt.

Wenn die Tool-Ausführung selbst scheitert, gehört der Fehler in das Ergebnisobjekt und sollte als isError: true gekennzeichnet werden. Ein Protokollfehler ist dagegen für Fälle reserviert, in denen das Tool nicht gefunden wird, die Serverfunktion fehlt oder die Nachricht grundsätzlich nicht verarbeitet werden kann. Diese Unterscheidung entscheidet darüber, ob das Modell den Fehler sehen und sinnvoll korrigieren kann.

Warum kann ein MCP-Ergebnis für den Downstream trotzdem unbrauchbar sein?

Ein Client kann structuredContent ignorieren und ausschließlich content lesen. Ein anderer kann nur eine bestimmte Objektform akzeptieren. Ein dritter validiert gegen outputSchema und lehnt zusätzliche oder fehlende Felder ab.

Prüfen Sie deshalb:

Wird outputSchema zusammen mit dem Tool veröffentlicht?
Entspricht structuredContent exakt diesem Schema?
Ist content als kompatible Textdarstellung vorhanden?
Wird isError korrekt gesetzt?
Bleiben _meta-Informationen erhalten, wenn der nächste Verarbeitungsschritt sie benötigt?
Ist die Schema-Version im Ereignisprotokoll sichtbar?

Für ein Mac-basiertes Agent-System kommt eine weitere Grenze hinzu: Das Tool kann zwar korrekt antworten, während die zugrunde liegende macOS-Umgebung nicht den erwarteten Zustand besitzt. Fehlende Zugriffsrechte, ein nicht laufender Dienst, eine andere Arbeitsverzeichnisstruktur oder eine abweichende Version eines Kommandozeilenwerkzeugs erscheinen dann zunächst als JSON-Problem, sind aber Betriebsprobleme.

Ein einheitliches Fehlerprotokoll für den AI Agent JSON Datenfluss

Wenn Sie jede Schicht mit einer eigenen Ereignisart erfassen, wird die Ursache eines Fehlers deutlich schneller sichtbar. Speichern Sie pro Aufruf mindestens:

Eingangsereignis mit Gesprächs- und Interaktions-ID.
Modellentscheidung mit Tool-Name und Argumenten.
Schema-ID oder Schema-Version.
Validierungsergebnis einschließlich Fehlerpfad.
Berechtigungsentscheidung ohne geheime Zugangsdaten.
Beginn und Ende der Ausführung.
API- oder Tool-Ergebnis mit Fehlerklasse.
Zuordnung von Aufruf-ID und Ergebnis-ID.
MCP-Felder wie content, structuredContent und isError, sofern verwendet.
Finale fachliche Validierung und Antwortstatus.

Für DSGVO-konforme Protokolle sollten Sie Nutzereingaben minimieren, personenbezogene Werte maskieren und Aufbewahrungsfristen festlegen. Loggen Sie nicht automatisch komplette Prompts oder Tool-Ergebnisse, wenn diese Kundendaten, Tokens oder interne Quelltexte enthalten. Eine getrennte technische Ereignis-ID reicht oft aus, um einen Fehler reproduzierbar zu untersuchen.

Für längere Agent-Läufe empfiehlt sich außerdem eine Korrelation zwischen Agent-Ereignis und Ausführungsumgebung. Bei Abhängigkeiten von macOS-Tools sollten Sie Betriebssystemzustand, installierte Tool-Versionen, Benutzerrechte und Netzwerkpfad getrennt vom eigentlichen Modellereignis erfassen. So erkennen Sie, ob ein Fehler bei der Datenübergabe oder erst auf dem Remote-System entstanden ist.

So reproduzieren Sie die vier wichtigsten Fehlerklassen

Arbeiten Sie die folgenden Schritte in einer isolierten Testumgebung ab:

Schemafehler erzeugen: Entfernen Sie ein Pflichtfeld, ändern Sie einen Boolean in eine Zeichenkette und fügen Sie ein unerwartetes Feld hinzu. Prüfen Sie, ob jede Variante eine eigene, verständliche Fehlermeldung liefert.
Berechtigung verweigern: Verwenden Sie eine Identität ohne Zugriff auf die Testressource. Der Adapter muss permission_denied oder eine gleichwertige stabile Fehlerklasse zurückgeben, ohne das Modell raten zu lassen.
Aufruf-ID verlieren: Starten Sie mindestens zwei Tool-Aufrufe parallel und vertauschen Sie absichtlich die Ergebniszuordnung. Der Test gilt nur dann als bestanden, wenn der Orchestrator den Fehler erkennt.
MCP-Ergebnis brechen: Entfernen Sie ein im outputSchema erforderliches Feld oder liefern Sie einen falschen Datentyp in structuredContent. Prüfen Sie zusätzlich, ob der Text-Fallback weiterhin vorhanden ist.
Verlauf unterbrechen: Lassen Sie die Resultatnachricht aus oder übergeben Sie nur einen Teil des bisherigen Verlaufs. Der Agent darf daraus keinen erfolgreichen Abschluss ableiten.
Fachliche Prüfung ergänzen: Senden Sie ein technisch gültiges Ergebnis mit einem ungültigen Ressourcenstatus. Die Geschäftslogik muss diesen Zustand unabhängig vom JSON-Parser ablehnen.
Umgebung variieren: Wiederholen Sie denselben Aufruf mit unterschiedlichem Arbeitsverzeichnis, Benutzerrecht oder macOS-Dienststatus. Damit trennen Sie Protokollfehler von Infrastrukturfehlern.

Abnahme-Checkliste für Tool-Aufrufketten

[ ] Syntaxprüfung und Schema-Prüfung erzeugen getrennte Statuswerte.
[ ] Jedes Tool besitzt einen eindeutigen Namen und eine konkrete Beschreibung.
[ ] Die erlaubte Tool-Menge wird je Aufgabe eingeschränkt.
[ ] Berechtigungsentscheidungen werden vor der Ausführung protokolliert.
[ ] Jeder Aufruf erhält eine unveränderliche Korrelation-ID.
[ ] Parallele Ergebnisse werden nicht über Listenpositionen zugeordnet.
[ ] Ausführungsfehler werden strukturiert und ohne Geheimnisse zurückgegeben.
[ ] structuredContent wird gegen outputSchema validiert.
[ ] MCP-Ergebnisse enthalten für kompatible Clients einen Text-Fallback.
[ ] Schema-Version, Tool-Version und Umgebungsstatus sind im Log auffindbar.
[ ] Wiederholungen sind bei nicht idempotenten Aktionen gesperrt oder abgesichert.
[ ] Testdaten und Produktionsdaten bleiben getrennt.
[ ] DSGVO-relevante Werte werden vor der Speicherung maskiert.
[ ] Ein vollständiger Verlauf kann für einen fehlgeschlagenen Aufruf rekonstruiert werden.

Ein gutes Abnahmekriterium lautet nicht „Der Agent antwortet meistens richtig“. Es lautet: „Für jede Fehlerklasse kann das Team anhand eines Ereignisses bestimmen, welche Schicht verantwortlich ist und ob eine Wiederholung sicher ist.“

Aktuelle Umgebung oder gemieteter Mac für die Reproduktion?

Wenn Sie diese Fehler nur auf einem einzelnen Entwicklergerät reproduzieren, bleiben mehrere Nachteile bestehen: Abhängigkeiten verändern sich unbemerkt, lokale Berechtigungen unterscheiden sich, und ein beschädigter macOS-Dienst kann die Ursache verdecken. Eine gemeinsam nutzbare Cloud-Umgebung ist zwar flexibel, bringt aber oft zusätzliche Netzwerkpfade, wechselnde Laufzeitbedingungen und schwerer kontrollierbare Zugriffsebenen mit sich.

Für kurzfristige Tests, reproduzierbare macOS-Toolketten und die Prüfung von Agenten, die echte Apple-Umgebungen benötigen, kann das Mieten eines Mac über Kvmzen die sauberere Zwischenlösung sein. Sie erhalten dabei eine getrennte Umgebung, können Abhängigkeiten und Logs gezielt festhalten und den Fehlerfall von Ihrem lokalen Rechner entkoppeln. Prüfen Sie vorab, ob Sie physische Anschlüsse, dauerhaft hohe Last oder eine langfristig unveränderte Einzelumgebung benötigen; in diesen Fällen kann ein eigener Mac wirtschaftlich und organisatorisch sinnvoller sein. Für temporäre Reproduktionen und parallele Testumgebungen ist eine Mac-Mietumgebung für Entwicklungs- und Agententests dagegen meist leichter in einen bestehenden Prüfprozess einzubinden.

Wenn Sie vor der Entscheidung die verfügbaren Standorte, Zugriffswege und Datenschutzanforderungen prüfen möchten, beginnen Sie mit der Übersicht der Mac-Mietoptionen. Entscheidend ist nicht, dass JSON überall vorkommt, sondern dass jede Übergabe einen überprüfbaren Vertrag besitzt: Schema, Berechtigung, Aufruf-ID, Ergebnisform und fachliche Bedeutung müssen zusammenpassen.