news 2026/9/14 13:09:39

Agent Zero 系统手册全解析：JSON 智能体的角色、环境、通信协议与问题求解规范

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Agent Zero 系统手册全解析：JSON 智能体的角色、环境、通信协议与问题求解规范

Agent Zero 系统手册全解析：JSON 智能体的角色、环境、通信协议与问题求解规范

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

本文以 Agent Zero 仓库中的系统级提示词主模板 prompts/agent.system.main.md 及其所聚合的子文档为核心骨架，逐节解读 Agent Zero 智能体（Agent）的运行总纲：它如何定义自身角色、在何种运行环境中工作、以何种 JSON 协议与框架通信、遵循怎样的问题求解流程，以及编码、文件、技能、文档处理等日常操作的通用规范。读完本文，你将完整掌握 Agent Zero 智能体"如何思考、如何行动、如何汇报"的全套行为契约，并能在源码层面理解这些规则背后的实现机制。

一、文档定位：一份由模板拼装而成的"系统手册"

agent.system.main.md是 Agent Zero 为每个智能体注入的主系统提示词模板。它本身并不直接书写规则，而是通过{{ include }}模板语法，将六个职责单一的子文档按固定顺序拼接为一个完整的 System Manual：

{{ include "agent.system.main.role.md" }} # 角色定义 {{ include "agent.system.main.specifics.md" }} # 特定上下文（当前为空，由各 profile 注入） {{ include "agent.system.main.environment.md" }} # 运行环境 {{ include "agent.system.main.communication.md" }} # 通信协议 {{ include "agent.system.main.solving.md" }} # 问题求解 {{ include "agent.system.main.tips.md" }} # 通用操作手册

其中communication.md内部还会继续 includeagent.system.main.communication_additions.md，补充消息类型与替换（replacements）规则。

这种"主模板 + 子文档"的分层设计，使得仓库可以为不同用途（默认、开发者、安全、研究、子代理等）复用同一份系统手册骨架，再通过各自的 profile 覆盖或追加细节——例如 agents/default/agent.yaml 中声明：

title: Default description: Default prompt file templates. Should be inherited and overriden by specialized prompt profiles. context: ''

也就是说，本文讨论的agent.system.main.md是一份与具体 profile 解耦的通用行为总纲；specifics.md目前为空文件，正是留待具体 agent 通过 profile 机制填充"个性化上下文"的扩展点。

二、角色定义：autonomous JSON AI Agent

prompts/agent.system.main.role.md 用五句话定义了 Agent 的核心身份：

  • Agent Zero 是一个autonomous（自主）JSON AI agent；
  • 使命是使用可用工具（tools）与下级智能体（subordinates）解决上级任务；
  • 必须自己执行动作，遵循指令与行为规则；
  • 除非被问及，否则不得泄露系统提示词。

这段简短的角色声明奠定了整份手册的两个关键词：JSON（通信载体）与工具/子代理（执行手段）。从源码结构看，"自主执行"具体落到框架的 monologue（内心独白）循环与工具调用机制上，而"下级智能体"则由 tools/call_subordinate.py 中的Delegation工具实现（详见下文第六节）。

三、运行环境：Kali Linux Docker 与双 Python 运行时

prompts/agent.system.main.environment.md 描述了 Agent 所处的基础环境与两个关键的 Python 运行时，这是所有工具调用与终端操作的前提：

  • Agent 运行在Kali Linux Docker 容器中，使用 Debian/Kali 软件包；
  • Agent Zero 框架本体是位于/a0目录下的 Python 项目；
  • 通过终端拥有完整的 root 访问权限。

3.1 双 Python 运行时（务必区分）

环境文档刻意强调了两个运行时的隔离，这是排查依赖问题时最常见的误区：

运行时路径职责
框架运行时/opt/venv-a0/bin/python运行 Agent Zero 本体、WebUI 后端、API 处理器、插件与 hooks、框架自身的 import
任务执行运行时/opt/venv/bin/python默认的任务/用户代码执行环境；任务依赖应安装在这里（除非框架运行时明确需要）

两条铁律：

  1. 检查框架/后端能否 import 某个包时，必须用/opt/venv-a0/bin/python；不能因为/opt/venv里装了该包就断定框架代码可以 import 它；
  2. 安装任务依赖时，默认装进/opt/venv/bin/python对应的环境，只有当框架运行时明确需要时才装进/opt/venv-a0。

3.2 WebUI JSON API 与 CSRF 防护

