breadcrumb

¿Qué es breadcrumb?

breadcrumb es un sistema open-source para el tracing e inspección de la actividad de LLM en tus agentes de IA. Se centra en capturar el prompt completo y la completion de cada solicitud, junto con detalles de tiempo y tokens/coste, para que puedas explorar qué hacen las llamadas a tu modelo.

El proyecto se describe como nativo de TypeScript y autoalojable. Está diseñado para ayudar a los desarrolladores a entender cada trace (no solo almacenar telemetría) y ofrecer una vista de extremo a extremo de prompts, respuestas, uso de tokens y coste por llamada trazada.

Características clave

• Tracing autoalojable para llamadas de agentes de IA: despliega en plataformas mencionadas en el sitio (p. ej., Railway, Fly o tus propios servidores) para que el tracing funcione dentro de tu infraestructura.
• SDK nativo de TypeScript: diseñado para integrarse en flujos de trabajo e instrumentación de TypeScript.
• Tracea prompts y completions: cada solicitud trazada incluye el prompt real enviado y la respuesta completa recibida.
• Visibilidad de latencia y coste por trace: muestra cuánto tardó una llamada y desglosa el uso de tokens y coste por trace.
• Configuración de baja fricción: el sitio destaca “tres líneas de código”, sin archivos de config ni decoradores, y sin guías largas de setup.
• Tracing automático con el Vercel AI SDK: la página indica que funciona de inmediato con llamadas a generateText y streamText al añadir el helper de telemetría.

Cómo usar breadcrumb

1. Instala el SDK e inicialízalo una vez en tu código de TypeScript.
2. Crea un cliente de breadcrumb llamando a init({ apiKey, baseUrl }).
3. Inicializa el helper de telemetría del AI SDK con initAiSdk(bc).
4. Pasa el helper de telemetría a tus llamadas de LLM usando la opción experimental_telemetry mostrada en el ejemplo.

Tras ejecutar tu primera llamada a generateText (o streamText), el trace debería aparecer en la app de breadcrumb (el sitio referencia una experiencia de demo de traces).

Ejemplo del sitio (abreviado para el flujo 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"),
});

Casos de uso

• Depuración de comportamientos inesperados del modelo en un agente: revisa el prompt exacto enviado y la completion devuelta para cada solicitud trazada y entiende de dónde vienen los cambios en la salida.
• Monitorización de rendimiento y latencia: usa la información de tiempo por llamada (cuánto tardó cada solicitud) para identificar requests más lentos en una cadena de operaciones.
• Control de costes y seguimiento de presupuesto: verifica el uso de tokens y desgloses de coste por trace para encontrar qué llamadas consumen más tokens antes de que afecten a las facturas.
• Observabilidad para llamadas streaming vs no streaming: instrumenta tanto generateText como streamText para trazar el ciclo de vida completo de las solicitudes de un agente.
• Experimentación en equipo con autoalojamiento: ejecuta el tracing en Railway, Fly o tus propios servidores y extiende el código open-source según necesites para tu flujo de trabajo.

Preguntas frecuentes

¿Es breadcrumb solo una herramienta de almacenamiento, o ayuda a inspeccionar traces?

breadcrumb se describe como construido para “explorar tus traces, no solo almacenarlos”, con visibilidad en prompt, completion, tiempo y coste por solicitud.

¿Funciona con el Vercel AI SDK?

Sí. La página indica que funciona de inmediato con el Vercel AI SDK, trazando automáticamente las llamadas a generateText y streamText al pasar el helper de telemetría.

¿Necesito archivos de configuración o decoradores para empezar a trazar?

El sitio afirma que la configuración evita archivos de config y decoradores, y está pensada para empezar con “tres líneas de código”.

¿Puedo desplegarlo en mi propia infraestructura?

Sí. La página lo describe como autoalojable y menciona opciones de despliegue como Railway, Fly o tus propios servidores.

¿Qué datos incluye un trace?

Según la página, cada trace muestra el prompt enviado, la respuesta completa recibida, cuánto tardó y un desglose de uso de tokens y coste.

Alternativas

• Herramientas open-source de observabilidad/telemetría para LLM: hay otros enfoques para registrar prompts, outputs y datos de tokens/coste, usados típicamente para depuración y monitorización. Las diferencias suelen estar en cómo se integran con tu framework (middleware/hooks de SDK) y cómo la UI explora los traces.
• Stacks generales de APM/logging (con instrumentación personalizada de LLM): puedes enrutar metadatos de solicitudes/respuestas de LLM a herramientas de logging/métricas, pero podrías necesitar construir más del tracing y desglose de coste/tokens tú mismo.
• Tracing/análisis en la nube para apps de IA: plataformas alojadas reducen el trabajo operativo, pero pueden sacrificar el autoalojamiento y personalización open-source según el modelo del proveedor.
• Utilidades ligeras de inspección de prompts/respuestas: herramientas enfocadas en capturar inputs/outputs ayudan en depuración, aunque podrían no ofrecer el mismo desglose de uso de tokens y coste por trace descrito aquí.