開発者ガイド

Agent-Lab フレームワークでアプリケーションを構築・拡張・リリースする

2 つの開発方法

Agent-Lab は、ライブラリとして利用するフレームワークであると同時に、直接作業できるリポジトリでもあります。どちらの方法もサポートされています。

ライブラリとして利用する（プロダクトに推奨）。 自分のプロジェクトに btech-agent-lab を追加し、基底クラスを拡張してエージェントを定義し、create_app() でアプリを組み立てます。フレームワークは公開 API（サブクラス化、デコレーター、設定）を通じて拡張し、フレームワークのコードを編集することはありません。まずはチュートリアルまたはクイックスタートから始め、続いてフレームワークの拡張をお読みください。定型コードを省きたい場合は、 uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter ですぐに使えるコンシューマープロジェクトを生成できます（cookiecutter/README.md を参照）。
リポジトリ内で開発する（コントリビューターとリファレンス実装向け）。 リポジトリをクローンし、agent_lab/services/agent_types/ の下にエージェントを追加し、同梱のリファレンスアプリを実行して、ノートブックや統合テストを利用します。組み込みエージェントはこの方法で開発されています。エージェントワークフローの構築を参照してください。

どちらの方法も同じ構成要素を使います。違いはコードをどこに置くかだけです。プロジェクトに合ったほうを選んでください。

セットアップ

インストール

Agent-Lab は Python 3.12+ を対象としており、依存関係の管理には uv を使用します。

Agent-Lab をライブラリとして利用する場合：自分のプロジェクトにインストールします。

pip install btech-agent-lab
# or
uv add btech-agent-lab

リポジトリで作業する場合：クローンして環境を同期します。

git clone https://github.com/btech-software/agent-lab.git
cd agent-lab
uv sync                 # runtime dependencies
uv sync --group test    # add the test/simulation dependencies

Docker または他のコンテナランタイムがインストールされ、実行中であることを確認してください。統合テストは（testcontainers 経由で）これを使用し、同梱の Docker Compose ファイルがアプリケーションの依存関係を提供します。

サンプルの環境ファイルをコピーする

cp .env.example .env

このファイルには、AI サプライヤーの API キーと、エージェントシミュレーションで使用するエンドポイントが含まれています。すべての変数は設定リファレンスに記載されています。

リファレンス実装

リポジトリには、すべての組み込みエージェント（RAG、ブラウザ自動化、ボイスメモ、ビジョン、マルチエージェントのスーパーバイザー）を登録した完全なリファレンスアプリケーション（agent_lab.main）が同梱されています。これはデプロイ可能なプロダクトであると同時に、フレームワークの利用方法を示す標準的な例でもあります。中身は、組み込みのエージェントパッケージに対して create_app() を呼び出しているだけです。

# agent_lab/main.py
from agent_lab.app_factory import create_app

app = create_app()  # scans DEFAULT_SCAN_PACKAGES: all built-in capabilities

独自のアプリを構築する際の生きたリファレンスとして、また Agent-Lab をエンドツーエンドで試す最速の方法として活用してください。開発環境や本番環境でのインフラ（3 つの PostgreSQL データベース、 Redis、Keycloak、Vault）のプロビジョニングについては、デプロイガイドで説明しています。次のセクションでは、ローカルでの実行方法を紹介します。

アプリケーションの実行

Uvicorn でアプリケーションを起動する

IDE を使った開発やデバッグでは、リファレンスアプリを直接実行します。

uvicorn agent_lab.main:app --reload

インタラクティブな OpenAPI ドキュメントには http://localhost:8000/docs でアクセスできます。

Agent-Lab をライブラリとして利用する場合も、自分のアプリを同じ方法で実行します。 create_app() を呼び出すモジュールを uvicorn に指定してください。

uvicorn app:app --reload    # where app.py defines `app = create_app(scan_packages=[...])`

Docker Compose でアプリケーションを起動する

事前設定済みの 2 つの Docker Compose ファイルで、リファレンスアプリをオブザーバビリティスタックと一緒に実行できます。

compose-grafana.yml：アプリケーションに加えて Grafana、Prometheus、Tempo、Loki。
compose-opensearch.yml：アプリケーションに加えて OpenSearch Dashboards。

docker compose -f compose-grafana.yml up --build       # Grafana stack
docker compose -f compose-opensearch.yml up --build    # OpenSearch Dashboards stack

アプリケーションの起動後、API は http://localhost:18000/docs で利用できます。オブザーバビリティのダッシュボードは次のとおりです。

Grafana：http://localhost:3000（デフォルトの認証情報：admin/admin）。Grafana の例を参照してください。
OpenSearch Dashboards：http://localhost:5601。OpenSearch の例を参照してください。

開発プラクティス

依存性注入

アプリケーションは依存性注入に Dependency Injector を使用しています。これにより関心事が分離され、テストが容易になります。

コンテナは agent_lab/core/container.py で定義されています。Agent-Lab をライブラリとして利用する場合は、Container をサブクラス化して独自のプロバイダーを追加し、そのインスタンスを create_app(container=...) に渡します。リポジトリ内で作業する場合は、追加のフレームワークサービスをコンテナに直接登録します。

