SDKs

Chaque SDK capture l'activité des agents IA directement dans le processus et la transmet à l'API du registre, de sorte que le code de votre agent reste par ailleurs inchangé. Ils suivent tous le même contrat, quel que soit le langage :

• Observer, jamais s'interposer — rien ici ne se trouve dans un chemin de requête.
• Ne jamais bloquer — capturer un événement consiste en un push synchrone dans un tampon ; la livraison se fait de manière asynchrone sur une minuterie. (La seule exception délibérée est l'envoi de contenu binaire — voir Blobs ci-dessous.)
• Ne jamais faire planter l'hôte — chaque point d'entrée public est sûr vis-à-vis des exceptions ; les échecs sont dirigés vers un callback on_error plutôt que de se propager.
• Ne jamais perdre silencieusement — si le tampon déborde, la perte est comptabilisée et signalée sous forme d'événement de cycle de vie une fois la livraison rétablie.
• Capturer tel quel — aucune normalisation, aucune rédaction. Le serveur calcule chaque hash ; le SDK ne fait que rapporter ce qui s'est passé.

État des langages

!NOTE Aucun de ces SDK n'est encore publié sur un registre de paquets (npm, PyPI, Maven, NuGet) — c'est une décision de blocage de lancement encore en attente. Chaque page de langage ci-dessous explique comment intégrer le SDK tel qu'il se présente aujourd'hui.

Pour les applications instrumentées avec OTel en Go, Java ou C#, faites pointer votre exportateur existant vers le récepteur OTLP du registre (/v1/otlp/v1/traces) plutôt que de recourir à un processeur de spans propre à chaque langage — chaque span gen_ai.* devient automatiquement un événement du registre, côté serveur.

Concepts fondamentaux

Ceux-ci s'appliquent à tous les langages :

• endpoint — l'URL de base de l'API du registre (http://127.0.0.1:4010 pour une pile de développement locale — voir Hébergement avec Docker).
• ingest_key — une clé par équipe ; la tenancy est résolue côté serveur à partir de celle-ci. Obtenez-en une via npm run seed:demo (développement, affiche une clé de démo) ou depuis le tableau de bord une fois une véritable organisation configurée.
• agent_id — une URI nommant le système IA agissant, par exemple urn:agent:research-assistant.
• record(...) — capture une action IA : un appel LLM, un appel d'outil, une recherche, ou une lecture/écriture de données. Synchrone et non bloquant ; retourne un identifiant de span.
• flush() — livre immédiatement les événements en tampon. S'exécute aussi automatiquement sur une minuterie (toutes les 2s par défaut).
• Idempotence — chaque événement porte une clé d'idempotence (son identifiant de span) ; le serveur déduplique sur (org, span_id), donc les nouvelles tentatives après une livraison échouée sont toujours sûres.

Champs de record()

Lignée décisionnelle

Chaque événement peut référencer l'événement qui l'a provoqué via parent_ref (un identifiant de span), de sorte qu'une chaîne comme recherche → appel LLM ayant utilisé cette recherche → appel d'outil ayant agi sur le résultat soit reconstituable. Chaque SDK expose également un assistant de « span courant » ambiant (within() / with()) afin que les appels imbriqués héritent automatiquement du bon parent, sans avoir à faire transiter un identifiant manuellement à travers chaque signature de fonction.

Blobs

Le contenu binaire (images, PDF, audio) ne peut pas être transmis en ligne dans record() sous forme de texte. Envoyez-le d'abord — c'est le seul appel bloquant de chaque SDK, puisque le blob doit exister côté serveur avant qu'un événement puisse le référencer — puis passez l'identifiant de blob retourné comme blob_ref d'un payload ou d'une récupération. Les envois sont adressés par contenu : renvoyer des octets identiques retourne le même identifiant de blob.

Garanties de livraison

La livraison se fait au moins une fois (at-least-once). Un flush échoué (erreur réseau, 5xx, 429) laisse le lot en tampon pour le prochain cycle de la minuterie — rien n'est perdu lors d'un échec transitoire. Un 401 signifie que la clé d'ingestion est incorrecte ; cela est signalé via on_error et le lot est laissé en tampon plutôt que d'être abandonné. Si le tampon lui-même se remplit (plafond par défaut : 10 000 événements), les événements les plus anciens sont supprimés pour faire de la place, mais cette suppression n'est jamais silencieuse — un événement lifecycle comptabilisant l'écart est scellé avant le lot suivant, de sorte que l'écart lui-même fasse partie de la piste d'audit.