メインコンテンツへ移動
AIチュートリアル

IvyClaw実践：計画・コーディング・テスト・レビューに対応するマルチエージェント開発システムの構築

本稿では、IvyClawの中核アーキテクチャ、環境設定、API、非同期タスクの起動方法を紹介し、エンジニアリングの観点から、マルチエージェント連携、サンドボックス実行、永続化、人による承認、可観測性、本番環境へのデプロイについて解説します。

約17分で読了
IvyClaw実践：計画・コーディング・テスト・レビュー対応のマルチエージェント開発システム

一、IvyClaw とは

IvyClaw は、ソフトウェア開発タスク向けのマルチエージェント AI Agent エンジニアリングシステムです。DeepAgents と LangGraph を基盤に構築されています。単一の大規模モデル呼び出しを一度実行するだけでなく、要件理解、タスク計画、資料検索、コード実装、自動テスト、コードレビュー、結果返却を、継続的に実行可能な Agent Workflow として組織化します。

プロジェクトでは、Python、FastAPI、PostgreSQL、Redis、ARQ、Docker、Prometheus、Grafana などの技術を使用しており、AI Agent のエンジニアリング実装を学習・実践する用途に適しています。

ただし、リポジトリ内の一部機能は、まだエンジニアリングプロトタイプまたはデモ実装の段階です。生産環境で使用する場合は、認証、権限管理、セキュリティ分離、インフラ設定をさらに整備する必要があります。

プロジェクトのアドレス：IvyClaw GitHub Repository。

二、コアワークフローとシステムアーキテクチャ

IvyClaw は、1 件の開発リクエストを複数の明確な責務を持つ Agent に分割します。典型的なフローは次のとおりです。

User Request
      ↓
   Gateway
      ↓
  Dispatcher
      ↓
   Planner
      ↓
Researcher（必要時）
      ↓
    Coder
      ↓
   Tester
      ↓
  Reviewer
      ↓
Final Response

Planner は要件の理解、タスクの計画、意思決定を担当します。Researcher は必要に応じて資料を検索・整理します。Coder はコードの実装・変更を担当し、Tester はテストを実行して問題を特定します。Reviewer は最終結果をコードレビューします。

リクエストは通常、まず API Gateway に入り、チャネルアダプターと Dispatcher を経由して Agent Runtime に渡されます。PostgreSQL はセッション状態と LangGraph Checkpointer、Store のデータを永続化し、Redis はキャッシュ、レート制限、ランタイム状態、タスクキューに使用されます。時間のかかるタスクは ARQ Worker に渡され、非同期で実行されます。

三、実行環境の準備

開始前に、Python プロジェクトの実行環境、利用可能な PostgreSQL および Redis サービス、プロジェクトの設定要件を満たすモデル API を用意してください。プロジェクトでは uv で Python 依存関係を管理します。

まずリポジトリをクローンし、プロジェクトディレクトリに移動します。

git clone https://github.com/ivyfan-toowell/IvyClaw.git
cd IvyClaw

次に、サンプルファイルからローカル環境設定を作成します。Linux、macOS、または Unix 系環境では次を実行できます。

cp .env.example .env

Windows PowerShell では次を実行できます。

Copy-Item .env.example .env

.env にローカル環境に応じた必要な設定を入力します。例：

IVC_API_KEY=your_api_key_here
IVC_POSTGRES_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_DATABASE_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_REDIS_URL=redis://localhost:6379/0

実際の .env ファイルを GitHub にコミットしないでください。LLM API Key、LangSmith API Key、Feishu App Secret、データベースパスワード、実際のゲートウェイ API Key などの機密情報は、ローカルまたは安全なデプロイ環境に保存してください。

四、依存関係のインストールとサービスの起動

Python 依存関係のインストール

プロジェクトルートで次を実行します。

uv sync

このコマンドにより、プロジェクト設定に従って Python 環境と依存関係が同期されます。

FastAPI API の起動

次のコマンドで開発サーバーを起動します。

uv run uvicorn api.app:app --reload --port 8000

起動後に http://localhost:8000/docs を開くと、FastAPI が自動生成した Swagger API ドキュメントを確認できます。

ARQ Worker の起動

時間のかかる Agent タスクを処理する場合は、別のターミナルで ARQ Worker も起動します。

uv run arq tasks.worker.WorkerSettings

リクエストは Redis キューを通じて Worker に送信でき、Worker が Agent Runtime を呼び出してタスク結果を永続化します。非同期タスクフローには通常、Job ID、タスク状態の照会、バックグラウンド実行、冪等な送信、結果取得が含まれます。

Feishu 長時間接続の起動

Feishu WebSocket 接続を使用する場合は、次を実行できます。

