level-up

エージェントを次のレベルへ

このスキルでは、トレース、プロンプトのバージョン管理、評価実験、エージェントのシミュレーションテストを含む LangWatch スタック全体をエージェントに設定します。各手順は前の手順を基に進みます。

プランの上限

LangWatch の無料プランでは、プロンプト、シナリオ、評価器、実験、データセットに上限があります。上限に達すると、API はアップグレードリンクとともに "Free plan limit of N reached..." を返します。

対処方法：

• 上限内で作業します。該当する種類のリソースが3つまで許可されている場合は、10個ではなく、意味のあるものを3つ作成します。
• 作成するものすべてに価値を持たせます。それぞれが明確な価値を示すようにします。
• まず、動作するものを見せます。上限に達した場合は、達成した内容をまとめ、プランをアップグレードすると上限が増えることを伝えます。プラットフォームのサブスクリプション設定、または CLI がセルフホストのエンドポイントを参照している場合はライセンス設定を案内します。CLI が実際に使用しているエンドポイントを確認します。これは .env、プロセス環境、または保存済みの CLI 設定から取得される場合があります。
• 上限に空きを作るために既存のリソースを削除したり、上限を回避するために既存のリソースを転用したりしないでください。

前提条件

langwatch docs <path> を使って、ドキュメントを Markdown として読みます。役立つ入口は次のとおりです。

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

langwatch --help と langwatch <subcommand> --help でコマンドを確認します。list コマンドと get コマンドは、機械可読な出力を得るために --format json を受け付けます。すべての list コマンドでは、行数を制限する --limit <n> と、回答の一部を読み取る --jq <expr> を使用できます。ページ分割された list の回答はエンベロープ形式なので、行配列を通じて行数を数えます（--jq '.traces | length'）。総数は .pagination.total で確認します。--jq length のみを指定すると、行数ではなくエンベロープのフィールド数が数えられます。SDK API や CLI フラグを推測するのではなく、まずドキュメントを読みます。

シェルが使えない場合は、プレーン HTTP 経由で同じ Markdown を取得します。任意のドキュメントパスに .md を追加します（例：https://langwatch.ai/docs/integration/python/guide.md）。インデックス：https://langwatch.ai/docs/llms.txt。シナリオのインデックス：https://langwatch.ai/scenario/llms.txt

このスキルを実行中に問題が起きたり、内容が分かりにくかったりした場合（コマンドの不具合、実際の動作と異なるドキュメント、回避策が必要だったエラーなど）は、ユーザーの許可を得て、--title と --summary（または --session <transcript.jsonl>）を付けて npx --yes langwatch report --user-approved を実行し、LangWatch チームに報告します。報告内容は、修正すべき項目に直接反映されます。ログインや API キーは不要です。--user-approved を指定しない限り何も送信されません。また、--dry-run を指定すると、送信せずに正確なペイロードを表示します。タイトル、概要、トランスクリプトは、送信前にパターンに基づいてローカルでスクラブされます。対象はシークレットと API キーに加え、メールアドレス、電話番号、カード番号、パブリック IPv4 アドレスです。いずれのパターンにも一致しない内容は、--email で指定した連絡先アドレスを含め、そのまま送信されます。--session を使う場合は、必ず先に --dry-run を実行し、ユーザーにペイロードを確認してもらってください。トランスクリプトには、ユーザーが確認していない内容が含まれるためです。オプションについては npx --yes langwatch report --help を参照してください。

プロジェクトと API キー：個人用ではなく、実際のプロジェクトを対象にしてください。

LangWatch のプロジェクトには2種類あります。

• チーム／共有プロジェクト：組織内の実際のプロジェクトです。評価、実験、プロンプト、データセット、シミュレーション、インストルメンテーションは、必ずこれらのいずれかを対象にする必要があります。
• 個人プロジェクト：単一ユーザーに紐づく、プライベートな「マイワークスペース」の作業用スペースです。ユーザーの評価、実験、本番トレースをここに送信しないでください。ここは個人的な探索専用であり、実際のプロジェクトと取り違える可能性があります。

認証方法は2種類あります。

