Agent オブザーバビリティとは?実行トレース、ツール呼び出し、タスク結果

AI エージェントのモデル呼び出しやツールの再試行をトレースで調べ、タスクが期待した結果に至ったかを別途確認する方法を紹介します。

ベストプラクティス
複数のロボットアームが連携して作業するイラスト

会議室を探すアシスタントが「東棟にバリアフリー対応の空き会議室が見つかりました」と答えました。HTTP ステータスは 200 で、2 回のモデル呼び出しも完了しています。ところが、案内された部屋は西棟にありました。

トレースを開くと、最初の空き状況照会はタイムアウトし、再試行で結果が返っています。これで待ち時間の理由は分かります。案内が誤っていた理由を調べるには、利用者の条件と会議室台帳を照らし合わせる必要があります。

Agent オブザーバビリティとは、エージェントの実行中に観測できる操作をたどり、タスクが期待どおりの結果に至ったかを確認する取り組みです。 モデル呼び出し、ツールの実行、アプリケーションの状態をタスクの結果に結びつけます。計装した操作なら、どのツールを呼び、どんなステータスが返ったかを確認できます。モデル内部の非公開の推論過程や、記録されなかった操作までは分かりません。

まず一つの実行をたどる

エージェントの実行入口から、モデル呼び出し、ツール実行、検索、状態変更を見ていきます。会議室の例で、次のような記録が得られたとします。

記録された操作 分かること
最初のモデル呼び出し 空き状況を照会するためのツール呼び出しを準備した。
1 回目の照会 ツールがタイムアウトした。
2 回目の照会 再試行が成功し、空き状況を取得した。
最後のモデル呼び出し アシスタントが回答を生成した。
タスク結果の確認 案内された部屋は「東棟」という条件を満たしていなかった。

ここでタスクの結果を判定するのは、アプリケーションのチェック処理や評価の仕組みです。ツールの失敗は 2 回の試行のうち 1 回。タスクとしては 1 件が条件を満たしませんでした。数えている対象が違います。

同じトレースの中では、Span の親子関係とタイムスタンプから、並列処理も含めて記録済みの操作を読み取れます。一つの会話に複数のトレースが含まれることもあります。中断したタスクを別のトレースで再開する場合は、アプリケーション側の実行 ID で前後をつなぎます。元の Span のコンテキストがあり、因果関係が明確なら、Span Link でも関連を表せます。

操作に合ったフィールドを記録する

操作 まず記録したい項目
エージェントの実行 エージェントまたはワークフローの名前とバージョン、処理時間、実行 ID。会話 ID はアプリケーションから取得でき、収集が許可されている場合に記録する。
モデル呼び出し 取得できる場合はリクエスト時と応答時のモデル名、処理時間、報告されたトークン使用量。未報告の使用量は不明のままにする。
ツール実行 固定のツール名、処理時間、実行結果、失敗時のエラー種別。再試行を集計するなら、試行ごとに記録する。
検索や状態変更 種類が限られた参照先や処理段階の名前、結果件数や状態遷移の結果。照合に必要なら実行 ID も残す。

OpenTelemetry GenAI のエージェント実行入口、モデル推論、ツール実行のセマンティック規約は、いずれも Development 段階です。invoke_agent や execute_tool といった操作が定義されています。実際にどの Span や属性が出力されるかは、フレームワークと計装ライブラリのバージョンをそろえて確認します。一般的な HTTP 計装で外部通信の遅れが分かっても、ツール名や再試行が記録されているとは限りません。

収集はメタデータから始めます。プロンプトやメッセージ、ツールの引数や返り値には、要約した後でも個人情報やシークレットが残ることがあります。内容の収集は明示的に有効化し、アクセスできる人と保持期限を決め、調査に不要な情報は送信前に削ります。記録した入出力は当時の実行を振り返る手がかりになりますが、同じ結果を再現できる保証はありません。

トレースで原因を調べ、タスク結果で成否を測る

最初は、期待どおりだったかを確認できるタスクを一つ選びます。会議室アシスタントなら、テスト用の台帳で部屋の ID を引き、利用者の条件を満たしたかを確かめます。判定結果とルールのバージョンを実行 ID にひも付けておけば、モデルやツールを変えた後も同じ基準で比較できます。

最初のトレースを確認できたら、タスク全体の処理時間、ツールの試行失敗率、再試行、タスク成功率を集計します。例えば 2 回再試行したタスクは、ツールの試行が 3 回、タスクが 1 件です。メトリクスにはワークフローのバージョンや既知のツール名など、値の種類を管理できるラベルを使います。実行 ID や会話 ID はアクセス制御されたトレースやログの調査に使えば、実行ごとに時系列が増えるのを防げます。

Guance で同じ実行を調べる

OpenTelemetry の Span が出ているなら、DataKit 経由でアプリケーションのトレースを取り込み、APM でタイムアウトから再試行、最後のモデル呼び出しまでをたどれます。AgentScope など対応するフレームワークを使っている場合は、別途 Agent モニタリングの導入ガイドに沿って設定します。Explorerでは収集されたモデル呼び出しやツール実行を、トレースやセッション単位で確認できます。

会議室のテストで調べたいことは二つです。待ち時間の理由はツールの時系列で、部屋が条件を満たしたかどうかは台帳との照合で確かめます。評価に使えるデータがそろっていれば、Guance の出力品質評価でルール、モデルによる判定、人手のアノテーションも利用できます。業務システムの記録に基づく判定は、アプリケーション側で直接行います。

関連記事

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