← AiAgent
主流 Agent 框架
本质
所有框架都是把 Agent.md 里的概念封装成库，让你少写重复代码。
自己写：定义工具 + 手写 while 循环 + 处理工具结果
用框架：agent.invoke("帮我查合同风险") ← 内部帮你做了一样的事
理解了 Agent.md 的概念，所有框架上手都很快。
各框架重点封装的概念
| 框架 | 语言 | 重点 |
|---|
| LangChain | Python/JS | 工具调用 + 记忆 + RAG（全包） |
| LlamaIndex | Python/JS | RAG / 文档问答（做到极致） |
| LangGraph | Python | 复杂工作流、状态管理 |
| CrewAI | Python | 多 Agent 角色协作 |
| Vercel AI SDK | JS/TS | 工具调用 + 流式输出，前端友好 |
| Mastra | JS/TS | LangGraph 的 JS 版 |
如何选
JS 开发者 → Vercel AI SDK（入门）→ Mastra（复杂工作流）
Python 开发者 → LangChain（入门）→ LangGraph（复杂工作流）
做文档问答/RAG → LlamaIndex
多 Agent 协作 → CrewAI
学习路径
原生 SDK（理解原理）→ 选一个框架 → 加 RAG → 复杂场景
框架到底帮你做了什么（完整清单）
判断标准：这件事不用框架就得自己写代码，用了框架就是一行配置或一个装饰器。
一、Agent 主循环 ★核心
| 能力 | 不用框架 | 用框架 |
|---|
| ReAct 循环 | 手写 while：调模型 → 判断 tool_calls → 执行 → 结果塞回 messages → 再调 | agent.invoke(...) |
| 最大轮次限制 | 自己计数、自己 break | max_iterations=10 |
| 死循环检测 | 自己比对历史动作是否重复 | 内置 |
| 工具报错处理 | try/except + 把错误信息喂回模型 | 内置，自动重试 |
| 超时控制 | 自己包 timeout | 配置项 |
| 中断/取消 | 自己管信号 | abortSignal |
| 能力 | 说明 |
|---|
| Schema 自动生成 | 从 Python 类型注解 / Zod / TS 类型自动生成 JSON Schema，不用手写 |
| 参数校验 | 模型传错类型自动拦截并让它重试 |
| 返回值序列化 | 对象/DataFrame 自动转成模型能读的文本 |
| 并行调用 | 模型一次返回 3 个工具调用，自动并发执行 |
| 工具选择策略 | 强制调用某工具 / 禁止调用 / 自动决定 |
| 内置工具箱 | 搜索、计算器、Python REPL、SQL、Shell、爬虫、文件读写、Gmail、Slack… |
| MCP 接入 | 直接挂载 MCP Server 的工具 |
| 人工确认 | 危险操作（删库、付款）先暂停等审批 |
三、记忆 / 上下文管理
| 能力 | 说明 |
|---|
| 对话历史 | 自动维护 messages 数组 |
| 超长截断 | 超出窗口自动裁剪最早的消息 |
| 摘要压缩 | 老对话自动总结成一段摘要，省 token |
| 长期记忆 | 存向量库，下次对话按语义召回 |
| 实体记忆 | 自动抽取"用户叫张三、住北京"这类事实 |
| 会话隔离 | 多用户 / 多线程 thread_id 隔离 |
| 持久化 | 存 Redis / Postgres / SQLite，重启不丢 |
四、RAG（LlamaIndex 最强）
整条链路都帮你做完：
| 环节 | 帮你做的 |
|---|
| 加载 | PDF / Word / Excel / PPT / HTML / Notion / 数据库，100+ 种 loader |
| 切块 | 按字符 / 句子 / 语义 / Markdown 标题层级切分 |
| 向量化 | 对接 OpenAI / BGE / 本地 embedding 模型，批量 + 缓存 |
| 存储 | 对接 Chroma / Milvus / Pinecone / PGVector，统一 API |
| 检索 | 向量检索 + 关键词 BM25 + 混合检索 |
| 重排 | Rerank 模型二次排序，提升精度 |
| 查询改写 | 把用户口语问题改写成更好的检索 query |
| 引用溯源 | 回答里标注来自哪个文档第几页 |
五、输出控制
| 能力 | 说明 |
|---|
| 结构化输出 | 定义 Pydantic / Zod Schema，保证吐出合法 JSON |
| 自动修复 | 模型输出格式错了，自动带着报错让它重来 |
| 流式输出 | token 逐字返回 |
| 流式工具事件 | 前端能实时看到"正在搜索…""正在读文件…" |
| 前端集成 | Vercel AI SDK 配 useChat hook，几行代码接完 |
六、工作流编排（LangGraph / Mastra）
| 能力 | 说明 |
|---|
| 状态机 | 定义节点 + 边 + 跳转条件，流程可控不靠模型瞎决定 |
| 分支 / 循环 / 并行 | 图结构表达复杂流程 |
| 检查点 Checkpoint | 每步存状态，崩了能从中间续跑 |
| 时间旅行 | 回退到任意历史状态重跑 |
| Human-in-the-loop | 关键节点暂停，等人工审批再继续 |
| 子图嵌套 | 复杂流程拆成模块复用 |
七、多 Agent（CrewAI / AutoGen）
| 能力 | 说明 |
|---|
| 角色定义 | 研究员 / 写手 / 审校，各自的 Prompt 和工具 |
| 任务分配 | 顺序执行 / 层级派发（Manager 分活） |
| Agent 通信 | 消息传递、结果交接 |
| 共享上下文 | 多个 Agent 看同一份工作区 |
八、可观测性 / 运维
| 能力 | 说明 |
|---|
| 调用链追踪 | 每一步 Prompt、返回、工具调用全记录（LangSmith / Langfuse） |
| Token 统计 | 每次调用花了多少钱 |
| 耗时分析 | 哪一步慢 |
| 评估测试 | 建测试集跑分，改 Prompt 后看指标有没有退步 |
| 日志回放 | 线上出问题能复现 |
九、模型抽象层
| 能力 | 说明 |
|---|
| 多厂商统一 | OpenAI / Claude / Gemini / 通义 / 本地 Ollama，一行切换 |
| 参数归一化 | 不同厂商的 temperature、tool 格式差异帮你抹平 |
| 失败降级 | 主模型挂了自动切备用模型 |
| 请求缓存 | 相同输入直接返回缓存，省钱 |
| 限流重试 | 429 自动退避重试 |
框架不会帮你做的（真正的核心竞争力）
| 事项 | 说明 |
|---|
| 任务怎么拆 | 这个业务该分几步、每步谁来做 |
| 需要哪些工具 | 领域里真正要调的 API / 数据库 |
| Prompt 怎么写 | 角色、约束、few-shot 示例 |
| 领域知识从哪来 | 法规、SOP、历史案例的整理和清洗 |
| 什么算做对了 | 评估标准、验收条件 |
| 出错怎么兜底 | 模型答错了业务上怎么办 |
结论：框架解决"怎么跑起来"，你要解决"跑得对不对"。
