原生大模型 Agent 应用：产品设计、开发理论与实践教程

本章目标：理解为什么 2026 年 AI 产品正在从“会聊天”走向“能行动”，以及什么场景真的需要 Agent。

过去的 AI 产品大多是 Chatbot：用户提问，模型回答。它能生成内容、解释概念、写代码片段，但它不会主动拆任务、调用工具、等待反馈、继续修正。Agent 的关键变化是：模型不只是回答，而是在循环中持续做决策。

一句话定义：Agent 是一个带工具、记忆和反馈循环的 LLM 系统。它接收目标，拆解步骤，调用外部工具，读取环境反馈，再决定下一步。

时代背景：模型推理能力提升、Function Calling 成熟、MCP/A2A 等协议标准化、LangGraph/OpenAI Agents SDK 等框架完善，让 Agent 从演示进入可落地阶段。

不要滥用 Agent：能一次 LLM 调用解决的，不要做 Agent；能用固定 Workflow 解决的，不要让模型自由规划；只有任务步骤不可预测、需要根据环境反馈调整时，Agent 才值得上。

实战练习：把你自己的一个业务任务分成三类：1）单次问答；2）固定工作流；3）需要 Agent。比如“总结一篇文章”通常是单次问答，“抓取数据后写日报”是 Workflow，“修复未知 bug 并跑测试”才是 Agent。

Workflow 与 Agent 的区别：Workflow 是 LLM 和工具沿预定义代码路径执行，步骤固定、可预测、容易审计；Agent 则由 LLM 动态决定流程和工具使用，适合开放问题，但成本和不确定性更高。

Agent 的基本循环：用户目标 → Agent 规划 → 工具调用 → 环境反馈 → 调整计划 → 再次调用工具 → 完成或请求人类反馈。

增强型 LLM 的三件套：检索、工具、记忆。检索让模型看到外部知识；工具让模型改变外部世界；记忆让模型跨会话保留长期偏好和任务状态。

核心能力边界：Agent 不是“自动万能员工”。它依赖工具质量、上下文质量、反馈质量和停止条件。没有好工具的 Agent，只是一个更贵的聊天机器人。

最小 Agent 架构：System Prompt 定义角色和约束；Tool Schema 定义可执行能力；Loop 控制最大轮数；State 保存中间结果；Evaluator 判断是否完成。

代码练习：写一个伪代码循环：while not done and step < max_turns: ask_llm_for_action(); execute_tool(); append_observation();。重点不是框架，而是理解 Agent Loop。

1. Prompt Chaining：把任务拆成顺序步骤，每一步只做一件事。适合“先生成大纲，再写正文，再检查格式”的确定性流程。优点是稳定，缺点是慢。

2. Routing：先分类，再把任务交给不同模型、提示词或工具。比如简单客服走小模型，复杂退款走强模型；代码问题走 coding agent，营销问题走 copy agent。

3. Parallelization：并行执行多个子任务，最后合并结果。适合资料搜集、候选方案生成、多模型投票。核心收益是降低总耗时和提高覆盖面。

4. Orchestrator-Worker：由一个编排器动态拆任务，再分配给多个 worker。适合复杂编码、研究报告、SEO 批量生产。缺点是 token 消耗大，协调成本可能占 15%-45%。

5. Evaluator-Optimizer：一个模型生成，一个模型审查，再循环优化。适合代码审查、翻译润色、合规检查、复杂搜索。前提是你有清晰评估标准。

选型口诀：步骤固定用 Prompt Chain；输入类型多用 Routing；子任务独立用 Parallel；任务不可预判用 Orchestrator；质量可评分用 Evaluator。

Supervisor / Orchestrator-Worker：一个中央 Agent 分发任务给多个 worker，再聚合结果。这是企业部署里最常见的模式，控制性强、易审计，但中央节点可能成为瓶颈。

Chain / Pipeline：多个 Agent 串行处理，每个 Agent 负责一个固定阶段。适合内容生产、审核流程、数据清洗等确定性场景。

Flat / Peer-to-Peer / Mesh：多个平等 Agent 直接互动、辩论、投票。适合多视角决策，但调试和成本控制更难。

Dynamic / Adaptive：系统根据任务动态选择 Agent、模型和拓扑。这是前沿方向，但生产复杂度高，早期项目不要一开始就做。

Handoff / Swarm：控制权从一个 Agent 转给另一个 Agent。客服、销售、技术支持等多角色流程很适合这种模式。

Consensus / Ensemble：多个 Agent 独立处理同一输入，再投票或加权聚合。适合高风险判断、交易信号、事实核验。

