Article by: Dominik Buszowiecki , Shaun Kaasten（読了時間：4分）
Sentry に送られてくるデータをユーザーに最大限活用してもらうには、そのデータを簡単に見つけられるようにすることが重要です。私たちのチームは、検索クエリやフィルターを使って特定のイベントを探し出し、データを閲覧しやすくする機能を開発しています。検索バーでは、検索語を指定するだけでデータを見つけられます。
検索には Sentry Search Syntax を使いますが、これがユーザーにとって障壁になることがあります。そこで、最近の他のツールと同じように、自然言語で検索語を指定したいというユーザーもいます。そうしたニーズに応えるため、自然言語のプロンプトを Sentry Syntax の検索語に変換する Search Query Assistant を開発しました。
出力は非決定的なため、応答の性能を高め、測定するために eval を使っています。
必要な作業は2つです。中心となるユーザーシナリオの eval を書くこと、そしてそれを実行して、エージェントが正しいクエリをどれだけ生成できるかを確認することです。エージェントが期待どおりのクエリを一貫して生成できれば、それで完了です。
次のシナリオに進みます。クエリが誤っているときは、エージェントが何を見て、何をしたのか、そしてどうすれば正しい答えに導けるのかをデバッグします。
失敗した eval をデバッグする
eval をローカルで再現してデバッグできる場合もあります。特定のデータが存在していることに依存しない場合やモックのツール呼び出しだけで問題を診断・修正できる場合です。そうしたケースでは、結果を確認するのに簡単なツールで十分です。たとえば、LLM の生成結果やツール呼び出しの JSON 出力を見る、といった具合です。
ただ、挙動がもっと複雑な場合もあります。ツール呼び出しから返ってくる特定のデータ、使用する LLM モデルのバージョンの違い、あるいはインフラのエラーが原因になっているケースです。そうした場合には、Sentry の AI Conversation ビューがデバッグに役立つツールになっています。
実際のクエリ生成バグ
エンドツーエンドのテストを行っていたとき、指定したフィールドが数値型のカスタム属性である場合に、クエリが結果を返さないことに気づきました。
たとえば、あるショッピングサービスが、購入時にカート内の商品数を数えるカスタム属性を付けてイベントを送信しているとします。ユーザーはその数が10より大きい購入イベントをすべて見たいと考えるかもしれません。ところが検索アシスタントを使うと、イベントが1件も返ってきませんでした。
AI Conversation を見つける
API エンドポイントのエラーをデバッグするなら、まず Sentry でそのイベントを探し、キャプチャされたデータを確認するところから始めるはずです。今回は LLM が生成したエラーですが、同じ手順をたどることができました。
このケースではAgents ビューに移動し、フィルターを使って対象のやり取りを探しました。ここでは時間範囲、使用しているエージェント（今回はトレース向けのもの）、自分のメールアドレスでフィルタリングしてトレースを見つけられます。
そこから、やり取りのタイムラインを確認できました。JSON の塊を眺めるよりずっと簡単です。
さらに、その（誤った）応答を生成するために実行されたシステムプロンプト、LLM の生成、ツール呼び出しも確認できました。
ツール呼び出しがなぜ特定のデータを返したのかを把握することは重要です。
このビューからはトレースへのリンクをたどれます。トレースを見れば、エージェントが行ったバックエンドの API 呼び出しがわかり、フロントエンドのバグのような AI 以外のエラーを調べるのと同じ要領で調査することができます。
タイムラインとトレースを見て、根本原因を突き止めました。原因はシステムプロンプトを生成する際に、（自社の API エンドポイントから返ってきた）ツール呼び出しの結果をどう使っていたかにありました。
プロンプトでは利用可能なフィールドが、Sentry Search Syntax で必要な tags[bug_predictions_count, number] という形式ではなく、bug__predictions_count という名前単体で表示されていました。
これで、問題を再現して修正するための新しい eval シナリオを作るのに十分な情報が得られました。
本番環境で検証する
修正によってローカルの eval が通ることは確認できましたが、本番環境でも動作するのを見られると気持ちがいいものです。
デプロイ後に同じクエリを実行すると、正しいデータが返ってきました。
その後、AI Conversation ビューに戻ってトレースを探し、システムプロンプトに修正後の情報が反映されていることを確認できました。API 呼び出しに渡されたパラメータが正しいデータを返していることも確認できました。
ローカル開発にも組み込みました
非常に便利だとわかったので、ローカルの eval 実行にもインストルメンテーションを施し、データを Sentry に送信するようにしました。おかげで、プルリクエストを開く前の段階から、ローカルで eval を回しつつ結果を Sentry で確認できます。
使い慣れたツールが摩擦を減らす
AI Conversation のトレース を他のイベントデータと並べて Sentry 内に置いておくことで、次のことが可能になりました。
- 使い慣れたツールで関連する会話のトレースを見つけられる
- ツール間で ID やデータをコピー＆ペーストせずに済む
- 応答を生成するためにエージェントが自社の API へ行ったツール呼び出しに直接ジャンプできる
全体として、こうしたエージェントのトレースを他のデータと並べて扱えるようになったことで、この種の問題のデバッグがはるかに楽になりました。今では改善が必要なクエリ応答を掘り下げるとき、まず最初に見る場所になっています。
自分で AI エージェントを構築しているなら、Sentry のエージェントトレーシングのドキュメント を確認して、自分のトレースでも同じ可視性を得る方法をご覧ください。
Original Page: Debugging our AI search assistant with agent tracing
IchizokuはSentryと提携し、日本でSentry製品の導入支援、テクニカルサポート、ベストプラクティスの共有を行なっています。Ichizokuが提供するSentryの日本語サイトについてはこちらをご覧ください。またご導入についての相談は「お問い合わせ」からお気軽にお問い合わせください。
