框架

Agent Zero 拆解:一个 18.9k Star 的通用 Agent 框架

Agent Zero 用 Docker 沙箱让 AI 自主跑代码、做研究、写文件,主 Agent 还能派生子 Agent。本文拆它的架构、跑通流程,再聊聊和 AutoGPT、LangGraph 的差异。

字号

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 沙箱(执行隔离)    │
└─────────────────────────────

几个关键点:

  1. 主 Agent 是入口。它接需求、做任务分解、决定要不要派活儿给子 Agent
  2. 子 Agent 由主 Agent 动态创建。每个子 Agent 处理一个独立子任务,结束后可以把结果汇报回主 Agent
  3. 工具层封装了终端执行、文件读写、浏览器自动化(Playwright)、代码执行
  4. 记忆系统分两层:短期(当前会话的 context window)和长期(跨会话的向量存储 / 文件)
  5. 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 步:

  1. 思考任务分解(需要 requests、beautifulsoup4)
  2. 调用 terminal 工具:pip install requests beautifulsoup4
  3. 写爬虫代码到 /work_dir/hn_scraper.py
  4. 执行测试
  5. 发现语法错误(自己写的代码有 bug)
  6. Debug,改代码
  7. 再执行,还有 bug
  8. 再 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 框架工作原理、又不想被配置劝退的人,它是个不错的起点。

参考:Agent Zero GitHub

来源: https://github.com/agent0ai/agent-zero