决策树：任务是否固定？固定用 Pipeline；不固定但要中央控制，用 Orchestrator；需要多视角，用 Mesh/Debate；需要角色转交，用 Handoff；需要稳定结论，用 Consensus。

Function Calling 的本质：LLM 不是真的执行函数，而是生成结构化调用意图，比如 {"function":"get_weather","args":{"city":"北京"}}，由外部系统执行，再把结果返回模型。

工具设计比提示词更重要：工具名、参数名、描述、返回结构、错误信号都会直接影响 Agent 表现。一个描述不清的工具，会让再强的模型也频繁调用错误。

ACI 原则：Agent-Computer Interface 要像人机界面一样设计。给模型看的工具文档，要有主动语态、前置条件、边界示例、输入格式和副作用说明。

MCP 解决什么：过去是 N 个 Agent × M 个工具，需要大量适配；MCP 把它变成标准协议，工具通过 MCP Server 暴露 Tools、Resources、Prompts、Sampling 等能力。

MCP 架构：Host（Claude Desktop、Cursor、IDE）通过 MCP Client 连接 MCP Server；Server 再连接数据库、文件系统、外部 API。传输层通常是 stdio 或 HTTP+SSE，消息格式是 JSON-RPC 2.0。

工具设计 Checklist：参数是否无歧义？结果是否结构化？失败时是否返回可恢复错误？是否限制危险操作？是否有 50+ 输入样例测试？

为什么需要记忆：LLM 天生无状态；上下文窗口有限；长上下文成本高；模型会受 Lost in the Middle 影响。记忆系统的目标不是把所有历史塞进 prompt，而是只取当前任务最相关的信息。

三类记忆：工作记忆保存当前任务状态；情节记忆保存过去事件和交互；语义记忆保存长期偏好、事实和知识。生产系统通常三类都需要。

提取-存储-检索循环：每次对话后，用小模型提取稳定事实和偏好；写入向量库或结构化数据库；下次任务开始时根据当前 query 检索 Top-K 相关记忆注入 prompt。

示例代码：extract_memories(conversation) 提取事实；store_memories(user_id, memories) 存储到 Chroma/Qdrant；retrieve_relevant_memories(user_id, query, top_k=5) 检索相关记忆。

Mem0 类方案：Mem0 自动做记忆提取、更新、搜索和冲突处理，适合快速构建个人助理、客服和长期协作 Agent。

最佳实践：记忆必须有 user_id 隔离；旧事实要能更新和删除；每次只注入 3-5 条；敏感信息不能进入共享索引；记忆块用 明确包裹。

安全三层栈：Guardrails 做实时拦截；Evaluation 做离线质量验证；Observability 做线上追踪和告警。三者缺一不可。

Input Guardrail：在 Agent 执行前检查输入是否越权、危险、含敏感信息或不属于当前业务范围。高风险场景下要先阻塞检查，避免浪费 token 和触发工具。

Output Guardrail：在结果返回用户前检查 PII、违规内容、幻觉、危险建议、格式错误。可以用小模型或规则引擎做第一层过滤。

Tool Guardrail：每次工具调用前后检查权限、参数范围和副作用。比如删除文件、发消息、付款、部署生产环境，都应有人类确认或强约束。

循环与失控防护：设置 max_turn、timeout、per-session 成本预算、指数退避和熔断器。Agent 卡住时，最危险的不是失败，而是一直花钱重试。

生产建议：低成本小模型做常规护栏；强模型只处理复杂判断；所有工具调用写 trace；外部写操作默认需要确认；关键业务有人工抽检样本。

三种协作模式：Handoff 是控制权转移；Orchestrator 是中央调度；Network 是无中心协作。不要把所有多 Agent 都做成复杂网络，大多数生产场景 Orchestrator 更稳。

Handoff：当前 Agent 判断自己不适合继续处理，把上下文交给另一个 Agent。比如售前 Agent 交给技术 Agent，技术 Agent 再交给部署 Agent。

Agents-as-Tools：编排器把子 Agent 当作工具调用。优点是中央视角完整、容易调试；缺点是编排器上下文压力大。

A2A 协议：Agent-to-Agent 用于 Agent 间水平协调，与 MCP 的 Agent-to-Tool 垂直集成互补。未来的标准栈很可能是 MCP 连接工具，A2A 连接 Agent。

什么时候需要 Multi-Agent：任务确实需要多角色专业化、并行搜索、独立审查或权限隔离时才需要。否则单 Agent + 好工具 + 好状态管理更便宜。

设计练习：为“自动生产一篇 SEO 文章”设计三个 Agent：Research、Writer、Reviewer。再判断它应该是 Pipeline、Orchestrator 还是 Handoff。

