SDKs

Jedes SDK erfasst KI-Agenten-Aktivität in-process und liefert sie an die Ledger API aus, sodass Ihr Agenten-Code ansonsten unverändert bleibt. Sie folgen alle demselben Vertrag, unabhängig von der Sprache:

• Beobachten, nie vermitteln — nichts hier sitzt in einem Request-Pfad.
• Nie blockieren — das Erfassen eines Events ist ein synchroner Buffer-Push; die Zustellung erfolgt asynchron per Timer. (Die eine bewusste Ausnahme ist der Upload von Binärinhalten — siehe Blobs unten.)
• Nie den Host zum Absturz bringen — jeder öffentliche Einstiegspunkt ist exception-safe; Fehler gehen an einen on_error-Callback, statt sich zu propagieren.
• Nie stillschweigend verlieren — wenn der Buffer überläuft, wird der Drop gezählt und, sobald die Zustellung sich erholt, als Lifecycle-Event gemeldet.
• Wortgetreu erfassen — keine Normalisierung, keine Redaktion. Der Server berechnet jeden Hash; das SDK meldet nur, was geschehen ist.

Sprachstatus

!NOTE Keines davon ist bisher in einer Paket-Registry veröffentlicht (npm, PyPI, Maven, NuGet) — das ist eine Launch-Gate-Entscheidung, die noch aussteht. Jede Sprachseite unten beschreibt, wie Sie das SDK derzeit einbinden.

Für OTel-instrumentierte Apps in Go, Java oder C# richten Sie Ihren bestehenden Exporter auf den OTLP-Receiver des Ledgers (/v1/otlp/v1/traces), statt einen sprachspezifischen Span-Prozessor zu suchen — jede gen_ai.*-Span wird automatisch, serverseitig, zu einem Ledger-Event.

Kernkonzepte

Diese gelten für jede Sprache:

• endpoint — die Basis-URL der Ledger API (http://127.0.0.1:4010 für einen lokalen Entwicklungs-Stack — siehe Hosting mit Docker).
• ingest_key — ein Key pro Team; die Mandantenzuordnung wird serverseitig daraus aufgelöst. Einen erhalten Sie über npm run seed:demo (Entwicklung, gibt einen Demo-Key aus) oder über das Dashboard, sobald Sie eine echte Organisation eingerichtet haben.
• agent_id — eine URI, die das handelnde KI-System benennt, z. B. urn:agent:research-assistant.
• record(...) — erfasst eine KI-Aktion: einen LLM-Aufruf, Tool-Aufruf, eine Suche oder ein Daten-Read/-Write. Synchron und nicht blockierend; gibt eine Span-ID zurück.
• flush() — liefert gepufferte Events sofort aus. Läuft ebenfalls automatisch per Timer (standardmäßig alle 2 s).
• Idempotenz — jedes Event trägt einen Idempotenz-Key (seine Span-ID); der Server dedupliziert auf (org, span_id), sodass Wiederholungen nach einer fehlgeschlagenen Zustellung immer sicher sind.

Felder von record()

Entscheidungs-Lineage

Jedes Event kann über parent_ref (eine Span-ID) auf das Event verweisen, das es verursacht hat, sodass eine Kette wie Suche → LLM-Aufruf, der sie verwendet hat → Tool-Aufruf, der auf dem Ergebnis gehandelt hat rekonstruierbar ist. Jedes SDK bietet außerdem einen ambienten "current span"-Helfer (within() / with()), sodass verschachtelte Aufrufe den richtigen Parent automatisch erben, ohne eine ID von Hand durch jede Funktionssignatur reichen zu müssen.

Blobs

Binärinhalte (Bilder, PDFs, Audio) können nicht als Text inline in record() mitfahren. Laden Sie sie zuerst hoch — dies ist der einzige Aufruf in jedem SDK, der blockiert, da der Blob serverseitig existieren muss, bevor ein Event darauf verweisen kann — und übergeben Sie dann die zurückgegebene Blob-ID als blob_ref eines Payloads oder Retrievals. Uploads sind content-addressed: Das erneute Hochladen identischer Bytes gibt dieselbe Blob-ID zurück.

Zustellungsgarantien

Die Zustellung erfolgt at-least-once. Ein fehlgeschlagener Flush (Netzwerkfehler, 5xx, 429) belässt den Batch gepuffert für den nächsten Timer-Tick — bei einem vorübergehenden Fehler geht nichts verloren. Ein 401 bedeutet, dass der Ingest-Key falsch ist; das wird über on_error gemeldet, und der Batch bleibt gepuffert, statt verworfen zu werden. Wenn der Buffer selbst voll läuft (Standard-Obergrenze: 10.000 Events), werden die ältesten Events verworfen, um Platz zu schaffen — dieser Drop ist jedoch nie stillschweigend: Ein gezähltes Lücken-lifecycle-Event wird vor dem nächsten Batch versiegelt, sodass die Lücke selbst Teil des Audit-Trails ist.