5_Agent 与 Subagent 从概念到实践
1. Agent 与 Subagent 核心概念
1.1 概念对比
| 维度 | Agent（主代理） | Subagent（子代理） |
|---|---|---|
| 定义 | 自主感知、决策、执行的 AI 实体 | 被主代理调用的专业化功能模块 |
| 职责 | 处理复杂任务，负责全局规划与最终交付 | 聚焦特定领域，降低主代理复杂度 |
| 执行模式 | 感知 → 规划 → 执行 → 反思（完整循环） | 接收指令 → 执行 → 返回结果 |
1.2 关键洞察
- 涌现能力：多个简单 Subagent 协作可产生单体 Agent 无法实现的复杂行为。如同蚁群效应，个体行为简单，但群体能构建复杂系统。
- Token 成本陷阱：调用 Subagent 会消耗额外的上下文传输成本。三层嵌套的 Subagent 系统，Token 消耗可能达到单体 Agent 的 5-10 倍，需谨慎权衡。
- Subagent 形态多样性：Subagent 不必局限于 LLM。它可以是简单的 Python 脚本（Function Calling），也可以是针对特定任务微调的 7B 小模型，以平衡成本与性能。
1.3 常见误区与最佳实践
| ❌ 错误做法 | ✅ 正确做法 | 💡 原因 |
|---|---|---|
| 过度拆分 | 仅在需专业领域隔离时拆分 | 避免不必要的通信开销和延迟 |
| 网状通信 | 星型拓扑：所有通信经由主 Agent | 避免依赖关系混乱，降低调试难度 |
| 无限递归 | 强制设置最大调用深度（如 3 层） | 防止死循环和 Token 爆炸 |
1.3.1 过度设计（Over-engineering）
误区：为简单任务构建复杂 Agent 链。例如查询天气，构建了 “ 意图识别 Agent”+” 地理位置 Agent”+”API 调用 Agent”。
修正：遵循 奥卡姆剃刀原则。简单的逻辑判断优先使用 Code 或 Function Calling。Prompt 能解决的不用 Agent，单体 Agent 能解决的不用 Subagents。
1.3.2 死循环（Infinite Loops）
误区：Subagent A 修改代码，Subagent B 测试失败，A 再次修改，B 再次失败，陷入无尽循环。
修正：引入 最大迭代次数（Max Iterations）。若尝试 3 次仍未解决，主 Agent 应终止流程并向用户报错或寻求人工介入。
1.3.3 上下文控制（Context Control）
误区：主 Agent 将全部历史对话透传给 Subagent。
修正：坚持 最小权限原则。仅传递 Subagent 完成任务所需的最小必要信息，避免噪声干扰，降低 Token 消耗。
2. Agent 核心架构
标准 Agent 由四大核心组件构成：
Agent = LLM + Planning + Memory + Tools
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#4F46E5', 'primaryTextColor': '#000', 'primaryBorderColor': '#3730A3', 'lineColor': '#6366F1', 'secondaryColor': '#10B981', 'tertiaryColor': '#F59E0B'}}}%%
flowchart LR
subgraph Core["Agent Core"]
direction TB
Profile["👤 Profile<br/>Role & Boundaries"]
Memory["🧠 Memory<br/>Context & History"]
Planning["📝 Planning<br/>Decomposition & Reflection"]
Tools["🛠️ Tools<br/>External Interaction"]
end
Profile --> Memory
Memory --> Planning
Planning --> Tools
Tools --> Memory
classDef primary fill:#4F46E5,stroke:#3730A3,color:#fff
classDef success fill:#10B981,stroke:#059669,color:#fff
classDef warning fill:#F59E0B,stroke:#D97706,color:#fff
classDef info fill:#06B6D4,stroke:#0891B2,color:#fff
class Profile primary
class Memory success
class Planning warning
class Tools info| 组件 | 作用 | 技术实现示例 |
|---|---|---|
| Profile | 定义角色人设与能力边界 | System Prompt |
| Memory | 存储上下文、历史与中间结果 | 短期：Window Buffer；长期：Vector DB (RAG) |
| Planning | 任务拆解、路径规划与自我反思 | CoT (Chain of Thought), ReAct, TOT |
| Tools | 连接物理世界与外部系统 | API Calls, Python REPL, Shell |
Subagent 本质上是基于同一架构的实例，但被约束在更窄的职责范围内，且受主 Agent 编排。
2.1 Prompt 驱动 Vs Code 驱动
Prompt 是灵魂，Code 是骨架。 没有外层代码逻辑维持的循环（Loop），Prompt 仅能完成单次推理，无法构成真正的 Agent。
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#4F46E5', 'primaryTextColor': '#000'}}}%%
stateDiagram-v2
[*] --> Prompt: 定义行为规范
state "Execution Loop" as Execution {
Prompt --> LLM_Response: LLM 推理
LLM_Response --> Tool_Analysis: 解析工具调用
state "Tool Execution" as Tools {
Tool_Analysis --> Pause_LLM: 挂起生成
Pause_LLM --> Run_Tool: 执行工具代码
Run_Tool --> Inject_Result: 注入执行结果
}
Inject_Result --> LLM_Response: 继续推理
}
LLM_Response --> [*]: 任务完成| 架构类型 | Prompt 权重 | Code 权重 | 典型代表 |
|---|---|---|---|
| 低代码/无代码 | 高 | 低 | GPTs, Coze, Dify |
| 代码优先 | 中 | 高 | LangChain, AutoGen, CrewAI |
2.2 协议选择：为什么是 Markdown？
Markdown 已成为 Agent 间通信的事实标准协议：
- LLM 亲和性：LLM 对 Markdown 结构（标题、列表、代码块）的理解和生成能力最强。
- 通用性：System Prompt 和输出报告天然适合 Markdown 格式。
- 解析效率：结构清晰，易于代码解析（Parsing）。
注：底层数据交换仍主要依赖 JSON，但内容载体倾向于 Markdown。
3. Skills 与 Subagent：架构决策
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#4F46E5', 'primaryTextColor': '#000', 'primaryBorderColor': '#3730A3', 'lineColor': '#6366F1'}}}%%
flowchart TD
subgraph SkillFlow["Skill Execution Chain"]
S1["Agent Detects Intent"] --> S2["Load Skill Tool"]
S2 --> S3["Read SKILL.md"]
S3 --> S4["Inject into Context"]
end
subgraph SubagentFlow["Subagent Execution Chain"]
A1["User/Agent Delegation"] --> A2["Initialize Task"]
A2 --> A3["Create Isolated Session"]
A3 --> A4["Independent Execution Loop"]
end
classDef skill fill:#10B981,stroke:#059669,color:#fff
classDef agent fill:#4F46E5,stroke:#3730A3,color:#fff
class S1,S2,S3,S4 skill
class A1,A2,A3,A4 agent| 特性 | Skills (技能) | Subagent (子代理) |
|---|---|---|
| 定义 | 增强 Agent 能力的插件/工具包 | 独立的 AI 专家实体 |
| 上下文 | 与主会话共享上下文 | 拥有独立的上下文窗口 |
| 并发性 | 串行执行 | 支持高并发（如同时启动 50+ 实例） |
| 应用场景 | 标准化、流程化任务（Lint, Format） | 探索性、复杂决策任务（Refactor, Debug） |
| 配置 | SKILL.md + 脚本 | 独立 Profile + 专用工具集 |
决策法则：
- Skill 是「SOP 的代码化」，适合高频、低熵值的任务。
- Subagent 是「专家的数字化」，适合低频、高熵值的复杂任务。
3.1 Subagent 适用场景
- 资源隔离：需大量文件 I/O 或中间数据（如全库代码搜索）。
- 模型异构：使用廉价模型进行广度搜索，昂贵模型进行深度分析。
- 权限沙箱：授予子代理更高或更低的系统权限。
- 并行加速：同时处理多个独立子任务。
3.2 Skill 适用场景
- 工程规范：Git Commit 规范检查、代码风格修正。
- 知识注入：特定框架的 API 文档、最佳实践指南。
- 轻量增强：无需独立会话即可完成的辅助功能。
4. 实践案例：OpenCode & Ralph Loop
4.1 OpenCode 代理架构
OpenCode 采用了经典的主从代理架构：
主代理 (Main Agents)
| 代理名称 | 核心定位 | 权限等级 |
|---|---|---|
| Build Agent | 全能工程师 | High (读写文件, 执行命令) |
| Plan Agent | 架构师 | Medium (只读, 规划) |
子代理 (Subagents)
| 代理名称 | 核心定位 | 典型任务 |
|---|---|---|
| General | 通用助手 | 复杂逻辑推理、多步方案生成 |
| Explore | 探索者 | 代码库全局搜索、依赖分析 |
4.2 Ralph Loop：自动化闭环的威力
Ralph Loop 指的是 Agent 在无人值守情况下实现的 “ 修改 - 验证 - 修复 “ 自动化闭环。这是 Agent 从 “ 聊天机器人 “ 进化为 “ 数字员工 “ 的关键质变。
挑战与应对：
面对顽固 Bug，Ralph Loop 可能陷入无效尝试（Thrashing）。
- 策略 1：预算熔断。监控 Token 消耗速率。
- 策略 2：最大重试。同一错误重试 >3 次强制中断，请求人类工程师介入（Human-in-the-loop）。