研究者ガイド

このガイドの対象読者

Agent-Lab で実験を探索・再現・拡張したい AI 研究者と開発者を対象としています。Python を書き、 Jupyter を使い、実験、エージェント、パイプラインという観点で考える方なら、すぐになじめるはずです。 LLM、RAG、コンテナの基礎知識があると役立ちますが、必須ではありません。

Agent-Lab は、再利用可能なコンポーネント（エージェントタイプ、ツール、インテグレーション）に加えて、ステップバイステップの例を収めた Jupyter ノートブック集を提供しているため、すぐに成果を上げられます。

クイックスタート：サンプルを実行する

必要なもの：Python 3.12+、動作する Jupyter 環境（JupyterLab または Notebook）、およびエンドツーエンドのインテグレーション用に任意でローカルの Docker。リポジトリのクローン上で作業します。

uv sync --group notebooks   # runtime + notebook dependencies in one virtualenv
jupyter lab                 # from the repository root

notebooks/ を開き、01_… から始めて、興味のあるノートブックへと順に進めてください。

注意点：

• ノートブックはほぼ自己完結しています。各ノートブックの冒頭に、必要な環境変数と外部サービス（API キー、エンドポイント）が記載されています。
• 必要なキーは .env に保存します。.env.example をコピーして値を入力してください（設定リファレンスを参照）。
• リポジトリではなく独自のプロジェクトから Agent-Lab を使って実験するには、 pip install btech-agent-lab を実行し、create_app() でアプリを組み立てます。開発者ガイドのフレームワークの拡張を参照してください。

プロジェクト構成：クイックツアー

• notebooks/：エージェントタイプ、評価、インテグレーションのインタラクティブな例です。まずはここから始めてください。
• agent_lab/：フレームワークのパッケージです。
  • app_factory.py：コンポジションルート create_app()。
  • core/：設定ソース、DI コンテナ、extra_deps の解決。
  • domain/：モデル、リポジトリインターフェース、例外（エンティティドメインモデル）。
  • services/：ビジネスロジックと agent_types/ の実装。
  • interface/：api/（HTTP ルーター）と mcp/（MCP サーバー）。
  • infrastructure/：データベース、認証、メトリクス／トレーシングのアダプター。
• tests/：unit/、integration/、template/、simulation/ の各スイート（テストとシミュレーションを参照）。
• doc/：いまお読みのドキュメントです。

これらのレイヤーを理解すれば、振る舞いがどこにあるかがわかります。例は notebooks に、中核となるコントラクトは core/ と domain/ に、アダプターは infrastructure/ にあります。

ノートブック：主要な学習パス

一般的な進め方は次のとおりです。

各ノートブックには、実験の目的の簡単な説明、必要な環境変数とシークレット、ヘルパー関数、エージェントの判断やメトリクスを確認するための出力（テキスト／ビジュアル）が含まれています。

ヒント：ノートブックを順番に実行すると、段階的に学習を進められます。試行錯誤の間は小さめのデータセットとサンプルサイズを使い、実行を高速に保ちましょう。

基本概念

• Agent：agent_lab/services/agent_types/ に登録された実装です（@discoverable_agent）。レジストリは DI コンテナを通じてこれを遅延解決し、宣言された extra_deps を注入します。
• Tools：エージェントが呼び出せる個別の機能（検索、ブラウジング、TTS/ASR）で、 agent_lab/infrastructure/ または agent_lab/interface/ にアダプターとして実装されています。
• Container：DI のコンポジションオブジェクト（agent_lab/core/container.py）です。サブクラス化して、実験用のプロバイダーを追加できます。
• Repositories：agent_lab/domain/repositories/ にあるデータアクセスインターフェースです。
• ConfigSource：設定の取得元です。実験では YAML ソースを、本番環境では Vault を使用します。

振る舞いを変更したいときは、その変更が実験的なもの（ノートブックのみ）か、アーキテクチャに関わるもの（core/domain/services）か、インテグレーションレベルのもの（infrastructure のアダプター）かを判断してください。小さくテスト可能な変更を優先し、新しい振る舞いを示すノートブックを追加または更新しましょう。

実験の実行と結果の記録

ノートブックは途中経過を出力します。より堅牢な実験を行うには、次の点に留意してください。

• ランダム性が影響する箇所では、決定論的なシードを使用します。

• 検証したい問いに関連するメトリクス（レイテンシ、トークン使用量、ツール呼び出し回数、ジャッジのスコア）を記録します。オブザーバビリティレイヤーはすべてを OpenTelemetry としてエクスポートし（オブザーバビリティを参照）、シミュレーションハーネスはジャッジのスコアを Langfuse/LangWatch に記録します（テストとシミュレーションを参照）。

• 繰り返し実行できるようにするには、ノートブックのセルをスクリプトとしてエクスポートし、CI や計算ノード上で実行します。

  jupyter nbconvert --to script notebooks/02_test_agent_type-adaptive_rag.ipynb

• docker/app/Dockerfile は、再現可能な実行のためにバージョンを固定したランタイムイメージをビルドします。

新しい振る舞いのプロトタイピング

1. 新しいエージェントタイプを追加する：agent_lab/services/agent_types/ の下にクラスを作成し、 @discoverable_agent("your_type") でデコレートします。そのうえで、DI コンテナを通じてクラスをマウントし、小さなシナリオで動作を確認するノートブックを追加します。詳しい手順はエージェントワークフローの構築にあります。
2. 埋め込みプロバイダーを差し替える：互換性のあるアダプターを agent_lab/infrastructure/ の下に実装し、ノートブック 01 で検証します。
3. 検索用ストアやベクトル DB を追加する：agent_lab/domain/repositories/ にリポジトリメソッドを、 agent_lab/infrastructure/database/ にアダプターを実装します。小さなローダーノートブックでデータを投入し、クエリ用のノートブックで検索を実演します。

設計のヒント：アダプターのインターフェースは狭く保ち、小さな単体テストで個別にテストしましょう。

テストと評価

make test_unit           # unit tests — no infrastructure needed
make test                # unit + integration with coverage
make test_simulations    # LLM-as-judge agent simulations (live LLMs)

中核の振る舞いを変更した場合は、単体テストと、その変更を示す短いノートブックを追加してください。この組み合わせこそが、ここでの研究を再現可能にするものです。ハーネス全体、ジャッジの設定、評価プラットフォームについてはテストとシミュレーションで説明しています。

再現性チェックリスト

• 環境を固定します（uv + pyproject.toml / uv.lock）。
• シードと設定ファイル（config-dev.yml、config-test.yml）を記録します。
• ノートブックのチェックポイントと出力成果物（CSV/JSON）を、実験とあわせて保存します。
• エクスポート先のトレーシングエンドポイントを記録します。トレースは実験ログそのものです。