AI智能体设计

核心理念

智能体并非魔法——它们是具有输入、输出、记忆、工具和决策逻辑的系统。请以构建生产级软件的严谨态度来设计它们。每个智能体都应有明确的目的、定义的边界以及显式的故障模式。

智能体设计原则

1. 行动前先澄清意图

当用户意图不明确时，智能体必须在执行任何不可逆操作之前提出澄清性问题。使用以下模式：

目标明确吗？如果不明确，提出一个聚焦的问题。
约束条件已知吗？（范围、输出格式、数据源）
成功的标准是什么？

2. 规范先行，代码后写

在编写智能体逻辑之前，先生成一个规范或任务列表文件：

定义智能体的角色和职责
列出其需要访问的所有工具
定义输入/输出合约
识别故障模式及回退行为
然后编写代码

3. 单一职责

每个智能体应专注于做好一件事。优先选择一组专业化智能体，而非通用型智能体。

编排模式

模式	使用场景	描述
序列式	线性管道	智能体按固定顺序串联（草稿 → 审核 → 发布）
监督式	复杂多模块任务	主智能体将任务路由给专门的工作智能体
ReAct	自主问题解决	结合推理（思考）与行动（工具使用）
群聊式	协作任务	多智能体通信，辅以人工监督
DAG	有状态工作流	有向无环图，适用于循环、有状态的编排

框架选择指南

框架	最适合	状态
LangGraph	复杂有状态智能体、循环工作流、多智能体编排、生产级	✅ 活跃 — 2025年5月正式发布
LangChain	简单RAG管道、线性工作流、快速原型	✅ 活跃 — 用于RAG，不用于智能体
CrewAI	基于角色的多智能体团队（"经理"、"研究员"、"作家"）	✅ 活跃
Microsoft Agent Framework	Azure生态中的企业级智能体 — 取代AutoGen + Semantic Kernel	✅ 活跃 — 2025年10月公开预览，目标2026年Q1正式发布
AutoGen	遗留框架 — 仍可工作但无新功能	⚠️ 自2025年10月起处于维护模式
自定义 (MCP)	轻量级、可移植、可互操作的智能体工具，基于开放标准	✅ 活跃

LangChain vs LangGraph — 如何选择

LangChain团队现在明确建议如下划分：

LangGraph → 用于智能体：有状态、循环、多智能体、长时间运行的任务
LangChain → 用于RAG和线性管道：简单的文档问答、逐步转换

LangGraph构建于LangChain之上——你可以同时使用两者，从LangChain开始，当需要更多控制时切换到LangGraph。

RAG管道设计

标准RAG流程

用户查询 → 嵌入查询 → 向量搜索 → 检索块 → 增强提示 → LLM → 响应

分块策略（2026年最佳实践）

使用语义分块——按意义分割，而非字符数
块大小：256–512 tokens用于精确检索；1024 tokens用于叙事内容
始终包含元数据：来源、页码、章节、时间戳

混合搜索（推荐）

结合密集向量（语义）与稀疏向量（关键词）以获得最佳召回率：

最终得分 = α × 密集得分 + (1 - α) × 稀疏得分

向量数据库选择

数据库	最适合
pgvector	现有PostgreSQL栈、简单用例
Pinecone	托管服务、生产规模、运维极简
Weaviate	多模态、内置混合搜索
Milvus	高性能、自托管、大规模
Chroma	本地开发、原型设计

智能体记忆架构

类型	描述	实现
上下文内	当前对话窗口	聊天历史数组
外部短期	会话范围的记忆	Redis / 内存存储
外部长期	跨会话持久化	向量数据库 + 元数据
情景记忆	总结过去交互	总结链 → 向量存储

上下文衰减警告： 长上下文窗口会随时间推移降低智能体质量。每N轮对话执行一次总结步骤以保持相关性。

工具调用与函数调用

工具定义模式

每个工具都需要：

name: descriptive_tool_name
description: 何时使用此工具及其功能（请明确说明）
parameters:
  - name: param_name
    type: string
    description: 此参数期望的内容
    required: true

工具使用最佳实践

工具应尽可能幂等
始终在将工具输出传递给下一步之前进行验证
为外部工具调用实现超时和重试机制
记录所有工具调用以供调试

智能体通信模式

意图澄清协议

当智能体收到模糊请求时：

识别歧义——具体哪里不清楚？
提出一个问题——最重要的问题，而不是全部
提供一个默认假设——"除非你另有说明，否则我将假定X"
在不可逆操作前确认——在删除、发布或发送之前始终询问

进度报告

对于长时间运行的任务，智能体应报告：

[步骤 1/4] 正在获取文档... ✓
[步骤 2/4] 正在分块和嵌入... ✓
[步骤 3/4] 正在查询向量存储...

错误通信

✗ 工具失败: [tool_name]
原因: [具体错误]
回退方案: [我正在采取的替代措施]

MCP（模型上下文协议）

MCP是用于将智能体连接到外部工具和数据源的开放标准。在构建可移植、可互操作的智能体工具时使用它。

MCP服务器结构

my-mcp-server/
├── server.py (或 index.ts)
├── tools/
│   └── my_tool.py
└── README.md

何时使用MCP vs 直接集成

当工具需要在多个智能体/平台间复用时，使用MCP
对于项目特定、一次性的工具实现，使用直接集成

有关详细的MCP服务器实现指南，请参阅 mcp-builder 技能。

安全与保障

绝不允许智能体在未沙箱化的情况下执行任意代码
对所有LLM API调用实施速率限制
在将输入传递给工具之前进行验证和清理
记录所有智能体决策以便审计
实施护栏以防止失控的token成本或递归循环
使用系统提示注入防护——用清晰的分隔符将用户输入与系统指令分开

弹性智能体设计（自愈）

智能体在生产中会失败。从一开始就为恢复而设计。

验证-重试循环（LoopAgent模式）

生成输出 → 验证输出 → 如果无效：反馈 + 重新生成
最大迭代次数：3  ← 断路器，防止无限循环

计划–验证–执行–观察–重新计划

计划：   生成计划，在行动前检查可行性
执行：   采取行动
观察：   成功了吗？检查输出，运行测试
重新计划：如果观察显示失败 → 调整并重试
停止：   如果达到最大重试次数 → 明确报告失败，请求帮助

智能体回退层级

主要方法失败 → 尝试替代方法
替代方法失败    → 向开发者请求澄清
未获得澄清      → 安全的默认操作或优雅停止

输出在呈现前进行验证

在呈现生成的代码之前运行测试/静态分析
验证输出格式是否符合要求
使用单独的验证器步骤（不同的模型或提示）检查生成器的输出
绝不要将未经验证的输出呈现为完成状态

智能体断路器

设置硬性限制以防止失控行为：

每项任务最大工具调用次数（例如 10）
每次会话最大token消耗
每个失败步骤最大重试次数（例如 3）
每次工具调用超时时间

有关完整的韧性理念和代码模式，请参阅 self-healing-mindset 技能。

在你喜欢的 AI 中提问

文档