アプリケーションの設定

設定は ConfigSource（agent_lab/core/config.py を参照）を通じて読み込まれ、 DI コンテナにバインドされます。フレームワークには開発・テスト用の 3 つの YAML ソースが同梱されており、環境変数によって自動的に選択されます。

config-dev.yml：開発環境用。DEVELOPING が設定されていると有効になります。IDE でのデバッグを想定しています。
config-test.yml：テスト環境用。TESTING が設定されていると有効になります。統合テストのセットアップで使用されます。
config-docker.yml：Docker Compose 環境用。DOCKER が設定されていると有効になります。

これらのファイルはデータベース接続や認証などの設定を定義するもので、開発とテスト専用です。本番環境では、VaultConfigSource（環境フラグが設定されていない場合のデフォルト）を通じて Vault を使用してください。別のバックエンドから設定を供給するには、独自の ConfigSource を実装して create_app(config_source=...) に渡します。すべての設定キーと環境変数は設定リファレンスに記載されています。

エンティティドメインモデル

データモデル（アプリケーション全体で使用されるエンティティとそのリレーション）については、エンティティドメインモデルを参照してください。

ロギングとオブザーバビリティ

アプリケーションはロギングとオブザーバビリティに OpenTelemetry を使用しており、セットアップは agent_lab/infrastructure/metrics/tracer.py にあります。FastAPI、 HTTPX、LangChain、SQLAlchemy、OpenAI の呼び出しは標準で計装されており、 Langfuse と LangWatch 用のバックエンドをプラグインとして追加できます。詳しくはオブザーバビリティガイドを参照してください。

テスト

このプロジェクトは pytest を使用し、統合テストに重点を置いています（カバレッジの基準：90%）。Testcontainers により、テストは Docker コンテナ内の実際のサービスに対して実行されます。別のシミュレーションスイートでは、 LLM-as-judge を使ってエージェントの振る舞いをエンドツーエンドで評価します。

make test               # unit + integration with coverage
make test_simulations   # end-to-end agent simulations (calls live LLMs)

初回の実行では Docker イメージと埋め込みモデルをダウンロードするため、数分かかることがあります。全体像についてはテストガイドを参照してください。

pre-commit を初期化する

コードベースにコントリビュートする場合や、Agent-Lab の上に新しいエージェントを構築する場合は、 pre-commit フックをインストールしてください。

pre-commit install

これにより、コミット前にコードがプロジェクトのコーディング規約に従っていることを確認できます。

エージェントワークフローの構築

Agent-Lab は LangGraph の上に構築されています。LangGraph は、 LLM を使ったエージェントワークフローを構築するための強力な手段を提供します。モジュール化されたアーキテクチャとエージェントの基底クラスのおかげで、ワークフローの構築は簡単です。

新しい Agent 実装を定義する

Agent は Agent-Lab の中核となる概念で、タスクを実行し、判断を下し、他のエージェントや外部システムとやり取りできる自律的な存在を表します。エージェントは、次のいずれかの基底クラスの具象実装です。

Agent-Lab の基底クラス

WorkflowAgentBase を拡張したクラスは、次のものを定義します。

エージェントの振る舞い（タスク、意思決定、他のエージェントや外部システムとのやり取り）を表すワークフロー。
エージェントの振る舞いをカスタマイズするプロンプト（Jinja2 テンプレート）などの初期化パラメーターや、その他の設定（ベクトルストアのコレクション、temperature など）。

以下は、音声の文字起こしと分析を行うエージェントについて、エージェントを作成してデータベースに保存した後の、永続化された初期化パラメーターの例です。

エージェントの初期化パラメーター

同じ実装に基づく複数のエージェントを、REST API を通じて作成・調整できます。

`@discoverable_agent` でエージェントを登録する

AgentBase のサブクラスを @discoverable_agent("<agent_type>") でデコレートします。エージェントの登録に必要なのはこのデコレーターだけで、これによりエージェントは次のようになります。

エージェントレジストリ（agent_lab/services/agent_types/registry.py）から検出可能になります。
DI コンテナを通じて解決可能になります。コンテナはエージェントを遅延的にインスタンス化し、宣言された extra_deps を注入します。
エージェント作成用のスキーマが agent_type をレジストリに対して動的に検証するため、API で有効になります。

from agent_lab import AgentBase, AgentUtils, discoverable_agent


@discoverable_agent("my_agent", extra_deps=("my_service",))
class MyAgent(AgentBase):
    def __init__(self, agent_utils: AgentUtils, my_service):
        super().__init__(agent_utils)
        self.my_service = my_service
    ...

注意（移行）： 以前のバージョンでは、各エージェントを手動で container.py に配線し、 registry.py に追加し、agents/schema.py の Pydantic スキーマを拡張する必要がありました。これらの手順は不要になりました。@discoverable_agent がすべてを処理します。宣言した extra_deps は、インスタンス化の時点で（サブクラス化されている可能性のある）コンテナから名前で解決されます。

