Agent Zero 示例 Agent Profile 全解析：以 agents/_example 为模板掌握 Prompt、工具与扩展的定制体系

Agent Zero 示例 Agent Profile 全解析以 agents/_example 为模板掌握 Prompt、工具与扩展的定制体系【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroAgent Zero 将智能体行为定制收敛为一种可复制的目录结构每个 Agent Profile 由agent.yaml元数据、prompts/提示词覆盖、tools/工具与extensions/生命周期扩展四部分组成。本文以官方参考 Profile agents/_example 为主体结合仓库源码与 a0-create-agent 技能文档逐层拆解这套 Profile 布局的设计意图、文件契约与验证方法读完即可照模板创建属于自己的 Agent Profile。一、定位为什么需要一个_example参考 Profile在 Agent Zero 中每个可直接运行的智能体Agent都由一个Profile 目录描述。仓库内置了default、agent0、developer、hacker、researcher、tiny-local等 Profile而_example承担着特殊职责——它不追求业务能力而是作为参考标本存在。agents/_example/AGENTS.md 明确写明了它的使命Own the reference profile used to demonstrate bundled profile layout拥有并维护参考 Profile向开发者展示内置 Profile 的标准布局Show how profile-local prompts, tools, and extensions fit besideagent.yaml示范 profile 级提示词、工具、扩展如何与agent.yaml元数据文件并存。也就是说_example是理解整个 Agent Zero Profile 定制体系的最小完整示例。从 skills/a0-create-agent/SKILL.md 可以确认它的完整参考布局agents/_example/ ├── agent.yaml # profile 元数据title / description / context ├── prompts/ │ ├── agent.system.main.specifics.md # 角色提示词覆盖 │ └── agent.system.tool.example_tool.md # 工具使用说明自动并入系统提示词 ├── tools/ │ ├── example_tool.py # 全新工具 │ └── response.py # 重定义核心 response 工具 └── extensions/ └── agent_init/ └── _10_example_extension.py # init 生命周期钩子需要说明的是在当前仓库检出中该目录实际包含prompts/、tools/、extensions/三个子目录agent.yaml未一并检出其元数据职责由文档约定仓库内可直接对照的同结构文件为 agents/agent0/agent.yaml。此外_example是隐藏参考在 helpers/settings.py 中Profile 列表会执行item[key] ! _example过滤避免它出现在 WebUI 的 Profile 选择器中干扰用户。二、职责划分Ownership每个目录只干一件事_example的 AGENTS.md 将目录内各文件的职责边界规定得非常清晰这也是所有 Profile 都应遵守的划分原则目录 / 文件职责仓库内对应实现agent.yaml承载 Profile 元数据title/description/context供发现与委派使用参考 agents/agent0/agent.yamlprompts/存放提示词覆盖示例按同名覆盖机制生效见第四节tools/存放 Profile 级工具示例见第五节extensions/存放 Profile 级生命周期扩展示例见第六节父级文档 agents/AGENTS.md 进一步补充了两条关键约束agent.yaml是 Profile 的唯一入口且必须是合法 YAML用户自建 Profile 应放在usr/agents/下而不是agents/目录——agents/只保留随产品发布的框架级 Profiledefault、agent0、developer、hacker、researcher、_example。skills/a0-create-agent/SKILL.md 也以醒目提示强调了这一约定。三、Profile 元数据agent.yaml的极简三字段模型_example文档强调agent.yamlowns the example profile metadata而 Agent Zero 刻意将元数据压缩到极小。从 agents/agent0/agent.yaml 可以看到实际结构title: Agent 0 description: Main agent of the system communicating directly with the user. context: 三个字段的语义依据 skills/a0-create-agent/SKILL.mdtitle人类可读的显示名称出现在 WebUI 的 Agent 选择器中description一行能力摘要用于展示与检索context写给上级 Agent的委派说明告诉它在什么场景下应把任务委派给这个 Profile。重要限制agent.yaml只允许这三个内容字段。不要往里面塞模型名、temperature、allowed_tools等配置——模型预设由_model_config插件的独立配置文件管理工具可用性由插件激活控制。这是 skills/a0-create-agent/SKILL.md 明确强调的 schema 约束也是避免配置漂移的关键设计。四、prompts/同名文件覆盖机制与两个示范文件Profile 的提示词行为默认继承根目录 prompts/ 与defaultProfile只有在需要改变行为时才提供覆盖。覆盖机制非常简单把同名文件放进profile/prompts/加载器优先命中 profile 级文件否则回退到默认。_example用两个文件示范了两种典型覆盖场景。4.1agent.system.main.specifics.md角色/身份扩展槽agents/_example/prompts/agent.system.main.specifics.md 是覆盖agent.system.main.specifics.md的示例。这个文件是框架专门为 Profile 角色定制预留的扩展槽根目录版本 prompts/agent.system.main.specifics.md 与default中的版本默认均为空因此 Profile 可以放心覆盖而不必担心与基础提示词冲突。它会被嵌入agent.system.main.md中紧跟agent.system.main.role.md的位置在继承的角色之上叠加专属身份。_example用它演示了一个虚构的Agent Zero 电影角色人设## Your role You are Agent Zero, a sci-fi character from the movie Agent Zero.文件头部的注释还记录了覆盖规则只复制并修改你确实需要改的文件其余保持默认避免因复制未变更的大文件而在框架升级时产生静默漂移skills/a0-create-agent/SKILL.md 对此有专门提醒。4.2agent.system.tool.example_tool.md工具的自动提示词注入agents/_example/prompts/agent.system.tool.example_tool.md 示范了另一个机制任何匹配agent.system.tool.*.md命名的文件都会被自动并入系统提示词用于向模型描述某个工具的用法与 JSON 调用格式。示例文件给出了完整的工具调用 JSON 模板usage: ~~~json { thoughts: [ Lets test the example tool..., ], headline: Testing example tool, tool_name: example_tool, tool_args: { test_input: XYZ, } } ~~~这条规则意味着新增一个 Profile 级工具后必须配套一个agent.system.tool.tool_name.md提示词文件否则模型不知道何时、如何调用该工具。五、tools/Profile 级工具与核心工具重定义Profile 级工具与根 tools/ 中的工具遵循完全相同的Tool契约这是 agents/AGENTS.md 与_example文档共同强调的约束。_example/tools/下提供了两个示范。5.1example_tool.py从零定义一个工具agents/_example/tools/example_tool.py 展示了一个最小可用的工具类from helpers.tool import Tool, Response class ExampleTool(Tool): async def execute(self, **kwargs): test_input kwargs.get(test_input, ) print(Example tool executed with test_input: test_input) return Response( messageThis is an example tool response, test_input: test_input, break_loopFalse, )对照基类 helpers/tool.py 可以理解其底层契约Tool抽象基类子类只需实现async def execute(self, **kwargs)其构造函数会注入agent、name、method、args、loop_data等上下文Responsedataclass包含message回传给 Agent 的消息、break_loop为True时终止当前消息链以及可选的additional字典用于附带额外的工具结果元数据基类还提供了before_execution/after_execution钩子负责日志记录、参数展示与把工具结果写入 Agent 历史hist_add_tool_result。5.2response.py同名文件替换核心工具agents/_example/tools/response.py 示范了 Profile 定制体系的另一个强大能力在 profile 目录放入与核心工具同名的文件即可仅对该 Profile 生效地替换核心工具实现。该文件重定义了根 tools/response.py 的ResponseTool在execute中直接从参数提取文本并break_loopTrue结束对话回合并注释说明日志职责已由live_response扩展接管这也是 Profile 级工具与扩展协同的实例。使用 Profile 级工具必须记住两条规则skills/a0-create-agent/SKILL.md新工具必须配套prompts/agent.system.tool.tool_name.md提示词文件与核心工具同名的文件是替换而非并存。六、extensions/Profile 级生命周期扩展agents/_example/extensions/agent_init/_10_example_extension.py 展示了生命周期扩展的写法from helpers.extension import Extension class ExampleExtension(Extension): async def execute(self, **kwargs): # rename the agent to SuperAgent0 self.agent.agent_name SuperAgent str(self.agent.number)关键点文件路径约定扩展放在profile/extensions/hook_point/_NN_name.py其中hook_point是生命周期节点如agent_init_NN_数字前缀控制同一节点的执行顺序——_10_即表示该扩展在 init 阶段的早期执行执行时机该示例在 Agent 初始化时把当前 Agent 重命名为SuperAgent编号演示了在扩展中访问self.agent运行时对象的能力契约一致Profile 级扩展与框架自身的扩展体系extensions/使用同一套Extension契约。一个值得注意的兼容性细节根据 skills/a0-development/references/extensions.md 的说明仓库检出的_example仍保留了extensions/agent_init/...的旧式布局而当前框架的扩展发现代码期望的是extensions/python/point结构。因此在实际复制该目录时应把扩展放到extensions/python/hook_point/下框架自身的扩展即采用此结构例如 extensions/python/system_prompt/_11_tools_prompt.py。这也印证了_example文档保持简单示例的定位——它示范的是概念具体路径以源码与 DOX 为准。七、契约与边界什么能放、什么不能放_example的 AGENTS.md 用 Local Contracts 一节明确了参考 Profile 的维护边界这些约束对所有 Profile 同样适用保持通用、最小、安全Profile 应generic, minimal, and safe to copy into user or plugin profile work即任何人可以放心地把_example作为起点复制到自己的用户 Profile 或插件 Profile 中不塞产品行为不要在_example里加入本该属于正式内置 Profile 的业务逻辑工具与扩展必须遵守与根级相同的契约倾向用简单示例说明结构而不是追求复杂行为。父级 agents/AGENTS.md 还补充了一条安全红线内置 Profile 中不得包含密钥、Provider API Key、本地路径或用户特定设置。若 Profile 需要私密信息应走独立的安全机制如 helpers/secrets.py 或 prompts/agent.system.secrets.md 约定的流程而不是硬编码进 Profile 文件。八、验证如何确认 Profile 改动正确_example文档把验证拆成两层手工检查编辑后人工检查 YAML 与 prompt 文件名的合法性命名是否匹配agent.system.tool.*.md等约定自动化测试当改动涉及 Profile 发现机制或 schema 假设时运行 Profile 加载相关测试如pytest。结合 skills/a0-create-agent/SKILL.md 的端到端验证流程一个完整的验证路径是新 Profile 在下次 Agent 初始化时被拾取无需重启已有会话但需要新开一个 Agent/子 Agent 才会生效由上级 Agent 通过call_subordinate委派时使用目录名而非title作为 Profile 标识依次核对UI Agent 选择器中的标题、系统提示词中的角色覆盖是否生效、Profile 级工具是否可调用且其 prompt 文件已注入若 Profile 未出现按顺序检查目录名是否匹配^[a-z0-9_-]$且唯一、agent.yaml是否为合法 YAML、是否位于受支持的搜索路径用户级在usr/agents/插件级在usr/plugins/plugin/agents/项目级在project/.a0proj/agents/。九、实战把_example变成你自己的 Profile综合以上所有机制从_example模板创建一个业务 Profile 的最小步骤为确定作用域默认在usr/agents/profile_name/下创建不要放进agents/写元数据创建agent.yaml仅含title、description、context三字段写角色提示词创建prompts/agent.system.main.specifics.md这是绝大多数定制的主战场——仓库内所有内置 Profileagent0、developer、hacker、researcher都覆盖了该文件agents/developer/prompts/agent.system.main.specifics.md 是内容最丰富的范本按需添加组件只有确需改变协议时才覆盖agent.system.main.communication.md、agent.system.main.solving.md等更底层的提示词只有确需新能力时才添加tools/与extensions/且新工具必须配套agent.system.tool.name.md测试并委派按第八节流程验证随后即可通过call_subordinate把任务委派给新 Profile。_example的价值正在于此它把 Profile 定制所需的全部机制浓缩在一个目录里是理解 Agent Zero 多智能体架构、以及动手创建新智能体的最佳起点。无论你是要做一个垂直领域的专家 Agent还是要随插件分发一套团队 Profile都可以先复制_example的形状再逐层替换为自己的内容。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考