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. 例で示すexperimental_telemetryオプションを使ってLLM呼び出しにテレメトリヘルパーを渡す。

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

ユースケース

• エージェントの予期せぬモデル挙動のデバッグ: 各トレースリクエストの送信プロンプトと返却完了をレビューし、出力変化の原因を特定。
• パフォーマンスとレイテンシ監視: 各リクエストの所要時間情報を使い、オペレーション連鎖内の遅いリクエストを特定。
• コスト制御と予算追跡: トレースごとのトークン使用量とコスト内訳を確認し、請求に影響する前にトークン消費の多い呼び出しを発見。
• ストリーミング/非ストリーミング呼び出しの可観測性: generateTextとstreamTextの両方を計測し、エージェントのリクエストライフサイクルをフルトレース。
• セルフホスティングでのチーム実験: Railway, Fly, または自社サーバーでトレーシングを実行し、ワークフローに応じてオープンソースコードを拡張。

FAQ

breadcrumbはストレージツールだけですか、それともトレース検査を助けますか？

breadcrumbは「トレースをただ保存するのではなく探索する」よう構築されており、リクエストごとのプロンプト、完了、タイミング、コストの可視化を提供すると記述。

Vercel AI SDKと動作しますか？

はい。Vercel AI SDKにそのまま対応し、テレメトリヘルパーを渡すとgenerateTextとstreamText呼び出しを自動トレースすると記載。

トレーシング開始に設定ファイルやデコレータは必要ですか？

サイトでは設定ファイルやデコレータを避け、「3行のコード」で開始可能と主張。

自社インフラにデプロイできますか？

はい。セルフホスト可能で、Railway, Fly, または自社サーバーのデプロイオプションを記載。

トレースに含まれるデータは何ですか？

ページによると、各トレースは送信プロンプト、返却フルレスポンス、所要時間、トークン使用量とコストの内訳を表示。

代替案

• オープンソースLLM可観測性/テレメトリツール: プロンプト、出力、トークン/コストのログに他の手法あり、主にデバッグ・監視用。フレームワーク統合（ミドルウェア/SDKフック）やUIでのトレース探索に違い。
• 汎用APM/ログスタック（カスタムLLM計測付き）: LLMリクエスト/レスポンスメタデータをログ/メトリクスシステムにルーティング可能だが、トレーシングやコスト/トークン内訳を自力構築が必要。
• AIアプリ向けクラウドトレーシング/アナリティクス: ホスト型プラットフォームは運用負担を減らすが、プロバイダモデル次第でセルフホスティングやオープンソースカスタマイズを犠牲。
• その他のプロンプト/レスポンス検査ユーティリティ: 入力/出力キャプチャに特化した軽量ツールでデバッグに役立つが、ここで記述のトレース別トークン使用量・コスト内訳は提供しない場合あり。