先看要点#

• research-assistant 是一个多智能体研究系统：你抛出一个研究问题，它最终还你一份带图表、带引用的 PDF 研究报告。
• 架构上只存在一个「前台角色」——lead agent。它的系统提示词写得很直白：你只负责规划与派活，绝不亲自干活，示例通过 allowed_tools=["Task"] 配合提示词，让它以派活为主；该权限配置本身不能证明其他工具已被硬性禁用。
• 三个「执行者」用 AgentDefinition 注册：researcher（搜集）→ data-analyst（分析出图）→ report-writer（整合成 PDF），是一套标准的流水线式编排。
• 子智能体之间不直接对话，而是通过约定的 files/ 目录交换产物——这是本示例最值得抄的设计：用文件系统当多智能体的「共享黑板」。
• 全程由 Hooks 拦截所有工具调用做追踪，落成 JSONL 审计日志与一份「会话记录」，让看不见的多智能体协作变成看得见的流水线台账。

一、先看整体：一次研究是怎么「跑」起来的#

把代码里的真实调用链画出来，长这样：

1
你：「量子计算的最新进展有哪些？」
2
        │
3
        ▼
4
┌─────────────────────────────────────────────┐
5
│            LEAD AGENT（研究主管）              │
6
│  system_prompt：你只负责分解任务并派活         │
7
│  allowed_tools = ["Task"]   ← 派活配置      │
8
│  绝不直接搜索、绝不直接写文件                  │
9
└─────────────────────────────────────────────┘
10
        │  Task(researcher, description=…)
11
        ▼
