代理架构模式
构建强大AI代理系统的实用指南。除了即时工程，这是代理的系统工程。
*Brendan之间的合作 @阿扎巴兹 Jared（Clawdbot人工智能代理）*
目录
______________________________________________________________________
1.代码模式
问题
传统的代理工具调用成本很高。每次工具调用都需要：
- 上下文中的完整架构
- 详细的JSON响应
- 每次操作的往返延迟
对于需要搜索、过滤和处理数据的代理，这会快速消耗令牌。
模式：搜索（）+执行（）
Cloudflare的代码模式模式将数据密集型操作的令牌减少了99.9%：
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ search() │ ──► │ Filter │ ──► │ execute() │
│ (explore) │ │ (in code) │ │ (act) │
└─────────────┘ └─────────────┘ └─────────────┘它是如何工作的：
search(query)返回轻量级引用（ID、名称、元数据）- 代理在代码中过滤/选择（不是通过LLM推理）
execute(action, target_ids)执行批量操作
例子：
# Instead of: "Find all users who signed up last week and send them email X"
# Which requires the LLM to see every user record...
# Code Mode approach:
users = search("signups last 7 days") # Returns IDs + minimal metadata
target_ids = [u.id for u in users if u.plan == "free"] # Code filtering
execute("send_email", template="welcome", targets=target_ids) # Bulk action何时使用：
- 数据探索（日志、用户、记录）
- 批量操作
- 在采取行动之前进行过滤的任何工作流程
关键见解： LLM决定 *什么* do，代码句柄 *多少* 涉及数据。
______________________________________________________________________
2.MCP集成
问题
每个代理框架都发明了自己的工具接口。切换提供者意味着重写集成。
模式：模型上下文协议
MCP规范了代理与外部工具和数据源的交互方式：
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Agent │ ──► │ MCP Layer │ ──► │ Tools │
│ (any) │ │ (standard) │ │ (any) │
└─────────────┘ └─────────────┘ └─────────────┘核心概念：
- 工具：代理可以调用的函数（使用类型化架构）
- 资源：代理可以读取的数据（文件、API、数据库）
- 提示：可重复使用的提示模板
优点：
- 编写工具一次，与任何MCP兼容的代理一起使用
- 声明性模式（代理无需探测即可知道功能）
- 内置身份验证/权限处理
MCP工具定义示例：
{
"name": "github_create_issue",
"description": "Create a new GitHub issue",
"inputSchema": {
"type": "object",
"properties": {
"repo": { "type": "string" },
"title": { "type": "string" },
"body": { "type": "string" }
},
"required": ["repo", "title"]
}
}何时使用：
- 构建可重用代理工具
- 需要共享工具的多代理系统
- 任何需要清洁工具边界的生产代理
______________________________________________________________________
3.模块化提示架构
问题
单片系统提示变得无法维护。个性融入规则，规则融入程序。
模式：灵魂/代理/身份分离
受Clawdbot架构的启发，将系统提示符拆分为可组合的模块：
┌─────────────────────────────────────────────────┐
│ System Prompt │
├─────────────┬─────────────┬─────────────────────┤
│ SOUL.md │ AGENTS.md │ IDENTITY.md │
│ (personality│ (rules, │ (who am I, who │
│ & tone) │ procedures) │ do I serve) │
└─────────────┴─────────────┴─────────────────────┘SOUL.md --The *如何* 沟通的
- 语气和口吻
- 幽默风格
- 反应模式
- 什么不该说
代理商.md --The *什么* 行为
- 审批流程（不问、获得批准、从不批准）
- 预定任务
- 工具使用规则
- 错误处理
身份.md --The *谁* 和 *边界*
- 代理人的姓名和身份
- 代理人为谁服务
- 隐私规则（在哪里分享什么）
- 上下文感知（我在哪个聊天室？）
优点：
- 在不违反规则的情况下改变个性
- 跨不同角色重用AGENTS.md
- 明确行为变化的审计跟踪
示例结构：
workspace/
├── SOUL.md # "You're a cheerful ship's computer..."
├── AGENTS.md # "Get approval before sending external messages..."
├── IDENTITY.md # "You are Jared, running on Alex's WhatsApp..."
├── USER.md # Owner profile and preferences
└── TOOLS.md # Environment-specific tool notes______________________________________________________________________
4.存储层
问题
上下文窗口是有限的。特工们忘记了。长时间运行的代理需要持久的内存。
模式：三个内存层
┌─────────────────────────────────────────────────┐
│ Working Memory (Context) │
│ Current conversation + recent tools │
├─────────────────────────────────────────────────┤
│ Session Memory (Logs) │
│ Daily logs, session notes, recent state │
├─────────────────────────────────────────────────┤
│ Long-term Memory (Curated) │
│ Key facts, preferences, relationships, todos │
└─────────────────────────────────────────────────┘第1层：工作记忆（上下文窗口）
- 当前对话中的所有内容
- 由模型自动管理
- Volatile——上下文重置时消失
第2层：会话内存（结构化日志）
- 每日降价文件(
memory/2024-01-15.md) - 会话状态(
memory/session-state.json) - 可搜索、带时间戳、仅可追加
第三层：长期记忆（精心策划的知识）
MEMORY.md--人工整理的关键事实- 关系图、偏好、重复模式
- 定期更新，不是每条消息都更新
内存操作：
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Recall │ │ Store │ │ Forget │
│ (search) │ │ (write) │ │ (prune) │
└──────────┘ └──────────┘ └──────────┘召回模式：
# Before answering questions about past work:
results = memory_search("project X status")
if results:
context = memory_get(results[0].path, lines=results[0].lines)
else:
say("I checked my notes but don't have that recorded.")店铺模式：
# After completing significant work:
append_to_log(f"## {timestamp}\n- Completed {task}\n- Decision: {why}\n")何时使用每一层：
| 需求 | 等级 |
|---|---|
| 当前对话 | 工作记忆 |
| 今天发生了什么 | 会话记忆 |
| 这个人是谁？长期记忆 | |
| 持续的偏好 | 长期记忆 |
| 调试出了什么问题 | 会话内存 |
______________________________________________________________________
5.多智能体协调
问题
单个代理达到了极限：上下文窗口、专业化、并行性。复杂的任务需要多个代理协同工作。
模式A：分层委托
┌─────────────┐
│ Leader │
│ (orchestrator)
└──────┬──────┘
┌─────────────┼─────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Worker │ │ Worker │ │ Worker │
│ A │ │ B │ │ C │
└─────────┘ └─────────┘ └─────────┘何时使用： 任务分解、并行执行、领域专业化
实施（MUSE模式）：
tribe muse start # Leader agent
tribe muse spawn "Fix auth bug" auth-worker
tribe muse spawn "Write tests" test-worker
tribe muse spawn "Update docs" docs-worker
tribe muse status # Monitor all主要特点：
- Git工作树隔离（每个worker都有自己的分支）
- tmux会话管理（监视、提示、终止）
- 用于低延迟产卵的暖池
模式B：审批层次结构
并非所有代理行为都是平等的。实施分级审批：
┌─────────────────────────────────────────────────┐
│ Do Without Asking │
│ - Read data, search, summarize │
│ - Draft responses (but don't send) │
│ - Update internal state │
├─────────────────────────────────────────────────┤
│ Get Approval First │
│ - Send external messages │
│ - Create/modify resources │
│ - Make commitments on behalf of user │
├─────────────────────────────────────────────────┤
│ Never Do │
│ - Delete important data │
│ - Share private information │
│ - Make purchases │
│ - Impersonate the user │
└─────────────────────────────────────────────────┘模式C：对抗性亚主体（本我/自我/超我）
为了在决策中避开局部最优解：
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Id │ │ Superego │ │ Ego │
│ Temp 1.2 │ │ Temp 0.1 │ │ Temp 0.7 │
│ (creative) │ │ (strict) │ │ (synthesis) │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└────────────────►├◄────────────────┘
│
┌─────────────┐
│ Output │
└─────────────┘它是如何工作的：
- ID （高温）：产生创造性的替代方案，打破假设
- 超我 （低温）：强制约束，验证正确性
- 自我 （中温）：将两者综合成实际解决方案
死锁处理： 当本我和超我不能达成一致时，升级到人类（就像参议院的副总统决胜局）。
模式D：群体进化代理（GEA）
根据加州大学旧金山分校的研究——在不同会话中相互学习的代理：
Session 1 Session 2 Session 3
│ │ │
▼ ▼ ▼
┌───────┐ ┌───────┐ ┌───────┐
│Agent A│───learn──│Agent B│───learn──│Agent C│
└───────┘ └───────┘ └───────┘
│ │ │
└──────────────────┼──────────────────┘
▼
┌─────────────┐
│Shared Memory│
│ (tribal │
│ knowledge) │
└─────────────┘关键见解： 不要只是坚持数据，坚持 *学习模式*什么奏效了？什么失败了？将成功的策略反馈给未来的代理人。
______________________________________________________________________
快速参考
何时使用What
| 挑战 | 模式 |
|---|---|
| 令牌密集型数据操作 | 代码模式 |
| 可重复使用的工具集成 | MCP |
| 可维护的系统提示 | 模块化架构 |
| 持久知识 | 记忆层 |
| 复杂任务分解 | 分层委托 |
| 逃离局部最优解 | 对抗性子代理 |
| 跨课程学习 | GEA |
要避免的反模式
- 单片式提示 --分为灵魂/代理人/身份
- 扁平剂群 --使用层次结构，而不是点对点混乱
- 内存转储 --策展人，不要只记录一切
- 无限自主 --审批级别可防止灾难
- 单代理思维 --复杂的任务需要协调
______________________________________________________________________
延伸阅读
- TRIBE MUSE文件 --多代理编排
- 模型上下文协议 --标准化工具接口
- Cloudflare AI网关 --代码模式起源
- Clawdbot 文档 --模块化提示架构在实践中的应用
______________________________________________________________________
学分
核心贡献者：
- 布伦丹 @阿扎巴兹 --概念架构、弗洛伊德模式、多智能体协调
- 贾里德 （Clawdbot AI代理）——文档、综合、实现模式
图案起源：
- 代码模式：Cloudflare AI网关团队
- MCP标准：人类学
- MUSE/分级委托：TRIBE框架
- 模块化提示：Clawdbot架构
______________________________________________________________________
*最后更新时间：2026-02-22* *状态：草案----等待安置决定*