langsmith

LangSmith

このスキルを使う場面

• ユーザーがすでに LangSmith を選んでいて、トレース、評価、レビュー、プロンプトの所有管理、またはトレース伝播に必要な最小限の情報を求めている場合。
• 依頼に LangChain のトレース、@traceable / traceable、wrap_openai / wrapOpenAI、アノテーションキュー、実行ツリー、トレース ID、データセット、または 実験の比較 が含まれている場合。
• チームが、変更に デバッグ用トレース、オフライン評価ゲート、オンラインレビュ​​ーキュー、Prompt Hub / プロンプトレジストリ の作業、または 複数サービスにまたがるリネージ のどれが必要か判断する必要がある場合。
• ユーザーがすでに LangSmith をある程度設定しているものの、まだ確信が持てず、監査 / ギャップレビュー が必要な場合。

次の場合は、このスキルを主要なワークフローとして使わないでください。

• 実際の作業が 一般的なダッシュボード / アラート / SLO / テレメトリの所有管理 → monitoring-observability
• 実際の作業が 既存ログの根本原因のトリアージ → log-analysis
• 実際の作業が コードレベルでの再現 / バグの切り分け → debugging
• 実際の作業が デプロイ / ロールアウトの調整 → deployment-automation
• 実際の作業が 一般的なエクスポート済みメトリクスの解釈や KPI の統合 → data-analysis
• 実際の作業が 実行時のガードレール / 承認 / ポリシーミドルウェア → 該当するセキュリティまたはポリシーのスキル

基本的な考え方

langsmith は、巨大な SDK 百科事典ではなく、ワークフローパケットのルーターとして機能させてください。

1. API を挙げる前に、依頼の種類を分類します。
2. 主要パケットを 1 つ選びます。
3. 問いに答えるために必要な、最小限の計装 / 評価 / レビューの範囲を選びます。
4. 簡潔な運用者向け概要を提示します。
5. 関連するオブザーバビリティ、デバッグ、デプロイ、ポリシーの作業は、速やかに別のスキルへ振り分けます。

パケットを選ぶ前に、次のサポートドキュメントを読んでください。

• references/intake-packets-and-route-outs.md
• references/modes-and-routing.md
• references/python-sdk.md
• references/typescript-sdk.md
• references/cli.md

手順

ステップ 1：依頼を正規化する

まず、プロンプトを次の受付パケットに変換します。

langsmith_packet:
  primary_packet: trace-debug | eval | review | prompt-registry | propagation | audit
  app_shape: chat | rag | tool-calling | agent | batch-job | multi-service | mixed | unknown
  runtime: python | typescript | mixed | cli-only | unknown
  request_type: setup | debug | pre-ship gate | production review | prompt decision | cross-service tracing | audit
  current_evidence: traces | datasets | evaluators | feedback queues | prompt versions | exported runs | none
  confidence_problem: missing traces | noisy traces | no regression gate | weak review rubric | prompt drift | broken lineage | mixed | unknown
  route_after: stay-here | monitoring-observability | log-analysis | debugging | deployment-automation | data-analysis

実行に使う主要パケットを 1 つ選びます。2 つが候補に見える場合は、最も早く不確実性を減らせる方を選びます。

ステップ 2：パケットを選ぶ

パケット	使用する場面	主な出力	典型的なシグナル
trace-debug	実際の問いが「何が起きたのか？」の場合	トレースデバッグパケット	可視性の不足、ラッパー / デコレーター、トレースの網羅性、メタデータの管理
eval	変更の出荷前、または回帰に対する確信が必要な場合	評価パケット	データセットの作成、評価器、実験、ベースラインと候補の比較
review	トレースは存在するものの、本番環境での信頼性が低い場合	レビューパケット	アノテーションキュー、フィードバック基準、人によるスコアリング、インラインレビュー
prompt-registry	プロンプト / バージョンの所有管理がボトルネックになっている場合	プロンプトパケット	Prompt Hub、プロンプトのバージョン、Git 同期、プロンプトのバリエーションの比較
propagation	1 つのリクエストがサービス、ジョブ、ツール、またはエージェントにまたがる場合	伝播パケット	親 / 子のトレース ID、サービス間ヘッダー、複数ホップにまたがるリネージ
audit	LangSmith が導入されているものの、まだ役立っていない場合	監査パケット	ノイズの多いトレース、ID の欠落、評価の不在、プロンプトの所有管理が不明確

パケット選択のルール：

• チームが実行ツリーを説明できない場合は、trace-debug を優先します。
• 次のリスクが回帰ゲートなしで出荷することなら、eval を優先します。
• 実ユーザー向けの出力に、人による品質フィードバックや構造化された品質フィードバックが必要なら、review を優先します。
• プロンプト / バージョンの選択が実際のボトルネックである場合に限り、prompt-registry を優先します。
• 1 つのリクエストが単一のサービス境界を越えて広がる場合は、propagation を優先します。
• システムにすでに「LangSmith がある」にもかかわらず、まだ確信が持てない場合は、audit を優先します。

