Die TypeSafe-API aus einem Agenten heraus aufrufen: Anfragestruktur, Fehler, Wiederholungsversuche und Versionsfixierung

Ziel

Einen ersten korrekten Aufruf durchführen, die dokumentierten Fehlerstatus behandeln und Ergebnisse über Modell-Releases hinweg reproduzierbar halten.

Voraussetzungen

Ein API-Schlüssel aus der Anbieter-Konsole (zum Zeitpunkt der Abfassung im Early Access), exportiert als TYPESAFE_API_KEY, den beide offiziellen SDKs standardmässig einlesen. Python: pip install typesafe-sdk oder uv add typesafe-sdk. JavaScript (Node.js 20 oder neuer): npm install @typesafe-ai/sdk. Direktes HTTP funktioniert auch ohne SDK.

Schritte

1. Die Anfrage aufbauen: POST https://api.typesafe.ai/v1/systemone mit Authorization: Bearer <key> und einem JSON-Body mit state (String, Objekt oder Array), model (jev-latest oder eine versionierte ID wie jev-1.13.0) und questions, einer Map von einem selbst gewählten Schlüssel zu einer typisierten Frage (type mit noul, choice oder score, instructions und criteria, sofern der Typ es verlangt).
2. Die Antwort lesen: model (die versionierte ID, die geantwortet hat), answers unter denselben Schlüsseln (ein noul-Wert; oder choice, probabilities und confidence; oder score, legend, probabilities und confidence) sowie usage mit input_tokens und output_tokens. Im Python-SDK sind dieselben Antworten auch über response.nouls[...], response.choices[...] und response.scores[...] erreichbar.
3. Fehler nach Status behandeln: 401 bedeutet einen fehlenden oder ungültigen Schlüssel; 422 bedeutet, dass der Body die Validierung nicht bestanden hat, wobei der Body das betroffene Feld nennt; 429 bedeutet, dass ein Rate-Limit überschritten wurde; 529 bedeutet, dass der Dienst überlastet ist. Die Referenz rät, 429 und 529 mit exponentiellem Backoff zu wiederholen, nie sofort.
4. Bei Verwendung des Python-SDKs dessen Standardwerte kennen: eine RetryPolicy mit zwei Wiederholungen, anfänglichem Backoff von 0,5 s bis zu 5 s mit Jitter, wiederholbaren Status 408, 429 und 5xx, respect_retry_after aktiviert und einem Timeout von 30 s; diese überschreiben, wenn die eigene Frist des Agenten kürzer ist.
5. Innerhalb der dokumentierten Budgets bleiben: 64k Token pro Anfrage, 32k für State plus die längste Frage, höchstens 255 Choice-Optionen und 10 Score-Stufen. Ein Überschreiten führt zu 422, nicht zu einer abgeschnittenen Antwort.
6. Das Modell fixieren, sobald die Schwellenwerte abgestimmt sind: Aliasse verschieben sich bei einem Release; GET /v1/models listet die Aliasse, die das eigene Konto senden kann, und versionierte IDs werden akzeptiert, unabhängig davon, ob sie dort erscheinen.
7. Für einen Coding-Agenten den Skill des Anbieters installieren (<coding-agent> plugin marketplace add typesafe-ai/skills und <coding-agent> plugin install typesafe@typesafe-ai für den Coding-Agenten, npx skills add typesafe-ai/skills --skill typesafe-ai andernorts) und ihn vor der Verwendung aktualisieren; der Anbieter führt erfundene Anfrage- oder Antwortfelder auf einen veralteten Skill zurück.

Erwartetes Ergebnis

Eine Anfrage, die beim ersten Mal validiert wird, ein Client, der bei 429 und 529 zurückweicht, ohne den Endpunkt zu bombardieren, und Protokolle, die das versionierte Modell hinter jeder Entscheidung benennen.

Grenzen und Prüfbasis

Alles oben Genannte ist die Dokumentation des Anbieters mit Stand September 2026; Rate-Limits können sich laut Angabe während des Early Access ohne Vorankündigung ändern, daher 429 als erwartet statt als Ausnahme behandeln. Es wird keine Latenz- oder Genauigkeitsmessung beansprucht.