LangSmith で数分でコデックスセッションを全追跡

AI コーディングエージェント「Codex」の内部挙動を可視化！LangSmith で全セッションを追跡する設定ガイド

AI エージェントが生成したコードや実行プロセスの裏側が見えないと、バグの原因特定もコスト管理も困難です。本記事では、開発者向け AI コーディングエージェント「Codex」の実行セッションを LangSmith でリアルタイムに追跡・可視化する具体的な設定手順を紹介します。

CLI のインストールから環境変数の設定までを順を追って解説し、最終的にどのようなトレース情報が取得できるかを明確にします。これにより、コード生成プロセスの透明性を高め、エンタープライズ環境でのガバナンスやトークンコスト管理を確立できます。

事前準備：CLI の更新とプラグインの追加

まず、Codex を LangSmith で追跡可能にするための土台作りから始めます。必要なのは、バージョン 0.142 以降の Codex CLI と、LangSmith の API キーです。

トレース機能を使うには、CLI からマーケットプレースにトレーシングプラグインを追加する必要があります。

コマンドを実行するとプラグインが取得されますが、これだけで自動的に有効になるわけではありません。プラグイン自体を動かすためのフック設定が別途必要になります。

設定ファイルでプラグインと機能を明示的にオンにする

取得したプラグインを有効化するには、プロジェクトごとの設定ファイル ~/.codex/config.toml を編集します。このファイルに「features」と「plugins」の 2 つのブロックを追加し、フックを明示的に true に設定する必要があります。

設定が不十分だと、後述する環境変数を設定してもトレースは開始されません。必ず設定ファイル側でプラグインフックが有効になっているか確認してください。

環境変数で追跡機能を稼働させる

設定ファイルでの準備が整ったら、最後に環境変数を設定して実際の追跡を開始します。ターミナルの新しいタブを開き、以下の 3 つの環境変数をエクスポートします。

1. TRACE_TO_LANGSMITH: 追跡機能をオンにするフラグ（true に設定）
2. CODEX_API_KEY: Codex の API キー
3. LANGSMITH_CODEX_PROJECT: LangSmith 上のプロジェクト名を指定

実際のキーを入力する際は、プレースホルダーではなく実物の API キーを設定してください。

これにより、Codex が実行される際にすべてのセッションが自動的に LangSmith に送信されるようになります。設定ファイルでも同様の設定が可能ですが、環境変数の方が管理しやすくおすすめです。

LangSmith での可視化：階層構造を維持したトレースの確認

実際に Codex にタスクを実行させると、LangSmith のダッシュボード上で詳細なトレースが確認できます。例えば、「GitHub でトレンド上位のリポジトリを検索し、Python CLI ツールとして整形して表示する」といった複雑なタスクも、以下のような構造で記録されます。

会話履歴とメタデータの蓄積

LLM ラン（実行）を確認すると、入力には会話の履歴全体が蓄積され、出力はアシスタントの応答となります。メタデータ欄にはモデルプロバイダー、モデル名、停止理由、そして何より重要な「トークン使用量」が含まれます。

ツール呼び出しの詳細なログ

LLM ランの下には、実行中に使われたすべてのツール呼び出しがリストされます。関数呼び出し、シェルコマンド、ウェブ検索、ファイル読み込みなど、それぞれの入力と出力が詳細に記録されています。

サブエージェントの階層構造

Codex が内部でサブエージェントを開始した場合、その関係性は単なる長いリスト（フラット化）にはなりません。親のターン直下にネストされた子として表示され、誰が何を呼び出したかの階層構造が維持されます。

実行をキャンセルした場合でも、セッションが完了していればトレースはアップロードされます。もし画面に何も表示されない場合は、設定の不備を確認する必要があります。

トラブルシューティング：トレースが表示されない場合

LangSmith に何も表示されない場合は、以下の 4 点をチェックしてください。

1. プラグインフックの有効化: config.toml ファイル内で plugin_hooks が true に設定されているか確認する
2. トレーシングプラグインの存在: プラグインが正しくインストールされているか確認する
3. 追跡フラグの設定: 環境変数で TRACE_TO_LANGSMITH が true になっているか確認する
4. プロジェクト名の指定: 間違ったプロジェクトにデータが届いている場合、LANGSMITH_CODEX_PROJECT の設定を確認する

これらの設定を正しく行うことで、Codex のすべてのセッション（ターン、ツール呼び出し、トークン使用量、サブエージェントの階層）が完全なトレースとして記録されます。Claude Code や Cursor などの他の AI エージェント向けにも同様のセットアップが可能であり、開発プロセスの透明性向上に直結します。