エージェントが AgentUtils 以外の協調オブジェクトを必要とする場合は、それらをコンテナのプロバイダーとして公開し（ライブラリとして利用する場合は Container をサブクラス化します）、extra_deps に名前を指定します。

エージェントを検出可能にする

フレームワークは指定されたエージェントモジュールだけをインポートし、それによってデコレーターが実行されます。

リポジトリ内： エージェントを agent_lab/services/agent_types/ の下に配置します。リファレンスアプリは DEFAULT_SCAN_PACKAGES（create_app()）の一部としてこのパッケージをスキャンします。
ライブラリとして： パッケージを create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) に渡します。明示的なリストはデフォルトを置き換えます（組み込み機能を除外する方法でもあります）。あるいは、インストール済みパッケージから agent_lab.agents エントリーポイントグループを通じて公開すれば、コンシューマー側で自動的に読み込まれます。
```
# pyproject.toml of the package that ships the agents
[project.entry-points."agent_lab.agents"]
my_agents = "my_agents"
```

エージェント実装を試す

同じ依存性注入の仕組みを使い、Jupyter でエージェントを対話的にテストする例については、ノートブックを参照してください。管理された環境で振る舞いのプロトタイピングと検証を行うのに便利な方法です。研究者ガイドも参照してください。

REST API によるエージェントインターフェース

エージェントを登録したら、REST API を通じてそのインスタンスを作成・管理します。同じ実装から、それぞれ独自のプロンプトと設定を持つ複数のインスタンスを実行できます。エンドポイントの一覧とリクエスト例については REST API リファレンスを参照してください。

エージェントをテストする

統合テスト（tests/integration/）は、pytest と testcontainers を使い、実際のインフラに対してエージェントを検証します。
シミュレーション（tests/simulation/）は、LLM-as-judge を使って振る舞いをエンドツーエンドで評価します。テストガイドを参照してください。

MCP サーバー

エージェント（および追加のツール）を Claude Desktop などの MCP クライアントに公開し、エージェントの検出、対話履歴、エージェント間通信を行う方法については、MCP サーバーガイドを参照してください。

フレームワークの拡張

Agent-Lab をライブラリとして利用する場合、アプリケーションは create_app() と、トップレベルの agent_lab パッケージからエクスポートされる公開 API だけで形作ります。フレームワークのコードを編集することはありません。

拡張ポイント	方法
エージェント	基底クラスをサブクラス化し、`@discoverable_agent` でデコレートして、`scan_packages=[...]` または `agent_lab.agents` エントリーポイントで登録します。
サービスと依存関係	`Container` をサブクラス化してプロバイダーを追加し、`create_app(container=...)` として渡します。
設定	`ConfigSource` を実装し（または `YamlConfigSource` / `VaultConfigSource` を使用し）、`create_app(config_source=...)` に渡します。
追加の HTTP ルート	`APIRouter` を作成し、（認証ポリシーとともに）`RouterMount` でラップして、`create_app(extra_routers=[...])` に渡します。
MCP ツールとプロンプト	`@discoverable_mcp_tool` / `@discoverable_mcp_prompt` / `@discoverable_mcp_registrar` でデコレートし、エージェントと同じ `scan_packages` / エントリーポイントの仕組みで登録します。MCP の instructions のフラグメントは `create_app(mcp_instructions=[...])` で追加します。
トレーシングバックエンド	`TracingBackend` をサブクラス化して `Container` に登録し、スパンを独自のプラットフォームにエクスポートします。

from agent_lab import (
    DEFAULT_SCAN_PACKAGES,
    Container,
    RouterMount,
    YamlConfigSource,
    create_app,
)

class MyContainer(Container):
    my_service = ...  # providers.Factory(MyService, ...)

app = create_app(
    container=MyContainer(),
    scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"],
    config_source=YamlConfigSource("config.yml"),
    extra_routers=[RouterMount(my_router, "/custom", ["custom"])],
    mcp_instructions=["Extra guidance for MCP clients."],
)

上記はすべて agent_lab からエクスポートされています（agent_lab/__init__.py を参照）。これらの設定項目が使用する設定キーの完全な一覧は、設定リファレンスにあります。

コントリビュート

コミュニティからのご支援を心より歓迎します。問題が発生した場合や改善のご提案がある場合は、 GitHub Issues ページで Issue を作成してご報告ください。

プロジェクトにコントリビュートするには、次の手順に従ってください。

リポジトリをフォークします。
機能追加またはバグ修正用の新しいブランチを作成します。
pre-commit install を実行して pre-commit フックを有効にし、変更を加え、明確で簡潔なメッセージでコミットします。
変更が pre-commit フックと 90% のカバレッジ基準（make test）を満たしていることを確認します。
フォークしたリポジトリに変更をプッシュします。
元のリポジトリの main ブランチに対してプルリクエスト（PR）を作成します。

PR をレビューし、フィードバックをお送りします。コントリビューションとご支援に感謝いたします。

本番環境へのデプロイ

同梱の Helm チャートと Terraform スクリプトを使って、リファレンスアプリケーションを本番環境にデプロイする方法については、デプロイガイドを参照してください。