フレームワーク

Agent Zero を解剖する:18.9k Star の汎用 Agent フレームワーク

Agent Zero は Docker サンドボックスで AI にコード実行や調査、ファイル操作を任せ、メイン Agent が子 Agent を動的に生成する。本記事ではアーキテクチャと実動作を分解し、AutoGPT や LangGraph との違いを整理する。

文字サイズ

GitHub には Agent フレームワークが山ほどあるが、本当に動く上にマシンを壊さないものは少数派だ。Agent Zero はその一つで、18.9k Star、Python 製、Docker によるサンドボックスで AI を隔離して走らせる。

実際に動かしてみたので、以下に分解していく。

何の課題を解決するのか

2023 年に AutoGPT がバズった頃、インストールして初回の実行で後悔した人は多いはずだ。Agent がローカルファイルシステムの権限をそのまま握っているため、プロンプトを typo するだけで rm -rf / が現実になる。

Agent Zero のアプローチは明快で、Agent を Docker コンテナに閉じ込める。ターミナル、ブラウザ、ファイル読み書きといった全ツールを渡す一方で、物理的に隔離する。同時に「プロセスの透明性」を重視し、思考とツール呼び出しをすべてユーザーに見せる。

この立ち位置は、二つの極端の中間にあたる。

  • AutoGPT:構造なし。Agent が自分でツールを作り、自分で手順を決める。自由度が高いが制御も失いやすい。
  • LangGraph:高度に構造化され、状態機械駆動で組み立ては大変。
  • Agent Zero:動く Agent + サンドボックス + UI を箱から出してすぐ使える状態で提供。プロセスは強制しない。

使い方

まず Docker Desktop をインストールし、リポジトリを clone する。

git clone https://github.com/agent0ai/agent-zero
cd agent-zero
./run.sh

起動スクリプトが自動でコンテナを build し、作業ディレクトリをマウントし、API key の設定を要求する。完了後、ブラウザで Web UI を開けば、コマンドライン操作は不要になる。

設定は ini ファイルで行う。conf/agent-zero.ini:

[llm]
provider = openai  # anthropic / ollama / その他も対応
model = gpt-4o
api_key = sk-xxx

UI に入ったら Agent にプロンプトを投げる。例えば「GitHub で人気の Python Web フレームワーク上位 5 個を調査して」のように入力すれば、あとは Agent が勝手に動く。

アーキテクチャ

3 層構造になっており、おおまかには下图のようになる。

┌────────────────────────┐
│  メイン Agent (Agent Zero) │ ← 入口。依頼を受け、タスクを分解
└────────────┬─────────────┘
             │ 動的生成
       ┌─────────────┐
       ▼             ▼
┌─────────┐     ┌─────────┐
│ 子 Agent │     │ 子 Agent │ ← 独立したサブタスクを処理
└────┬─────┘     └────┬─────┘
     │                │
     ▼                ▼
─────────────────────────────
│  ツール層(ターミナル/ファイル/ブラウザ) │
└─────────────────────────────
         │
         ▼
┌────────────────────────┐
│  Docker サンドボックス(実行分離)       │
└────────────────────────┘

押さえておきたいポイント:

  1. メイン Agent がエントリーポイント。依頼を受け、タスクを分解し、子 Agent に投げ分けるかどうかを判断する。
  2. 子 Agent はメイン Agent が動的に生成する。それぞれ独立したサブタスクを処理し、完了後にメイン Agent へ結果を返す。
  3. ツール層 はターミナル実行、ファイル読み書き、ブラウザ自動化(Playwright)、コード実行をラップしている。
  4. メモリシステム は二段構成。短期(現在のセッションの context window)と長期(セッションをまたぐベクトルストア / ファイル)。
  5. Docker コンテナ が実行分離を担う。すべての shell コマンドとファイル操作はコンテナ内で実行され、ホスト環境を汚染しない。

中核ループは典型的な ReAct パターン:思考 → ツール選択 → 実行 → 結果観察 → 継続。

良い点と弱点

良い点

  • Docker による分離が本当に効いている。Agent が rm -rf / を書いても、被害を受けるのはコンテナだけ。
  • 設定がシンプル。ini で LLM を指定すれば動き、フレームワーク特有の概念を学ぶ必要はない。
  • Web UI の出来が良い。各ステップが可視化されるため、純粋な CLI より圧倒的にデバッグしやすい。
  • 多 Agent 協調の階層構造が複雑なタスクで効く。例えば「5 つのフレームワークを調査」を 5 体の子 Agent に並列処理させることができる。
  • コミュニティが活発。18.9k Star、issue や PR にも人がついている。

弱点

  • 依存が重い。Docker 必須で、ディスク消費は 5GB 以上、起動も遅い。
  • Agent の挙動が予測不能。複雑なタスクではループに陥りやすい。同じツールを何度も呼び、token を燃やし尽くす。
  • デバッグが難しい。エラー時はログを見るしかない。Agent の「思考」は見えるものの、根本原因の特定は推測に頼ることになる。
  • token 消費が大きい。後述のタスクで約 12k tokens、複雑なタスクでは軽く 100 万を超える。
  • 日本語環境でのツール呼び出し精度は英語に劣る。日本語の説明が原因となって、Agent が誤ったツールを選ぶことがある。

LangGraph と比べると構造化の度合いは低いが、立ち上げの手間は 10 分の 1。AutoGPT と比べると安全性と安定性は圧倒的に上。

実際に試してみた

マシン:8GB メモリの Mac mini(M1)。

タスクのプロンプト:

「Python でスクレイパーを書いて、Hacker News のトップページのタイトルを取得し、CSV に保存して。」

Agent は約 4 分かけ、8 ステップで処理した。

  1. タスク分解(requests、beautifulsoup4 が必要と判断)
  2. terminal ツール呼び出し:pip install requests beautifulsoup4
  3. スクレイパーコードを /work_dir/hn_scraper.py に書き出し
  4. テスト実行
  5. 構文エラーを発見(自分で書いたコードにバグ)
  6. デバッグ、コードを修正
  7. 再実行、まだバグが残る
  8. 再度デバッグし、最終的に成功。CSV ファイルが作業ディレクトリに出力

合計で約 12k tokens を消費(GPT-4o)。

最小起動フローの例(README と実際の設定に基づく):

# Agent Zero の最小起動フロー

# 1. clone して起動
# git clone https://github.com/agent0ai/agent-zero
# cd agent-zero && ./run.sh

# 2. LLM 設定(conf/agent-zero.ini)
[llm]
provider = openai  # anthropic / ollama も対応
model = gpt-4o
api_key = sk-xxx

# 3. Agent にタスクを投げる(Web UI または API)
prompt = """
タスク:Python でスクレイパーを書き、Hacker News のトップページのタイトルとリンクをすべて取得し、CSV に保存して。
要件:ページネーションに対応し、最低 3 ページ分のデータを取得すること。
"""

# Agent は自動で:
# - タスクを分解
# - terminal ツールで依存ライブラリをインストール(requests, beautifulsoup4)
# - コードを /tmp に書き出し
# - 実行とデバッグ
# - 最終結果を作業ディレクトリに出力

# 4. 重要設定:作業ディレクトリのマウント
# Docker 起動時に ./work_dir がコンテナの /work_dir に自動マウントされる
# Agent のすべてのファイル操作はこのディレクトリ内で行われる

遭遇した問題:

  • 初回コードに構文エラーがあり、Agent は自力で 2 回デバッグしてようやく通した。
  • タスクがより複雑(「Web アプリを完成させて」など)になると、Agent はツールを繰り返し呼び、token をあっという間に燃やす。
  • 8GB メモリだとややきつい。Docker + Python + ブラウザツール(Playwright)で RAM をしっかり食う。

どんな人に向くか

向いているケース:

  • Agent の力をサクッと体感したい、フレームワークをゼロから組みたくない人
  • リサーチ系・データ処理系のタスク(スクレイピング、データクリーニング、レポート生成)
  • ローカル動作が必要で、データプライバシーを重視する用途(データを社外に出さない)
  • 多 Agent 連携のデモを作りたい人

向かないケース:

  • 本番運用向けの業務システム(安定性が足りず、SLA は保証できない)
  • 実行フローを厳密に制御したい用途(その場合は LangGraph が適切)
  • 低スペックマシン(Docker と LLM API の両方がリソースを食う)
  • フロントエンドやデザイン系のタスク(Agent の得意領域ではない)

Agent フレームワーク初心者が最初に触るなら、ここから始めるのがおすすめだ。AutoGPT より安全で、LangGraph よりシンプルで、ReAct ループを手書きするより圧倒的に楽。


Agent Zero は銀の弾丸ではないが、「Agent をサンドボックス内で自律的に働かせる」というパターンを、実際に使える製品としてまとめ上げている。Agent フレームワークの動作原理を理解したいけれど、設定で挫折したくないという人には、悪くない入り口だ。

参考:Agent Zero GitHub

出典: https://github.com/agent0ai/agent-zero