qwen_agent/.features/skill/decisions/2026-05-subagent-support.md

date	status	topic	impact
2026-05-11	pending	subagent-support	skill agent deep_assistant

Sub-Agent 在 skill 内的承载方式

背景

业务方 (pmda-drug-info) 需要在单个 skill 内同时承载若干面向不同子任务的专用 agent （single-drug / interaction / adverse-event / patient-specific），每个子 agent 需要独立的 system prompt 和工具白名单，但应与主 agent 复用同一组 MCP 工具实例 与同一份 LLM。

[待补充]：是否考虑过用 skill-per-subagent 的方式（每个子 agent 一个独立 skill）。

选项

选项 A：skill 内 agents/*.md + 全局 SubAgentMiddleware（已实现）

• 优点：
  • skill 包自洽，子 agent 定义与 hook / MCP 同包发布。
  • 复用 deepagents.middleware.subagents.SubAgentMiddleware，无需自研路由层。
  • 工具按 tools 字段白名单过滤，统一以 MCP tool name 引用。
• 缺点：
  • 跨 skill 子 agent 同名时静默 last-wins 覆盖，仅有 warning，无强校验。
  • 中间件位置耦合：SubAgentMiddleware 必须插在 CustomFilesystemMiddleware 之后、AnthropicPromptCachingMiddleware 之前 （与 create_deep_agent 顺序匹配），改动中间件顺序时容易踩坑。

选项 B：每个子 agent 单独建一个 skill

• 优点：天然隔离，命名冲突由 skill 加载层处理。
• 缺点：同一业务的多个子 agent 在 skill 列表里散落，部署 / autoload 配置复杂； pmda-drug-info 的 4 个子 agent 强相关，作为同一 skill 更自然。

决策

选择 选项 A（已落地）。

影响

• 需要改动：调用方知道 init_agent 返回元组现已包含 sandbox（与 daytona 改动叠加）。
• 风险：sub-agent 同名静默覆盖；未来如多 skill 都暴露 sub-agent，需要增加冲突检测。
• 后续任务：
  1. 沉淀 sub-agent 编写规范（agents/*.md frontmatter 字段 + 工具白名单约定）。
  2. 跨 skill sub-agent 命名冲突的检测策略——是否升级为 error / 加 skill 名前缀。