claude code构建长期运行Multi-Agent系统的Context-Engineering经验

发表于 更新于 分类于

构建智能体

什么时候需要智能体

  1. 对任务成功率要求低时采用智能体，否则采用工作流
    当前普遍的Agent架构，一般都无法做到比较高的成功率，有时平均成功率低到40、50%，所以Agent结果无法直接应用于业务，而是需要人来干预结果，人来参与进结果的生成，比如编程、写PPT等。
  2. 任务比较复杂时采用智能体（需要多步推理），否则采用工作流
  3. 需要解决的任务是复杂而有价值的则使用智能体，否则采用工作流
  4. 任务异常恢复的代价很低则使用智能体，否则采用Agent的只读模式（不会进行实际上的文件读写或支付等操作）、或采用human in loop模式让人介入进来

参考文档
https://blog.crewai.com/build-agents-to-be-dependable/
https://www.youtube.com/watch?v=XSZP9GhhuAc

构建智能体系统的要素

智能体是一个循环决策的工作流，它自主地或在人类参与的情况下，朝着既定目标进行规划、行动和学习。

  • 对所发生事件的记忆
  • 影响世界的工具
  • 执行审计、约束
  • 需要实现的目标

12 Factor Agents - 构建可靠LLM应用的原则

基于12 Factor Agents框架，以下是构建生产级智能体系统的12个核心原则：

Factor 1: 自然语言到工具调用 (Natural Language to Tool Calls)

将自然语言输入转换为结构化的工具调用，确保LLM能够准确理解和执行用户意图。

Factor 2: 拥有你的提示词 (Own your prompts)

不要依赖框架的默认提示词，要完全控制和管理你的提示词，确保它们符合你的具体需求。

Factor 3: 拥有你的上下文窗口 (Own your context window)

主动管理上下文窗口，包括记忆、状态和相关信息，而不是让框架自动处理。

Factor 4: 工具就是结构化输出 (Tools are just structured outputs)

将工具调用视为结构化输出，使用模式验证和类型安全来确保输出质量。

Factor 5: 统一执行状态和业务状态 (Unify execution state and business state)

将智能体的执行状态与业务状态统一管理，避免状态不一致的问题。

Factor 6: 启动/暂停/恢复的简单API (Launch/Pause/Resume with simple APIs)

设计简单的API来管理智能体的生命周期，支持启动、暂停和恢复操作。

Factor 7: 通过工具调用联系人类 (Contact humans with tool calls)

当需要人类干预时，通过工具调用的方式优雅地请求人类帮助。

Factor 8: 拥有你的控制流 (Own your control flow)

完全控制智能体的决策流程，而不是依赖框架的默认行为。

Factor 9: 将错误压缩到上下文窗口 (Compact Errors into Context Window)

将错误信息压缩并整合到上下文窗口中，帮助智能体更好地理解和处理错误。

Factor 10: 小型、专注的智能体 (Small, Focused Agents)

构建小型、专注的智能体，每个智能体负责特定的任务，而不是构建大型通用智能体。

Factor 11: 从任何地方触发，在用户所在的地方见面 (Trigger from anywhere, meet users where they are)

支持多种触发方式，让智能体能够在用户需要的地方出现。

Factor 12: 让你的智能体成为无状态归约器 (Make your agent a stateless reducer)

将智能体设计为无状态的归约器，通过纯函数处理状态转换，提高可靠性和可测试性。

参考文档
https://github.com/humanlayer/12-factor-agents

构建多智能体系统

some problems are too complex, too parallel, or too specialized for one agent to handle alone.
如果单agent的职责过多（比如既需要做PPT、又要通过browser-use实现浏览器检索、又需要使用terminal来写一些脚本来进行复杂运算），每次使用prompt来reasoning时，大模型都需要进行复杂的推理、并在很多工具中进行决策，随着agent的运行，上下文会变得非常复杂不可控。

多智能体系统的难点

多智能系统的难点不在于运行多智能体，而是协同多智能体，如果希望构建一个长期运行的多智能体系统，关键是：

  • 任务复杂度过高，需要分解和专业化处理
  • 需要并行处理多个子任务
  • 要求错误隔离和容错机制
    代理是有状态的，错误会累积，，在长时间的执行过程中，Agent会在多次工具调用中保持状态，需要持续处理过程中的错误，然后在出错时，具备中断恢复的能力。
  • 需要动态上下文管理和状态协调

