LangSmith のトレース機能を用いたコーディングエージェントのデバッグ方法

コーディングエージェントはブラックボックスだ。その正体を暴く方法

先週、レポート用エンドポイントの CSV エクスポート機能を実装しようとした際、コーディングエージェントがサブエージェントを分岐させてページネーション処理を担当させました。しかし、作成されたのは意図しないものばかりでした。データはカーソルベースで管理されているのに、エージェントはオフセット方式でのページングを実装し続けていたのです。

指摘して指示を書き換え、再実行しても、結果は微妙に異なるだけで一向に改善しません。ターミナルには自信満々ながら間違った回答が溢れ、時間とトークン消費するだけでした。

結局、私は諦めてゼロから作り直しました。

しかし、実はこうすればよかったのです。トレース（Trace）を見ていれば、問題は即座に見つかったはずです。親エージェントがサブエージェントに渡した際、コードベースの別の場所にある古いヘルパー関数を指し示していたのです。その関数はオフセット方式でページングを行うものでしたが、現在は非推奨となっています。要件を改めて説明するのではなく、単に「その非推奨ヘルパーは使わない」と強調すればよかったのです。

コーディングエージェントを使ったことがある方なら、似たようなもどかしさを経験したことがあるはずです。そこで登場するのが LangSmith です。エージェントの意思決定プロセスや中間ステップ、そして出力結果を容易に可視化し、観察できるようにするためのツールです。

見えないものをデバッグすることはできない

コーディングエージェントは、現在ほとんどの開発者のエンジニアリングスタックに組み込まれています。コードの作成、ツールの呼び出し、長時間のセッション実行など、その役割は多岐にわたります。開発者はそれぞれのタスクに合わせて最適なエージェントを選択し続けるでしょう。例えば、シェル操作には Claude、インライン編集には Cursor、PR レビューには Copilot、ワークフロー作成には Codex といった具合です。しかし、各エージェントが記録する「何が起こったか」の形式はバラバラです。

一部のツールはフックを公開しており、OpenTelemetry を出力するものもあれば、プラグインに依存しているものもあります。この断片化により、ツールを切り替えるたびにデバッグワークフローが変わってしまいます。Codex と Cursor で行われる「ツールの呼び出し」が同じ種類の作業であっても、各エージェントが記録する構造やメタデータ、用語は異なります。「今週どのセッションが失敗し、その理由は何か」といった単純な質問に答える際にも、複数の場所を確認し、異なるイベント形式に対応した複数の思考モデルを頭の中で切り替える必要が生じます。

LangSmith は、主要なコーディングエージェントすべてに対して単一の観測性レイヤーを提供します。Claude Code、Codex、Cursor、GitHub Copilot Chat、Pi、OpenCode、そして DeepAgents Code（dcode）のトレースをサポートしています。これらのツールからのセッションデータは、LangSmith 上で標準化された構造を持つ「トレース」として蓄積されます。この構造を用いて、データの閲覧、クエリ、共有が可能になります。エージェントワークフローを追跡し、サブエージェントの分岐（ファンアウト）を確認し、モデル呼び出しを精査することもできます。また、機密情報を隠蔽した状態で結果をチームと共有することも可能です。

トレースされたセッションの実際の様子

設定が完了すると、LangSmith 上でのセッション表示は、本番環境で実行されたエージェントのランと同じようになります。トレースには以下のような情報が含まれます。

• ユーザーとアシスタントのやり取り
• モデル呼び出し（入力・出力・キャッシュ・トークン数・コスト）
• ツール呼び出し
• シェルコマンドの実行
• MCP の活動状況
• サブエージェントの起動
• エラー発生とリトライ履歴
• 実行時間やメタデータ

内部の仕組みを覗いてみる

デバッグの観点から、この可視性は極めて重要です。最終的な差分（diff）だけをレビューするのではなく、セッション全体を再構築して失敗箇所を特定し、その情報を今後の実行に活かすことができます。

実際には以下のような形で確認できます。

• 再構築: thread_id でフィルタリングすれば、一連の実行順序をすべて見ることができます。ユーザーからのリクエストからアシスタントの応答、モデルやツールの呼び出し、サブエージェントの起動、リトライ、実行時間、トークン数、コストまで把握可能です。

• デバッグ: 気になる箇所にズームインして詳細を確認します。ここではテスト実行の失敗事例が該当します。確認できるのは、「テスト失敗 → エージェントがアサーションを読み込む → ファイルを編集（再実行ではない） → テスト成功」という一連の流れです。

差分情報だけでは最終的に緑色のチェックマークが表示されるだけですが、トレースを使えばそこに至るまでの近道や経路をすべて見ることができます。

• テストに失敗した

• 機能の再評価を行うべきところを、テストコードを編集してしまっていた

改善策：この失敗を、エージェントが今後守るべきルールとして定義する。

こうすることで、各セッションから得た教訓をすべてのケースに適用できます。例えば「スキル」は複数のエージェント間で共有可能です。失敗したセッションを保存して評価（evals）に活用すれば、修正が本当に機能していることを証明できるだけでなく、将来同じミスを繰り返さないように検知することも可能になります。単に悪い実行結果を理解するだけでなく、重要なのは「次回の実行で同様の失敗が起きないようにする」ことです。

セッションの再生以外にも、チームはトレースを用いて異なるエージェント間の動作比較（例：同じワークフローにおける Claude Code と OpenAI Codex の比較）、見落としがちなサブエージェントの展開状況の特定、そしてレビューが必要なセッションの抽出を行います。また、レイテンシやコスト、トークン使用量でフィルタリングすることは、コストガバナンス を始めるための第一歩でもあります。

コーディングエージェントのデバッグワークフローを統一する

単一のコーディングエージェントのログを確認すれば、その 1 回の実行に関するデバッグは可能です。しかし、複数のコーディングエージェントを導入すると、デバッグの手順が最初からやり直しになります。なぜなら、各プロバイダーが提供するフックや出力されるペイロードの形式が異なるからです。

LangSmith は、こうしたすべてのセッションを単一の共通トレーススキーマにマッピングします。Claude Code のセッションも、Cursor のセッションも、OpenCode のセッションも、コアとなるフィールドはすべて同じです。これにより、検索、フィルタリング、比較、詳細な確認を、どのエージェントでも一貫した方法で行うことができます。

トレースメタデータ契約について詳しく読む

この仕組みによって、個別のプロンプト修正にとどまらない段階へと進めます。すべてのエージェントの実行結果が同じ場所に集約されることで、運用 fleet の改善を効率的に行えるようになります。「どのワークフローをエージェントが得意としているか」「失敗が繰り返されている箇所は哪里か」「どのスキルや指示の更新が必要か」、そして「変更が実際にパフォーマンス向上につながっているかどうか」を明確に把握できます。

エージェントが実際に何をしているか可視化する

エージェントエンジニアリングプラットフォームである LangSmith は、開発者がエージェントのすべての意思決定をデバッグし、評価結果の変更を確認し、ワンクリックでデプロイできるように支援します。