experiments

エージェントの実験を実行する

実験は、デプロイ前に実施するバッチテストです。データセットを使ってアプリケーションを実行し、再利用可能な評価器で出力を比較します。プロンプトやモデルの比較、回帰テスト、ベンチマーク、CI の品質ゲートに適しています。

本番環境の評価リクエストを引き継ぐ

ユーザーが本番環境のトレースやスレッドを採点したい場合、本番環境の品質を監視したい場合、または安全でないトラフィックをブロックしたい場合は、このワークフローは適切ではありません。

1. online-evaluations スキルが利用可能な場合は、読み込んで今すぐ従ってください。

2. それ以外の場合は、次のコマンドでインストールするようユーザーに伝えてください。

   npx [email protected] add langwatch/skills/online-evaluations
   

このスキルを使ってモニターやガードレールを設定しないでください。

実験とシナリオ

測定可能な結果が得られる、単一の入力と出力の例を多数扱う場合は、実験を使用してください。エンドツーエンドの複数ターンにわたる動作やツール呼び出しのシーケンスには、scenarios スキルを使用してください。

範囲を決める

「自分のエージェントをテストして」といった一般的なリクエストの場合：

1. エージェントのコード、システムプロンプト、ツール、関連する git 履歴を確認します。
2. 最も回帰が起きやすい動作を特定します。
3. ドメイン固有のデータセットを作成します。
4. 目的の動作を測定する評価器を選ぶか、候補の中から最適なものを選ぶことが目的なら比較を行います。
5. 実際に実験を作成し、実行します。
6. 結果を解釈し、具体的な改善策を提案します。

対象が明確なリクエストの場合は、その動作に重点を置き、作成した実験を実行してください。

プランの制限

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 のフラグを推測せず、まずドキュメントを読んでください。

シェルが利用できない場合は、同じ Markdown をプレーン HTTP で取得してください。ドキュメントのパスに .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 種類があります。

• チーム／共有プロジェクト：組織内の実際のプロジェクトです。評価、実験、プロンプト、データセット、シミュレーション、計測は、必ずこれらのいずれかを対象にしてください。
• 個人用プロジェクト：1 人のユーザーに紐づく、非公開の「My Workspace」というスクラッチスペースです。ユーザーの評価、実験、本番トレースをここに送信してはいけません。個人的な探索にのみ使用するもので、実際のプロジェクトと間違えるおそれがあります。

認証方法は、次の 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 のどこで確認できるかを伝えてください。

コードを書く前に、実験のドキュメントを読んでください。

langwatch docs evaluations/experiments/overview
langwatch docs evaluations/experiments/sdk

ドメイン固有のデータセットを作成する

例は、アプリケーションが実際に行うことに合致している必要があります。まず、システムプロンプト、関数シグネチャ、ツール、ナレッジソースを確認してください。

良い例は、このアプリケーションへの実際のリクエストに似ており、通常のケース、エッジケース、過去に失敗したケースを網羅しています。アプリケーション自体がトリビアシステムでない限り、「2+2は？」や「フランスの首都は？」のような一般的なトリビアは使わないでください。

既存の LangWatch データセットが適切であれば、langwatch dataset list --format json と langwatch dataset get --help を使って調べてください。そうでない場合は、コードでデータセットを作成するか、datasets スキルを使用してください。

実験を作成する

コードベースに合った SDK を使用してください。認証情報は環境変数に保存し、プロジェクトで既に使用されている依存関係マネージャーを使ってください。

Python

import langwatch
import pandas as pd

dataset = pd.DataFrame([
    {
        "input": "A realistic request for this application",
        "expected_output": "The expected behavior",
    },
])

experiment = langwatch.experiment.init("agent-regression")

for index, row in experiment.loop(dataset.iterrows()):
    response = my_agent(row["input"])
    experiment.evaluate(
        "ragas/response_relevancy",
        index=index,
        data={"input": row["input"], "output": response},
        settings={"model": "openai/gpt-6-luna", "max_tokens": 2048},
    )

TypeScript

import { LangWatch } from "langwatch";

const langwatch = new LangWatch();
const dataset = [
  {
    input: "A realistic request for this application",
    expectedOutput: "The expected behavior",
  },
];

const experiment = await langwatch.experiments.init("agent-regression");

await experiment.run(dataset, async ({ item, index }) => {
  const response = await myAgent(item.input);
  await experiment.evaluate("ragas/response_relevancy", {
    index,
    data: { input: item.input, output: response },
    settings: { model: "openai/gpt-6-luna", max_tokens: 2048 },
  });
});

評価器を選ぶ前に langwatch docs evaluations/evaluators/list を読み、評価器の型スラッグは記憶に頼らず、必ず langwatch evaluator types --format json から取得してください。評価でスラッグと expected の一覧を示す validation_error が発生した場合は、その一覧に基づいて修正し、一度だけ再試行してください。適切であれば、プロジェクトの既存の評価器を再利用してください。スコアリング関数は実験の一部であり、実験そのものではありません。

ターゲットを比較して勝者を選ぶ

評価器は「この出力は合格か？」に答えます。比較は「どれがより良いか？」に答えます。主観的な品質を評価する場合、候補を並べて判定者に順位付けさせるほうが、それぞれを個別に絶対評価するより有益なことが通常です。