ステップ 3：役に立つ最小限の範囲を選ぶ

範囲	使用するケース	強み	リスク
プロバイダーラッパー（wrap_openai、wrap_anthropic、wrapOpenAI）	モデル呼び出しを手早く網羅する必要がある	トレースをすぐに確認できる	単独で使用すると、より高レベルのワークフローコンテキストを捉えられない
デコレーター／traceable()	アプリ関数の周囲に名前付きスパンが必要	スパンの境界が明確で、再利用可能	それでも意図的な配置が必要
手動のトレースブロック／トレーシングコンテキスト	対象を限定した可視化や一時的な可視化が必要	監査や疑わしいブロックの調査に適している	計測が不十分になりやすい
アノテーションキュー＋フィードバック基準	構造化された人によるレビューが必要	評価基準とレビューフローを維持できる	レビューの責任者は別途設計する必要がある
データセット＋実験ワークフロー	ベンチマークやリグレッションチェックが必要	リリース前の比較ができる	範囲を限定しないと、一般的な評価理論に流れやすい
CLI のエクスポート／一覧表示／取得フロー	計測よりも監査／エクスポート操作が必要	スクリプトや調査に適している	計測設計の代わりにはならない
サービス間の伝播ヘッダー／メタデータ	エンドツーエンドの系譜が必要	親／子のコンテキストを維持できる	サービス境界で忘れやすい

ルール：

• 現在の質問に答える最小限の範囲を優先してください。
• プロジェクト／ワークスペース／環境のグループ分けを必ず明記してください。
• 後で人や下流ツールが実行をレビューする場合は、run_id、trace_id、メタデータを保持してください。
• CLI、ワーカー、短時間で終了するジョブでは、シャットダウン時のフラッシュ／待機の動作を含めてください。

ステップ 4：必要な場合にのみ評価またはレビューのレイヤーを選ぶ

レイヤー	使用するケース	備考
決定論的評価／コード評価	出力を機械的にチェックできる	構造／事実に関するルールに最適な第一選択肢
LLM による判定（openevals）	品質が主観的、または参照情報が少ない	役立ちますが、正解そのものではありません
人によるレビュー	影響が大きい、またはニュアンスが重要	評価基準、レビュアー、実施頻度が必要
ペアワイズ比較	2 つのプロンプト／モデル／アプリのバージョンを比較する	ベースラインと候補の判断に適している
オンライン評価	本番トラフィックの継続的なスコアリングが必要	明示的なアラート／レビューの運用ルールと組み合わせる

あるレイヤーがほかのレイヤーを置き換えるかのように装わないでください。

ステップ 5：簡潔な LangSmith ブリーフを 1 つ返す

デフォルトの回答形式：

## LangSmith brief
- Packet: trace-debug | eval | review | prompt-registry | propagation | audit
- App shape: ...
- Runtime: ...
- Current evidence: ...

## Chosen surface
- wrappers / decorators / manual trace / dataset+experiment / review queue / prompt registry / propagation headers

## Required config
- `LANGSMITH_API_KEY`
- project/workspace/environment
- endpoint/workspace overrides if self-hosted

## Required IDs / metadata
- `run_id`, `trace_id`, tags, metadata fields, user/session identifiers as needed

## Verification step
- one trace query, one experiment comparison, one queue review check, or one prompt-version sanity check

## Route-out
- next neighboring skill if the bottleneck moves

簡潔にまとめてください。目的は、SDK に関する説明を大量に並べることではなく、次に着手する最小限の成果物を 1 つユーザーに残すことです。

ステップ 6：パケット固有のヒューリスティクス

trace-debug の場合

• 可視化が不足している箇所から始めます：アプリのスパン、ツール呼び出し、検索、プロバイダー呼び出し、またはワーカー境界です。
• 何でも盲目的にトレースするのではなく、ラッパーに少数の価値の高いデコレーターを組み合わせる方法を優先します。
• 計測が入ったらチームが最初に実行すべきトレースクエリ／フィルターを返します。

eval の場合

• リスクのある変更を反映する最小限のデータセットを定義します。
• 決定論的チェックと、LLM による判定または人によるレビューを分けます。
• ベースライン／候補の比較、実験名、並行実行数／コストの上限、リリース可否の判断ポイントを明記します。

review の場合

• フィードバックキー、スケールの意味、レビュアーの責任者、キューの実施頻度を定義します。
• 後でフィードバックを正しい成果物に関連付けられるよう、run_id／trace_id を保持します。
• 問題が出力レビューの範囲を超える場合は、より広範なサポート運用ワークフローとして別途扱います。

prompt-registry の場合

