主会话别被调研淹没：同步 `Agent` 子代理

系列回顾主循环 · 代码库工具 · REPL · 项目上下文 · Skills · 权限 Write · MCP 概念 · MCP 实现 · Context Budget · Bash · compact 2.0 · autocompact · Hooks · Memory主会话一路 Read / Grep / Bash细节全堆进messages[]——下一轮还要带着这些噪音继续聊。人会说「你去旁边查一下回来只告诉我结论。」这篇讲v6-subagents内置Agent工具同步嵌套一次query()子任务用独立消息列表跑完只把摘要塞回父会话的tool_result——父循环骨架仍是原来的 ReAct。为什么需要「旁边那间屋」主会话适合定目标、做决策、改代码。不适合一次性扫半个仓库、跑一长串探索工具却把每一步轨迹永久留在父历史里。主会话自己干Agent子代理消息历史写进QueryEngine.messages独立数组不写回父回给主模型的整段 tool 轨迹末条 assistant 文本摘要上下文污染高低费用/延迟少一次嵌套多一次完整子循环所以子代理不是「另一个产品」而是同一套query()换一间干净房间干完只交报告。工具长什么样Agent({description:Find auth entrypoints,// 必填3–5 词短描述TRACE / 状态prompt:在仓库里找出登录相关入口文件只列路径与一句理由。,// 必填子任务全文tool_names:[Glob,Grep,Read],// 可选子工具白名单})字段必填作用description是给人看的短标签不当子推理正文prompt是子会话的第一条 user 消息tool_names否白名单缺省 父工具表去掉Agent后的全部父侧tool_result成功时大致是[Agent: Find auth entrypoints] src/auth/login.ts — 登录表单入口 …中间子工具的tool_use/tool_result不会进入父messages。一张图嵌套怎么跑父 querydepth0 → 模型 tool_use: Agent → AgentTool.call → createSubagentContextdepth1新 AbortController 链到父 → toolsForSubagent去掉 Agent可选白名单 → 嵌套 query({ messages: [prompt], depth: 1, … }) → 子自己 ReActcallModel → 工具 → … → 取最后一条 assistant 的 text≤32KB超长留尾 → 父 tool_result [Agent: description] 摘要 → 父继续下一轮对应实现src/tools/AgentTool.tssrc/utils/subagent.ts。防递归两道闸子代理若还能再调Agent就会无限套娃。mini 用双保险子工具池排除AgenttoolsForSubagentdepth上限默认 1父为 0 时可 spawn depth1已在 depth≥1 再调 → 直接错误tool_result不启嵌套depth 0主会话──Agent──▶ depth 1子 └── 再 Agent→ 拒绝 / 池子里根本没有depth与 Stop hooks共用同一语义只有depth 0跑 Stop子代理收尾不跑 Stop也不做单独的SubagentStop。权限、中止、失败主题行为权限默认复用父canUseTool父 deny 对子生效写操作仍可能弹 REPLy/NAbort子有独立AbortController但链到父父中止 → 子中止失败异常 /aborted/ 无文本 → 父侧is_error的tool_resultfail-soft不炸主循环Compact子用同一套 deps子历史独立不写回父 EngineAgent标成非只读、非并发安全派生子任务有副作用与串行成本不跟只读工具抢并发。和 Skills / Memory / Hooks 怎么区分机制一句话Skills往主会话注入说明书仍在同一 messagesMemorysystem 里跨会话偏好Hooks工具前后拦 / 记Stop 只在顶层Agent另开一轮嵌套 query只交摘要Skills 是「给当前大脑多读一页纸」Agent 是「派一个实习生去查回来交纪要」。30 秒感受一下bun run dev# 或 mock需能走到真实工具时再试 Agent自然语言示例用 Agent 工具在仓库里找与 MCP 配置相关的文件只返回路径列表。 description 用 Locate MCP config。TRACE1时 stderr[trace] agent.start descriptionLocate MCP config depth1 [trace] agent.end descriptionLocate MCP config oktrue reasoncompleted和主循环的关系L1 主 query / QueryEngine → 照旧Agent 只是多一个 Tool L2 AgentTool.call → 嵌套 query独立 messages L3 createSubagentContext → depth1、abort 链、工具池裁剪 L4 摘要回传 → 父 tool_result子轨迹不进父历史子代理复用query()不另写一套循环隔离的是消息列表与深度不是换引擎。刻意没做什么没做意味着什么swarm / 多 worker / Coordinator一次一个同步子任务worktree / 后台 fork子跑完才回父无并行隔离目录subagent_type命名 agent 目录不按角色配置多套 agentSubagentStop子收尾不跑 Stop顶层 Stop 另算完整 resume UI / 换模型字段入参只有 description / prompt / tool_names这一刀验证的是「隔离调研」的最小面Agent 工具 → 嵌套 query → depth≤1 排除 Agent → 权限派生 → 摘要回父 → TRACE 可观测系列拼图篇能力主循环单会话 ReActcompact / Memory主会话怎么瘦、怎么记住Hooks工具生命周期本篇旁路子任务结论回传Harness 再多一根柱子循环、工具、会话、上下文、技能、权限、MCP、预算、hooks、memory、subagent。你可以从这里带走什么子代理 嵌套query() 独立 messages——不是新框架。父只要摘要——中间工具轨迹留在子会话里。防递归靠池子 depth——去掉Agent且默认 maxDepth1。权限与中止要继承——派生canUseToolabort 链到父。depth 是全局语义——顶层才 Stop子不跑 Stop。失败 fail-soft——错误进父tool_result主循环继续。仓库与相关文档GitHubhttps://github.com/jimchou-h/react-agent-mini上一篇Memory源码AgentTool.ts · subagent.ts术语src/tools/CONTEXT.md欢迎 Star、Issue 和 PR。本文基于 react-agent-mini 变更v6-subagents同步Agent工具 depth/防递归 摘要回传撰写。