langsmith-trace

LangSmith トレース

エージェントにトレースを追加し、デバッグのためにトレースをクエリします。Python と TypeScript に対応しています。

重要

このスキルは AgentSeek テンプレートのバックエンド（LangGraph ＋ ミドルウェアスタック）に合わせて調整されています。LangSmith の一般的な概念については、上流の langsmith-skills リポジトリを参照してください。

注意

CLI フラグとして --api-key を渡したり、シェルコマンドやツール呼び出しで API キーを公開したりしないでください。 CLI は環境から LANGSMITH_API_KEY を自動的に読み込みます。--api-key <value> を使うと、シェル履歴、プロセス一覧、エージェントのツール呼び出しログに秘密情報が漏洩します。シェルプロファイルまたは .env ファイルに設定した環境変数を必ず使用してください。

インストールとセットアップ

1. CLI をインストールする

curl -sSL https://raw.githubusercontent.com/langchain-ai/langsmith-cli/main/scripts/install.sh | sh

バイナリは ~/.local/bin/langsmith にインストールされます。インストール後に langsmith が見つからない場合は、シェルプロファイルに以下を追加してください。

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. API キーを設定する（環境変数のみ）

~/.zshrc（またはテンプレートの .env ファイル）に追加します。ユーザー自身のキーを入力してください。

export LANGSMITH_API_KEY=<your-key-here>  # starts with lsv2_pt_

キーの形式は lsv2_pt_ で始まる必要があります。キーは https://smith.langchain.com/settings から取得できます。

CLI はこの環境変数を自動的に読み込みます。--api-key フラグは絶対に使用しないでください。 シェルコマンドやツール呼び出しの引数で、キーの値をエコー、表示、または渡さないでください。

3. 確認する

langsmith project list

プロジェクトの JSON 配列が表示されれば、設定は完了です。よくあるエラーは次のとおりです。

• command not found — ~/.local/bin が PATH に含まれていません（手順 1 を参照）
• 401 Unauthorized — キーが間違っているか、有効期限が切れています。LangSmith の設定で再生成してください
• 空の配列 [] — 認証は有効ですが、まだプロジェクトがありません。UI で作成するか、トレースを有効にしたアプリを実行してください

トレースの追加

LangGraph / LangChain アプリ（自動）

環境変数を設定するだけで、コードを変更する必要はありません。

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-key-here>  # must be set; do NOT pass via --api-key flag
export LANGSMITH_PROJECT=my-project  # optional, defaults to "default"

サーバーレス（Python）の場合は、関数の終了前にトレースが確実にフラッシュされるよう、LANGCHAIN_CALLBACKS_BACKGROUND=false も設定してください。

LangChain 以外のアプリ

@traceable デコレーター（Python）または traceable() ラッパー（TypeScript）を使用して、LLM クライアントをラップします。

from langsmith import traceable
from langsmith.wrappers import wrap_openai
from openai import OpenAI

client = wrap_openai(OpenAI())

@traceable
def my_pipeline(question: str) -> str:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": question}],
    )
    return resp.choices[0].message.content

import { traceable } from "langsmith/traceable";
import { wrapOpenAI } from "langsmith/wrappers";
import OpenAI from "openai";

const client = wrapOpenAI(new OpenAI());

const myPipeline = traceable(async (question: string) => {
  const resp = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: question }],
  });
  return resp.choices[0].message.content || "";
}, { name: "my_pipeline" });

トレースのデバッグ（ステップごと）

エージェントの動作を調査する際に推奨されるワークフローです。

ステップ 1：適切なプロジェクトを見つける

langsmith project list

last_run_start_time を確認して、最近アクティビティがあったプロジェクトを見つけます。決めつけないでください。LangGraph アプリは、名前付きプロジェクトではなく "default" プロジェクトをデフォルトで使用します。

ステップ 2：最近のトレースを一覧表示する

langsmith trace list --project default --limit 5

# Or with full hierarchy inline (combines steps 2+3):
langsmith trace list --project default --limit 5 --show-hierarchy

