breadcrumb

breadcrumb이란?

breadcrumb는 AI 에이전트의 LLM 활동을 추적하고 검사하는 오픈소스 시스템입니다. 각 요청에 대한 전체 프롬프트와 완료를 캡처하는 데 중점을 두며, 타이밍과 토큰/비용 세부 정보를 함께 제공하여 모델 호출이 어떻게 작동하는지 탐색할 수 있습니다.

프로젝트는 TypeScript 네이티브이자 자체 호스팅 가능으로 설명됩니다. 개발자들이 각 트레이스를 이해(단순 텔레메트리 저장이 아닌)하고 프롬프트, 응답, 토큰 사용량, 추적된 호출당 비용의 엔드투엔드 뷰를 제공하도록 구축되었습니다.

주요 기능

• AI 에이전트 호출용 자체 호스팅 트레이싱: 사이트에 언급된 플랫폼(예: Railway, Fly, 또는 자체 서버)에 배포하여 인프라 내에서 트레이싱을 실행하세요.
• TypeScript 네이티브 SDK: TypeScript 워크플로우와 계측 패턴에 맞게 설계되었습니다.
• 프롬프트와 완료 추적: 각 추적된 요청에는 실제 전송된 프롬프트와 반환된 전체 응답이 포함됩니다.
• 트레이스당 지연 및 비용 가시성: 호출 소요 시간과 트레이스당 토큰 사용량 및 비용 상세 내역을 표시합니다.
• 저마찰 설정: 사이트에서 "코드 3줄"로 강조하며, 설정 파일이나 데코레이터, 긴 가이드 없이 가능합니다.
• Vercel AI SDK 자동 트레이싱: generateText와 streamText 호출에 텔레메트리 헬퍼를 추가하면 즉시 작동합니다.

breadcrumb 사용 방법

1. TypeScript 코드에서 SDK 설치 및 한 번 초기화.
2. init({ apiKey, baseUrl }) 호출로 breadcrumb 클라이언트 생성.
3. initAiSdk(bc)로 AI SDK 텔레메트리 헬퍼 초기화.
4. LLM 호출에 텔레메트리 헬퍼 전달 예제의 experimental_telemetry 옵션 사용.

첫 generateText(또는 streamText) 호출 후 breadcrumb 앱에 트레이스가 나타납니다(사이트에서 데모 트레이스 경험 참조).

사이트 예제(핵심 흐름 요약):

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

사용 사례

• 에이전트의 예상치 못한 모델 동작 디버깅: 각 추적된 요청의 정확한 전송 프롬프트와 반환 완료를 검토하여 출력 변화 원인을 파악하세요.
• 성능 및 지연 모니터링: 각 요청 소요 시간 정보를 활용해 작업 체인에서 느린 요청을 식별하세요.
• 비용 관리 및 예산 추적: 트레이스당 토큰 사용량과 비용 내역을 확인해 청구서에 영향을 주기 전에 가장 많은 토큰을 소비하는 호출을 찾으세요.
• 스트리밍 vs 비스트리밍 호출 관찰성: generateText와 streamText 모두 계측하여 에이전트 요청의 전체 라이프사이클을 추적하세요.
• 자체 호스팅 팀 실험: Railway, Fly 또는 자체 서버에서 트레이싱 실행하고 워크플로우에 맞게 오픈소스 코드를 확장하세요.

자주 묻는 질문

breadcrumb는 단순 저장 도구인가, 트레이스 검사를 돕나요?

breadcrumb는 "트레이스를 탐색하도록 구축"되었으며, 요청당 프롬프트, 완료, 타이밍, 비용 가시성을 제공합니다.

Vercel AI SDK와 작동하나요?

네. Vercel AI SDK와 즉시 작동하며, 텔레메트리 헬퍼 전달 시 generateText와 streamText 호출을 자동 추적합니다.

트레이싱 시작에 설정 파일이나 데코레이터가 필요하나요?

사이트에서 설정 파일과 데코레이터 없이 "코드 3줄"로 시작 가능하다고 강조합니다.

자체 인프라에 배포할 수 있나요?

네. 자체 호스팅 가능하며, Railway, Fly 또는 자체 서버 배포 옵션을 언급합니다.

트레이스가 포함하는 데이터는?

페이지에 따르면 각 트레이스는 전송된 프롬프트, 반환된 전체 응답, 소요 시간, 토큰 사용량 및 비용 내역을 표시합니다.

대안

• 오픈소스 LLM 관찰성/텔레메트리 도구: 프롬프트, 출력, 토큰/비용 데이터를 로깅하는 다른 접근법으로, 디버깅 및 모니터링에 사용. 프레임워크 통합(미들웨어/SDK 훅)과 UI 트레이스 탐색 방식이 다릅니다.
• 일반 APM/로깅 스택(커스텀 LLM 계측): LLM 요청/응답 메타데이터를 로깅/메트릭스 시스템으로 라우팅 가능하나, 트레이싱과 비용/토큰 내역은 직접 구축해야 합니다.
• AI 앱용 클라우드 기반 트레이싱/분석: 호스팅 플랫폼은 운영 부하를 줄이지만, 제공자 모델에 따라 자체 호스팅과 오픈소스 커스터마이징을 포기할 수 있습니다.
• 기타 프롬프트/응답 검사 유틸리티: 입력/출력 캡처에 초점 맞춘 경량 도구로 디버깅에 유용하나, 여기 설명된 트레이스당 토큰 사용량 및 비용 내역은 제공하지 않을 수 있습니다.