1. 项目概述：一份面向生产实践的智能体模式图鉴

如果你正在构建或计划构建一个真正能“干活”的AI智能体，而不是一个只会聊天的玩具，那么你大概率会遇到一个核心困境：教程里的Demo跑得飞快，但一到真实、复杂的生产环境，智能体就开始“犯傻”——上下文不够用、工具调用混乱、任务半途而废、成本失控……这些问题，那些光鲜亮丽的入门指南往往避而不谈。

awesome-agentic-patterns 这个项目，就是为了解决这个“理想与现实”的鸿沟而生的。它不是另一个AI工具列表，而是一个由社区驱动的、专注于 智能体模式（Agentic Patterns） 的实战经验库。简单说，这里收集的不是“用什么框架”，而是“ 怎么设计 才能让智能体更可靠、更高效、更经济地完成实际工作”。这些模式，是来自Sourcegraph、Vercel等一线团队在构建真实AI编码助手、自动化工作流时，踩过无数坑后总结出的可复用“设计图纸”和“操作手册”。

这个项目适合所有层级的从业者：如果你是刚接触智能体的开发者，可以把它当作一份“避坑指南”和设计灵感来源；如果你是有经验的架构师，这里面的模式能帮你系统化地思考智能体的可靠性、安全性和扩展性。它剥离了具体框架的束缚，直指智能体设计的核心逻辑，让你能从第一性原理出发，构建真正能交付价值的AI应用。

2. 智能体模式的核心价值与设计哲学

在深入具体模式之前，我们需要先理解：为什么需要“模式”？一个能调用API的LangChain链或AutoGen群聊，不就是智能体吗？这里的区别在于 设计的系统性和生产就绪性 。

2.1 从“能跑通”到“能扛住”

大多数智能体Demo停留在“单次任务成功”的层面。例如，给你一个需求，智能体能写出一段代码。但在生产环境中，需求是持续涌入的，代码库是不断变化的，外部API可能失败，模型会“胡言乱语”。这时，你需要的不再是一个孤立的智能体，而是一个具备 韧性（Resilience） 、 可观测性（Observability） 和 进化能力（Evolution） 的智能体系统。

项目中的模式正是围绕这些生产级需求组织的。比如 Agent Circuit Breaker （智能体熔断器） 模式，它借鉴了微服务中的熔断器概念。当智能体在短时间内连续失败（例如，多次调用工具超时或返回错误），熔断器会“跳闸”，暂时阻止该智能体或工具继续执行，并可能切换到降级策略（如使用更简单的模型、或通知人工接管）。这防止了单个故障点引发雪崩效应，是保障系统整体可用的关键设计。

2.2 模式的定义：可复用、聚焦智能体、有迹可循

项目对“模式”有着严格且实用的定义，这确保了收录内容的质量和参考价值：

1. 可复用性（Repeatable） ：必须被不止一个团队在实际项目中验证过。这意味着它不是一个脑洞大开的理论，而是经过实战考验的解决方案。例如， Plan-Then-Execute （先计划后执行） 模式，已被广泛应用于各种需要多步骤推理的任务中，如代码生成、数据分析流水线。
2. 聚焦智能体（Agent-centric） ：必须直接改善智能体的感知、推理或行动能力。它关注的是智能体本身的“心智”或“行为”模式，而不是底层的基础设施。比如 Context Window Auto-Compaction （上下文窗口自动压缩） ，就是专门解决大语言模型（LLM）上下文长度限制的智能策略，通过自动总结、过滤无关历史对话，让智能体在长程任务中保持“记忆”焦点。
3. 有迹可循（Traceable） ：每个模式都必须有公开的参考文献支持，如博客文章、技术演讲、开源代码或论文。这保证了模式的透明度和可追溯性，你可以深入原始资料去理解其上下文和实现细节。

这种定义方式，使得这个项目不同于普通的“Awesome List”。它更像是一个 经过同行评议的、面向工程实践的智能体设计模式手册 。

2.3 超越单智能体：系统思维的引入

许多初学者容易陷入“一个超级智能体解决所有问题”的误区。而该项目的模式库清晰地展示了现代智能体系统的复杂性，其分类本身就体现了一种系统架构思维：