• .env 内のプロジェクト API キー（LANGWATCH_API_KEY）：これらのスキルで使うすべての処理に必要な認証情報です。実在する 1 つのプロジェクトにスコープが限定されています。これがデフォルトです。ユーザーが明示的に別の方法を求めない限り、こちらを優先してください。
• langwatch login --device（AI ツール／SSO）：コーディングアシスタント（langwatch claude、langwatch codex など）をラップするための個人用デバイスセッションです。評価、プロンプト、データセット、シナリオ、SDK の計装には使用しません。また、個人用ワークスペースを参照します。これらのスキルで作業を設定するために実行しないでください。

したがって、これらのスキルでプロジェクトを読み書きする場合は、実在する共有プロジェクトの LANGWATCH_API_KEY が CLI から利用できることを確認してください。ローカルではプロジェクトの .env に設定します。CI ではランナーがプロセス環境に注入し、CLI はどちらからでも読み取ります。新しいキーを求める前に、この変数がすでに設定されているか確認し、CLI に値を読み取らせてください。値を表示、コピー、送信してはいけません。プロジェクトを選択するために langwatch login を実行してはいけません。また、個人用プロジェクトをデフォルトにしてはいけません。同じ場所で LANGWATCH_ENDPOINT も確認してください。設定されている場合、そのプロジェクトはセルフホスト可能なインスタンス上にあり、CLI は app.langwatch.ai ではなく、そのエンドポイントを使用します。

読み取った内容を、そのまま伝えるわけではありません。 これらのスキルは作業メモであり、読者向けの文章ではありません。プロジェクト自身の .env から LANGWATCH_API_KEY と LANGWATCH_ENDPOINT を読み取り、作業場所を把握してください。そのファイルからほかのものは読み取らないでください。そこにはデータベース、クラウド、プロバイダーの認証情報が含まれており、あなたが扱うべきものではありません。また、読み取った値はすべて、あなたのコンテキストやコマンド出力に取り込まれる可能性があります。回答に含めてはいけないのは、あなたが実行されているマシンについて説明する情報です。ワークスペース内のパス、コンテナのポート、このワーカーが接続するアドレスなどが該当します。そうした情報は作業の実施方法を示すものであって、作業の成果を示すものではありません。また、こちらのホスト情報は読者には何の意味もありません。何を行い、LangWatch のどこで確認できるかを伝えてください。

コンサルタントモード

すべての手順を完了したら、設定した内容をすべて要約し、コードベースから把握した内容に基づいて、さらに深掘りする方法を 2～3 個提案してください。詳しいガイダンス：

最初の成果を届けた後、ユーザーが最大限の価値を得られるよう支援するコンサルタントモードに移行してください。

フェーズ 1：まず読む。 コンテンツを生成する前に、コードベース全体（すべてのシステムプロンプト、関数、ツール定義）を読み、エージェント関連の変更について Git 履歴を調べてください（git log --oneline -30 を実行してから、プロンプト／エージェント／評価関連のコミットを掘り下げます。コミットメッセージにある WHY は WHAT より重要です）。また、ドメインの背景を把握するため、README とコメントも読んでください。

フェーズ 2：すぐに役立つ成果。 把握した内容に基づいて、最善を尽くしたコンテンツを生成してください。テストを実行して改善を重ねますが、同じ失敗に対する試行は 2 回までにとどめ、それ以上繰り返さず、妨げとなっている要因を報告してください。動作するものをユーザーに示してください。

フェーズ 3：さらに深掘りする。 フェーズ 2 の成果が出たら、提供した内容を要約し、コードベースに基づく具体的な改善案を 2～3 個提案してください。対象には、ドメイン固有のエッジケース、専門用語の知識や実データが必要な領域、統合ポイント（API、データベース、ファイルアップロード）、または Git 履歴で繰り返し見られ、テストカバレッジが必要な回帰パターンなどがあります。選択肢を示す簡潔な質問をしてください。自由回答式の質問は避けます（「X と Y のどちらのシナリオを作成しますか？」「Z が繰り返し発生していることに気付きました。回帰テストを追加しますか？」「実際の顧客からの問い合わせをテストに使えますか？」など）。「これで十分です」という意思を尊重し、きちんと締めくくってください。

