人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载导读本文基于 openJiuwen agent-core 中 agent_teams 模块的设计文档 F_26_spawn-tools-split-by-role.md完整讲解智能体团队Agent Team的“生成成员”工具是如何从一个参数臃肿、职责混杂的单一spawn_member工具重构为四个角色专属工具spawn_teammate/spawn_human_agent/spawn_bridge_agent/spawn_external_cli的。文章将覆盖重构动机、四个工具的扁平 Schema 契约、能力门控动态注册机制、predefined 团队模式门控、i18n 与系统提示词同步以及拒绝方案与验证基线并结合仓库源码与单元测试给出可复现的依据。读完本文读者将理解“面向 LLM 的工具设计为何要扁平化”并能直接参考源码把这一模式应用到自己的 Agent 工具集中。背景单一 spawn_member 工具的三个坏味道在重构之前agent_teams 的 leader 工具集中只有一个spawn_member工具。它的输入 Schema 把10 个参数平铺在第一层但这些参数实际上分属四个互斥的role_typeteammate/human_agent/bridge_agent/external_cli参数teammatehuman_agentbridge_agentexternal_climember_name / display_name / desc✓✓✓✓prompt / model_name✓运行时拒绝✓忽略cli_agent忽略忽略忽略必填mailbox_inject_mode / protocol / adapter_config忽略忽略✓忽略设计文档明确指出这种平铺设计带来的三个问题LLM 只能靠试错模型无法从 Schema 判断哪些参数组合合法——选teammate却填了cli_agent、选human_agent却填了model_name都会在运行时被拒绝白白消耗一次错误调用invoke 内的“特殊情况”坏味道invoke里堆着_spawn_bridge/_spawn_external_cli/ human_agent / teammate 等一串 role_type 分支每加一种角色分支和第一层参数就继续膨胀数据结构层其实早已对齐底层TeamMemberSpec基类与BridgeMemberSpec子类、ExternalCliAgentSpec已经按角色拆分backend 也早已提供spawn_member/spawn_human_agent/spawn_bridge_agent/spawn_external_cli_agent四个方法——只是工具层没有跟上。决策按 role_type 拆成四个独立工具重构的核心决策是按role_type拆成四个独立工具工具命名与 role_type 取值一一对齐spawn_teammate(member_name, display_name, desc, prompt?, model_name?)spawn_human_agent(member_name, display_name, desc)—— Schema不含model_name/promptspawn_bridge_agent(member_name, display_name, desc, mailbox_inject_mode?, protocol?, adapter_config?, model_name?)spawn_external_cli(member_name, display_name, desc, cli_agent)每个工具的 Schema 都是扁平且自包含的只暴露与自身角色相关的参数不存在“合法但用不上”或“非法但看起来合法”的字段。LLM 看到哪个工具就说明该角色的哪些参数可用——参数组合非法的情况从 Schema 层就被消灭了。共享基类 _SpawnToolBase公共逻辑收敛零 role 分支四个子类并非各自复制样板代码而是继承一个共享基类_SpawnToolBase(TeamTool, ABC)。源码位于 tool_member.py它封装了所有生成类工具的横切关注点member_name 校验复用_MEMBER_NAME_PATTERN定义于 tool_permissions.py正则^[a-z][a-z0-9-]*$校验失败返回明确的错误文案“必须以小写 ASCII 字母开头仅允许小写字母、数字与连字符member_name 会被复用作消息路由键和文件路径片段”persona fallbackdesc or prompt的默认取值逻辑ToolOutput 构造统一的_ok/_fail/_from_result帮助方法其中_from_result会把 backendMemberOpResult.reason透传到error让 LLM 能据此诊断被拒原因map_result / render_for_llm把成功结果渲染成一行摘要Member spawned: member_name... display_name... role...。基类内零 role 分支。四个子类各自只做两件事声明自己的扁平input_paramsSchema以及实现一条单一路径的invoke。原先的SpawnMemberTool整类删除。各子类 Schema 的源码级细节SpawnTeammateTooltool_member.py基础字段之外还支持isolation枚举仅worktree、permissions扁平{tool_name: level_string}收紧映射。当团队开启上下文继承fork_enabled对应TeamAgentSpec.enable_fork时额外注入fork/fork_source/fork_mode三个属性关闭时这些属性和描述里的 fork 段落一起被剔除omit_slots机制保证“模型读不到它无法传的参数”。SpawnHumanAgentTooltool_member.pySchema 刻意不含model_name/prompt——人类成员由真人通过 HumanAgentInbox 驱动模型与启动提示由框架内置模板托管不存在可填字段也就没有可误用的入口。SpawnBridgeAgentTooltool_member.pyprompt为必填它是远程 agent 通过adapter.connect采纳的角色系统提示词mailbox_inject_mode枚举passthrough/rephrase默认passthroughprotocol如a2a/acp/claudecode与adapter_configendpoint / auth / relay_timeout_s 等原样透传用于后续 BridgeProtocolAdapter 查找。SpawnExternalCliTooltool_member.pycli_agent与prompt必填fallback_model_name也是必填字段schema 允许string | null并附带由_model_catalog_context()动态渲染的fallback_model_catalog上下文含当前模型、各 CLI 类型协议兼容的模型池清单。若某 CLI 类型声明了builtin_models还会追加builtin_model/effort两个属性以及builtin_model_catalog目录。invoke 内对模型选择做了多重校验cli_agent必须命中TeamAgentSpec.external_cli_agents中预声明的静态配置、model_name仅当用户明确指定时才可填写、fallback 遵循“当前模型在池中且协议兼容时优先”的固定优先级。能力门控动态注册看不到就不会误调四个工具并非总是全部注册。create_team_toolstool_factory.py采用与既有plan_mode/persistent门控完全同款的“幂等集合减法”写法# 能力关闭的工具根本不向 LLM 注册——看不到就不会误调 # invoke 内的同名检查只是为 MCP 直连客户端保留的运行时降级兜底 if not agent_team.hitt_enabled(): allowed allowed - {spawn_human_agent, spawn_passive_human} if not agent_team.bridge_enabled(): allowed allowed - {spawn_bridge_agent} if not agent_team.external_cli_kinds(): allowed allowed - {spawn_external_cli}spawn_teammate始终注册——它是最基础的普通 LLM 队友生成能力。能力开关分别来自TeamAgentSpec.enable_hitt/enable_bridge/external_cli_agents空列表即关闭其“能力天花板”校验定义在 blueprint.py。同时LEADER_ONLY_TOOLStool_permissions.py用四个新工具名替换了原spawn_member确保只有 leader 角色能拿到这套工具。这一设计的关键收益一个 backend 会拒绝的能力其工具根本不会出现在 LLM 的可调用列表里——模型看不到就不存在误调的可能。invoke 内保留的hitt_enabled()/bridge_enabled()检查仅作为防御性兜底专门拦截绕过 Schema 校验、直接调用invoke的 MCP 客户端。predefined 模式门控固定花名册团队剔除全部动态生成工具对于team_modepredefined预定义团队花名册在 build 时固定的 leader动态生成成员的入口应当整体关闭。原实现只 exclude 一个spawn_member重构后改为从 leader 工具集 exclude 全部四个spawn_*。源码位于 agent_configurator.pyexclude ( [spawn_teammate, spawn_human_agent, spawn_bridge_agent, spawn_external_cli] if _resolve_team_mode(spec) predefined else [] )配合 leader_workflow_predefined.md 中的提示词约束“你不需要也不能使用spawn_teammate及其它spawn_*工具创建成员”实现工具层与提示词层的双重约束而混合团队hybrid模式则明确允许“预注册基础成员 动态spawn_teammate扩员”。i18n 与系统提示词同步工具的展示文案按四工具拆分工具参数 key 与descs/lang/*.md长描述按四个工具独立成文件中文位于 locales/descs/cn/member/英文位于 locales/descs/en/member/spawn_teammate.md/spawn_human_agent.md/spawn_bridge_agent.md/spawn_external_cli.md参数级翻译集中在 locales/cn.py如spawn_teammate.member_name、spawn_bridge_agent.adapter_config、spawn_external_cli.fallback_model_name等。leader 提示词模板把spawn_member更新为对应新工具名涉及 prompts/cn/ 与 prompts/en/ 下的leader_workflow*.md/leader_policy.md/hitt_leader.md/dispatch_*_leader.md以及 sections.py 中 HITT 段落。典型表述如leader_workflow.md“先建成员再规划任务用spawn_teammate按领域创建专业成员……按需动态扩容出现新的能力缺口时spawn_teammate补充对口成员”hitt_leader.md“若需要多个不同人类成员通过predefined_members传入 rolehuman_agent / passive_human 的 spec或用spawn_human_agent/spawn_passive_human动态添加”。拒绝的方案为什么不做兼容别名 / oneOf / tool search设计文档明确记录了三条被拒绝的替代路径及其理由保留spawn_member兼容别名拒绝。这是 LLM-facing 工具不是__init__.py这类 public API保留别名会让“10 参数平铺 role 分支”的坏味道复活且 LLM 同时看到 5 个工具更迷惑。单工具 discriminated uniononeOf role_type discriminator拒绝。框架透传支持 oneOf但模型对 oneOf 的解析不稳定且invoke仍需按 role dispatch独立工具是 100% 可靠的扁平 Schema。引入 tool search / deferred loading 或$ref跨工具去重拒绝。leader 仅约 12 个工具远未到 tool-search 的收益甜区且 Anthropic / OpenAI 的 toolinput_schema必须自包含$ref不能跨工具复用。公共参数如member_name的描述重复仅几百 token不值得引入复杂度——上下文优化靠文案分层即可。反转 F_22 的“拒绝独立工具”决策本特性还明确反转了先前 F_22 特性的决策F_22 当时基于“复用 spawn_member role_type、外部 CLI 团队语义即 teammate”拒绝新建独立spawn_external_cli工具。反转的理由是 F_22 未充分权衡LLM 正确调用工具的负担——随着 role_type 增多单工具的互斥参数平铺让模型选择面臃肿、易错。拆分后每个工具 Schema 扁平、无非法组合调用正确率显著优于“省下的几百 token Schema 重复”。同时F_07bridge的动态 spawn 同步迁移到spawn_bridge_agentF_07 / F_22 文档顶部均已加入指向本特性的变更注记。验证测试基线与覆盖点设计文档给出了可复现的验证命令source .venv/bin/activate export PYTHONPATH.:$PYTHONPATH make test TESTFLAGStests/unit_tests/agent_teams/test_team_tools.py tests/unit_tests/agent_teams/tools/test_bridge_spawn_tool.py make test TESTFLAGS-m level0 tests/unit_tests/agent_teams/ # 594 passed, 2 skipped测试覆盖四个维度均可直接在仓库中核对四工具各自的 happy path member_name 校验TestSpawnToolstest_team_tools.py覆盖spawn_teammate/spawn_human_agent/spawn_external_cli的扁平 Schema 断言如role_type、cli_agent、mailbox_inject_mode不出现在spawn_teammate的属性中、成功生成与role_type返回以及后端开发1/Member1/backend_dev_1/1backend等非法名被基类统一拒绝能力门控未注册场景TestSpawnToolCapabilityGatetest_team_tools.py验证“普通团队只暴露spawn_teammate”“全能力团队暴露四个工具”“仅 HITT 开启时只追加spawn_human_agent”三档门控行为bridge 工具专项test_bridge_spawn_tool.py 覆盖能力关闭时拒绝、缺prompt拒绝、happy path、非法mailbox_inject_mode拒绝、非 dict 的adapter_config拒绝模型选择边界test_team_tools.py 额外断言spawn_external_cli的fallback_model_name必填语义、模型协议兼容目录暴露不含 endpoint 密钥以及中英文文案一致性。已知遗留与后续关注设计文档如实记录了重构完成后的遗留项供后续维护者按“双向同步”约束刷新部分历史设计文档S_05 / S_07 / S_12、F_04 / F_08 / F_13 / F_15 / F_17 / F_20 / F_21 以及 architecture_cn.md仍含spawn_member字样。其中作为backend 方法名TeamBackend.spawn_member/TeamAgent.spawn_member在 team.py 仍存在的引用是正确的、应保留作为工具名的历史叙述属术语级遗留活契约以 S_08 与本文件为准源码层文案去重locale include/partial 让member_name规则等公共片段共享一份源未做优先级低——只省维护、不省运行时 context。延伸阅读活契约S_08_team-tools-contract.md能力源头bridge 见 F_07_bridge-agent.md、HITT 见 F_04_hitt-human-in-the-team.md、外部 CLI 见 F_22_external-cli-spawn-member-and-mcp-injection.md底层数据结构schema/team.py 中的TeamMemberSpec/BridgeMemberSpec/ExternalCliAgentSpec赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐openJiuwen agent-core 团队消息工具重构send_message 收件参数 to/targets 分离的设计与实践openJiuwen agent core 团队消息工具重构send_message 收件参数 to/targets 分离的设计与实践 导读 send_mes人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 外部 CLI 成员接入spawn_member 角色扩展、静态 Spec 配置与团队 MCP 自动注入实战openJiuwen agent core 外部 CLI 成员接入spawn_member 角色扩展、静态 Spec 配置与团队 MCP 自动注入实战 本文以人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 中 human-agent 团队事件角色感知渲染设计决策、源码实现与回归验证openJiuwen agent core 中 human agent 团队事件角色感知渲染设计决策、源码实现与回归验证 本文以 openJiuwen age人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习上一篇GoHBase性能优化7个提升HBase客户端性能的秘诀下一篇Talos Linux 用户卷 UserVolumeConfig 配置完全指南directory/disk/partition 三种卷类型与 LUKS2 加密实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考