• 编排与控制（Orchestration & Control） ：当任务过于复杂时，如何分解任务、协调多个子智能体（ Sub-Agent Spawning ）、管理执行流程（ Lane-Based Execution Queueing ）？这类似于软件工程中的工作流引擎或分布式任务调度。
• 反馈循环（Feedback Loops） ：智能体如何从错误中学习？如何通过CI/CD流水线（ Coding Agent CI Feedback Loop ）、自我批判（ Self-Critique Evaluator Loop ）或人类评审（ Human-in-the-Loop Approval Framework ）来持续改进其输出质量？这引入了“学习”和“迭代”的机制。
• 可靠性与评估（Reliability & Eval） ：如何确保智能体的行为是可预测、可测试的？模式如 Structured Output Specification （结构化输出规范） 强制智能体以预定格式（如JSON Schema）返回结果，便于后续程序化处理； Workflow Evals with Mocked Tools （使用模拟工具的工作流评估） 则允许你在不调用真实外部服务的情况下，对智能体流水线进行集成测试。

理解这些分类背后的逻辑，比记住单个模式更重要。它告诉你，构建一个生产级智能体，你需要从 记忆管理、任务编排、学习反馈、安全防护、工具生态、用户体验 等多个维度进行综合设计。

3. 核心模式深度解析与实战要点

让我们选取几个最具代表性且实用性极强的模式，深入拆解其设计思想、解决的具体问题以及实现时的关键考量。

3.1 模式解析： Plan-Then-Execute （先计划后执行）

这是最基础、也最核心的模式之一，尤其适用于复杂、多步骤的任务。

• 问题场景 ：你让智能体“帮我开发一个用户登录页面”。一个未经设计的智能体可能会直接开始写第一行HTML代码，而没有考虑需要后端API、数据库设计、样式文件、路由配置等。结果往往是代码片段零散、逻辑缺失，无法形成一个可运行的整体。
• 模式设计 ： Plan-Then-Execute 强制智能体将任务分解为两个明确的阶段：
  1. 计划阶段 ：智能体（通常由一个“规划者”模型或模块担任）分析任务，生成一个结构化的计划。这个计划可能是一个任务列表、一个流程图、或一个包含子目标和依赖关系的JSON结构。例如： [1. 设计数据库User表， 2. 创建后端注册/登录API端点， 3. 实现前端登录表单组件， 4. 添加路由和状态管理...] 。
  2. 执行阶段 ：另一个智能体（或同一个智能体的不同模式）根据计划，逐步执行每个子任务。每完成一步，其状态和结果会被更新到上下文中，作为后续步骤的输入。
• 实操要点与避坑指南 ：
  • 计划粒度 ：计划不能太粗（如“开发前端”），也不能太细（如“写一个div标签”）。需要根据任务复杂度和模型能力来调整。一个好的经验法则是，每个子任务应该对应一个可以独立验证的、有明确输入输出的“工作单元”。
  • 动态调整 ：僵化的计划无法应对执行中的意外（如工具调用失败、生成代码有bug）。高级的实现会引入 Reflection Loop （反思循环） 模式：在执行每个步骤后，让智能体检查结果是否符合预期，如果不符合，则重新评估并可能调整后续计划。
  • 上下文管理 ：执行阶段需要将庞大的计划拆解后喂给LLM，同时保留必要的全局上下文。这里可以结合 Context-Minimization Pattern （上下文最小化模式） ，只将当前步骤相关的历史和信息放入提示词，以避免上下文污染和浪费。

  注意 ：不要过度规划。对于简单或定义明确的任务，过度规划会引入不必要的延迟和复杂性。这个模式适用于“探索性”或“创造性”任务，而不是“查找性”任务。

3.2 模式解析： Self-Critique Evaluator Loop （自我批判评估循环）

如何让智能体自己发现并修正错误？这是提升其自主性和输出质量的关键。