ループ内で候補ごとにターゲットを1つ登録し、その後、行を一度だけ比較してください。その行の出力を記録したターゲットはすべて候補となるため、候補名を二度指定する必要はありません。また、判定結果はその行に記録されるため、追加のログ出力なしで結果ページに表示されます。

Python

for index, row in experiment.loop(dataset.iterrows()):
    with experiment.target("gpt-6-luna"):
        experiment.log_response(call_gpt(row["input"]))

    with experiment.target("claude-sonnet-5"):
        experiment.log_response(call_claude(row["input"]))

    verdict = experiment.compare(index, input=row["input"])

非同期ループ内では、同じオプションを受け取る experiment.acompare(...) を await してください。

TypeScript

await experiment.run(dataset, async ({ item, index }) => {
  await Promise.all([
    experiment.withTarget("gpt-6-luna", () => callGpt(item.input)),
    experiment.withTarget("claude-sonnet-5", () => callClaude(item.input)),
  ]);

  const verdict = await experiment.compare({ index, input: item.input });
});

既知の正解を golden に渡すと、すべての候補をその正解と照らし合わせて判定します。golden を省略すると（これがデフォルトです）、候補はそれぞれ単独で評価されます。

verdict.status を読み取り、次の5つの結果を区別してください。

• decided：判定者が勝者を選び、verdict.winner にその名前が記録されています。
• tie：判定者は候補を比較しましたが、他より優れた候補はないと判断しました。
• inconclusive：勝者が決まりませんでした。デフォルトでは候補の順序を逆にして2回目の判定を行うため、2回の結果が食い違った場合に発生します。
• skipped：その行の出力が2つ未満だったため、判定者は実行されませんでした。
• error：判定者が失敗したため、候補について何も測定されていません。

引き分け、結論が出なかった行、エラーになった行は、それぞれ異なる結果です。これらを互いに同じものとして報告すると、実行時に行われていない測定を行ったと主張することになります。

prompt を設定すると、判定者のプロンプト全体が置き換えられます。そこでは {input}、{golden}、{candidates} のプレースホルダーを使用できます。ユーザーから独自のプロンプトを求められない限り、設定しないでください。設定しない場合、各行に付随する内容に合ったプロンプトを判定者が使用できるためです。その他の判定者オプションについては、langwatch docs evaluations/experiments/sdk を参照してください。

実行して確認する

実験は必ず実行してください。未実行の実験は未完成です。

• Python スクリプト：プロジェクトの Python 環境で実行してください。
• ノートブック：たとえば jupyter nbconvert --to notebook --execute を使い、すべてのセルを実行してください。
• TypeScript：たとえば pnpm exec tsx experiment.ts のように、プロジェクトのパッケージマネージャーで実行してください。

実行後、CLI で結果を確認してください。

langwatch experiment list --format json

インストール済みのバージョンで、より具体的な読み取りや実行の方法が CLI に用意されている場合は、使用前に langwatch experiment --help で確認してください。

コンサルタントモード

初期成果を提供した後は、ユーザーが最大限の価値を得られるよう、コンサルタントモードに移行します。

フェーズ 1：まず読む。 コンテンツを生成する前に、コードベースを最初から最後まで読みます（すべてのシステムプロンプト、関数、ツール定義）。エージェント関連の変更について git の履歴を確認します（まず git log --oneline -30 を実行し、次にプロンプト、エージェント、評価に関連するコミットを詳しく調べます。コミットメッセージに記された WHY は WHAT より重要です）。また、ドメインの背景を理解するため、README とコメントも読みます。

フェーズ 2：すぐにできる改善。 得られた情報をもとに、最善を尽くしてコンテンツを生成します。テストを実行して改善を重ねますが、同じ失敗に対する試行は 2 回までにとどめ、再実行するのではなく、何が妨げになっているかを報告します。動作するものをユーザーに示します。

フェーズ 3：さらに掘り下げる。 フェーズ 2 が完了したら、提供した内容を要約し、コードベースに基づいた具体的な改善案を 2～3 件提案します。たとえば、ドメイン固有のエッジケース、専門家による用語の確認や実データが必要な領域、統合ポイント（API、データベース、ファイルアップロード）、あるいはテストでカバーすべき git 履歴に見られる回帰パターンです。「X と Y のどちらのシナリオを追加しますか？」「Z が繰り返し問題になっているようです。回帰テストを追加しますか？」「実際の顧客からの問い合わせを使えますか？」のように、自由回答ではなく、選択肢のある簡単な質問をします。「これで十分です」と言われたら、その意向を尊重し、簡潔に締めくくります。

フェーズ 1 と 2 を始める前に許可を求めてはいけません。まず価値を提供してください。一般的な質問や、提案を多くしすぎることは避けてください。すべて実際のドメインに即した内容にしてください。

よくある間違い

• このスキルを使って、本番環境のモニタリングやガードレールを設定しないでください。
• バッチ実行をオンライン評価と呼ばないでください。
• プレースホルダーのデータセットを使用しないでください。
• 結論が出ていない比較やエラーになった比較を、引き分けと報告しないでください。
• インストール済みのドキュメントが参照できる場合、SDK の API を推測しないでください。
• 実験を書いただけで終わらせないでください。実行し、実際の結果を確認してください。