• プロンプトの管理主体を Prompt Hub／LangSmith にするか、Git／アプリ設定を正とするかを明確に決めます。
• プロンプトのバージョンを評価または実験に結び付け、レジストリを独立したものとして扱わないでください。
• 公開ハブの参照があくまで参考であり、チームの信頼できる情報源ではない場合は、その旨を明確にします。

propagation の場合

• 親／子のヘッダー、メタデータの引き渡しルール、トレースコンテキストを保持する必要があるサービスを明記します。
• 分散システムの信頼性やアラートに関する懸念は、適切な場合には汎用的なオブザーバビリティの領域で扱います。

audit の場合

• 欠けているカバレッジ、不適切なメタデータ、評価の欠如、弱いレビューの流れ、プロンプト／バージョンの曖昧さ、フラッシュや系譜の不具合を、重大度順に並べます。
• 大規模な再インストール計画ではなく、最初の段階的な改善策を提案します。

ステップ 7：積極的に別の領域へ案内する

LangSmith が主なボトルネックではなくなったら、すぐに切り替えます。

• 汎用テレメトリー／ダッシュボード／アラート／SLO → monitoring-observability
• 既存ログを使った根本原因のトリアージ → log-analysis
• 再現とバグの切り分け → debugging
• ロールアウト／デプロイ／環境の昇格 → deployment-automation
• エクスポートしたメトリクス、実験、KPI の解釈 → data-analysis
• ポリシー／承認／ランタイムのガードレール → 該当するセキュリティまたはポリシーのスキル

例

例 1：トレースデバッグ用パケット

プロンプト：

この FastAPI RAG サービスに LangSmith を追加して、リトリーバーの変更後に回答品質が低下した原因をデバッグできるようにしてください。

適切な回答の構成：

• trace-debug を選択する
• 検索／ツールを可視化する必要がある場合は、ラッパーと対象を絞った上位レベルのスパンを推奨する
• プロジェクト／タグ／メタデータと、短時間で終了する実行のためのフラッシュ手順を定義する
• 汎用的なサービス健全性の可観測性は別の領域へ案内する

例 2：評価用パケット

プロンプト：

このプロンプトを書き換えてリリースする前に、ベースライン、候補、主観的な品質を評価するジャッジを 1 つ用意した LangSmith の評価ワークフローを構築してください。

適切な回答の構成：

• eval を選択する
• データセット、評価者の組み合わせ、実験の命名、検証手順を定義する
• 決定論的なチェックと LLM による評価、人間によるレビューを分ける
• ロールアウトのオーケストレーションは対象外にする

例 3：レビュー用パケット

プロンプト：

LangSmith のトレースはすでにありますが、サポート責任者はまだ AI アシスタントを信頼していません。人間による採点を含むレビューのワークフローを設定してください。

適切な回答の構成：

• review を選択する
• フィードバックキー、評価基準、キューの担当者、run-ID の保持を定義する
• 汎用的なプロンプト管理ではなく、レビューのワークフローに沿った回答にする

例 4：プロンプトレジストリ用パケット

プロンプト：

これらのプロンプトは LangSmith Prompt Hub に置くべきですか、それとも Git に残すべきですか？

適切な回答の構成：

• prompt-registry を選択する
• プラットフォーム管理のプロンプトと Git 管理のプロンプトを比較する
• その選択を実験やリリースの確実性と結び付ける
• Prompt Hub が任意である場合は、その点を正直に伝える

例 5：伝播用パケット

プロンプト：

1 回のチャットリクエストがワーカーやツールに分岐します。LangSmith で 1 つのトレースを維持するにはどうすればよいですか？

適切な回答の構成：

• propagation を選択する
• 親／子 ID、メタデータの伝播、サービス境界を定義する
• 必要に応じて、汎用的な分散システムの可観測性は別の領域へ案内する

ベストプラクティス

1. SDK の呼び出しではなく、パケットから始めます。
2. LangSmith はトレース／評価／レビューの基盤として扱い、本番環境の制御プレーン全体として扱わないでください。
3. run_id、trace_id、タグ、メタデータを意図的に保持します。
4. 現在の質問に答えられる、必要最小限の範囲を選びます。
5. 決定論的なチェック、LLM による評価、人間によるレビューを区別します。
6. Prompt Hub が任意または参考のみである場合は、明示します。
7. スクリプト、ワーカー、cron 形式のジョブでは、フラッシュ／待機の動作を含めます。
8. 最後に検証手順を 1 つと、別の領域へ案内する項目を 1 つ示します。

参考資料

• references/intake-packets-and-route-outs.md
• references/modes-and-routing.md
• references/python-sdk.md
• references/typescript-sdk.md
• references/cli.md
• 公式ドキュメント：https://docs.langchain.com/langsmith
• SDK リポジトリ：https://github.com/langchain-ai/langsmith-sdk
• OpenEvals：https://github.com/langchain-ai/openevals