Transcript Hygiene – Provider-Fixes für stabile LLM-Integrationen

Du kennst das Problem: Dein Code funktioniert lokal einwandfrei, aber sobald du zu einem anderen LLM-Provider wechselst, lehnt die API deine Requests ab. Mal passt die Reihenfolge der Turns nicht, mal sind die Tool-IDs zu lang oder ein Bild-Payload sprengt das Limit. Diese kleinen Formatierungsfehler sind zeitraubend und schwer zu debuggen, besonders wenn sie nur sporadisch nach einem Rate-Limit-Fehler auftreten.

Statt die Sessions manuell zu bereinigen, übernimmt das System diese Arbeit automatisch. Diese “Transcript Hygiene” sorgt dafür, dass die Daten genau so aufbereitet werden, wie der jeweilige Provider sie erwartet, ohne deine originalen Daten auf der Festplatte zu verändern.

Voraussetzungen

• Zugriff auf den Source Code des embedded runners.
• Die Konfigurationsdateien in src/agents/.
• Ein Verständnis der unterstützten Provider (OpenAI, Google, Anthropic, Mistral).

Schnellstart

Die Transcript Hygiene läuft automatisch im embedded runner ab, bevor der Model-Kontext aufgebaut wird. Hier ist der minimale Pfad, um zu verstehen, wo was passiert:

1. Policy Auswahl: In src/agents/transcript-policy.ts wird anhand von provider, modelApi und modelId entschieden, welche Regeln gelten.
2. Anwendung: Die Funktion sanitizeSessionHistory in src/agents/pi-embedded-runner/google.ts führt die eigentliche Bereinigung durch.
3. Bilder: Zu große Bilder werden über sanitizeSessionMessagesImages in src/agents/pi-embedded-helpers/images.ts automatisch herunterskaliert oder rekomprimiert.
4. Tool-Calls: In src/agents/session-transcript-repair.ts werden Assistant-Blocks ohne input oder arguments entfernt.

Wichtig ist: Alle diese Anpassungen passieren in-memory. Deine JSONL-Dateien bleiben unberührt, es sei denn, ein separater Repair-Pass muss defekte Zeilen vor dem Laden komplett entfernen.

Provider-Spezifische Regeln

Jeder Provider hat andere Anforderungen. Hier ist die aktuelle Matrix der Anpassungen:

• Google (Gemini/Antigravity): Erzwingt strikte alphanumerische Tool-IDs und korrigiert die Turn-Reihenfolge (Gemini-style alternation). Wenn die History mit einem Assistant-Turn beginnt, wird ein kleiner User-Bootstrap vorangestellt.
• Anthropic & Minimax: Repariert Tool-Result-Pairings und führt aufeinanderfolgende User-Turns zusammen, um die strikte Abfolge einzuhalten.
• Mistral: Kürzt Tool-IDs auf eine exakte Länge von 9 Zeichen (alphanumerisch).
• OpenRouter Gemini: Entfernt thought_signature Werte, die kein Base64-Format haben.
• OpenAI: Hier wird das “No-Touch”-Prinzip verfolgt. Außer der Bild-Sanitization werden lediglich verwaiste Reasoning-Signatures beim Modell-Wechsel entfernt.

Fehlerbehebung

Wenn eine Session-Datei beschädigt ist, greifen folgende Mechanismen:

• Malformed JSONL: Die Funktion repairSessionFileIfNeeded in src/agents/session-file-repair.ts löscht ungültige Zeilen vor dem Laden. Eine Backup-Datei wird automatisch neben der Session-Datei erstellt.
• Provider Rejections: Falls ein Provider einen Request wegen Tool-IDs ablehnt, prüfe in src/agents/transcript-policy.ts, ob der Provider korrekt erkannt wird.
• Fehlende Tool-Inputs: Wenn Tool-Calls nach einem Abbruch keine Argumente enthalten, werden sie automatisch gedroppt, um API-Fehler zu vermeiden.
• Oversized Images: Wenn Bilder zu groß sind, schau in src/agents/tool-images.ts nach der Implementierung der sanitizeContentBlocksImages.

Du hast Fragen zu einem speziellen Setup? Nutze den AI Setup Assistant für direkte Hilfe.

Nächste Schritte

• /reference/session-management-compaction
• src/agents/transcript-policy.ts