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 サンドボックス(実行分離) │
└────────────────────────┘
押さえておきたいポイント:
- メイン Agent がエントリーポイント。依頼を受け、タスクを分解し、子 Agent に投げ分けるかどうかを判断する。
- 子 Agent はメイン Agent が動的に生成する。それぞれ独立したサブタスクを処理し、完了後にメイン Agent へ結果を返す。
- ツール層 はターミナル実行、ファイル読み書き、ブラウザ自動化(Playwright)、コード実行をラップしている。
- メモリシステム は二段構成。短期(現在のセッションの context window)と長期(セッションをまたぐベクトルストア / ファイル)。
- 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 ステップで処理した。
- タスク分解(requests、beautifulsoup4 が必要と判断)
- terminal ツール呼び出し:
pip install requests beautifulsoup4 - スクレイパーコードを
/work_dir/hn_scraper.pyに書き出し - テスト実行
- 構文エラーを発見(自分で書いたコードにバグ)
- デバッグ、コードを修正
- 再実行、まだバグが残る
- 再度デバッグし、最終的に成功。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 フレームワークの動作原理を理解したいけれど、設定で挫折したくないという人には、悪くない入り口だ。