フェーズ 1 と 2 を始める前に、許可を求めてはいけません。まず価値を提供してください。一般的な質問をしたり、提案を多く出しすぎたりしてはいけません。一般的なデータセットを生成してはいけません。すべて、実際のドメインを反映した内容にしてください。

ステップ 1：トレースを追加する

LangWatch のトレース機能を追加し、すべての LLM 呼び出し、コスト、レイテンシーを記録します。

1. このプロジェクトのフレームワークに対応する統合ガイドを読みます。

   langwatch docs                                 # Browse the index to find the right page
   langwatch docs integration/python/guide        # Python (or pick your framework)
   langwatch docs integration/typescript/guide    # TypeScript (or pick your framework)
   

2. LangWatch SDK をインストールします（pip install langwatch または npm install langwatch）。
3. フレームワーク固有のガイドに従って計測機能を追加します。
4. .env に LANGWATCH_API_KEY を追加します。

確認：アプリケーションを短時間実行し、トレースが表示されることを確認します。

langwatch trace search --limit 5 --format json

ステップ 2：プロンプトをバージョン管理する

ハードコードされたプロンプトを LangWatch Prompts CLI に移し、バージョン管理と共同作業を可能にします。

1. Prompts CLI のドキュメントを読みます。

   langwatch docs prompt-management/cli
   

2. 初期化します：langwatch prompt init
3. プロンプトを作成します：コード内の各プロンプトに対して langwatch prompt create <name> を実行します。
4. アプリケーションのコードを更新し、ハードコードされた文字列の代わりに langwatch.prompts.get("name") を使用します。
5. 同期します：langwatch prompt sync

確認：langwatch prompt list を実行します（または https://app.langwatch.ai の Prompts セクションを確認します）。

プロンプトをコードにハードコードしないでください。prompts.get() の周囲に try/catch によるフォールバックを追加しないでください。

ステップ 3：評価実験を作成する

多数の例を用いてエージェントの品質を測定するバッチ評価を構築します。

1. experiments SDK のドキュメントを読みます。

   langwatch docs evaluations/experiments/sdk
   

2. エージェントのコードを分析し、その動作を理解します。
3. エージェントのドメインに合わせたデータセットを 10～20 件作成します（汎用的な例は使用しないでください）。
4. 実験ファイルを作成します。
   • Python：langwatch.experiment.init()、評価ループ、評価器を含む Jupyter ノートブック
   • TypeScript：langwatch.experiments.init() と evaluation.run() を含むスクリプト
5. 少なくとも 1 つの評価器を含めます（品質評価には LLM-as-judge が適しています）。

確認：実験を実行し（jupyter nbconvert --to notebook --execute experiment.ipynb または npx tsx experiment.ts）、結果が LangWatch Experiments ビューに表示されることを確認します。

ステップ 4：エージェントシミュレーションテストを追加する

現実的な複数ターンの会話でエージェントの動作を検証するシナリオテストを作成します。

1. Scenario のドキュメントを読みます。

   langwatch scenario-docs                  # Browse the index
   langwatch scenario-docs getting-started  # Getting Started guide
   langwatch scenario-docs agent-integration
   

2. Scenario SDK をインストールします（pip install langwatch-scenario または npm install @langwatch/scenario）。
3. AgentAdapter、UserSimulatorAgent、JudgeAgent を使用してシナリオテストを記述します。
4. JudgeAgent では正規表現による照合ではなく、セマンティックな基準を使用します。

確認：テストを実行し（pytest -s または npx vitest run）、成功することを確認します。

独自のテストフレームワークを決して作らないでください。@langwatch/scenario / langwatch-scenario を使用してください。

よくある間違い

• どのステップも省略しないでください。各ステップは前のステップを土台としています。
• 実験で汎用的なデータセットを使用しないでください。エージェントのドメインに合わせてください。
• プロンプトをハードコードしないでください。Prompts CLI を使用してください。
• テストフレームワークを独自に作らないでください。Scenario を使用してください。
• 確認手順を省略しないでください。各ステップの後にアプリケーション／実験／テストを実行してください。
• コードを書く前に、必ず langwatch docs ... / langwatch scenario-docs ... を使ってドキュメントを読みます。過去のフレームワークバージョンの記憶に頼って作業しないでください。