breadcrumb

O que é breadcrumb?

breadcrumb é um sistema open-source para rastreamento e inspeção de atividade de LLM em seus agentes de IA. Ele foca em capturar o prompt completo e a resposta para cada requisição, junto com detalhes de tempo e tokens/custo, para que você possa explorar o que suas chamadas de modelo estão fazendo.

O projeto é descrito como nativo em TypeScript e auto-hospedado. Ele foi construído para ajudar desenvolvedores a entender cada trace (não apenas armazenar telemetria) e fornecer uma visão end-to-end de prompts, respostas, uso de tokens e custo por chamada rastreada.

Principais Recursos

• Rastreamento auto-hospedado para chamadas de agentes de IA: implante em plataformas mencionadas no site (ex.: Railway, Fly ou seus próprios servidores) para que o rastreamento rode na sua infraestrutura.
• SDK nativo em TypeScript: projetado para se adequar a fluxos de trabalho e padrões de instrumentação em TypeScript.
• Rastreie prompts e respostas: cada requisição rastreada inclui o prompt real enviado e a resposta completa recebida.
• Visibilidade de latência e custo por trace: mostra quanto tempo uma chamada levou e fornece uma análise por trace de uso de tokens e custo.
• Configuração de baixa fricção: o site destaca “três linhas de código”, sem arquivos de config ou decoradores e sem guia longo de setup.
• Rastreamento automático com o Vercel AI SDK: a página afirma que funciona out-of-the-box com chamadas generateText e streamText ao adicionar o helper de telemetria.

Como Usar breadcrumb

1. Instale o SDK e inicialize uma vez no seu código TypeScript.
2. Crie um cliente breadcrumb chamando init({ apiKey, baseUrl }).
3. Inicialize o helper de telemetria do AI SDK com initAiSdk(bc).
4. Passe o helper de telemetria nas suas chamadas de LLM usando a opção experimental_telemetry mostrada no exemplo.

Após rodar sua primeira chamada generateText (ou streamText), o trace deve aparecer no app breadcrumb (o site referencia uma experiência de demo de trace).

Exemplo do site (resumido para o fluxo 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

• Debug de comportamento inesperado de modelo em um agente: revise o prompt exato enviado e a resposta retornada para cada requisição rastreada para entender de onde vêm as mudanças de saída.
• Monitoramento de performance e latência: use as informações de tempo por chamada (quanto cada requisição levou) para identificar requisições mais lentas em uma cadeia de operações.
• Controle de custo e rastreamento de orçamento: verifique uso de tokens e análises de custo por trace para encontrar quais chamadas consomem mais tokens antes de impactarem as faturas.
• Observabilidade para chamadas streaming vs não-streaming: instrumente tanto generateText quanto streamText para rastrear o ciclo de vida completo das requisições feitas por um agente.
• Experimentação em equipe com auto-hospedagem: rode rastreamento no Railway, Fly ou seus próprios servidores e estenda o codebase open-source conforme necessário para seu fluxo de trabalho.

FAQ

breadcrumb é só uma ferramenta de armazenamento, ou ajuda a inspecionar traces?

breadcrumb é descrito como construído para “explorar seus traces, não apenas armazená-los”, com visibilidade em prompt, resposta, tempo e custo por requisição.

Funciona com o Vercel AI SDK?

Sim. A página afirma que funciona out-of-the-box com o Vercel AI SDK, rastreando automaticamente chamadas generateText e streamText ao passar o helper de telemetria.

Preciso de arquivos de configuração ou decoradores para começar o rastreamento?

O site afirma que a configuração evita arquivos de config e decoradores e é feita com “três linhas de código”.

Posso implantá-lo na minha própria infraestrutura?

Sim. A página o descreve como auto-hospedado e menciona opções de deployment como Railway, Fly ou seus próprios servidores.

Quais dados um trace inclui?

De acordo com a página, cada trace mostra o prompt enviado, a resposta completa recebida, quanto tempo levou e uma análise de uso de tokens e custo.

Alternativas

• Ferramentas open-source de observabilidade/telemetria para LLM: há outras abordagens para logar prompts, saídas e dados de tokens/custo, tipicamente usadas para debug e monitoramento. Diferenças estão em como integram com seu framework (middleware/hooks de SDK) e como a UI explora traces.
• Stacks gerais de APM/logging (com instrumentação custom de LLM): você pode rotear metadados de requisição/resposta de LLM para ferramentas de logging/métricas, mas pode precisar construir mais do rastreamento e análise de custo/tokens você mesmo.
• Rastreamento/analytics em nuvem para apps de IA: plataformas hospedadas reduzem trabalho operacional, mas podem trocar auto-hospedagem e customização open-source dependendo do modelo do provedor.
• Outras utilidades de inspeção de prompt/resposta: ferramentas leves focadas em capturar entradas/saídas ajudam no debug, embora possam não fornecer a mesma análise de uso de tokens e custo por trace descrita aqui.