---
date: "2026-05-11"
status: pending
topic: "subagent-support"
impact: [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 名前缀。