项目目标：构建一个三阶段内容生产管道：Research Agent 研究主题，Writer Agent 写草稿，Reviewer Agent 审校质量并输出最终版本。

安装：pip install openai-agents pydantic，并配置 OPENAI_API_KEY。生产环境不要把 key 写进代码，使用环境变量或密钥管理。

Research Agent：输入主题，输出结构化研究发现，包括目标读者、搜索意图、关键论点、参考资料、风险点。返回格式建议用 Pydantic Schema。

Writer Agent：接收研究结果，生成正文草稿。提示词里明确风格、结构、字数、禁止编造数据、必须保留不确定性。

Reviewer Agent：检查事实一致性、结构完整性、SEO 标题、内部链接机会、是否有过度承诺。通过 Evaluator-Optimizer 循环让 Writer 修订。

成本估算：一篇文章约 7k 输入 + 3.4k 输出 token，低成本模型约 $0.003 级别；每天 1000 篇约 $3 级别。真实成本取决于模型和上下文长度。

扩展任务：给每个 Agent 增加 trace_id，把每一步输入、输出、成本和耗时写入 JSONL，方便后续评估和回放。

为什么用 LangGraph：当你的 Agent 有复杂状态、条件分支、循环、checkpoint 和恢复需求时，显式状态图比黑盒循环更稳。

项目目标：构建一个邮件处理 Agent：读取邮件 → 判断类型 → 调用工具归档、创建任务或生成回复 → 保留 thread_id 状态。

安装：pip install langgraph langchain-openai pydantic，并设置 OPENAI_API_KEY。

工具定义：archive_email、create_task、draft_reply。每个工具返回结构化 JSON，包括 ok、message、next_action，失败时返回可恢复错误。

StateGraph：定义 state 包含 messages、email_type、tool_results、final_response。email_agent 节点做决策，email_tools 节点执行工具，条件边判断是否继续循环。

Checkpoint：用 MemorySaver 或 PostgresSaver 保存状态。生产环境推荐 PostgresSaver，因为进程重启后仍可恢复。

LangGraph vs OpenAI Agents SDK：LangGraph 适合复杂状态机；OpenAI Agents SDK 适合快速原型和标准 Agent Loop。不要争框架优劣，要按任务复杂度选。

四层评估：基础正确性：任务是否完成、工具调用是否正确；流程质量：步数是否合理、是否循环；输出质量：答案是否清晰、准确、可用；安全合规：是否泄露敏感信息或越权。

常见 Benchmark：SWE-bench Verified 测编码 Agent；GAIA 测多步推理和工具使用；WebArena 测网页任务；AgentBench 测多环境能力；BFCL 测函数调用。

LLM-as-Judge：用另一个模型对输出打分，但必须提供评分标准、反例和少量人工校准。不要盲信 judge 模型，它也会偏。

可观测工具：LangSmith 适合 LangChain/LangGraph 生态；Phoenix 适合开源 LLM tracing；OpenTelemetry 适合跨服务标准化 trace。

必须记录的字段：trace_id、agent_name、model、prompt_version、tool_name、tool_args、tool_result、latency_ms、input_tokens、output_tokens、cost、error_type。

上线前测试集：至少准备 30 个真实任务样本，包括正常样本、边界样本、恶意输入、工具失败和超时样本。没有测试集，就不要声称生产可用。

成本控制：Multi-Agent 系统 token 消耗通常是普通 chat 的 3-15 倍。核心手段是模型分层、Prompt Caching、Semantic Caching、Top-K 记忆、硬预算和异常熔断。

延迟优化：能并行就 fan-out；路由和 guardrail 用小模型；长任务用流式输出；用户可见部分先返回进度，后台继续执行。

错误恢复：工具失败要可重试；Agent 循环要有限制；网络错误要指数退避；关键状态要 checkpoint；外部写操作要幂等。

状态管理：简单 Agent 可以无状态 + 外部数据库；复杂 Agent 用 LangGraph checkpoint；长期用户偏好用语义记忆；任务状态用结构化表，不要全塞 prompt。

生产 Checklist：成本预算、超时、max_turn、guardrail、trace、checkpoint、人工确认、测试集、回滚方案、日志脱敏、密钥隔离。

趋势：MCP 会成为 Agent 连接工具的 USB-C；A2A 会推动 Agent 间协作标准化；动态拓扑会逐步成熟。但最重要的原则不会变：从最简单的方案开始，只在必要时增加复杂度。

最终作业：设计一个你自己的生产级 Agent，包括目标、工具、状态、记忆、护栏、评估集、成本预算和部署方式。能写清楚这些，比会调用某个框架更重要。