SDKs

Cada SDK captura la actividad de agentes de IA en proceso y la entrega a la API del ledger, de modo que el código de su agente permanece por lo demás sin modificar. Todos siguen el mismo contrato, sin importar el lenguaje:

• Observar, nunca intermediar — nada aquí se sitúa en una ruta de solicitud.
• Nunca bloquear — capturar un evento es un push síncrono a un buffer; la entrega ocurre de forma asíncrona con un temporizador. (La única excepción deliberada es la subida de contenido binario — vea Blobs más abajo.)
• Nunca tumbar al host — cada punto de entrada público está a salvo de excepciones; los fallos van a un callback on_error en lugar de propagarse.
• Nunca perder en silencio — si el buffer se desborda, el descarte se cuenta y se reporta como un evento de ciclo de vida en cuanto la entrega se recupera.
• Capturar tal cual — sin normalización, sin redacción. El servidor calcula cada hash; el SDK solo reporta lo que ocurrió.

Estado por lenguaje

!NOTE Ninguno de estos SDKs está aún publicado en un registro de paquetes (npm, PyPI, Maven, NuGet) — esa es una decisión de puerta de lanzamiento todavía pendiente. Cada página de lenguaje de abajo explica cómo incorporar el SDK tal como está hoy.

Para aplicaciones instrumentadas con OTel en Go, Java o C#, apunte su exportador ya existente al receptor OTLP del ledger (/v1/otlp/v1/traces) en lugar de recurrir a un procesador de spans por lenguaje — cada span gen_ai.* se convierte automáticamente en un evento del ledger, del lado del servidor.

Conceptos centrales

Estos aplican en todos los lenguajes:

• endpoint — la URL base de la API del ledger (http://127.0.0.1:4010 para una pila de desarrollo local — vea Alojamiento con Docker).
• ingest_key — una clave por equipo; la tenancy se resuelve del lado del servidor a partir de ella. Obtenga una con npm run seed:demo (desarrollo, imprime una clave de demo) o desde el dashboard una vez que tenga una org real configurada.
• agent_id — una URI que nombra al sistema de IA actuante, por ejemplo urn:agent:research-assistant.
• record(...) — captura una acción de IA: una llamada a un LLM, una llamada a una herramienta, una búsqueda, o una lectura/escritura de datos. Síncrono y no bloqueante; devuelve un id de span.
• flush() — entrega ahora los eventos en buffer. También se ejecuta automáticamente con un temporizador (cada 2s por defecto).
• Idempotencia — cada evento lleva una clave de idempotencia (su id de span); el servidor deduplica por (org, span_id), así que los reintentos tras una entrega fallida siempre son seguros.

Campos de record()

Linaje de decisiones

Cada evento puede referenciar al evento que lo causó mediante parent_ref (un id de span), de modo que una cadena como búsqueda → llamada a un LLM que la usó → llamada a herramienta que actuó sobre el resultado es reconstruible. Cada SDK también expone un helper de "span actual" ambiental (within() / with()) para que las llamadas anidadas hereden el padre correcto automáticamente, sin tener que pasar un id a mano por cada firma de función.

Blobs

El contenido binario (imágenes, PDFs, audio) no puede viajar en línea dentro de record() como texto. Súbalo primero — esta es la única llamada en cada SDK que bloquea, ya que el blob debe existir del lado del servidor antes de que un evento pueda referenciarlo — y luego pase el id de blob devuelto como blob_ref de un payload o una recuperación. Las subidas están direccionadas por contenido: volver a subir los mismos bytes devuelve el mismo id de blob.

Garantías de entrega

La entrega es al-menos-una-vez. Un flush fallido (error de red, 5xx, 429) deja el lote en buffer para el siguiente tick del temporizador — nada se descarta ante un fallo transitorio. Un 401 significa que la clave de ingesta es incorrecta; eso se reporta vía on_error y el lote se deja en buffer en lugar de descartarse. Si el propio buffer se llena (tope por defecto: 10.000 eventos), se descartan los eventos más antiguos para hacer sitio, pero ese descarte nunca es silencioso — se sella un evento de lifecycle con el hueco contabilizado antes del siguiente lote, de modo que el propio hueco forma parte del rastro de auditoría.