uv run python -m channels.feishu_ws

IvyClaw は Feishu Webhook、Generic Webhook、CLI などの入口もサポートしています。各チャネルは統一的に InboundMessage へ変換され、その後、同じ handle_message() と Agent 処理ロジックを再利用します。

五、Agent のツール呼び出しを理解する

IvyClaw は、各 Agent に責務に適合した最小限のツールセットを割り当て、不要な呼び出しや誤操作のリスクを低減します。プロジェクトがサポートするツールの種類は次のとおりです。

  • Git：コードのバージョンを確認・操作します。
  • pytest：自動テストを実行します。
  • Python と Shell：開発コマンドを実行します。
  • Web Search：Tavily または Exa で情報を検索します。
  • MCP：外部ツールやサービスに接続します。
  • File Tools：ワークスペースのファイルを読み取り、変更します。
  • Sandbox：Agent が生成したコードを隔離実行します。

また、skills/ に再利用可能な開発フローを蓄積しています。これには、要件の明確化、体系的なデバッグ、テスト駆動開発、ユニットテスト、完了前の検証などが含まれます。代表的なディレクトリは次のとおりです。

skills/
├── fastapi-endpoint/
├── requirements-clarification/
├── systematic-debugging/
├── test-driven-development/
├── unit-test/
└── verification-before-completion/

六、コードサンドボックスと安全な実行

Agent が生成したコードは主要サービスプロセス内で直接実行されず、隔離環境に配置して実行できます。IvyClaw は Docker Sandbox と Daytona Sandbox をサポートし、Python、pytest、Git などのコマンドを実行できます。

サンドボックス機能には、独立した作業ディレクトリ、サンドボックスの再利用とライフサイクル管理、CPU、Memory、PID などのリソース制限が含まれます。生産環境ではデフォルトで Docker Sandbox を使用し、gVisor や Kata など、より強力な分離ランタイム向けの拡張余地も確保されています。

サンドボックスを設定する際は、実際のリスク評価に基づき、ネットワーク権限、ファイルアクセス範囲、リソース上限、同時実行規模を検討してください。README でも、生産環境ではセキュリティ分離をさらに強化する必要があり、現在のデモ設定を完全なセキュリティ対策と見なしてはならないと明記されています。

七、状態の永続化と非同期タスク

永続化コンポーネント

PostgreSQL は主に LangGraph Checkpointer、Store、セッション状態、その他の永続化データを保存します。Redis はキャッシュ、レート制限、タスクキュー、ランタイム状態などを担います。Checkpointer と Store により、Agent の実行コンテキストをリクエスト間で継続できます。

非同期タスクフロー

実行時間の長い開発タスクでは、FastAPI でタスクを作成し、Redis と ARQ Worker で非同期処理する方法を推奨します。

Client
  ↓
FastAPI
  ↓
Create Job
  ↓
Redis Queue
  ↓
ARQ Worker
  ↓
Agent Runtime
  ↓
Persist Result
  ↓
Query Job Status

この方法により、同期 HTTP リクエストを長時間占有することを避け、タスク状態の照会、リトライ、結果の永続化の基盤を提供できます。

八、Human-in-the-Loop：高リスク操作に承認を追加する

ファイルの削除や破壊的な変更の実行などの操作は、完全に自動化するのには適していません。IvyClaw は Human-in-the-Loop をサポートしており、Agent が高リスクなツール呼び出しを要求した際に実行を中断し、人間の判断を待つことができます。

Agent requests risky action
          ↓
       Interrupt
          ↓
    Human Approval
       ↓       ↓
    Approve   Reject
       ↓
 Command(resume)
       ↓
Agent continues

人間による承認後、再開コマンドで実行を続行します。拒否された場合は、現在のフローを終了または変更します。この仕組みにより、自動化の効率と操作の安全性の間に制御ポイントを設けられます。

九、ゲートウェイ、マルチテナント、安定性のガバナンス

リクエストは Agent Runtime に入る前にゲートウェイ層を通過し、本人確認と基本的なガバナンスが行われます。現在のリポジトリが提供する機能は次のとおりです。

  • API Key 認証。
  • Tenant の識別と分離。
  • Rate Limit によるレート制限。
  • Idempotency による冪等性制御。
  • Request Context によるリクエストコンテキスト。
  • Audit Log による操作監査。

README では、現在の Key と Tenant は主にデモ設定として扱われると特に説明されています。生産環境ではデータベースまたは専用の認証システムに接続し、テナント権限とデータ分離をさらに整備する必要があります。

インフラ層には、Retry、Timeout、Fallback、Concurrency Control、PostgreSQL Connection Pool、Redis Connection Pool、Sandbox Pool などの機構も用意されており、高い同時実行数、モデルの異常、インフラの不安定さに対応します。

