从Docker启动到自建工具：Agent Zero AI智能体框架完整指南

从Docker启动到自建工具：Agent Zero AI智能体框架完整指南

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero

想让 AI 自己查资料、跑任务、记住上次聊到哪？Agent Zero 是开源AI智能体框架（智能体：能自主调用工具干活的 AI 程序），内置搜索、浏览器、记忆、调度等工具。这篇给一条 Docker 部署路径、一次真实任务走查，以及加工具、改行为的最小改法。

🐳 跑起来：一条 docker run 命令部署

本机装依赖的路子不用走，Docker 一条命令就能起。

1. 确认 Docker 已安装并在运行（Docker Desktop 或命令行均可）。
2. 终端执行：

docker run -p 80:80 -v a0_usr:/a0/usr agent0ai/agent-zero

3. 浏览器打开 http://localhost:80，在欢迎页完成 onboarding：Settings → External Services → API Keys 填入模型供应商和密钥。用 Docker Desktop 的话，等价操作是搜 agent-zero 镜像 → Pull → Run 并配好端口映射。

验收标准：看到带 New Chat、Projects、Memory、Scheduler 等入口按钮的仪表盘，右下角有 System Resources 资源面板，就是跑起来了。

容器启动后的 Agent Zero 主界面，左侧是聊天列表，中间是功能入口

🔍 跟一个真实任务走查：调研并汇报

用"帮我调研 3 个自托管搜索服务，对比部署难度，给个推荐"当第一个任务，发出去。

第一步，智能体调用 tools/search_engine.py 做联网搜索，拿到候选清单，这一步替代的是你手工翻十几个搜索页。接着它可能调浏览器插件（plugins/_browser/，插件：可插拔的功能包）打开候选项目的官方文档，核实真实的安装步骤。如果聊天里附了本地文档，document_query.py 会直接查文件内容，不用你先摘录重点。

产出落在聊天窗口：一份带对比的推荐结论。人不在电脑前时，notify_user.py 会把结果推成一条通知。过程中"你偏好自托管"这类判断会被记忆插件（plugins/_memory/）存下，换会话还在。

聊天窗口里，每步工具调用（GEN/SKL 日志行）都会流式显示

任务之外，还有这些现成能力：

🔧 最小改动路径：加一个能力 vs 改一个行为

工具管"多一个能力"，扩展（挂在消息处理循环特定阶段上的代码）管"改一个行为"，两件事放两个目录。

加一个能力：往 tools/ 放文件。新建 weather.py，继承 helpers/tool.py 里的 Tool，实现 async execute 并返回 Response：

from helpers.tool import Tool, Response class WeatherTool(Tool): async def execute(self, **kwargs): city = self.args.get("city", "") return Response(message=f"{city} 晴 25℃", break_loop=False)

框架启动时扫描 tools/ 自动发现，不用改任何注册表。验证：在 Web UI 里让智能体"查一下上海天气"，看它是否选中你的工具、返回内容是否符合预期。

• 别这样：给工具写注册配置 → 改成这样：文件放对位置就够了，发现机制自动生效。
• 别这样：一个文件里塞搜索、汇总、通知三段逻辑 → 改成这样：按动作拆开，搜索归搜索、通知归通知，各占一个文件。
• 别这样：工具没有说明文件 → 改成这样：补同名的 weather.py.dox.md，写清参数、输出和 break_loop（是否终止本轮循环的开关）行为，tools/AGENTS.md 要求每个工具都配。

改一个行为：往 extensions/python/ 对应阶段目录放文件。目录名就是生命周期阶段：system_prompt/ 组装系统提示词（_10_main_prompt.py），message_loop_prompts_after/ 每轮消息注入上下文（_60_include_current_datetime.py 塞当前时间、_70_include_agent_info.py 塞智能体信息）。文件名前缀数字决定执行顺序，你的钩子放进该阶段目录、起个不冲突的编号即可。验证：同一个会话里对比改动前后的注入内容。

• 别这样：把"多一个工具"写成扩展 → 改成这样：能力进 tools/，扩展只在需要插手某个生命周期点时用；要带界面的完整功能，走 plugins/。

✅ 跑通之后做三件事

按固定顺序做：先验输出、再调配置、再留惯例。

1. 先验：同一任务连跑两遍，对比改动前后的输出差异。没有对比，就没有"改好了"这回事。
2. 再调：按依赖关系动设置——先 Chat Model（聊天模型与参数，所有工具输出的地基），再 Agent Config（默认智能体档案，档案文件在 agents/），最后调单个工具的开关和输出详略。每改一项，用同一个任务验收一次。

设置面板：Agent Config、Chat Model、Utility Model 等入口都在这里

3. 再留：遵守项目惯例——新工具配同名 .py.dox.md；扩展文件名保留数字前缀；改动涉及提示词时跑一下 tests/ 里的相关用例再收工。

路线很直接：先跑通一个真实任务，再写第一个工具，然后碰扩展改生命周期，最后按 docs/guides/ 里的 browser、memory、mcp-setup 等指南逐个深入。拿不准细节就去读 docs/，每个工具旁的 .dox.md 比源码好读。

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero