1. 从单体 Agent 到集群：为什么需要 DeepAgents 这一层抽象
如果你最近半年一直在折腾 Agent 相关的东西，大概率会有一种感觉：单个 Agent 能做的事情，其实很快就摸到天花板了。你给它挂几个工具，写一段系统提示词，它帮你查查资料、写写代码、整理整理文档，这些都没问题。但一旦任务变成"先调研、再拆解、然后并行处理几个子任务、最后汇总成一份报告"，单体 Agent 就开始力不从心了——上下文爆炸、工具调用混乱、中间状态丢失，随便一个问题都能让它卡死。
这就是 DeepAgents 这类框架出现的背景。它要解决的不是"怎么让一个 Agent 更聪明"，而是"怎么让一群 Agent 像一个团队一样协作"。这个区别很关键，因为团队协作涉及的问题和单体智能完全是两码事：任务怎么分配、状态怎么共享、子 Agent 之间怎么通信、失败了怎么重试、整个流程怎么编排，这些都是系统工程层面的问题。
我一开始接触 DeepAgents 的时候，最容易犯的错误就是把它当成"更高级的 LangChain"来用。实际上它的核心价值在于编排层——它提供了一套机制，让你可以把复杂的任务拆成多个子任务，每个子任务交给专门的 Agent 去处理，然后通过一套统一的协议把这些 Agent 串起来。这套机制里，MCP 负责工具和资源的标准化接入，A2A 负责 Agent 之间的通信，Skills 负责能力的模块化封装。三个东西各司其职，缺一不可。
理解这一点之后，你再看"可编排、可互通、可扩展"这三个词，就不是空话了。可编排对应的是任务调度和流程控制，可互通对应的是 A2A 协议下的 Agent 间通信，可扩展对应的是 Skills 和 MCP 带来的能力插拔。这三个维度构成了一个多智能体集群的完整骨架。
提示：如果你之前只写过单体 Agent，建议先把"任务拆解"这件事想清楚再上手 DeepAgents。框架本身不复杂，复杂的是你怎么设计任务的分工和边界。
2. MCP 到底解决了什么：工具接入的标准化问题
2.1 MCP 是软件协议，不是硬件协议
热词里有人问"mcp 是软件协议，硬件协议那个概念叫什么来着"，这个问题其实挺有代表性的。MCP 全称是 Model Context Protocol，它是一个软件层面的通信协议，定义的是"模型/Agent 怎么和外部工具、资源、数据源交互"这件事的标准。你可以把它类比成 USB-C——USB-C 不关心你插的是硬盘还是显示器，它只规定接口的形状和通信规则。MCP 也一样，它不关心你接的是数据库还是浏览器，它只规定 Agent 怎么发现工具、怎么调用工具、怎么拿回结果。
硬件协议那边对应的概念，通常指的是像 I2C、SPI、UART 这类物理层/链路层协议，它们管的是电信号怎么在芯片之间传输。两者不在一个层面上，不要混为一谈。MCP 是跑在应用层的，它假设底层网络和传输已经通了，它管的是"语义层面"的交互。
2.2 MCP 的三个核心原语：Tools、Resources、Prompts
MCP 协议里最核心的三个概念是 Tools、Resources 和 Prompts。很多人一开始只关注 Tools，觉得"能调工具就行了"，但实际上 Resources 和 Prompts 同样重要。
Tools是 Agent 可以主动调用的函数，比如"查询数据库""发送邮件""执行代码"。这是最直观的部分，也是大多数人最先接触的。
Resources是 Agent 可以读取的数据源，比如"某个文件的内容""某个 API 的返回结果""某个知识库的片段"。Resources 和 Tools 的区别在于：Tools 是"动作"，Resources 是"数据"。Agent 通过 Resources 获取上下文，通过 Tools 执行操作。
Prompts是预定义的提示词模板，可以让 Agent 在特定场景下复用。这个原语经常被忽略，但在多智能体场景下特别有用——你可以把某个子 Agent 的"角色设定"封装成一个 Prompt，需要的时候直接引用。
# MCP 工具注册的典型结构（伪代码，展示逻辑） mcp_server.register_tool( name="query_database", description="查询指定数据库并返回结果", parameters={ "db_name": {"type": "string", "required": True}, "query": {"type": "string", "required": True} }, handler=db_query_handler ) mcp_server.register_resource( name="project_docs", description="项目文档目录", uri="file:///docs/project", reader=doc_reader )2.3 browser use MCP 和 playwright MCP 的区别
热词里有人问 browser use MCP 和 playwright MCP 有什么区别，这个问题在实际选型时确实容易纠结。简单说：browser use MCP 更偏向"让 Agent 像人一样操作浏览器"，它封装的是高层语义动作，比如"点击这个按钮""在搜索框输入内容""读取页面上的某段文字"。它的优势是上手快，Agent 不需要理解 DOM 结构，直接用自然语言描述操作就行。
playwright MCP 更偏向"精确控制"，它暴露的是 Playwright 的底层能力，比如选择器、等待条件、网络拦截、截图对比。它的优势是可控性强，适合做自动化测试、爬虫、需要精确复现的场景。
选哪个取决于你的任务性质：如果是"让 Agent 帮我填个表单、点几下按钮"这种，browser use MCP 更省事；如果是"我需要稳定地抓取某个页面的结构化数据，还要处理登录态和反爬"，playwright MCP 更靠谱。我自己的做法是，原型阶段用 browser use MCP 快速验证，生产环境切到 playwright MCP 做精细控制。
2.4 MCP 接入时的常见坑
第一个坑是工具描述写得太模糊。MCP 的工具描述是给模型看的，不是给人看的。如果你写"查询数据"，模型不知道查什么数据、怎么查、返回什么格式，它就不敢调或者乱调。正确的做法是把描述写成"根据数据库名称和 SQL 查询语句，返回查询结果集，结果以 JSON 数组形式返回"。
第二个坑是Resources 的 URI 设计混乱。MCP 的 Resources 用 URI 标识，如果你不规划好 URI 的命名空间，后面资源一多就乱了。建议按"来源/类型/标识"的层级来设计，比如db://users/123、file://docs/readme。
第三个坑是忽略了 MCP 的权限控制。MCP 本身不强制权限，但生产环境里你必须自己加一层。哪些工具允许哪些 Agent 调用、哪些 Resources 允许哪些角色读取，这些都要在 MCP Server 层面做拦截，不能指望模型自觉。
3. A2A 协议：Agent 之间怎么"对话"
3.1 A2A 和 MCP 的分工
很多人第一次听到 A2A 和 MCP 会懵：这俩不都是协议吗，有什么区别？我打个比方：MCP 是 Agent 和"工具"之间的协议，A2A 是 Agent 和"Agent"之间的协议。MCP 解决的是"我怎么用外部能力"，A2A 解决的是"我怎么和另一个 Agent 协作"。
这个区分很重要，因为两者的设计目标完全不同。MCP 关注的是工具发现、调用、结果返回，它的交互模式是"请求-响应"。A2A 关注的是任务委派、状态同步、多轮协商，它的交互模式更接近"对话"——一个 Agent 可以把任务拆给另一个 Agent，可以追问进度，可以要求补充信息，可以处理失败重试。
3.2 A2A 的核心概念：Agent Card、Task、Message
A2A 协议里最核心的三个概念是 Agent Card、Task 和 Message。
Agent Card是 Agent 的"名片"，描述了这个 Agent 能做什么、接受什么输入、返回什么输出、支持哪些能力。它相当于 A2A 世界里的服务发现机制——你想找某个 Agent 干活，先看它的 Card，确认它能不能干、怎么干。
Task是 A2A 里的任务单元。一个 Task 有明确的生命周期：创建、进行中、需要补充信息、完成、失败。Task 可以嵌套，一个父 Task 可以派生出多个子 Task，这就构成了任务树。
Message是 Agent 之间传递的信息，可以是文本、结构化数据、文件引用等。Message 和 Task 的关系是：Task 是"要做什么"，Message 是"围绕这个任务说了什么"。
{ "agent_card": { "name": "research_agent", "description": "负责信息检索和初步整理", "capabilities": ["web_search", "doc_summarize"], "input_schema": {"topic": "string", "depth": "integer"}, "output_schema": {"summary": "string", "sources": "array"} } }3.3 任务委派的三种模式
在实际编排中，任务委派主要有三种模式，我分别说说适用场景。
第一种是广播式：主 Agent 把任务同时发给多个子 Agent，谁先完成用谁的结果，或者全部完成后做聚合。这种模式适合"多个来源并行查询"的场景，比如同时查几个数据库、同时调几个 API。
第二种是流水线式：任务按顺序经过多个 Agent，每个 Agent 处理完交给下一个。这种模式适合"分阶段处理"的场景，比如先清洗数据、再分析、再生成报告。
第三种是协商式：主 Agent 和子 Agent 之间有多轮交互，子 Agent 可以反问、可以要求补充信息、可以提出替代方案。这种模式适合"任务边界不清晰"的场景，比如开放式的研究任务。
我自己的经验是，大部分生产场景用前两种就够了，协商式虽然灵活但很难调试，容易陷入无限循环。如果你非要用协商式，一定要设置最大轮次限制和超时机制。
3.4 A2A 通信的可靠性问题
A2A 是分布式通信，分布式系统该有的问题它都有：网络抖动、消息丢失、重复投递、顺序错乱。DeepAgents 这类框架通常会提供一些内置的可靠性机制，但你不能完全依赖它。
我的做法是在应用层加一层幂等和重试。每个 Task 带一个唯一 ID，子 Agent 处理前先检查这个 ID 是否已经处理过，避免重复执行。重试策略用指数退避，不要用固定间隔，否则容易在服务端压力大时雪上加霜。
还有一个容易被忽略的点是超时设置。A2A 的 Task 如果没有超时，一个卡住的子 Agent 会拖垮整个流程。建议每个 Task 都设置合理的超时时间，超时后要么重试、要么降级、要么标记失败让主 Agent 决策。
4. Skills：把能力封装成可复用的模块
4.1 Skills 和 Tools 的区别
热词里"skills"出现的频率极高，但很多人对 Skills 的理解还停留在"就是工具"的层面。实际上 Skills 和 Tools 有本质区别：Tools 是原子能力，Skills 是能力的组合封装。
举个例子，"查询天气"是一个 Tool，"根据天气和用户日程给出出行建议"是一个 Skill。Skill 内部可能调用了多个 Tool，还包含了一些逻辑判断和提示词模板。Skill 的价值在于复用——你把一个常见的任务模式封装成 Skill，下次遇到类似场景直接调用，不用重新编排。
4.2 Skills 的封装粒度怎么定
这是我在实际项目里踩过最多的坑。封装太细，Skill 数量爆炸，管理成本高；封装太粗，Skill 不够灵活，换个场景就用不了。
我的经验是按"任务边界"来封装，而不是按"技术步骤"。比如"生成周报"是一个合理的 Skill 边界，因为它是一个完整的、有明确输入输出的任务。而"读取数据库""格式化文本""发送邮件"这些是技术步骤，应该作为 Tool 存在，不应该单独封装成 Skill。
另一个判断标准是看这个能力会不会被多个场景复用。如果只有某一个流程用得到，那它就不该是 Skill，直接写在流程里就行。Skill 应该是跨场景的、通用的能力单元。
4.3 Skills 的版本管理和依赖问题
Skills 一旦多了，版本管理就是个大问题。你今天改了一个 Skill 的内部逻辑，可能影响到所有依赖它的流程。我的做法是给每个 Skill 加版本号，并且保持向后兼容。如果必须做破坏性变更，就发一个新版本，旧版本保留一段时间，让依赖方有时间迁移。
依赖问题更麻烦。Skill A 依赖 Skill B，Skill B 又依赖 Skill C，一旦 C 出问题，整个链路都挂。我的建议是尽量减少 Skill 之间的嵌套依赖，如果非要嵌套，控制在两层以内。超过两层，就应该考虑把它们合并成一个 Skill，或者用编排层来协调而不是在 Skill 内部硬编码依赖。
4.4 从热词看 Skills 的生态现状
热词里出现了大量和 Skills 相关的内容：codex skills、claude agent skills、skills 开发、skills 下载平台、skills 推荐等等。这说明 Skills 已经形成了一个小生态，大家在互相分享和复用。
但我要泼一盆冷水：别人的 Skills 不一定适合你。Skills 往往和具体的业务场景、数据格式、工具链深度绑定，直接拿来用大概率水土不服。我的做法是参考别人的 Skill 设计思路，但实现自己重写。特别是涉及数据处理和外部调用的 Skill，一定要自己过一遍，确认没有隐藏的假设和依赖。
5. 编排层设计：让一群 Agent 真正协同起来
5.1 编排的核心是状态管理
多智能体系统最难的不是"让 Agent 干活"，而是"让 Agent 知道彼此在干什么"。这就涉及状态管理。一个任务从创建到完成，中间会产生大量状态：任务进度、中间结果、错误信息、依赖关系。这些状态如果管理不好，整个系统就会乱套。
DeepAgents 这类框架通常提供两种状态管理方式：集中式和分布式。集中式是所有状态存在一个中心节点，Agent 通过读写中心节点来同步。分布式是每个 Agent 维护自己的状态，通过消息传递来同步。
集中式的好处是简单、一致性强，坏处是中心节点容易成为瓶颈。分布式的好处是可扩展，坏处是一致性难保证。我的建议是小规模用集中式，大规模用分布式，但无论哪种，都要有状态快照和恢复机制，否则一旦崩溃就全丢了。
5.2 任务拆解的粒度控制
任务拆得太粗，子 Agent 压力大、容易失败；拆得太细，编排开销大、通信成本高。这个度怎么把握？
我的经验是按"可独立完成"来拆。一个子任务应该是"一个 Agent 在合理时间内能独立完成，且不需要频繁和其他 Agent 交互"的单元。如果两个子任务之间需要频繁来回传数据，那它们可能就不该拆开。
另一个参考标准是按"失败影响范围"来拆。如果一个子任务失败会导致整个流程重来，那它就应该拆得更细，把失败隔离在小范围内。如果一个子任务失败只是局部影响，那可以粗一点。
5.3 错误处理和降级策略
多智能体系统里，错误是常态而不是异常。网络会断、模型会抽风、工具会超时、数据会格式不对。你不能指望一切顺利，必须提前设计好错误处理。
我的做法是分三级处理：第一级是自动重试，适合临时性错误（网络抖动、限流）；第二级是降级，适合某个子 Agent 不可用时用备用方案（换一个 Agent、换一个工具、返回缓存结果）；第三级是人工介入，适合无法自动处理的错误（数据缺失、逻辑冲突）。
降级策略特别重要。比如你的流程依赖一个外部 API，这个 API 挂了怎么办？是直接失败，还是返回上一次的缓存结果，还是用规则引擎兜底？这些都要提前想好，不能等出事了再临时补。
5.4 可观测性：你怎么知道系统在干什么
多智能体系统最让人头疼的一点是黑盒感。单体 Agent 你还能看它的思考过程，多智能体系统里，信息在多个 Agent 之间流转，出了问题你根本不知道是哪一环。
所以可观测性是必须的。至少要记录：每个 Task 的创建时间、开始时间、结束时间、状态变化；每个 Agent 的输入输出；每次工具调用的参数和结果；每次 A2A 通信的消息内容。
这些日志不能只是记下来，还要能关联查询。比如我想知道"为什么这个任务失败了"，我需要能顺着 Task ID 把相关的所有日志串起来看。这就要求日志里带足够的上下文信息（Task ID、Parent Task ID、Agent ID 等）。
6. 实战：搭一个最小可用的多智能体集群
6.1 环境准备和依赖安装
先说环境。DeepAgents 这类框架通常对 Python 版本有要求，建议用 3.10 以上。依赖管理用 uv 或者 poetry，别用裸 pip，否则依赖冲突会让你怀疑人生。
# 用 uv 管理依赖（推荐） uv init multi-agent-demo cd multi-agent-demo uv add deepagents mcp a2a-sdkMCP Server 和 A2A 的通信层通常需要单独配置。MCP Server 可以本地起，也可以远程连。本地起的好处是调试方便，坏处是资源占用。远程连的好处是解耦，坏处是网络延迟。原型阶段建议本地起，生产环境再考虑远程。
6.2 定义第一个 Agent 和它的 Skill
先定义一个最简单的 Agent，它只做一件事：根据关键词搜索信息并整理成摘要。
from deepagents import Agent, Skill class ResearchSkill(Skill): name = "research" description = "根据关键词搜索并整理信息" def execute(self, keyword: str, depth: int = 3): # 调用搜索工具 results = self.call_tool("web_search", query=keyword, limit=depth) # 调用摘要工具 summary = self.call_tool("summarize", texts=results) return {"summary": summary, "sources": results} research_agent = Agent( name="researcher", skills=[ResearchSkill()], system_prompt="你是一个研究助手，负责根据关键词检索并整理信息。" )这个例子很简单，但它包含了 Skill 的核心要素：名称、描述、执行逻辑、工具调用。你可以照着这个模式，把常见的任务模式都封装成 Skill。
6.3 用 A2A 把两个 Agent 串起来
现在加一个"写作 Agent"，它接收研究 Agent 的输出，生成一篇结构化的文章。
writer_agent = Agent( name="writer", skills=[WritingSkill()], system_prompt="你是一个写作助手，负责把研究结果整理成结构化的文章。" ) # 通过 A2A 建立协作关系 orchestrator = Orchestrator() orchestrator.register(research_agent) orchestrator.register(writer_agent) # 定义流程：研究 -> 写作 result = orchestrator.run( task="写一篇关于多智能体协作的文章", pipeline=["researcher", "writer"] )这里的pipeline就是编排的核心。你可以把它理解成一个任务流水线，每个环节的输出是下一个环节的输入。实际项目里，流水线可能更复杂，会有分支、循环、并行，但基本模式是一样的。
6.4 跑通之后的第一个坑：上下文膨胀
流程跑通之后，你很快会遇到第一个坑：上下文膨胀。研究 Agent 返回的结果可能很长，写作 Agent 接收之后，再加上自己的提示词和历史消息，很快就超出模型的上下文窗口了。
解决办法有几个：一是在 Agent 之间传递摘要而不是全文，研究 Agent 输出的时候就做一次压缩；二是用外部存储，把长文本存到文件或数据库，Agent 之间只传引用；三是分段处理，把长任务拆成多个短任务，每个短任务独立处理。
我自己的做法是组合使用：研究 Agent 输出结构化摘要（关键信息 + 来源引用），写作 Agent 按段落处理，每段独立生成。这样既控制了上下文，又保证了质量。
6.5 第二个坑：Agent 之间的"理解偏差"
第二个坑更隐蔽：Agent 之间的理解偏差。研究 Agent 觉得"我返回的信息很清楚了"，写作 Agent 却理解成了另一个意思。这种偏差在单体 Agent 里不明显，因为只有一个"大脑"，但在多智能体系统里会被放大。
解决办法是在 Agent 之间定义明确的数据契约。不要用自然语言传递关键信息，用结构化数据（JSON Schema）。研究 Agent 输出的时候，严格按照 Schema 来；写作 Agent 接收的时候，先校验 Schema 再处理。这样即使模型有理解偏差，也能在数据层面被拦住。
# 定义 Agent 之间的数据契约 research_output_schema = { "type": "object", "properties": { "topic": {"type": "string"}, "key_points": {"type": "array", "items": {"type": "string"}}, "sources": {"type": "array", "items": {"type": "string"}}, "confidence": {"type": "number"} }, "required": ["topic", "key_points"] }7. 扩展性设计：怎么让集群越用越强
7.1 新 Agent 的接入成本
一个多智能体集群的价值，很大程度上取决于接入新 Agent 的成本。如果每加一个 Agent 都要改一堆代码、调一堆配置，那这个集群就很难扩展。
降低接入成本的关键是标准化。Agent Card 标准化、Skill 接口标准化、A2A 消息格式标准化。只要新 Agent 符合这些标准，就能即插即用。DeepAgents 这类框架通常会提供一些脚手架和模板，帮你快速生成符合标准的 Agent。
我的经验是先定标准再写 Agent。不要先写几个 Agent 再回头抽象标准，那样抽象出来的标准往往不伦不类。正确的顺序是：先想清楚集群里会有哪些类型的 Agent、它们怎么交互、需要哪些公共能力，然后定标准，最后按标准实现。
7.2 Skill 市场的可能性
热词里出现了"skills 下载平台""skills 推荐""skills 大全"这些词，说明 Skills 的共享生态正在形成。从工程角度看，Skill 市场是可行的，但有几个前提。
第一是接口标准化。Skill 的输入输出必须用统一的 Schema 描述，否则没法自动匹配和组合。第二是依赖隔离。一个 Skill 依赖的库和另一个 Skill 冲突怎么办？需要沙箱或者容器化。第三是质量评估。怎么知道一个 Skill 好不好用？需要有一套评估机制，比如成功率、延迟、成本。
目前这些条件还不完全成熟，但方向是明确的。我预计未来一两年内，会出现比较成熟的 Skill 共享平台，到时候多智能体系统的开发效率会有质的提升。
7.3 性能优化的几个方向
多智能体系统的性能瓶颈通常在三个地方：模型调用、工具调用、Agent 间通信。
模型调用是大头。优化方向有：用小模型处理简单任务、用缓存避免重复调用、用批处理合并请求。我实测下来，缓存能省 30% 到 50% 的调用，特别是那些重复性高的查询任务。
工具调用的优化主要是并行化。如果多个工具调用之间没有依赖，就并行发出去，不要串行等。DeepAgents 通常支持并行工具调用，但你要在编排层显式开启。
Agent 间通信的优化是减少往返次数。每次 A2A 通信都有开销，能合并的消息就合并，能异步的就异步。我见过一些实现，Agent 之间为了确认一个细节来回传了七八条消息，这种就是设计问题，应该在数据契约层面解决。
7.4 安全边界：别让 Agent 失控
最后说说安全。多智能体系统里，Agent 有工具调用能力，如果失控，后果比单体 Agent 严重得多。一个 Agent 可能调用另一个 Agent 去执行危险操作，而主 Agent 根本不知道。
我的做法是在三个层面设边界。第一层是工具权限，每个 Agent 只能调用白名单里的工具。第二层是资源配额，每个 Agent 有调用次数、token 消耗、执行时间的上限。第三层是行为审计，所有关键操作都记录日志，异常行为触发告警。
还有一点是人工确认机制。对于高风险操作（删除数据、发送外部请求、修改配置），不要让 Agent 自动执行，必须经过人工确认。这个机制会降低自动化程度，但在安全面前，这点效率损失是值得的。
8. 我踩过的几个真实坑和对应的解法
8.1 Agent 无限循环：A 让 B 干活，B 又让 A 干活
这是最经典的坑。A Agent 接到任务，发现自己干不了，转给 B；B 一看，觉得这应该是 A 的活，又转回给 A。两个 Agent 互相踢皮球，任务永远完不成。
解法是加任务归属标记。每个 Task 带一个owner字段，标记这个任务当前由谁负责。Agent 接到任务时先检查 owner，如果是自己转出去的，就不能再转回来。同时设置最大转交次数，超过就标记失败，让人工介入。
8.2 工具调用参数错误：模型"编造"了不存在的参数
模型有时候会"幻觉"出一些工具不支持的参数，或者把参数名写错。MCP 层面如果没做严格校验，这个错误会一直传到工具执行层才报错，排查起来很麻烦。
解法是在 MCP Server 层面做参数校验。每个工具注册的时候，把参数的 Schema 定义清楚，调用时先校验再执行。校验失败直接返回明确的错误信息，让模型知道哪里错了，它下次就会改。
8.3 状态不一致：两个 Agent 看到的数据不一样
分布式状态管理里，两个 Agent 可能同时读写同一个状态，导致不一致。比如 A 读到的库存是 10，B 也读到 10，A 扣了 1，B 也扣了 1，最后库存变成 8，但实际上应该只扣一次。
解法是用乐观锁或者悲观锁。乐观锁是读的时候记版本号，写的时候检查版本号有没有变，变了就重试。悲观锁是读的时候就加锁，写完再释放。多智能体场景下，我倾向于乐观锁，因为 Agent 之间的操作通常不频繁冲突，悲观锁的开销不划算。
8.4 日志太多：出了问题反而找不到关键信息
可观测性做过头也是问题。每个 Agent 的每次思考、每次工具调用、每次消息传递都记日志，日志量爆炸，真出问题的时候反而找不到关键信息。
解法是分级日志 + 结构化日志。日常运行只记 INFO 级别，关键节点记 WARN，异常记 ERROR。日志用 JSON 格式，带足够的上下文字段，方便过滤和关联。另外，给每个 Task 分配一个 trace ID，所有相关日志都带这个 ID，排查的时候一搜就出来了。
9. 从"能跑"到"好用"：一些工程上的体会
多智能体系统从 demo 到生产，中间隔着的不是技术难度，而是工程细节。我见过太多 demo 跑得很漂亮、一上生产就各种问题的案例。总结下来，有几个体会值得分享。
第一，不要追求"全自动"。很多人一开始就想做一个完全自主的多智能体系统，结果发现不可控、不可调试、不可维护。正确的做法是先做"人机协作"，关键节点让人确认，跑顺了再逐步自动化。自动化程度应该是渐进的，不是一步到位的。
第二，简单优先。能用两个 Agent 解决的，不要用五个。能用流水线解决的，不要用协商式。每增加一个 Agent、每增加一种交互模式，系统的复杂度和调试难度都是指数级上升的。我自己的原则是在满足需求的前提下，Agent 数量越少越好。
第三，可观测性要前置。不要等出了问题再补日志，一开始就要把可观测性设计进去。Task 的生命周期、Agent 的输入输出、工具调用的参数结果，这些都要有记录。没有可观测性，多智能体系统就是个黑盒，你根本不知道它在干什么。
第四，测试要覆盖异常路径。正常路径的测试很容易写，但多智能体系统的价值恰恰体现在异常处理上。网络断了怎么办、工具超时怎么办、Agent 返回了格式错误的数据怎么办，这些都要有测试用例。我通常会用混沌工程的方式，随机注入故障，看系统能不能正确降级。
第五，文档和契约要跟上。Agent 之间的数据契约、Skill 的接口定义、MCP 工具的参数说明，这些文档如果不同步更新，后面接手的人会非常痛苦。我的做法是把契约写成代码，用 Schema 定义，自动生成文档，这样就不会出现文档和实现不一致的问题。
最后说一个心态上的体会。多智能体系统现在还处于早期，很多最佳实践还没形成，你踩的坑别人可能也在踩。所以多和社区交流、多看别人的实现、多分享自己的经验，比一个人闷头搞效率高得多。这个领域变化很快，保持学习和开放的心态，比掌握某个具体框架更重要。
