breadcrumb

Cos'è breadcrumb?

breadcrumb è un sistema open-source per il tracing e l'ispezione dell'attività LLM nei tuoi agenti AI. Si concentra sulla cattura del prompt completo e della completion per ogni richiesta, insieme a dettagli su tempi e token/costo, così puoi esplorare cosa fanno le chiamate al tuo modello.

Il progetto è descritto come nativo TypeScript e self-hostable. È costruito per aiutare gli sviluppatori a comprendere ogni trace (non solo memorizzare telemetria) e fornire una vista end-to-end di prompt, risposte, utilizzo token e costo per chiamata tracciata.

Caratteristiche Principali

• Tracing self-hostable per chiamate agli agenti AI: distribuiscilo sulle piattaforme menzionate nel sito (es. Railway, Fly o i tuoi server) così il tracing può girare nella tua infrastruttura.
• SDK nativo TypeScript: progettato per adattarsi ai workflow e pattern di instrumentazione TypeScript.
• Trace di prompt e completions: ogni richiesta tracciata include il prompt effettivo inviato e la risposta completa ricevuta.
• Visibilità su latenza e costi per trace: mostra quanto tempo ha impiegato una chiamata e fornisce una scomposizione per trace di utilizzo token e costi.
• Setup a basso attrito: il sito evidenzia “tre righe di codice”, senza file di config o decoratori e senza guide di setup lunghe.
• Tracing automatico con Vercel AI SDK: la pagina afferma che funziona out-of-the-box con chiamate generateText e streamText aggiungendo l'helper di telemetria.

Come Usare breadcrumb

1. Installa l'SDK e inizializzalo una volta nel tuo codice TypeScript.
2. Crea un client breadcrumb chiamando init({ apiKey, baseUrl }).
3. Inizializza l'helper di telemetria AI SDK con initAiSdk(bc).
4. Passa l'helper di telemetria nelle tue chiamate LLM usando l'opzione experimental_telemetry mostrata nell'esempio.

Dopo aver eseguito la tua prima chiamata generateText (o streamText), il trace dovrebbe apparire nell'app breadcrumb (il sito fa riferimento a un'esperienza demo di trace).

Esempio dal sito (abbreviato per il flusso principale):

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"),
});

Casi d'Uso

• Debug di comportamenti inattesi del modello in un agente: rivedi il prompt esatto inviato e la completion restituita per ogni richiesta tracciata per capire da dove provengono i cambiamenti nell'output.
• Monitoraggio performance e latenza: usa le informazioni sui tempi per chiamata (quanto tempo ha impiegato ogni richiesta) per identificare richieste più lente in una catena di operazioni.
• Controllo costi e tracciamento budget: verifica utilizzi token e scomposizioni costi per trace per trovare quali chiamate consumano più token prima che impattino sulle fatture.
• Osservabilità per chiamate streaming vs non-streaming: instrumenta sia generateText che streamText così puoi tracciare il ciclo di vita completo delle richieste fatte da un agente.
• Sperimentazione team-based con self-hosting: esegui il tracing su Railway, Fly o i tuoi server e estendi il codebase open-source come necessario per il tuo workflow.

FAQ

breadcrumb è solo uno strumento di storage, o aiuta a ispezionare i trace?

breadcrumb è descritto come costruito per “esplorare i tuoi trace, non solo memorizzarli”, con visibilità su prompt, completion, tempi e costi per richiesta.

Funziona con Vercel AI SDK?

Sì. La pagina afferma che funziona out-of-the-box con Vercel AI SDK, tracciando automaticamente le chiamate generateText e streamText quando passi l'helper di telemetria.

Ho bisogno di file di configurazione o decoratori per iniziare il tracing?

Il sito afferma che il setup evita file di config e decoratori ed è pensato per partire con “tre righe di codice”.

Posso distribuirlo sulla mia infrastruttura?

Sì. La pagina lo descrive come self-hostable e menziona opzioni di deployment inclusi Railway, Fly o i tuoi server.

Quali dati include un trace?

Secondo la pagina, ogni trace mostra il prompt inviato, la risposta completa ricevuta, quanto tempo ha impiegato e una scomposizione di utilizzo token e costi.

Alternative

• Strumenti open-source di osservabilità/telemetria LLM: ci sono altri approcci per loggare prompt, output e dati token/costo, tipicamente usati per debug e monitoring. Le differenze sono spesso in come si integrano con il tuo framework (middleware/SDK hooks) e come l'UI esplora i trace.
• Stack APM/logging generali (con instrumentazione LLM custom): puoi instradare metadati richiesta/risposta LLM in tool come sistemi di logging/metrics, ma potresti dover costruire più tracing e scomposizioni costi/token da te.
• Tracing/analytics cloud-based per app AI: piattaforme hosted riducono il lavoro operativo, ma potrebbero scambiare self-hosting e customizzazione open-source a seconda del modello del provider.
• Altri utility di ispezione prompt/risposta: tool leggeri focalizzati sulla cattura input/output possono aiutare il debug, anche se potrebbero non fornire la stessa scomposizione per trace di utilizzo token e costi descritta qui.