ステップ 3：トレースの階層を取得する

langsmith trace get <trace-id> --project <name>

これにより、実行ツリー全体が返されます。エージェントの実行フローを理解するために使用してください。

ステップ 4：トレース内のすべての実行の入出力を取得する

langsmith run list --trace-ids <trace-id> --project <name> --include-io

すべての実行（LLM 呼び出し、ツール呼び出し、ミドルウェア）の入力と出力が取得できます。

ステップ 5：特定の実行を詳しく調べる

langsmith run get <run-id> --include-io

AgentSeek のトレース構造

テンプレートでは、一般的に次のような階層のトレースが生成されます。

<agent_name> (root chain)
├── SkillsMiddleware.before_agent
├── PatchToolCallsMiddleware.before_agent
├── MemoryMiddleware.before_agent
├── model (chain) ← LLM turn
│   ├── TodoListMiddleware.awrap_model_call
│   ├── SkillsMiddleware.awrap_model_call
│   ├── FilesystemMiddleware.awrap_model_call
│   ├── SubAgentMiddleware.awrap_model_call
│   ├── SummarizationMiddleware.awrap_model_call
│   ├── AnthropicPromptCachingMiddleware.awrap_model_call
│   ├── MemoryMiddleware.awrap_model_call
│   └── ChatOpenAI (llm) ← actual LLM call (inputs/outputs here)
├── TodoListMiddleware.after_model
├── tools (chain) ← tool execution
│   ├── FilesystemMiddleware.awrap_tool_call
│   └── <tool_name> (tool) ← actual tool (inputs/outputs here)
├── model (chain) ← next LLM turn
│   └── ... (same middleware stack)
└── TodoListMiddleware.after_model

要点：

• 実際の LLM 呼び出しは、常に最も内側の ChatOpenAI 実行です
• ツールの結果は <tool_name> 実行内にあります（例：generate_cover、execute）
• ミドルウェアのラッパーは透過的です。遅延は増加しますが、確認したい入出力はリーフノードにあります

注意点

個々の実行における --full と --include-io

問題： データが存在していても、langsmith run get <id> --full で入力と出力が null として返されることがあります。--full は --include-metadata --include-io --include-feedback と同等とドキュメントに記載されていますが、一部の CLI バージョンでは、個々の実行を取得する際の基盤となる API の動作が異なります。

解決策： 特定の実行を調べる場合は、必ず --include-io を明示的に使用してください。

# DO THIS
langsmith run get <run-id> --include-io

# NOT THIS (may return null IO despite docs saying it includes --include-io)
langsmith run get <run-id> --full

--full は trace export と run list では安定して動作しますが、個々の run get 呼び出しでは動作が一貫しません。将来の CLI バージョンで修正された場合でも、--include-io は正しく動作するため、常に安全に使用できます。

--include-io を指定しても入出力が null になる

--include-io を指定しても入力／出力が null で返される場合、プロジェクトで IO ログが無効になっています。テンプレートの .env に次の環境変数がないか確認してください。

LANGCHAIN_HIDE_INPUTS=true    # hides inputs from traces
LANGCHAIN_HIDE_OUTPUTS=true   # hides outputs from traces

デバッグ用に IO のキャプチャを有効にするには、削除するか、false に設定してください。

プロジェクトの混乱

LANGSMITH_PROJECT が明示的に設定されていない場合、LangGraph アプリのトレースは "default" プロジェクトに記録されます。まず必ず langsmith project list を実行し、last_run_start_time を確認して、トレースが実際に記録された場所を特定してください。

ヒント

• 対話型のデバッグで人が読みやすい形式の出力を表示するには、--format pretty を追加してください
• セルフホストの LangSmith インスタンスに接続する場合は、LANGSMITH_ENDPOINT 環境変数を使用してください
• トレースツリー内のミドルウェアの順序は設定可能です。テンプレートによっては、上の図と少し異なる場合があります

CLI リファレンス

コマンドの完全なリファレンス：reference/cli-commands.md