6.3 最佳实践与设计模式
6.3 最佳实践与设计模式
好的多智能体系统，拆开看都有相似的骨架。这一节把我们反复验证有效的几条设计模式讲清：职责分离、模块化、单一事实源、失败显式化。
模式一：职责分离
一个 Agent 只干一类事。写代码的别同时审，查数据的别同时答。分离后每个角色系统提示更聚焦，产出更可控，也方便单独替换或降级。
# 反例：一个 Agent 又写又审又跑，提示互相打架 all_in_one = AssistantAgent("all", llm_config=cfg, system_message="你写代码、审代码、跑代码。") # 正例：拆成三个，各司其职 writer = AssistantAgent("writer", llm_config=cfg, system_message="只写代码。") reviewer = AssistantAgent("reviewer", llm_config=cfg, system_message="只审不写。") executor = UserProxyAgent("executor", human_input_mode="NEVER", code_execution_config={"use_docker": False})
模式二：模块化——Agent 工厂
别在业务代码里散落 Agent 创建。抽成工厂函数，配置集中管理，会话级隔离（5.2）也顺手实现。
def make_coder(strong_cfg): return AssistantAgent("coder", llm_config=strong_cfg, system_message="你写代码。") # 业务处只调用 make_coder，不沾配置细节，便于统一改模型
模式三：单一事实源
跨 Agent 共享的关键信息（目标、约束、进度）放一处：要么进对话历史，要么进外部存储（3.5），别让每个 Agent 各记一份，否则会串。
模式四：失败显式化
函数出错返回结构化错误信息（5.3），而非抛异常中断。让 Agent 能看到"为什么失败"并自行调整，比断在半路强。
def safe_task(x: int) -> str: if x <= 0: return "错误: 参数须为正" # 显式失败，Agent 可据此改参 return str(x * 2)
模式五：终止与人工兜底成对出现
任何自动执行的 GroupChat（4.2/4.4），必有 max_round 兜底 + 关键处 TERMINATE（4.5）。这是上线铁律。
反模式清单
- 角色过多（>4）却无协调者，群聊必乱。
- 系统提示写"你是全能助手"，等于没分工。
- 函数体拼接外部输入，敞开注入。
- 上线 NEVER 又无终止条件。
模块化工厂的完整示例
把 Agent 创建收进工厂，业务层只调用，配置集中、隔离顺手实现。
import os strong = {"model": "gpt-4o", "api_key": os.environ.get("OPENAI_API_KEY")} cheap = {"model": "gpt-4o-mini", "api_key": os.environ.get("OPENAI_API_KEY")} def make_reviewer(): return AssistantAgent("reviewer", llm_config=cheap, system_message="你只挑代码毛病，不写。") def make_writer(): return AssistantAgent("writer", llm_config=strong, system_message="你只写代码。") # 业务处：每个会话新建一对，天然隔离 session_writer = make_writer() session_reviewer = make_reviewer()
单一事实源的落实
跨 Agent 共享的目标、约束，统一放"白板消息"或外部存储，别让每个 Agent 各记。下面示意白板模式。
# 白板：所有关键状态进对话，人人可见 board = {"goal": "写登录页", "constraints": ["响应式", "不超过两色"]} board_msg = {"role": "user", "content": f"[白板] 目标={board['goal']} 约束={board['constraints']}"} # 每个 Agent 发起前都能看到，避免各做各的
反模式再强调
最致命的反模式是"裸 NEVER + 无终止 + auto 群聊"，这在生产环境等于失控烧钱。其次是系统提示写"全能助手"让 Agent 失去聚焦。把这些写进团队的代码评审清单，能挡掉大多数低级坑。
为什么单一事实源常被忽略
开发者习惯把"当前目标"写在某个 Agent 的提示里，以为大家都懂。但群聊里每个 Agent 只看到共享历史，提示是私有的。于是 A 按旧目标做，B 按新目标做，对不上。白板消息把目标显式广播，才对齐。这个坑极小概率在单 Agent 出现，却几乎必然在多 Agent 出现——因为多 Agent 把"共享理解"这件事显式化了，你不能再假设"大家都懂"。
模块化带来的测试红利
Agent 走工厂创建后,单测变简单:mock 掉模型,只测"这个工厂产出的 Agent 系统提示对不对、注册了哪些函数"。我们给每个工厂写一条断言测试,改配置时立刻知道有没有破坏角色定义。模块化不只是代码整洁,更是可测性的前提——而多智能体系统恰恰难测,能测的局部越多越稳。
模式要因地致宜
这些模式不是铁律。超小任务(比如一句话分类)用不上职责分离,单 Agent 足矣。模式的价值随任务复杂度上升而显现。我们判断该不该套模式,看"角色间会不会互相踩"——会,就分;不会,就别过度设计。
本节要点回顾
- 职责分离、模块化工厂、单一事实源、失败显式化、终止+兜底。
- 反模式：角色过多无协调、提示太泛、注入拼接、裸 NEVER。
⚠️ 系统提示写"全能助手"看似灵活，实则让 Agent 失去聚焦，产出飘忽难控。
💡 设计模式是"对话即编排"的工程经验沉淀——同样的编排思想，骨架好坏天差地别。