breadcrumb

Qu'est-ce que breadcrumb ?

breadcrumb est un système open source pour tracer et inspecter l'activité LLM dans vos agents IA. Il se concentre sur la capture du prompt complet et de la complétion pour chaque requête, ainsi que sur les détails de timing et de tokens/coûts, afin que vous puissiez explorer ce que font vos appels de modèle.

Le projet est décrit comme natif TypeScript et auto-hébergeable. Il est conçu pour aider les développeurs à comprendre chaque trace (pas seulement stocker la télémétrie) et à fournir une vue d'extrémité à extrémité des prompts, réponses, utilisation de tokens et coûts par appel tracé.

Fonctionnalités clés

• Traçage auto-hébergeable pour les appels d'agents IA : déployez-le sur les plateformes mentionnées sur le site (ex. : Railway, Fly ou vos propres serveurs) pour que le traçage s'exécute dans votre infrastructure.
• SDK natif TypeScript : conçu pour s'intégrer aux workflows et patterns d'instrumentation TypeScript.
• Traçage des prompts et complétions : chaque requête tracée inclut le prompt réel envoyé et la réponse complète reçue.
• Visibilité latence et coûts par trace : affiche la durée d'un appel et fournit un détail par trace de l'utilisation de tokens et des coûts.
• Mise en place simple : le site met en avant « trois lignes de code », sans fichiers de config ni décorateurs, et sans guide de mise en place long.
• Traçage automatique avec le Vercel AI SDK : la page indique qu'il fonctionne directement avec les appels generateText et streamText en ajoutant l'helper de télémétrie.

Comment utiliser breadcrumb

1. Installez le SDK et initialisez une fois dans votre code TypeScript.
2. Créez un client breadcrumb en appelant init({ apiKey, baseUrl }).
3. Initialisez l'helper de télémétrie du AI SDK avec initAiSdk(bc).
4. Passez l'helper de télémétrie dans vos appels LLM via l'option experimental_telemetry comme dans l'exemple.

Après votre premier appel generateText (ou streamText), la trace devrait apparaître dans l'app breadcrumb (le site référence une expérience de trace démo).

Exemple du site (abrégé pour le flux principal) :

import { init } from "@breadcrumb-sdk/core";
import { initAiSdk } from "@breadcrumb-sdk/ai-sdk";

const bc = init({ apiKey, baseUrl });
const { telemetry } = initAiSdk(bc);

const { text } = await generateText({
  // ...
  experimental_telemetry: telemetry("summarize"),
});

Cas d'usage

• Débogage de comportements inattendus du modèle dans un agent : examinez le prompt exact envoyé et la complétion retournée pour chaque requête tracée afin de comprendre l'origine des changements de sortie.
• Surveillance des performances et latences : utilisez les infos de timing par appel (durée de chaque requête) pour identifier les requêtes plus lentes dans une chaîne d'opérations.
• Contrôle des coûts et suivi budgétaire : vérifiez l'utilisation de tokens et les détails de coûts par trace pour repérer les appels qui consomment le plus de tokens avant impact sur les factures.
• Observabilité pour appels streaming vs non-streaming : instrumentez generateText et streamText pour tracer le cycle de vie complet des requêtes d'un agent.
• Expérimentation en équipe avec auto-hébergement : exécutez le traçage sur Railway, Fly ou vos propres serveurs et étendez le code open source selon vos besoins.

FAQ

breadcrumb est-il juste un outil de stockage, ou aide-t-il à inspecter les traces ?

breadcrumb est décrit comme conçu pour « explorer vos traces, pas seulement les stocker », avec visibilité sur le prompt, la complétion, le timing et les coûts par requête.

Fonctionne-t-il avec le Vercel AI SDK ?

Oui. La page indique qu'il fonctionne directement avec le Vercel AI SDK, traçant automatiquement les appels generateText et streamText quand vous passez l'helper de télémétrie.

Ai-je besoin de fichiers de config ou de décorateurs pour démarrer le traçage ?

Le site affirme que la mise en place évite les fichiers de config et décorateurs, et se fait en « trois lignes de code ».

Puis-je le déployer sur mon infrastructure ?

Oui. La page le décrit comme auto-hébergeable et mentionne des options comme Railway, Fly ou vos propres serveurs.

Quelles données inclut une trace ?

Selon la page, chaque trace affiche le prompt envoyé, la réponse complète reçue, la durée, et un détail de l'utilisation de tokens et des coûts.

Alternatives

• Outils open source d'observabilité/télémétrie LLM : d'autres approches pour logger prompts, sorties et données tokens/coûts, souvent pour débogage et monitoring. Les différences portent sur l'intégration au framework (middleware/hooks SDK) et l'exploration des traces dans l'UI.
• Stacks APM/logging généraux (avec instrumentation LLM custom) : vous pouvez router les métadonnées des requêtes/réponses LLM vers des outils de logging/métriques, mais vous devrez souvent construire plus de traçage et de détails tokens/coûts vous-même.
• Traçage/analytics cloud pour apps IA : les plateformes hébergées réduisent le travail opérationnel, mais peuvent sacrifier l'auto-hébergement et la personnalisation open source selon le modèle du fournisseur.
• Autres utilitaires d'inspection prompt/réponse : outils légers focalisés sur la capture des entrées/sorties pour débogage, bien qu'ils ne fournissent pas toujours le même détail par trace sur tokens et coûts décrit ici.