• 问题场景 ：智能体生成了一段代码，但里面可能有逻辑错误、安全漏洞或风格不一致。完全依赖外部工具（如linter、测试）或人工检查，效率低下且无法形成闭环。
• 模式设计 ：在智能体生成一个输出（如代码、文档、方案）后，不直接将其作为最终结果，而是启动一个“批判者”角色。这个角色可以由同一个LLM实例扮演（通过切换提示词），也可以由一个专门的、可能更擅长分析的模型（如GPT-4）担任。批判者基于一组标准（功能正确性、安全性、代码风格、是否符合需求等）对输出进行评审，并提出修改建议。然后，原始智能体或另一个“修改者”根据建议进行修正。这个过程可以迭代多次，直到输出通过批判或达到迭代上限。
• 实操要点与避坑指南 ：
  • 批判标准的明确性 ：给批判者的提示词必须极其清晰、具体。模糊的指令如“检查代码质量”是无效的。应该像编写测试用例一样编写批判标准，例如：“检查函数是否处理了输入为null的情况”、“确保没有使用已知不安全的加密库”、“代码注释覆盖率是否达到20%”。
  • 防止循环和退化 ：有时，批判者和生成者会陷入无意义的拉锯战，或者修改反而引入了新问题。需要设置最大迭代次数（如3次），并在每次迭代后对比输出变化，如果质量没有提升甚至下降，则终止循环，可能转由人工处理。
  • 成本与延迟权衡 ：每次批判都是一次额外的LLM API调用，会增加成本和耗时。对于简单、低风险的任务，可能不需要此循环。可以设计一个“置信度”阈值，只有当智能体自身对输出的置信度较低时，才触发自我批判。
  • 与外部工具结合 ：自我批判不应取代自动化工具。最健壮的方案是：先运行静态代码分析、单元测试等快速工具，对于工具无法判断的“语义”或“设计”问题，再启动LLM驱动的自我批判循环。

3.3 模式解析： Budget-Aware Model Routing with Hard Cost Caps （具备硬性成本上限的预算感知模型路由）

对于任何希望将智能体投入生产的企业而言，成本控制是生死攸关的问题。

• 问题场景 ：你的应用混合使用了不同能力和价格的LLM（例如，便宜的 gpt-3.5-turbo 用于简单分类，昂贵的 gpt-4 用于复杂推理）。如何智能地将任务分发给最合适的模型，同时确保月度API费用绝不超支？
• 模式设计 ：这是一个典型的 决策路由 模式。它包含几个核心组件：
  1. 任务分类器 ：对输入任务进行快速分析（可能用一个非常轻量、便宜的模型或规则引擎），判断其复杂度、所需创造力等级。
  2. 模型路由表 ：一个配置表，定义了不同任务类型与推荐模型（及备选模型）的映射，以及每次调用的预估成本。
  3. 预算管理器 ：一个实时追踪所有模型调用消耗的计数器，并维护一个全局的、周期性的（如每日、每月）硬性成本上限。
  4. 路由决策逻辑 ：接收到任务后，结合任务分类结果、当前预算使用情况、各模型服务状态（健康检查），动态决定使用哪个模型。当预算即将用尽时，可以自动降级到更便宜的模型，甚至优雅地拒绝非关键任务。
• 实操要点与避坑指南 ：
  • 精准的成本预估 ：LLM API成本通常按输入/输出令牌数计算。你需要有能力在路由前相对准确地预估任务的令牌消耗。这可以通过历史数据分析、基于任务长度的启发式规则，或用一个小模型先进行“预览”来实现。
  • 状态持久化 ：预算计数器必须是持久化的（如存储在Redis或数据库中），并能跨多个服务实例同步，以防止在分布式部署下预算被突破。
  • 优雅降级策略 ：当触发成本上限时，直接返回“服务不可用”是糟糕的体验。更好的策略是：1) 对免费或低优先级用户降级模型；2) 返回一个缓存的结果（如果适用）；3) 将任务放入队列，待下一个预算周期执行。这需要与 Agent Circuit Breaker 模式结合设计。
  • 监控与告警 ：必须设置预算消耗的预警阈值（如达到80%时），以便运维人员提前干预，而不是等到完全耗尽。

4. 如何利用模式库进行智能体架构设计

面对上百个模式，直接套用是困难的。项目提供的网站工具（如Pattern Explorer, Decision Explorer）是很好的导航，但更重要的是掌握一套方法论，将这些模式像乐高积木一样组合起来，构建你自己的智能体系统。

4.1 从需求反推模式选择：一个实战案例

假设我们要构建一个“自动化代码重构助手”，它能够扫描代码库，识别出需要重构的代码坏味道（如过长的函数、重复代码），并安全地实施重构。

1. 分解核心能力与挑战 ：

   • 感知 ：需要“阅读”和理解整个代码库的结构和语义。
   • 规划 ：需要制定重构策略，决定先改哪里，怎么改，并评估影响范围。
   • 执行 ：需要安全地修改代码文件，并保证修改后的代码能通过编译和测试。
   • 验证 ：需要确保重构没有引入错误或改变原有行为。
   • 安全 ：必须防止破坏性修改，需要有回滚机制。