12
┌─────────────────────────────────────────────┐
13
│  1. researcher（研究员）                      │
14
│     tools: WebSearch, Write                  │
15
│     产出 → files/research_notes/*.md        │
16
└─────────────────────────────────────────────┘
17
        │  拿研究笔记后，Task(data-analyst)
18
        ▼
19
┌─────────────────────────────────────────────┐
20
│  2. data-analyst（数据分析师）                 │
21
│     tools: Glob, Read, Bash, Write           │
22
│     读笔记 → 抽数据 → matplotlib 画图          │
23
│     产出 → files/charts/*.png               │
24
│             files/data/*.md（数据摘要）       │
25
└─────────────────────────────────────────────┘
26
        │  Task(report-writer)
27
        ▼
28
┌─────────────────────────────────────────────┐
29
│  3. report-writer（报告撰写员）                │
30
│     tools: Skill, Write, Glob, Read, Bash    │
31
│     读全部中间产物 → reportlab 合成            │
32
│     产出 → files/reports/<问题>.pdf          │
33
└─────────────────────────────────────────────┘
34
        │
35
        ▼
36
  你收到一份带图表与引用的 PDF 研究报告 ✅

三个关键事实，从代码里可以直接验证：

1. lead 以调度为主：它的 allowed_tools=["Task"]，而角色分工写在 system_prompt=lead_agent_prompt 里；
2. 执行者各配专属工具箱：researcher 连写图表的 Bash 都没有，report-writer 干脆不给 WebSearch——工具配置表达分工，但不能代替文件、进程和网络层的隔离；
3. 协作不靠嘴、靠文件：files/research_notes/、files/charts/、files/data/、files/reports/ 四个目录，就是子智能体之间的「交接货架」。

二、角色表：三个执行者，各管一段#

注意 data-analyst 的 tools 里没有 WebSearch、report-writer 也没有——它们的 description 也反复强调“不进行网络搜索 - 只读取现有研究笔记并创建 PDF 报告”。这些配置用于收窄职责，但 Bash 本身仍可执行网络请求，不能把「未提供 WebSearch」等同于「无法联网」。

三、代码精读：三行配置，拼出一个「团队」#

1
# research-assistant/research_agent/agent.py（摘录，已精简）
2
from codebuddy_agent_sdk import CodeBuddySDKClient, CodeBuddyAgentOptions, AgentDefinition, HookMatcher
3

4
agents = {
5
    "researcher": AgentDefinition(
6
        description=(
7
            "当需要收集任何主题的研究信息时使用此智能体。"
8
            "研究员使用网络搜索从互联网上查找相关信息、文章和来源。"
9
            "将研究发现写入 files/research_notes/ 供报告撰写员后续使用。"
10
        ),
11
        tools=["WebSearch", "Write"],
12
        prompt=researcher_prompt,
13
        # model="claude-opus-4.5"  # 不指定模型，使用默认配置
14
    ),
15
    "data-analyst": AgentDefinition(
16
        description=(
17
            "在研究员完成工作后使用此智能体生成定量分析和可视化图表。"
18
            "数据分析师从 files/research_notes/ 读取研究笔记，"
19
            "提取数值数据（百分比、排名、趋势、对比），"
20
            "并通过 Bash 使用 Python/matplotlib 生成图表。"
21
            "将图表保存到 files/charts/，数据摘要写入 files/data/。"
22
        ),
23
        tools=["Glob", "Read", "Bash", "Write"],
24
        prompt=data_analyst_prompt,
25
    ),
26
    "report-writer": AgentDefinition(
27
        description=(
28
            "当需要创建正式研究报告文档时使用此智能体。"
29
            "报告撰写员从 files/research_notes/ 读取研究发现，"
30
            "从 files/data/ 读取数据分析，从 files/charts/ 读取图表，"
31
            "然后使用 reportlab 将它们整合成…PDF 报告，保存在 files/reports/。"
32
        ),
33
        tools=["Skill", "Write", "Glob", "Read", "Bash"],
34
        prompt=report_writer_prompt,
35
    ),
36
}

1
options = CodeBuddyAgentOptions(
2
    permission_mode="default",  # 本文改为默认权限模式；上游示例使用 bypassPermissions
3
    setting_sources=["project"],   # 从项目 .codebuddy 目录加载技能
4
    system_prompt=lead_agent_prompt,   # 研究主管人设
5
    allowed_tools=["Task"],            # 配合提示词将职责聚焦于派活，不是系统沙箱
6
    agents=agents,                     # ← 把团队注册进去
7
    hooks=hooks,                       # ← 全程埋点
8
)

1
tracker = SubagentTracker(transcript_writer=transcript, session_dir=session_dir)
2

3
hooks = {
4
    'PreToolUse': [
5
        HookMatcher(matcher=None, hooks=[tracker.pre_tool_use_hook])  # 匹配所有工具
6
    ],
7
    'PostToolUse': [
8
        HookMatcher(matcher=None, hooks=[tracker.post_tool_use_hook])
9
    ],
10
}

四、黑盒里的哨兵：SubagentTracker 怎么「看见」协作#

多智能体最大的工程痛点是不可观测：几个分身各干各的，谁先谁后、谁写了什么，lead 心里清楚，但你（开发者/用户）一无所知。

SubagentTracker 的解法是双通道记录：

1. Hook 通道（结构）：PreToolUse 钩子捕获 tool_name / tool_input，PostToolUse 钩子捕获 tool_response。每次 Task 调用会被登记为一个 SubagentSession（以 parent_tool_use_id 为键），子智能体内部每一次工具调用则归入 tool_calls.jsonl 的结构化日志——父子关系、调用时序全被记录下来。
2. 消息流通道（内容）：配合消息流解析维护“当前由哪个子智能体在跑”的执行上下文，把模型的思考与输出对应到正确的会话上。

它的核心数据模型如下（结构示意，省略了构造函数，不能作为完整 Python 类直接运行）：

1
class ToolCallRecord:      # 一次工具调用
2
    timestamp: str
3
    tool_name: str
4

5
class SubagentSession:     # 一个子智能体的执行会话
6
    subagent_type: str
7
    parent_tool_use_id: str   # ← 用它关联 lead 的 Task 调用
8

9
class SubagentTracker:
10
    # Map: parent_tool_use_id -> SubagentSession
11
    self.sessions: Dict[str, SubagentSession] = {}

而 _log_tool_use() 会在控制台实时打印（print(message, flush=True)），同时写入人类可读的 transcript 与机器可读的 tool_calls.jsonl。于是运行时你会看到类似这样的「实时战报」：

1
你：量子计算的最新进展有哪些？
2

3
[Task] 研究员研究员(Researcher) 开始任务…
4
  → WebSearch: 量子纠错 2026 进展
5
  → Write: files/research_notes/quantum-error-correction.md
6
[Task] 数据分析师(Data-Analyst) 开始任务…
7
  → Bash: python draw_charts.py
8
  → Write: files/charts/roadmap.png
9
[Task] 报告撰写员(Report-Writer) 开始任务…
10
  → Write: files/reports/量子计算研究报告.pdf

一个「看不见的多智能体会议」，被还原成一条可追溯、可回放、可审计的生产线台账。

五、为什么用「文件系统当黑板」是个好设计#

多智能体间的协作协议，业界主流有几种：共享内存消息总线、数据库、API 调用……而本示例选的是最朴素的一种——文件目录约定。它的收益：

在真实代码里，这条「交接协议」不是写在架构文档里，而是直接写进每个子智能体的 description：

• researcher 的 description 明确「将研究发现写入 files/research_notes/ 供报告撰写员后续使用」；
• data-analyst 明确「从 files/research_notes/ 读取…将图表保存到 files/charts/，数据摘要写入 files/data/」；
• report-writer 明确「从 notes/data/charts 三处读取 → 合成 PDF 到 files/reports/」。

把「交接协议」写进模型可见的 description，而不是埋在代码里——这是比任何类型系统都更直接的“接口文档”。

六、运行起来的样子#

1
# 在 research-assistant/ 下
2
uv run python research_agent/agent.py                # 交互式 REPL，多轮追问
3
# 启动后在 REPL 中输入研究问题；上游入口未解析命令行问题参数

交互模式底层是一个常驻的 CodeBuddySDKClient：同一客户端 while True 循环里反复 query()，每轮沿用同一 options（也就共享同一套智能体团队与钩子）。上游入口在进入 REPL 前调用一次 setup_session()，因此一次程序运行内的多轮研究共用日志目录，并非每个问题自动新建目录。files/ 产物目录也需要另外按任务隔离，避免旧材料混入新报告。

最终交付物：

1
research-assistant/
2
├── research_agent/
3
│   ├── agent.py               # 入口：chat() 组装 agents/options/hooks，含 REPL 输入
4
│   ├── prompts/               # lead/researcher/data-analyst/report-writer 提示词
5
│   └── utils/
6
│       ├── subagent_tracker.py # 追踪：SubagentSession / JSONL / 控制台战报
7
│       ├── transcript.py       # 会话记录（setup_session / TranscriptWriter）
8
│       └── message_handler.py  # assistant 消息解析（区分文本与 tool_use）
9
└── files/                    # 产出物（gitignore）
10
    ├── research_notes/       # 中间笔记（researcher 产出）
11
    ├── charts/               # 图表（data-analyst 产出）
12
    ├── data/                 # 数据摘要（data-analyst 产出）
13
    └── reports/              # PDF 报告（report-writer 产出）

七、这套实现中可复用的做法#

把研究助理「去业务化」之后，留下的是一套通用的多智能体工程范式：

1. 一个调度者，一串执行者 —— 调度者以 Task 派活，执行者各有工具配置；职责通过工具配置和提示词表达；强边界还需拒绝规则、权限回调及系统隔离，不能称为「物理锁死」。
2. 流水线而非星形总线 —— 角色间按“产物依赖”排成链：研究 → 分析 → 成稿；没有谁需要“知道所有人”。
3. 产物即接口 —— 每个角色的输出落成约定目录中的实体文件，description 里写清“我把什么放哪、我从哪拿什么”。
4. 一切皆可观测 —— Pre/PostToolUse 钩子把每个工具调用、每次子智能体生成变成日志与 JSONL；没有日志的多智能体系统，出了错只能靠猜。

这套范式尤其适合研究报告、代码审查、数据分析、长文档生成这类「多阶段、多专业、产物可分割」的任务。反过来，如果你的任务是一个连续对话的问答（不需要分工），就不要硬套多智能体——直接走会话 API 更划算。

本系列其余文章：

1. 全览：从七个示例看懂一个生态
2. 深度拆解：多智能体研究助理是怎么「分活」的
3. 从零构建 AI 聊天应用
4. 会话机制深潜：Session 与多轮对话