Server-Tools
Server-Tools sind Fähigkeiten, die Synthorai innerhalb einer einzigen Anfrage für Sie ausführt: Das Modell fordert etwas an, wir erledigen die Arbeit, und das Ergebnis kommt in derselben Antwort zurück. Sie fügen tools einen Eintrag hinzu — kein zweiter Endpoint, kein Callback zu implementieren.
Verfügbare Tools
Jedes Server-Tool trägt das Präfix synthorai: und kollidiert daher nie mit Ihren eigenen Tool-Namen:
| Parameter | Beschreibung | Preis |
|---|---|---|
synthorai:web_search | Das Web durchsuchen und die Ergebnisse lesen. | $0.01 |
synthorai:web_fetch | Den Volltext einer Seite lesen, deren URL Sie bereits haben. | $0.01 |
Der gemeinsame Vertrag
Jedes Server-Tool verhält sich gleich — was Sie bei einem lernen, gilt beim nächsten:
- Nur Opt-in. Nichts läuft, solange Sie das Tool nicht in
toolsaufnehmen. Eine Anfrage ohne ist eine gewöhnliche Anfrage. - Ein einziger Roundtrip. Die Tool-Schleife fahren wir für Sie; Sie erhalten eine einzelne Antwort, in der Tool-Aktivität und Ergebnis bereits enthalten sind.
- Ihre eigenen Tools funktionieren weiter. Server-Tools und Ihre Function-Tools können zusammen deklariert werden — ruft das Modell eines Ihrer Tools auf, geben wir mit einem ehrlichen
stop_reason: tool_usedie Kontrolle zurück. (Eine Ausnahme: die von uns injizierten Tool-Namen sind reserviert — siehe unten.) - Preis pro Aufruf, sichtbar in usage. Zähler landen in
usage.server_tool_use, der Betrag inusage.cost— jede Anfrage lässt sich mit ihrer Rechnung abgleichen. max_usesist eine echte Obergrenze. Sie begrenzt, was eine einzelne Anfrage ausgeben kann, und hält über interne Wiederholungen hinweg.
Tokens sind die andere Hälfte der Kosten
Die Gebühr pro Aufruf ist nur ein Teil der Anfragekosten. Was das Tool zurückbringt — Suchtreffer, Seitentext — geht als Eingabe-Tokens in die Unterhaltung ein und wird zum normalen Modelltarif berechnet. Bei langen Seiten ist dieser Token-Anteil meist die größere Zahl. Und weil das Gateway die Tool-Schleife intern fährt, ist usage.input_tokens die Summe über alle internen Züge — deutlich größer als Ihr gesendeter Prompt. Das sind die echten Kosten der Rückführung von Ergebnissen ans Modell, keine Doppelberechnung.
Die Unterhaltung fortsetzen
Hängen Sie die Assistant-Nachricht exakt so, wie Sie sie erhalten haben, samt Tool-Blöcken wieder an messages an. Deklarieren Sie dasselbe Server-Tool auch in Folgeanfragen, damit die Historie in ihrer reichsten Form bleibt; lassen Sie das Tool weg, werden frühere Tool-Ergebnisse zu reinem Text abgeflacht — das Modell sieht den Inhalt weiterhin.
Reservierte Tool-Namen
Solange Sie einen synthorai:-Parameter verwenden, ist der zugehörige nackte Name reserviert: Ein eigenes Tool namens web_search neben synthorai:web_search (oder web_fetch neben synthorai:web_fetch) zu deklarieren, liefert ein 400, das das Tool benennt. Benennen Sie Ihres um oder lassen Sie den synthorai:-Parameter weg.
Der Grund: Wir injizieren das Server-Tool unter genau diesem Namen. Zwei Tools kämen mit einem Namen beim Modell an, und niemand könnte sagen, wessen Aufruf zurückkommt — die Argumente Ihres Tools könnten an unseren Suchanbieter gehen, Ihr Aufruf könnte verloren gehen. Die Anfrage abzulehnen ist die einzig ehrliche Antwort. Ein eigenes Tool unter einem der Namen ohne den passenden synthorai:-Parameter zu deklarieren, bleibt unberührt: Wir injizieren nichts, also kollidiert nichts.
Fehlschläge werden nicht berechnet
Die Gebühr pro Aufruf gilt für Aufrufe, die ein Ergebnis geliefert haben. Ein Aufruf, den wir ablehnen, bevor er unser Netz verlässt — abgelehnte URL, blockierte Domain, nicht konfiguriertes Backend — kostet nichts. Ein Aufruf, der den Anbieter erreichte und dort scheiterte, wird berechnet, weil der Anbieter uns berechnet hat. In beiden Fällen zählt die Runde gegen Ihr max_uses-Budget — ein Modell, das eine kaputte URL wiederholt, kann nicht gratis in Schleife gehen.
Unterstützte Endpoints
Server-Tools laufen auf /v1/messages, /v1/chat/completions und /v1/responses. Ein synthorai:-Parameter an einen Endpoint, der sie nicht unterstützt — einen Gemini-Endpoint —, liefert ein 400, das genau das sagt. Wir lehnen lieber ab, als ein unbekanntes Tool stromaufwärts weiterzureichen: bestenfalls ein verwirrender Drittanbieterfehler, schlimmstenfalls wird es still ignoriert, die Suche findet nie statt, und Sie zahlen für eine normale Anfrage, die leise weniger tat als verlangt.
Verfügbarkeit
Server-Tools werden pro API-Schlüssel aktiviert. Ist ein Tool für Ihren Schlüssel nicht aktiviert, erhalten Sie ein explizites 400, das es benennt — statt eines stillschweigend ignorierten Parameters. Kontaktieren Sie uns zur Freischaltung.