Agent Zero 拆解:一个 18.9k Star 的通用 Agent 框架
GitHub 上 Agent 框架一堆,但真正能跑起来、又不把你电脑搞炸的不多。Agent Zero 是其中一个——18.9k star,Python 写,靠 Docker 把 AI 关进沙箱里跑。
我把它跑了一遍,下面是拆解。
它解决什么问题
2023 年 AutoGPT 火的时候,很多人装完第一次跑就后悔了。Agent 直接拿到本地文件系统权限,一个 prompt 写错,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 一个 prompt,比如"调研 GitHub 上最热门的 5 个 Python Web 框架",然后看它表演。
它怎么工作(架构)
三层结构,画出来大概是这样:
┌─────────────────────────────┐
│ 主 Agent (Agent Zero) │ ← 入口,接需求、分解任务
└──────────────┬──────────────┘
│ 动态创建
┌──────────────┐
▼ ▼
┌──────────┐ ──────────
│ 子 Agent │ │ 子 Agent │ ← 处理独立子任务
└────┬───── └─────────┘
│ │
▼ ▼
─────────────────────────────
│ 工具层(终端/文件/浏览器) │
└─────────────────────────────
│
▼
┌─────────────────────────────┐
│ Docker 沙箱(执行隔离) │
└─────────────────────────────
几个关键点:
- 主 Agent 是入口。它接需求、做任务分解、决定要不要派活儿给子 Agent
- 子 Agent 由主 Agent 动态创建。每个子 Agent 处理一个独立子任务,结束后可以把结果汇报回主 Agent
- 工具层封装了终端执行、文件读写、浏览器自动化(Playwright)、代码执行
- 记忆系统分两层:短期(当前会话的 context window)和长期(跨会话的向量存储 / 文件)
- Docker 容器负责执行隔离。所有 shell 命令、文件操作都跑在容器里,不会污染宿主机
核心循环很 ReAct:思考 → 选工具 → 执行 → 观察结果 → 继续。
它哪里好 / 哪里不好
好的方面
- Docker 隔离是真的落地,不是嘴上说说。Agent 就算写出
rm -rf /,炸的也是容器 - 配置简单。ini 文件配好 LLM 就能跑,不用学一堆框架概念
- Web UI 做得不错。每一步操作可视化,调试比纯命令行友好得多
- 多 Agent 协作的层级结构对复杂任务有用。比如"调研 5 个框架"可以拆成 5 个子 Agent 并行跑
- 社区活跃。18.9k star,issue 和 PR 都有人在跟
短板
- 依赖重。必须 Docker,磁盘占用 5GB+,启动慢
- Agent 行为不可预测。复杂任务容易卡死循环——它会反复调同一个工具,调到 token 烧光
- 调试困难。出错时你只能看日志,Agent 的"思考"过程虽然可见,但根因分析靠猜
- token 消耗大。我下面那个任务吃了 12k tokens,复杂任务轻松破百万
- 中文场景下工具调用准确率不如英文。Prompt 里的中文描述有时会让 Agent 选错工具
跟 LangGraph 比,结构化程度低,但上手快 10 倍。跟 AutoGPT 比,安全性和稳定性好得多。
我试了下
机器:8GB 内存的 Mac mini(M1)。
任务 prompt:
"用 Python 写个爬虫,抓取 Hacker News 首页标题,存成 CSV。"
Agent 大约花了 4 分钟,分了 8 步:
- 思考任务分解(需要 requests、beautifulsoup4)
- 调用 terminal 工具:
pip install requests beautifulsoup4 - 写爬虫代码到
/work_dir/hn_scraper.py - 执行测试
- 发现语法错误(自己写的代码有 bug)
- Debug,改代码
- 再执行,还有 bug
- 再 debug,最终成功,CSV 文件出现在工作目录
整个过程消耗约 12k tokens(GPT-4o)。
最小启动流程示例(基于 README 和实际配置):
# Agent Zero 的最小启动流程
# 1. 克隆并启动
# 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 文件
# - 执行并 debug
# - 输出最终结果到工作目录
# 4. 关键配置:工作目录挂载
# Docker 启动时会自动挂载 ./work_dir 到容器 /work_dir
# Agent 所有文件操作都在这个目录里
碰到的问题:
- 第一次写代码有语法错误,Agent 自己 debug 了两次才跑通
- 如果任务更复杂(比如"帮我做个完整 Web 应用"),Agent 会反复调用工具,token 烧得很快
- 8GB 内存跑起来有点紧,Docker + Python + 浏览器工具(Playwright)会吃不少 RAM
谁该用
适合:
- 想快速体验 Agent 能力、不想从零搭框架的人
- 做研究类、数据处理类任务(爬虫、数据清洗、报告生成)
- 需要本地部署、对数据隐私有要求的场景(数据不出本机)
- 想搞多 Agent 协作 demo 的人
不适合:
- 生产环境的业务系统(稳定性不够,SLA 保证不了)
- 需要严格可控执行流程的场景(用 LangGraph 更合适)
- 低配机器(Docker + LLM API 都吃资源)
- 纯前端 / 设计类任务(Agent 不擅长)
新手第一次玩 Agent 框架,推荐从这个开始。比 AutoGPT 安全,比 LangGraph 简单,比手动写 ReAct 循环省事。
Agent Zero 不是银弹,但它把"Agent 在沙箱里自主干活"这个模式做成了一个能用的产品。对于想理解 Agent 框架工作原理、又不想被配置劝退的人,它是个不错的起点。