Agent Zero 子代理委托指南用 call_subordinate 将复杂子任务交给专业 Agent【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本指南讲解 Agent Zero 框架中call_subordinate工具的完整用法如何把研究、数据分析等复杂子任务委托给专门配置的子代理subordinate如何通过profile选择子代理提示词配置、通过reset控制会话延续以及如何在子代理返回结果后高效收尾并复用长输出。读完本文你将掌握该工具的全部参数语义、调用示例、底层执行链路与测试依据能够直接在自己的对话中编写正确的委托调用。call_subordinate 是什么call_subordinate是 Agent Zero 提供给主代理superior agent的一种任务委托工具定义在 prompts/agent.system.tool.call_sub.md 中。它的定位非常明确delegate research or complex subtasks to a specialized agent即把需要专注研究或较复杂的子任务交给一个专门化的子代理去执行主代理则聚焦于整体目标协调。在实际使用中这通常意味着当主代理发现当前任务需要外部检索、专题研究、代码分析或深度报告生成时不必亲自逐步执行而是直接调用call_subordinate让一个具备对应专业配置的 Agent 去完成等待其返回结果后继续推进。工具对应的可执行实现位于 tools/call_subordinate.py 中的Delegation类底层会调用initialize_agent与Agent.monologue()完成子代理的创建和运行。参数详解call_subordinate接受三个参数其中只有message是必填参数是否必填类型说明message必填string向子代理下发的任务描述需明确角色role、目标goal和具体任务concrete taskprofile可选string子代理使用的提示词 profile 键名提供时必须精确匹配某个可用 profile留空则使用默认 profilereset可选booleanJSON 布尔值第一条消息或切换 profile 时必须为true继续同一子代理的对话时设为falsemessage任务描述的三要素message不是简单的一句话指令而是要求包含三个层次的内容role角色告诉子代理它以什么身份工作例如你是一名资深研究员goal目标说明本次委托期望达成的最终结果concrete task具体任务给出可执行的具体任务细节避免歧义。profile精确匹配的专业配置profile对应仓库中已注册的子代理 profile 键。根据 helpers/subagents.py 中的get_available_agents_dict可用 profile 来自多个来源的合并内置目录agents/origin 为 default、插件提供的 agents、用户自定义目录usr/agents/origin 为 user以及当前项目.a0proj下的 agentsorigin 为 project优先级依次覆盖。每个 profile 由一个agent.yaml或agent.json定义例如 agents/researcher/agent.yamltitle: Researcher description: Agent specialized in research, data analysis and reporting. context: Use this agent for information gathering, data analysis, topic research, and generating comprehensive reports.profile的匹配是精确匹配如果传入的键不在可用列表中实现会抛出可修复异常RepairableException并列出当前全部可用 profile 供纠正见 tools/call_subordinate.py 中的_validate_subordinate_profile。例如传入不存在的ghost会得到类似Agent profile ghost not found. Use one of the available profiles: developer (Developer), researcher (Researcher).的报错。reset子代理会话的续接与切换reset是一个 JSON 布尔值语义非常明确true用于第一次调用该工具或者需要切换 profile时强制重建子代理false用于继续同一子代理的已有对话保持其历史上下文。从源码看如果当前已存在子代理且请求了新的profile但未带resettrue执行会失败并提示需要设置resettrue才能切换tools/call_subordinate.py。完整调用示例以委托外部研究为例一个标准的调用如下原文示例来源于 prompts/agent.system.tool.call_sub.md{ thoughts: [Need focused external research before I continue.], headline: Delegating research subtask, tool_name: call_subordinate, tool_args: { profile: researcher, message: Research Italy AI trends and return key findings., reset: true } }要点拆解thoughts说明调用动机继续之前需要一次专注的外部研究headline给出人类可读的摘要tool_args中profile选researcher精确匹配 Researcher 子代理message描述了研究任务reset: true表示这是对该子代理的第一条消息。如果希望复用同一个子代理继续追问则后续调用保持reset: false子代理将保留之前的对话历史继续执行。从子代理结果到最终回答文档明确了子代理返回后的收尾规则这是提升效率的关键结果满足用户请求时直接基于子代理结果作答——不要重新做一遍相同的工作在子代理结果已足够的情况下不要再调用额外的工具——避免重复劳动和浪费推理预算。也就是说call_subordinate是一次彻底交付子代理运行完其完整 monologue独白后把最终结果交回主代理主代理的任务是把结果转化为对用户的答复而不是再次求解。复用长输出§§include(path)当子代理返回较长的输出时不要重写或压缩转录而应使用§§include(path)语法在后续消息中复用该文件内容。这一点在 prompts/fw.hint.call_sub.md 中有明确提示do not rewrite long responses, use §§include(file) instead!相关规则同样出现在 prompts/agent.system.response_tool_tips.md 与 prompts/agent.system.main.communication_additions.md 中对已有的长文本如先前工具输出使用§§include(abs_path)引用而不是重写。§§include的具体展开由 helpers/files.py 中的replace_include实现。可用 profile 列表的动态注入原文档末尾的{{if agent_profiles}} ... {{agent_profiles}} ... {{endif}}是一个模板变量占位运行时由变量插件 prompts/agent.system.tool.call_sub.py 中的CallSubordinate(VariablesPlugin)填充插件通过subagents.get_available_agents_dict(project)获取当前项目含全局可用的全部子代理将每个 profile 的名称、标题、描述与上下文注入为agent_profiles变量若没有任何可用 profile则该变量为None模板中的整个分支被跳过。这保证了系统提示中展示给模型的可用 profiles永远是实时的、与当前项目和插件状态一致的模型据此选择精确匹配的 profile 键。源码级原理一次委托的完整生命周期在 tools/call_subordinate.py 中Delegation.execute的执行流程可以拆解为以下阶段校验 profile调用_validate_subordinate_profile规范化profile兼容agent_profile别名未提供时返回空串表示默认 profile判断是否需要重建若当前不存在子代理self.agent.get_data(Agent.DATA_NAME_SUBORDINATE)为空或resettrue则用initialize_agent(override_settings{agent_profile: requested_profile})创建带指定 profile 的配置未指定则用默认 profile以Agent(self.agent.number 1, config, self.agent.context)创建编号递增的子代理实例通过sub.set_data(Agent.DATA_NAME_SUPERIOR, self.agent)与self.agent.set_data(Agent.DATA_NAME_SUBORDINATE, sub)建立双向的上下级引用常量定义见 agent.py下发消息subordinate.hist_add_user_message(UserMessage(messagemessage, attachments[]))将message写入子代理历史运行子代理await subordinate.monologue()让子代理完成完整的思考与工具执行循环返回最终结果封存话题subordinate.history.new_topic()将当前话题归档到topics为后续压缩做准备长输出提示若结果长度达到阈值save_tool_call_file.LEN_MIN附加fw.hint.call_sub.md提示提醒主代理用§§include(file)复用而不是重写返回结果Response(messageresult, break_loopFalse)将子代理结果交回主代理循环。主代理拿到结果后如果其自身也处于被委托状态agent.py 的_process_chain会沿DATA_NAME_SUPERIOR链递归把结果逐级回传从而支持多层委托的调用栈恢复包括从存档恢复对话时调用栈丢失的场景。测试验证仓库中的 tests/test_subagent_profiles.py 对委托逻辑提供了三个关键回归测试可作为行为契约参考test_call_subordinate_rejects_unknown_profile验证传入不存在的 profile 会抛出RepairableException且父代理不残留子代理数据test_call_subordinate_uses_valid_profile验证合法 profile 会创建对应配置的子代理、消息被正确写入其历史、且execute返回子代理的 monologue 结果test_call_subordinate_requires_reset_to_change_existing_profile验证已存在子代理时切换 profile 必须显式resettrue否则报错。这些测试与 helpers/persist_chat.py 中对DATA_NAME_SUBORDINATE/DATA_NAME_SUPERIOR的持久化处理相互印证说明委托关系是整个 Agent 会话生命周期中受控的一等公民。相关资源工具行为规范prompts/agent.system.tool.call_sub.md核心实现tools/call_subordinate.pyprofile 注入插件prompts/agent.system.tool.call_sub.py子代理注册与合并逻辑helpers/subagents.py示例 profile 定义agents/researcher/agent.yaml、agents/default/agent.yaml代理链回传机制agent.py回归测试tests/test_subagent_profiles.py【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考