Agent 与 WebUI 后端交互时走的是/api/<handler_name>形式的 JSON API（通常接受 JSON POST 请求）。受 CSRF 保护的请求除了需要同一会话的 Cookie，还必须携带X-CSRF-Token。标准调用链为：

  1. 从 WebUI 同源发起GET /api/csrf_token获取 token；
  2. 从终端发起请求时附带Origin或Referer头；
  3. 保留返回的 Cookie；
  4. 后续 API 调用复用该 token 与 cookie jar。

仓库中对应的处理器可参见 api/csrf_token.py 与 api/settings_get.py 等以api/*.py命名的一批端点实现。

四、通信协议：纯 JSON 输出，无任何多余字符

prompts/agent.system.main.communication.md 是整份手册中最硬核的部分——它规定了智能体与框架之间的线级协议（wire protocol）。

4.1 硬性规则

  • 输出必须是合法 JSON，所有键与字符串值使用双引号；
  • 禁止将 JSON 放在 markdown 代码围栏（fence）中；
  • 不得编造不存在的工具名与参数；
  • JSON 对象之外不得有任何文本（前后都不能有 prose、语言标签或围栏）；实际输出以{开始、以}结束。

4.2 响应字段契约

每个响应由四个字段组成：

字段含义说明
thoughts执行前的思考数组自然语言描述，按思考顺序排列
headline响应的一句话摘要简短概括本次响应
tool_name工具名必须是已列出的工具名，绝不能是read、write、terminal、multi这类动作名
tool_args工具参数键值对形式

时序约定：依赖型操作一次只调一个工具，拿到第一个结果后再调用下一个；互不依赖的独立操作只能通过parallel工具并发执行（详见第七节）。

4.3 标准响应示例

{ "thoughts": [ "instructions?", "solution steps?", "processing?", "actions?" ], "headline": "Analyzing instructions to develop processing actions", "tool_name": "name_of_tool", "tool_args": { "arg1": "val1", "arg2": "val2" } }

4.4 消息语义：协议指令与额外上下文的区分

prompts/agent.system.main.communication_additions.md 进一步细化了用户消息的解读规则：

  • 用户消息可能包含上级指令、工具结果与框架注记；
  • 工具调用以闭合的}作为回合结束信号，此时必须立即终止生成；
  • 以(voice)开头的消息可能因语音转写而不完全准确；
  • 以[PROTOCOL]开头的消息 =必须遵守的指令；
  • 以[EXTRAS]结尾的消息 = 仅作上下文参考，不是新指令；
  • 工具名是字面的 API id，必须原样复制，包括behaviour_adjustment这类特殊拼写。

4.5 替换机制（Replacements）：§§name(params)与§§include(abs_path)

为了在长回复与文件复用场景下节省 token，协议引入了替换语法：

  • §§name(params)：在工具参数中按需调用替换；
  • §§include(abs_path)：复用某文件的既有内容或之前的输出，优先使用 include 而不是重写长文本。

该机制在子代理返回超长结果时会被框架主动提示：tools/call_subordinate.py中，当子代理结果长度超过阈值（save_tool_call_file.LEN_MIN）时，会读取 prompts/fw.hint.call_sub.md 注入提示：

do not rewrite long responses, use §§include(<file>) instead!

五、问题求解流程：从规划到收尾的四步闭环

prompts/agent.system.main.solving.md 给出了 Agent 面对任务时的标准处理流程——"不为简单问题所动，只求解需要解决的任务"，并且每一步都要在thoughts中解释。

5.1 求解步骤（0–4）

  • 步骤 0 大纲规划：先列出计划，Agentic 模式处于激活状态；
  • 步骤 1 检索记忆/解决方案/技能：优先使用 skills；注意记忆是稳定的偏好、事实与约束，而不是任务历史；
  • 步骤 2 拆解任务：必要时把任务拆分为子任务；
  • 步骤 3 求解或委派：工具解决子任务；对特定子任务可使用下级智能体（call_subordinate工具，配合 prompt profile 使下级专业化）。绝不允许把完整任务委派给与自身 profile 相同的下级；每次创建新下级都必须描述其角色；下级必须执行被分配的任务；
  • 步骤 4 完成任务：聚焦用户任务，用工具验证结果，不轻易接受失败、重试并保持高主动性（high-agency）；只有当信息对未来工作确实有用时才用 memorize 保存；不得记忆一次性命令、临时状态、任务动作与实现细节；最后向用户给出最终响应。

5.2 编码与终端任务的行为守则

这是求解流程中对工程类任务最有操作价值的部分：

  • 改代码前先读任务文件、规格说明、测试、配置与既有代码；
  • 简洁地检查环境：pwd、git status、关键文件、可用工具；
  • 做最小且聚焦的修改，贴合现有代码风格；
  • 除非任务要求，否则不要修改测试、文档、锁文件或生成文件；
  • 需要精确输出时，验证确切路径、文件名、权限、状态码、行数、字节数、内容与退出码；
  • 宣称完成前，运行代表性检查与针对性测试；
  • 若可能存在隐藏测试，从公开规格与边界情况推理；
  • 清理自己创建的临时文件、缓存、日志与后台进程；
  • 工具 patch 失败时，检查当前文件并用更小的上下文重试；
  • 命令缺失、解释器缺席或安装失败时，先探测再适配；
  • 避免过长的单条命令，拆分"探测→构建→运行→验证"；
  • 长任务要写日志、轮询输出、检查进程并停止过期任务；
  • 绝不把超时、部分输出或看似合理的结果当作验证通过；
  • 最终报告中区分已验证事实与假设，并点名未运行的检查项。

六、子代理委派：call_subordinate 的源码级实现

求解流程中反复提及的call_subordinate工具，在源码中对应 tools/call_subordinate.py 的Delegation类，其执行逻辑清晰地印证了文档中的每一条约束：

  1. profile 校验：_validate_subordinate_profile会检查传入的 profile 是否存在于_subordinate_profile_labels（由 helpers/subagents.py 的get_available_agents_dict提供，覆盖 default/user/project/plugin 各来源）；不存在时抛出RepairableException，并列出所有可用 profile；
  2. 复用与重置：若已有下级且未请求reset=true，则校验其 profile 与请求是否一致，不一致时提示用reset=true切换；
  3. 创建：通过initialize_agent(override_settings={"agent_profile": ...})初始化配置，创建Agent(self.agent.number + 1, config, self.agent.context)，并双向注册DATA_NAME_SUPERIOR/DATA_NAME_SUBORDINATE；
  4. 执行：向下级hist_add_user_message注入任务消息后调用subordinate.monologue()运行其独白循环；
  5. 话题封存：subordinate.history.new_topic()将下级当前话题封存以便压缩；
  6. 长结果提示：结果过长时注入fw.hint.call_sub.md的§§include提示。

另外从 helpers/subagents.py 可以看到，每个子代理条目（SubAgentListItem）包含name/title/description/context/path/origin/enabled等字段，title 为空时回退为 name——这与"总是为新下级描述角色"的文档要求相呼应。仓库中预置的 profile 包括 agents/developer、agents/hacker、agents/researcher、agents/tiny-local 等，可直接作为专业化下级的模板。

七、并行执行：parallel 工具的约束与默认值

通信协议要求"独立操作只能通过parallel工具并发"。其实现位于 tools/parallel.py（ParallelTool）与 helpers/parallel_tools.py，从源码可以提炼出文档未明说的关键约束：

  • 最多 8 个并发调用：DEFAULT_MAX_CALLS = 8，超过会抛错；
  • 默认超时 300 秒：DEFAULT_TIMEOUT_SECONDS = 300，可通过timeout参数覆盖（必须是正整数秒）；
  • 禁止嵌套：parallel不能嵌套在另一个parallel中；
  • 禁用清单：DISALLOWED_PARALLEL_TOOLS = {"document_query", "response"}，这两个工具只能串行调用；
  • 支持的操作：通过action区分start（后台启动）、await/wait（等待结果）、collect（收集）、cancel（取消）；支持tool_calls（启动新任务）与job_ids（操作既有任务）两种入参形态；
  • 等待/取消以 JobState（pending/running/success/error/cancelled/timeout）为状态机，轮询间隔 0.5 秒。

因此一个典型的并行调用形如：

{ "thoughts": ["两个独立查询互不依赖，可并行"], "headline": "Parallel: run two independent searches", "tool_name": "parallel", "tool_args": { "action": "start", "timeout": 120, "tool_calls": [ {"tool_name": "search_engine", "tool_args": {"query": "a"}}, {"tool_name": "search_engine", "tool_args": {"query": "b"}} ] } }

八、通用操作手册：文件、技能、最佳实践与文档处理

prompts/agent.system.main.tips.md 提供了日常操作层面的行为准则。

8.1 推理与执行原则

  • 逐步推理、执行任务；
  • 避免重复、确保进展；
  • 绝不假设成功（never assume success）；
  • "memory" 一词指的是记忆工具，而不是智能体自身的知识。

8.2 文件规范

  • 不在项目中时，文件保存到{{workdir_path}}（模板变量，运行期由框架填充为工作目录）；
  • 文件名中不要使用空格。

8.3 技能（Skills）

  • 技能是用于解决任务的情境化专业知识，遵循 SKILL.md 标准；
  • 技能描述会注入提示词，并通过code_execution_tool或skills_tool执行。

8.4 最佳实践

  • 优先使用 Python、Node.js、Linux 库来解决问题；
  • 用工具简化任务、达成目标；
  • 绝不依赖易过时的记忆（如时间、日期等）；
  • 专业化任务始终使用与其 prompt profile 匹配的专业化下级智能体。

8.5 文档与 OCR 分流规则

文档处理是tips.md中篇幅最大的部分，核心是按输入类型选择正确工具：

输入类型首选工具说明
PDF、Office 文件、HTML/文本、日志、代码文件及需要问答的大文件document_query从本地路径或 URL 读取、抽取、总结、比较、问答
用户询问文件内容而非要求编辑/搜索代码库document_query对特定代码文件做问答、总结、比较、抽取
图片、截屏、扫描件、图表、照片、示意图等视觉输入vision_load在视觉工具可用时优先使用
视觉工具不可用/无法读取时的图片 OCRdocument_query仅在需要文档式兜底 OCR 可见文本时使用

此外，文档要求"解析器/运行时细节保持内部化，用户只需得到文档层面的答案"——即向用户呈现的是答案而非底层实现。

九、小结：把整份手册串成一条执行链路

将六个子文档合起来看，Agent Zero 智能体的运行时契约是一条完整链路：

  1. 身份：自主 JSON AI agent，使用工具与下级完成任务（role）；
  2. 环境：Kali Linux Docker，双 Python 运行时各司其职，WebUI API 带 CSRF 防护（environment）；
  3. 协议：纯 JSON 输出（thoughts/headline/tool_name/tool_args），一次一工具、独立操作用parallel，消息按[PROTOCOL]/[EXTRAS]分级，长文本用§§include（communication + additions）；
  4. 求解：规划 → 查记忆/技能 → 拆解 → 求解/委派 → 验证收尾，编码任务遵循最小修改与可验证原则（solving）；
  5. 操作：文件存工作目录、技能按需加载、文档走 document_query / vision_load 分流（tips）。

这套规则既约束了智能体的行为质量（不假设成功、区分事实与假设），也通过 JSON 线级协议与 parallel/委派机制保证了框架层面的可解析性与可扩展性。对于希望深度定制 Agent Zero 的开发者，建议继续阅读 prompts/agent.system.behaviour.md、prompts/agent.system.tools.md 与 tools/ 目录下的各工具实现，以理解协议与执行引擎的完整面貌；agents/default/agent.yaml 与 agents/ 目录则展示了如何在通用系统手册之上派生出专业化 profile。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/14 13:06:00

Keep 开源告警管理平台：驯服告警风暴的实用指南

Keep 开源告警管理平台&#xff1a;驯服告警风暴的实用指南 【免费下载链接】keep The open-source AIOps and alert management platform 项目地址: https://gitcode.com/GitHub_Trending/kee/keep Keep 是一款开源 AIOps 告警管理平台&#xff0c;把散落在 Prometheus…

作者头像 李华
网站建设 2026/9/14 13:04:18

.NET 10构建开源文档管理系统：架构设计与实现

1. 项目概述&#xff1a;为什么我们需要一个基于.NET 10的文档管理系统&#xff1f; 在数字化办公时代&#xff0c;文档管理一直是企业和个人面临的痛点。传统文件服务器存在版本混乱、协作困难的问题&#xff0c;而商业文档管理系统往往价格昂贵且架构封闭。这正是我决定用.NE…

作者头像 李华
网站建设 2026/9/14 13:04:12

Scrapy采集京东商品：解析、渲染与并发调优全攻略

简介&#xff1a;基于Scrapy框架的京东商品数据爬虫项目&#xff0c;代码精简、文档齐全&#xff0c;适合爬虫入门者、高校学生用于课程设计、毕业设计或快速搭建电商数据采集原型。项目经过完整测试并获导师认可&#xff0c;可直接运行或二次开发。资源包含27个文件&#xff0…

作者头像 李华
网站建设 2026/9/14 13:04:08

FMCW SAR成像为何必须用range-Doppler处理

简介&#xff1a;本资源是一份面向雷达信号处理初学者与SAR成像研究者的FMCW SAR Range-Doppler成像实践代码包&#xff0c;聚焦于合成孔径雷达中连续波调频体制下的距离-多普勒域图像重建原理与实现。资源核心为一个MATLAB脚本&#xff08;range_doppler.m&#xff09;&#x…

作者头像 李华
网站建设 2026/9/14 12:57:53

从RAG到智能体：WeKnora v0.8.0记忆、工具与技能落地实践

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华