Platzhalter in Tool-Args

<PDF:...>, <PDF_CONTENT_AVAILABLE> und wie sie zur Laufzeit aufgelöst werden.

Platzhalter sind Strings, die das Modell wie normalen Text in seine Tool-Argumente schreibt — und die der ToolRunner vor dem eigentlichen Aufruf durch reale Werte ersetzt.

Warum: das Modell soll große Inhalte (PDF-Volltexte, Session-Daten) nicht selbst durch den Chat tragen. Das würde Tokens verschwenden und jede Antwort langsamer machen.

#<PDF:key>

Verweist auf ein hochgeladenes PDF im aktuellen Chat. Beim Upload bekommt jedes PDF einen eindeutigen Key. Das Modell sieht den Platzhalter, nie den Inhalt.

Beispiel-Flow:

1. Benutzer lädt rechnung.pdf hoch.
2. Server extrahiert Text, speichert ihn mit Key pdf-9f2a in der DB.
3. Das Modell sieht im Chat: „Hier ist die Rechnung: <PDF:pdf-9f2a>".
4. Modell ruft Tool classifyInvoice mit Argument {"text": "<PDF:pdf-9f2a>"}.
5. ToolRunner erkennt den Platzhalter, ersetzt ihn durch den echten PDF-Text.
6. Das Tool bekommt die vollen Daten, ohne dass sie im Chat standen.

#<PDF_CONTENT_AVAILABLE>

Legacy-Platzhalter ohne Key. Wird ersetzt durch den Inhalt des zuletzt hochgeladenen PDFs im Chat. Nützlich in alten Prompts, bei neuen Tools nutze lieber <PDF:key> — das ist spezifischer und bricht nicht, sobald ein zweites PDF dazukommt.

#Auflösungs-Reihenfolge

Wenn ein Tool aufgerufen wird:

1. ToolRunner.runTool bekommt die Args.
2. resolvePlaceholders() scannt alle String-Werte rekursiv.
3. Für jeden Treffer: Lookup in der PDF-Cache der aktuellen Session.
4. Ersetzter Wert wird an preprocess / API-Call / handler weitergereicht.

Die Ersetzung passiert nur in Tool-Args — nicht im Prompt, nicht in der Antwort.

#Platzhalter in System-Prompts

Parallel dazu gibt es Platzhalter, die in System-Prompts ausgewertet werden (siehe System-Prompts):

Syntax: doppelte geschweifte Klammern, nicht spitze wie bei PDF-Placeholdern. Das ist bewusst — so kannst du nicht versehentlich einen Prompt-Platzhalter in Tool-Args verwenden oder umgekehrt.

#Eigene Platzhalter?

Aktuell nicht offiziell erweiterbar. Wenn du wiederkehrende Logik brauchst, baue das lieber als preprocess-Funktion in jedes betroffene Tool — dort hast du vollen PHP-Zugriff auf Session, Tenant-Config und vorherige Nachrichten.

#Debugging

Wenn ein Tool leere oder falsche Inhalte bekommt, wo du einen Platzhalter erwartest:

• Log prüfen: der ToolRunner loggt bei jeder Platzhalter-Ersetzung (Treffer oder Miss).
• chat_id korrekt? Platzhalter können nur aufgelöst werden, wenn der PDF im selben Chat hochgeladen wurde.
• Key-Schreibweise? Groß-/Kleinschreibung zählt.