十、可観測性、テスト、評価

IvyClaw は複数の可観測性コンポーネントを統合しています。LangSmith は Agent と LLM の呼び出しチェーンを追跡し、Prometheus はメトリクスを収集し、Grafana は可視化監視に使用されます。さらに、構造化ログと監査ログも提供しています。

ランタイムでは、次の指標を重点的に確認できます。

  • リクエスト遅延とエラー率。
  • 同時実行数。
  • LLM 呼び出し回数。
  • Token 使用量とコスト。
  • ARQ Worker の状態。
  • Sandbox の状態。

プロジェクトには tests/、eval/、loadtest/ ディレクトリも含まれており、pytest 自動テスト、Agent Runtime テスト、Code Cases、Execution Scorer、LLM Judge、Baseline Evaluation、Reviewer Flow Test、Locust 負荷テストをカバーしています。

Agent の信頼性を一度の人手による対話だけで判断するのではなく、「開発、自動テスト、Agent Evaluation、負荷テスト、メトリクス観測、問題改善」の順に検証サイクルを構築することを推奨します。

十一、Docker による本番デプロイ

サービススタック全体を起動する場合は、リポジトリが提供する本番 Compose 設定を使用できます。

docker compose -f docker-compose.prod.yml up -d --build

本番デプロイには、FastAPI Web サービス、ARQ Worker、Feishu サービス、PostgreSQL、Redis、Prometheus、Grafana が関わります。API と Worker は Agent Runtime に共同でアクセスでき、Agent Runtime は Docker Sandbox を通じて生成されたコードを実行します。

本番稼働前に、データベースと Redis の接続、シークレット管理、API 認証、テナント分離、レート制限戦略、サンドボックスのリソース制限、ログ監査、監視とアラートの設定を確認してください。

12. プロジェクト構成からコードを特定する

ディレクトリ構成を把握すると、機能をすばやく拡張できます。

IvyClaw/
├── agent/          # メイン Agent とタスクスケジューリング
├── api/            # FastAPI API
├── channels/       # CLI / Feishu / Webhook 接続
├── gateway/        # API 認証、Tenant、レート制限
├── infra/          # PostgreSQL、Redis、LLM Router
├── middleware/     # リクエストコンテキスト、並行処理、監査、コスト集計
├── obs/            # Metrics と可観測性
├── profiles/       # モデルと Agent Profile
├── sandbox/        # Docker / Daytona サンドボックス
├── skills/         # Agent Skills
├── subagents/      # Planner / Researcher / Coder / Tester / Reviewer
├── tasks/          # ARQ 非同期タスク
├── tools/          # Git / pytest / Search / MCP ツール
├── eval/           # Agent Evaluation
├── loadtest/       # Locust 負荷テスト
├── tests/          # 自動テスト
├── scripts/        # 開発、テスト、デモ用スクリプト
├── web/            # Web UI
├── Dockerfile
├── docker-compose.prod.yml
├── pyproject.toml
└── .env.example

13. 実践的な利用方法

  1. まず .env、PostgreSQL、Redis を設定し、API に Swagger ドキュメント経由でアクセスできることを確認します。
  2. まず同期 API または CLI で基本的な Agent Workflow を検証し、その後 ARQ Worker を起動して長時間のタスクを処理します。
  3. Coder、Tester、Reviewer のツール権限をそれぞれ確認し、単一の Agent に不要な高リスク機能を割り当てないようにします。
  4. 生成コードの実行にはサンドボックスを有効にし、CPU、メモリ、プロセス数、作業ディレクトリに適切な制限を設定します。
  5. 削除や破壊的な変更を伴う場合は Human-in-the-Loop を有効にし、デフォルトで自動承認しないでください。
  6. LangSmith、Prometheus、Grafana、構造化ログを使用して、リクエスト経路、コスト、レイテンシ、エラーを把握します。
  7. 本番稼働前に pytest、Agent Evaluation、Locust 負荷テストを実行し、結果に基づいてモデルルーティング、並行数、再試行戦略を調整します。

おわりに

IvyClaw の重点は単一のモデル呼び出しではなく、マルチエージェント協調、ツール呼び出し、コードサンドボックス、状態の永続化、非同期実行、人手による承認、ゲートウェイガバナンス、可観測性を組み合わせたソフトウェア開発 Agent のエンジニアリングシステムにあります。

ローカルでの起動が完了したら、既存の subagents/、tools/、skills/ から始め、Planner、Researcher、Coder、Tester、Reviewer の協調方法を段階的に理解してください。その後、業務要件に応じてチャネル、ツール、評価プロセスを拡張できます。