2. 匹配与组合模式 ：

   • 感知阶段 ：采用 Agentic Search Over Vector Embeddings （基于向量嵌入的智能体搜索） 来快速从海量代码中检索出与“坏味道”相关的代码片段。结合 Progressive Disclosure for Large Files （大文件渐进式披露） ，当需要深入分析某个大型文件时，只将相关部分（如单个函数）加载到上下文。
   • 规划阶段 ：采用 Plan-Then-Execute 作为顶层框架。规划者使用 Tree-of-Thought Reasoning （思维树推理） 来生成多个可能的重构方案，并评估各自的优劣。
   • 执行与验证阶段 ：这是一个关键循环。执行者（Worker）根据计划进行代码修改。每次修改后，立即触发一个 Coding Agent CI Feedback Loop （编码智能体CI反馈循环） ：自动运行项目的测试套件、静态分析工具。如果测试失败，则进入 Self-Critique Evaluator Loop ，分析失败原因并生成修正。这里可以引入 Output Verification Loop （输出验证循环） ，用简单的规则检查代码格式和语法。
   • 安全与可靠性 ：在整个流程外围，设置 Hook-Based Safety Guard Rails （基于钩子的安全护栏） ，例如，禁止直接修改 main 分支，所有修改必须通过Pull Request。实施 Canary Rollout and Automatic Rollback （金丝雀发布与自动回滚） ，先将重构后的代码部署到一小部分用户或测试环境，验证无误后再全量推广。
   • 状态与记忆 ：使用 Filesystem-Based Agent State （基于文件系统的智能体状态） 来持久化整个重构任务的分析结果、计划和执行日志，以便任务中断后可以恢复。

通过这样的映射，我们从一个模糊的需求，推导出了一个由多个成熟模式支撑的具体架构蓝图。每个模式都解决了系统中的一个具体子问题。

4.2 模式演进的视角：从简单到复杂

不要试图在第一个版本中就实现所有高级模式。智能体系统的构建应该是一个迭代演进的过程。

• V1.0（核心功能） ：实现最基本的 Plan-Then-Execute + Structured Output Specification 。确保智能体能理解任务，并以可解析的格式输出代码更改建议（而不是自然语言描述）。人工审核并应用这些建议。
• V1.5（引入自动化） ：加入 Code-Then-Execute Pattern （编码后执行模式） ，让智能体不仅能建议，还能在沙箱中直接生成代码补丁。同时加入 Human-in-the-Loop Approval Framework （人在回路审批框架） ，在自动应用前必须经过人工点击确认。
• V2.0（引入学习与优化） ：加入 CI Feedback Loop ，让智能体能看到自己修改的代码是否通过了测试。收集这些成功/失败的数据，用于未来的 Iterative Prompt & Skill Refinement （迭代式提示与技能优化） 。
• V3.0（系统化与规模化） ：引入 Multi-Agent Orchestration （多智能体编排） ，将代码分析、重构执行、测试验证拆分为不同的专职智能体。同时实施全面的 Budget-Aware Model Routing 和 LLM Observability （LLM可观测性） 来管控成本和监控质量。

这种渐进式的采纳，既能让你快速验证价值，又能随着复杂度增长，不断引入更强大的模式来维持系统的健壮性。

5. 常见陷阱、挑战与应对策略实录

在实际集成这些模式时，你会遇到一些教科书上不会写的挑战。以下是我从实践中总结的一些关键教训。

5.1 陷阱一：过度设计（Over-Engineering）

• 现象 ：在项目初期，就试图引入复杂的多智能体编排、动态服务发现、高级记忆机制等。
• 后果 ：系统复杂度爆炸，开发维护成本极高，却无法证明核心价值。智能体本身的不确定性叠加系统复杂性，导致调试极其困难。
• 应对策略 ： 坚持“最简单可行模式”原则 。从一个最核心、最垂直的用例开始，只使用解决该用例瓶颈所必需的模式。例如，如果你的智能体只是回答基于文档的问答，先从 Agentic Search Over Vector Embeddings （检索）和 Context Window Anxiety Management （上下文管理）开始，而不是一开始就搞 Swarm Migration Pattern （蜂群迁移模式）。

5.2 陷阱二：忽视工具生态的复杂性

• 现象 ：认为给智能体提供大量工具（Shell、数据库、浏览器）它就能自动学会高效使用。
• 后果 ：智能体陷入“工具选择困难症”，频繁调用错误或低效的工具，任务成功率低。
• 应对策略 ：
  1. 工具设计遵循 LLM-Friendly API Design （LLM友好API设计） ：工具的名称、描述、参数说明必须极其清晰、无歧义。使用结构化数据格式（如JSON Schema）定义输入输出。
  2. 实施 Tool Selection Guide （工具选择指南） ：在提示词中明确指导智能体在什么场景下优先使用什么工具。例如：“当需要查询用户数据时，优先使用 query_user_db 工具，而不是执行原始SQL。”
  3. 采用 Progressive Tool Discovery （渐进式工具发现） ：不要一次性暴露所有工具。根据任务上下文，动态地只提供最相关的几个工具选项，降低智能体的认知负荷。

5.3 陷阱三：低估评估与测试的难度

• 现象 ：没有建立科学的评估体系，仅凭感觉或少数几个例子判断智能体好坏。
• 后果 ：无法量化改进效果，迭代方向盲目，可能越“优化”效果越差。
• 应对策略 ：
  1. 建立基准测试集 ：针对你的核心任务，构建一个包含输入、期望输出和评估标准的测试用例集。这个集合需要覆盖常见场景、边界情况和易错点。
  2. 实施自动化评估流水线 ：借鉴 Workflow Evals with Mocked Tools 模式，搭建一个可以自动运行测试集、调用智能体、并对比其输出与期望值的流水线。评估标准可以是精确匹配、模糊匹配（如BLEU分数）、或使用另一个LLM作为裁判（ CriticGPT-Style Evaluation ）。
  3. 监控生产环境指标 ：除了离线测试，更要监控线上真实使用的指标，如任务完成率、平均处理时间、用户满意度评分、人工接管率等。这些是衡量智能体真实价值的黄金标准。

5.4 陷阱四：对“智能”的期望不切实际

• 现象 ：期望智能体能完全自主地处理开放域、定义模糊的复杂任务。
• 后果 ：智能体表现不稳定，频繁失败，导致项目失去信心。
• 应对策略 ： 拥抱“光谱式控制”（ Spectrum of Control / Blended Initiative ） 。认识到完全自主只是一个理想端点。在实际设计中，应该根据任务的风险、复杂度和价值，灵活调整人的参与程度。可以设计多种交互模式：
  • 全自动 ：对低风险、高重复性任务（如代码格式化、生成API文档草稿）。
  • 建议-批准 ：智能体提出多个方案，由人选择或修改后批准（ Human-in-the-Loop Approval Framework ）。
  • 协同编辑 ：智能体作为“副驾驶”，实时提供建议和补全。
  • 纯手动 ：对于高创意或高风险的决策。

将智能体定位为“增强人类能力”的工具，而不是替代品，是项目成功的关键心态调整。

6. 从模式到实践：构建你自己的智能体工具箱

awesome-agentic-patterns 项目本身是一个宝库，但它的价值在于被应用。最后，我想分享几个将模式落地到具体技术栈时的实用思路。

首先，不要试图从头造轮子 。许多模式已经有优秀的开源实现或可以依托现有框架快速搭建。例如：

• 编排与控制 ：可以基于LangGraph、AutoGen、CrewAI来构建 Plan-Then-Execute 、 Sub-Agent Spawning 等工作流。
• 工具使用 ：利用LangChain/Tavily的丰富工具集成，或遵循MCP（Model Context Protocol）标准来构建你自己的工具。
• 评估与测试 ：利用RAGAS、TruLens、Phoenix等框架来搭建评估流水线。

其次，建立你的“模式决策日志” 。当你为一个新功能选择某个模式时，记录下：

• 决策背景 ：你要解决的具体问题是什么？
• 候选模式 ：考虑了哪几个模式？为什么最终选择这个？
• 预期收益与风险 ：希望它带来什么改进？可能引入什么新复杂度？
• 实施后的回顾 ：实际效果如何？有哪些偏差？下次会怎么调整？

这份日志将成为你们团队极其宝贵的知识资产，能极大加速后续项目的设计决策过程。

最后，保持开放与贡献的心态 。智能体工程是一个飞速发展的领域，最佳实践每天都在更新。如果你在实践中摸索出了一套有效的模式，或者对现有模式有新的见解和变体，强烈建议你回馈给社区。就像这个项目本身源于一篇“What Sourcegraph learned”的博客，你的经验也可能成为照亮他人道路的一盏灯。真正的“Awesome”之处，不在于收集了多少链接，而在于社区共同推动整个领域向前发展的那份协作与分享。