LangSmithトレースでコーディングエージェントをデバッグする方法

コーディングエージェントはブラックボックスです。それを開く方法をご紹介します。

先週、私はレポートエンドポイント用のCSVエクスポートを構築しようとしていました。コーディングエージェントはページネーションを処理するサブエージェントを分割しました。しかし、間違ったものを作り続けました。データはカーソルベースなのに、オフセットでページングしていました。指摘し、指示を編集し、再実行しても、少し違う方法で戻ってきました。時間とトークンを浪費し、自信満々だが間違った答えから何も学べませんでした。

結局諦めて、最初からやり直しました。

しかし、トレースを見ていれば、すぐに問題がわかりました。ハンドオフ中に、親エージェントがサブエージェントをコードベースの別の部分にある古いヘルパー（オフセットでページングするもの）に誘導していたのです。要件を再説明する代わりに、非推奨のヘルパーを強調するだけでよかったのです。

コーディングエージェントを使ったことがあるなら、同様のフラストレーションを経験したことがあるでしょう。だからこそ、LangSmithを使ってエージェントの決定、中間ステップ、出力を観察しやすくしています。

見えないものはデバッグできません

コーディングエージェントは現在、ほとんどの開発者のエンジニアリングスタックの一部です。コードを書き、ツールを呼び出し、長時間のセッションを行います。開発者はタスクに合わせてさまざまなエージェントを選択し続けます。Claudeでシェルを実行し、Cursorでインライン編集を処理し、CopilotでPRをレビューし、Codexでワークフローをドラフトするかもしれません。各エージェントには独自の記録方法があります。フックを公開するもの、OpenTelemetryを発行するもの、プラグインに依存するものがあります。

この断片化により、ツールを切り替えるたびにデバッグワークフローが変わります。Codexのツール呼び出しとCursorのツール呼び出しは同じ作業を表すかもしれませんが、各エージェントは異なる構造、メタデータ、用語で記録します。すべてのエージェントにわたって「今週どのセッションが失敗したか、その理由は？」という単純な質問に答えるには、複数の場所を確認し、複数のイベント形式に対応する複数のメンタルモデルを持つ必要があります。

LangSmithは、すべての主要なコーディングエージェントにわたる単一の可観測性レイヤーをチームに提供します。Claude Code、Codex、Cursor、GitHub Copilot Chat、Pi、OpenCode、DeepAgents Code (dcode) のトレースをサポートしています。これらのツールからのセッションは、標準化された構造を使用してLangSmithにトレースとして取り込まれ、検査、クエリ、共有が可能です。エージェントワークフローをトレースし、サブエージェントのファンアウトを追跡し、モデルコールを検査し、機密情報を編集して結果を共有できます。

トレースされたセッションの外観

構成が完了すると、セッションは運用エージェントの実行と同じ方法でLangSmithに表示されます。トレースには以下を含めることができます：ユーザーとアシスタントのターン、入出力、キャッシュ、トークン、コストを含むモデルコール、ツールコール、シェルコマンド、MCPアクティビティ、サブエージェント呼び出し、エラーとリトライ、タイミングとメタデータ。

内部を見る

デバッグの観点から、この可視性は重要です。最終的な差分だけを確認するのではなく、セッションを再構築し、障害を見つけ、将来の実行にその情報を活用できます。

実際の例：

再構築：thread_idでフィルタリングし、全体の実行を順番に表示します。ユーザーリクエスト、アシスタントターン、モデル/ツールコール、サブエージェント、リトライ、タイミング、トークン、コスト。

デバッグ：関心のある領域にズームインします。ここでは失敗したテスト実行です。シーケンス：テスト失敗→エージェントがアサーションを読み取る→エージェントがファイルを編集（再実行ではない）→テスト合格。差分は最後の緑のチェックマークだけを示しますが、トレースはそこに至るショートカットを示します。

改善：間違いをエージェントが従うべきルールに変えます。

こうして、各セッションから学んだ教訓があらゆる場所に適用されます。たとえば、スキルはエージェント間で機能します。失敗したセッションを保存し、評価（詳細はこちら）に使用し、修正が実際に機能することを証明し、後退した場合にキャッチできます。悪い実行を理解するだけでなく、次の実行が同じように失敗しないようにすることが目標です。

セッションリプレイを超えて、チームはトレースを使用して、同じワークフローでのエージェント間の動作を比較し、目に見えないサブエージェントファンアウトを発見し、レビューが必要なセッションを特定します。レイテンシ、コスト、トークン使用量でフィルタリングすることは、コストガバナンスの出発点でもあります。

すべてのコーディングエージェントにわたる1つのデバッグワークフロー

単一のコーディングエージェントのログは1回の実行のデバッグに役立ちます。しかし、複数のコーディングエージェントを採用すると、各プロバイダーが異なるフックを公開し、異なる形状のペイロードを発行するため、デバッグワークフローは毎回最初からやり直しになります。

LangSmithはすべてのセッションを単一の共有トレーススキーマにマッピングします。Claude Codeセッション、Cursorセッション、OpenCodeセッションはすべて同じコアフィールドを持つため、同じ方法で検索、フィルタリング、比較、検査できます。トレースメタデータ契約の詳細をご覧ください。

これにより、個別のプロンプト修正を超えた進歩が可能になります。すべてのエージェントの実行が同じ場所に取り込まれると、エージェント群を効率的に改善できます：エージェントがうまく処理するワークフロー、失敗が繰り返される場所、更新が必要なスキルや指示、変更が実際にパフォーマンスを向上させるかどうか。

はじめに

各コーディングエージェントのセットアップ手順を提供しています。Claude Code、Codex、Cursor、GitHub Copilot Chat、Pi、OpenCode、dcodeの統合手順をご覧ください。

構成後、コーディングエージェントチャット内のインストルメンテーションを変更する必要はありません。通常どおりエージェントを実行すると、セッションがトレースとしてLangSmithに表示されます。

コーディングエージェントの統合を見つけて、トレースを開始してください。

エージェントが実際に何をしているかを見る

LangSmith（エージェントエンジニアリングプラットフォーム）は、開発者がエージェントのすべての決定をデバッグし、変更を評価し、ワンクリックでデプロイするのに役立ちます。

LangSmithを試す

デモを取得