AI Agent PM Coordinator
全エージェントのタスク実行を統合管理するオーケストレーションデーモン。
🚨 致命的な設計違反警告 (2026-01-09)
現在の実装には致命的な設計違反があります。修正が必要です。
問題点
Coordinator/Runnerは純粋なMCPクライアントであるべきですが、現在の実装は以下の不正な情報を保持しています:
| 設定項目 | 問題 | 対応 |
|---|---|---|
mcp_server_command |
サーバー起動コマンドを保持 | 削除必須 |
mcp_database_path |
DBパス(内部実装詳細)を保持 | 削除必須 |
設計原則
✅ 正しい設計: Coordinatorはソケット接続のみ行う純粋なクライアント
❌ 現在の実装: Coordinatorがサーバー起動やDB接続情報を管理
影響
- Agent Instanceごとに新しいMCPサーバーをstdio transportで起動
- 複数のMCPサーバーが同じDBに同時アクセス → データ整合性の問題
- テストと本番で異なるDB設定が必要 → 設定の複雑化
正しいアーキテクチャ
[アプリ] → MCPデーモン起動(唯一のサーバー)
[Coordinator] → Unix Socketで接続(クライアントのみ)
[Agent Instance] → 同じUnix Socketで接続(クライアントのみ)
詳細は docs/plan/PHASE4_COORDINATOR_ARCHITECTURE.md の警告セクションを参照。
クイックスタート
cd runner
pip install -e .
# デフォルト設定で起動(config/coordinator_default.yaml を使用)
python -m aiagent_runner --coordinator
Coordinatorモード(推奨)
単一のCoordinatorが全ての(agent_id, project_id)ペアを管理します。
基本起動
# デフォルト設定で起動
python -m aiagent_runner --coordinator
# 詳細ログ出力
python -m aiagent_runner --coordinator -v
カスタム設定ファイル
python -m aiagent_runner --coordinator -c /path/to/config.yaml
設定ファイル例
# config/coordinator_default.yaml がデフォルトで読み込まれます
# カスタム設定で上書き可能
polling_interval: 10
max_concurrent: 3
# AI providers
ai_providers:
claude:
cli_command: claude
cli_args:
- "--dangerously-skip-permissions"
- "--max-turns"
- "50"
# Agents (passkeyのみ - ai_type等はMCPから取得)
agents:
agt_developer:
passkey: secret123
agt_reviewer:
passkey: ${REVIEWER_PASSKEY} # 環境変数展開対応
log_directory: /tmp/coordinator_logs
バックグラウンド実行
nohup python -m aiagent_runner --coordinator -v > coordinator.log 2>&1 &
設定の優先順位
- コマンドライン引数 (
--polling-interval等) - 指定した設定ファイル (
-c /path/to/config.yaml) - デフォルト設定 (
runner/config/coordinator_default.yaml) - 組み込みデフォルト値
動作フロー
- MCPサーバーに接続(Unixソケット)
list_active_projects_with_agents()で全プロジェクト・エージェントを取得- 各(agent_id, project_id)ペアに対して
get_agent_action()を呼び出し - 作業が必要な場合、Agent Instance(Claude CLI等)をスポーン
- Agent Instanceが
authenticate→get_my_task→ 実行 →report_completed - 待機して2に戻る
前提条件
- MCPサーバーが起動していること
- エージェントがアプリで登録済みで、passkeyが設定されていること
- 該当エージェントがプロジェクトに割り当てられていること
- タスクが
in_progressステータスであること
Legacy Runnerモード(非推奨)
1エージェント = 1デーモン の旧アーキテクチャ。
# 非推奨: Coordinatorモードを使用してください
aiagent-runner --agent-id <AGENT_ID> --passkey <PASSKEY> --project-id <PROJECT_ID>
開発
pip install -e ".[dev]"
pytest
Metadata
Release files for aiagent-runner 0.1.13
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aiagent_runner-0.1.13.tar.gz | 159.2 kB | Without provenance | Details for aiagent_runner-0.1.13.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aiagent_runner-0.1.13-py3-none-any.whl | Python 3 | none | any | Details for aiagent_runner-0.1.13-py3-none-any.whl |
Total release size: 205.5 kB
Release files / aiagent_runner-0.1.13.tar.gz
| Download URL | aiagent_runner-0.1.13.tar.gz |
|---|---|
| Size | 159.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3300601b86a6e1d9ea84303633a734e08894f807b8297cc08141bcc316dd0f5f
|
|
BLAKE2b-256 checksum How to use checksums |
b42ac89e465e3d0f743a6898757240d86019624889e849df00a7f2ee0d68ef32
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / aiagent_runner-0.1.13-py3-none-any.whl
| Download URL | aiagent_runner-0.1.13-py3-none-any.whl |
|---|---|
| Size | 46.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2fcdc48a51692fd0da5ac0bbe4139fcfb07288dae75ca09eb636f0d79179c224
|
|
BLAKE2b-256 checksum How to use checksums |
c3efa8b5982ba492b2b27054eead629ea48342b3f03772bba6b281c84bd628cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for aiagent-runner 0.1.13
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.