テストとシミュレーション

エージェントのテストは、後付けではなくフレームワークの中核となる機能です。 Agent-Lab には相互に補完する 2 つのハーネスが同梱されており、フレームワーク自体の検証にも、その上に構築したエージェントの検証にも使用できます。

• 統合テストは、testcontainers で必要に応じて起動する実際のインフラ（Postgres、 Redis、Keycloak、埋め込み、ヘッドレス Chrome）に対してシステムを動作させます。外部サービス、データベース操作、ベクトル検索、API エンドポイントをカバーします。
• エージェントシミュレーションは、実際の LLM を相手にエージェントの振る舞いをエンドツーエンドで評価します。 LLM-as-judge によってスコアリングされ、Langfuse と LangWatch で継続的に追跡されます。

統合テストの主な設定は tests/conftest.py にあります。ご自身の環境に合わせてカスタマイズしてください。

注意： 統合テストとシミュレーションは外部サービスを実際に呼び出すため、費用が発生する場合があります。管理された環境で実行し、使用量を監視してください。

統合テスト

Docker（または他のコンテナランタイム）が必要です。このスイートは testcontainers を使って実際のコンテナをプロビジョニングします。

make test_unit         # fast lane: boots the app with no infrastructure
make test_integration  # the full real-infrastructure suite
make test              # both, with coverage (gate: 90%)

初回の実行には数分かかることがあります。Docker イメージと埋め込みモデルは一度だけダウンロードされます。 agent_lab/ のカバレッジは CI（SonarCloud）でチェックされます。

スキャフォールドで生成したプロジェクトも同じ構成です。tests/ には、コンテナを使わないスモークテストと、任意で使える testcontainers のスイートが含まれています。

エージェントシミュレーション

エンドツーエンドのエージェントシミュレーションは tests/simulation/ にあり、実際の LLM プロバイダーを呼び出します。これらには agent_test マークが付いており、デフォルトでは除外されます。次のように実行します。

make test_simulations
# or a single track:
make scenario_simulation
make langwatch_simulation
make langfuse_simulation

相互に補完する 3 つのトラックは、エージェントのブートストラップ用ヘルパー、ジャッジ、 tests/simulation/datasets/ にあるデータセット定義を共有しています。

• tests/simulation/scenario/：langwatch-scenario フレームワークを使った会話型シミュレーションです。ユーザーシミュレーターがエージェントを操作し、ジャッジエージェントがインタラクションをスコアリングします。
• tests/simulation/langfuse/：Langfuse のデータセットを使った、データセット駆動の実験です。各実行ではデータセット定義を同期し、項目ごとにエージェントを呼び出し、クライアント側の LLM-as-judge で出力をスコアリングし、実行結果とスコアを Langfuse に記録して経時的に比較できるようにします。 LANGFUSE_BASE_URL（または非推奨の LANGFUSE_HOST）、LANGFUSE_PUBLIC_KEY、 LANGFUSE_SECRET_KEY が設定されていない場合は自動的にスキップされます。
• tests/simulation/langwatch/：同じデータセット実験を langwatch.experiment を通じて LangWatch にミラーリングし、項目ごとにジャッジのスコアを記録します。定義は単一の統合された simulations データセットに冪等に同期されます（LangWatch の無料プランではプロジェクトあたり最大 3 つのデータセットしか使えないため、dataset 列で元の定義を識別します）。 LANGWATCH_ENDPOINT と LANGWATCH_API_KEY が設定されていない場合は自動的にスキップされます。

各トラックでカバーされるリファレンスエージェントは、coordinator-planner-supervisor、 react RAG、vision/document、ブラウザ自動化、ボイスメモ、adaptive RAG の各エージェントです。

ジャッジとエージェントの LLM 設定

ジャッジ（およびシナリオのユーザーシミュレーター）は、litellm のモデル ID を使い、任意の OpenAI API 互換エンドポイントに接続します。

テスト対象のエージェントは、任意の OpenAI 互換エンドポイント（LAN 内の推論サーバーなど）が提供するデフォルトの LLM で実行され、テストごとに tests/simulation/common/llm_factory.py によってプロビジョニングされます。例外はボイスメモエージェントで、音声によるチャット入力が必要なため OpenAI を使い続けます。埋め込みは引き続き EMBEDDINGS_ENDPOINT のフォールバック（bge-m3 を提供するテスト用 Ollama コンテナ）を使用し、 pgvector のダンプと整合させています。supervisor ベースのスイート（ブラウザ自動化、supervisor）では、エンドポイントがツール呼び出し／構造化出力に対応している必要があります。

評価プラットフォームのセットアップ

make test_simulations（およびトラックごとのターゲット）は、最初に sync_simulation_evals ステップを実行し、設定済みのすべてのプラットフォームにデータセット定義をミラーリングします。さらに Langfuse のサーバー側評価のセットアップ（ジャッジモデル用の LLM 接続、simulation_llm_as_judge 評価器、シミュレーションデータセットごとに 1 つの評価ルール。Langfuse の Evaluations セクションで確認できます）もプロビジョニングするには、次を実行します。

uv run python tests/setup_simulation_evals.py

このスクリプトは冪等で、何度実行しても安全です。