LangSmith でカーソルエージェントの全ターンを追跡

Cursor エージェントの全ターンを可視化！LangSmith 連携設定ガイド

開発者向けエディタ「Cursor」で動作する AI エージェントの内部挙動を、LangChain が提供する分析ツール「LangSmith」で詳細に追跡できるようになる設定方法を紹介します。これにより、モデルの実行履歴やツールの呼び出し、さらには添付ファイルの復元まで一元管理できるため、複雑化する AI アプリケーションの開発デバッグが劇的に効率化されます。

Cursor 公式プラグインの導入と再起動

まず、LangSmith と Cursor を連携させるための基盤となるプラグインをインストールします。Cursor の設定画面から「Plugins（プラグイン）」を開き、「Plugin Link」欄に LangChain 公式リポジトリの URL を貼り付けます。

「Confirm adding LangSmith tracing for Cursor」という確認メッセージが表示されたら、追加ボタンを押して完了です。

このリポジトリは事前コンパイルされたバンドルになっているため、特別なビルド作業なしで即座に導入可能です。インストール後は必ず Cursor を再起動し、プラグインが正常に読み込まれたことを確認してください。

追跡機能の有効化：環境変数または設定ファイル

Cursor の再起動後、エージェントの動作を LangSmith に送信するための設定を行います。Shell（コマンドライン）の設定ファイルに以下の 3 つの変数を追加するのが標準的な方法です。

• TRACE_TO_LANGSMITH: true に設定することで追跡機能をオンにします。
• API KEY: 自身の LangSmith API キーを指定し、認証を行います。
• PRODUCT NAME: トレースが保存されるプロジェクト名を指定します。省略するとデフォルトで「Cursor」という名前になります。

Shell の編集が面倒な場合は、プロジェクトルートに cursor-langsmith.json という設定ファイルを作成し、上記と同じフィールドを記述する代替手段もあります。この設定により、エージェントの各ターンが自動的に LangSmith へ送信されるようになります。

トレーシングの確認と可視化

設定が完了したか確認するには、ログファイルを監視します。コマンドラインで tail コマンドを実行し、Cursor エージェントにタスクを実行させると、プラグインの動作ログが表示されます。ここで正常な動きを確認できたら、いよいよ LangSmith 側の画面を見てみましょう。

LangSmith の「Cursor プロジェクト」を開くと、エージェントが実行した各ターンが個別のトレースとして記録されているのが確認できます。構造は非常に整理されており、以下のような階層で表示されます。

1. 最上位: モデルの実行情報（モデル名、トークン使用量、入力・出力）
2. 下位: ツールの呼び出し履歴（ファイルの読み込みやシェルコマンドなど）
3. ネスト構造: サブエージェントが起動した場合は、そのタスクがネストして表示され、独自のツール呼び出しも記録されます。

特に注目すべき点は、プロンプトに画像やファイルが含まれていた場合です。これらは Cursor のローカルデータベースに保存されており、プラグインが自動的に復元してユーザーメッセージとして再描画します。つまり、過去のコンテキストを失うことなく、当時の状態を完全に再現してデバッグできるのです。

まとめ

この設定により、Claude Code や Codex 版のトレースと同じ構造で Cursor の動作を追跡できるようになり、3 つのエージェントを同じワークスペースで比較分析することも可能です。AI エージェント開発における「ブラックボックス化」を防ぎ、堅牢なアプリケーション構築を実現するための重要なステップです。