核心是上下文工程（Context Engineering）和错误传播控制。
context_engineering

  • 上下文压缩：agent运行过程中对历史上下文做summary或prune，去除冗余信息，比如一些<think>块
  • 上下文卸载：将占据大量空间的工具结果存储到外部空间，在需要时加入到上下文中
  • 上下文隔离：为多个agent创建相互隔离的上下文，互相之间不会共享窗口

上下文压缩

压缩（Compaction）：当对话接近上下文窗口限制时，总结内容并重新初始化新的上下文窗口。

核心原则：

  • 保留关键信息（架构决策、未解决的bug、实现细节）
  • 清理冗余内容（工具输出、重复消息）
  • 维持最小性能损失

实现方式：

  • Claude Code：压缩消息历史 + 保留最近访问的5个文件
  • 工具结果清理：最安全的轻量级压缩方式

挑战：在保留与丢弃之间平衡，避免过度压缩导致关键信息丢失。

上下文卸载

结构化笔记（Structured Note-taking）：智能体定期将笔记持久化到上下文窗口外的存储中，需要时再拉回上下文。

核心优势：

  • 提供持久化记忆，开销最小
  • 跟踪复杂任务进度，维护关键上下文和依赖关系
  • 支持跨工具调用的长期连贯性

实现方式：

  • Claude Code：创建待办事项列表
  • 自定义智能体：维护NOTES.md文件
  • Claude Developer Platform：基于文件系统的记忆工具

应用场景：长期任务中保持状态连续性，避免上下文重置导致的信息丢失。

混合策略（Hybrid Strategy）

在某些场景下，最有效的智能体可能采用混合策略：预先检索一些数据以提高速度，同时根据任务需要自主探索更多信息。决策边界取决于具体任务的特点。

Claude Code的混合模式示例：

  • 预先将CLAUDE.md文件直接放入上下文，提供快速访问
  • 使用glob和grep等基础工具进行实时环境导航和文件检索
  • 有效避免了过时索引和复杂语法树的问题

适用场景：

  • 混合策略更适合内容变化较少的场景，如法律或金融工作
  • 随着模型能力提升，智能体设计将趋向于让智能模型更自主地行动
  • 人工策划的需求将逐渐减少

上下文隔离 - sub-agent

子智能体架构（Sub-agent Architectures）：通过专门的子智能体处理专注任务，避免单一智能体维护整个项目状态。

核心设计：

  • 主智能体：协调高级计划，专注于结果综合和分析
  • 子智能体：执行深度技术工作，使用工具查找相关信息
  • 上下文隔离：详细搜索上下文保持在子智能体内，避免污染主智能体

工作流程：

  • 子智能体可能使用数万token进行广泛探索
  • 返回压缩、精炼的工作总结（通常1,000-2,000 tokens）
  • 实现关注点分离，提高系统效率

适用场景：

  • 复杂研究和分析任务
  • 需要并行探索的场景
  • 相比单智能体系统有显著改进

架构示例：
multiagent_longrunningtask

参考文档
https://www.anthropic.com/engineering/multi-agent-research-system?ref=blog.langchain.com
https://cognition.ai/blog/dont-build-multi-agents
https://blog.langchain.com/how-and-when-to-build-multi-agent-systems/

https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents

https://www.xiaohongshu.com/explore/6882005d000000001d00d53a?app_platform=android&ignoreEngage=true&app_version=8.92.0&share_from_user_hidden=true&xsec_source=app_share&type=normal&xsec_token=CBIAt7FwVT3rmjUCxeIUs-9z3euUYE-PTih9HgqFRJcJE=&author_share=1&xhsshare=CopyLink&shareRedId=ODc4Rjc2PDs2NzUyOTgwNjY1OTk4Rj1C&apptime=1753439829&share_id=c6e6707db94640ef8bd24b59ea1b466e&share_channel=copy_link
https://github.com/zilliztech/claude-context/blob/master/packages/core/src/context.ts
https://github.com/shareAI-lab/analysis_claude_code/blob/main/claude_code_v_1.0.33/stage1_analysis_workspace/docs/ana_docs/task_agent_analysis.md
https://baoyu.io/translations/decoding-claude-code

多智能体系统的一些范例

https://blog.langchain.com/langgraph-multi-agent-workflows/
https://langchain-ai.github.io/langgraph/concepts/multi_agent/?h=scratchpad