Agent产品从零搭建：核心架构、工具设计与工程实践

1. 先想清楚Agent 产品到底在解决什么问题1.1 从“能聊”到“能干活”的分界线很多人第一次接触 Agent 这个概念是从 Chat 类产品开始的。你问它一句它答你一句体验很顺滑但用久了会发现一个尴尬的事实它什么都懂一点但什么都干不成。你让它帮你订个会议室它给你写一段“如何订会议室”的教程你让它查一下项目进度它给你编一段看起来很合理的假数据。这不是模型不行而是产品形态不对。Agent 产品和纯 Chat 产品的本质区别在于前者有行动能力。Chat 是“你问我答”Agent 是“你说目标我来拆解、执行、交付”。中间差的不是模型智商而是一整套围绕目标运转的机制任务怎么拆、工具怎么调、状态怎么存、失败怎么重试、结果怎么验证。这些东西加起来才构成一个 Agent 产品的骨架。我见过不少团队一上来就堆模型参数觉得模型够强 Agent 就够聪明。实际做下来会发现模型只是发动机真正决定这辆车能不能上路的是底盘、传动和刹车。一个 7B 的模型配上好的 workflow 编排和工具设计在垂直场景里能跑赢一个 70B 模型裸奔。这个结论我在多个项目里反复验证过不是理论推演。1.2 三类典型场景决定了你的产品形态Agent 产品不是一种东西它至少分三类每类的设计重心完全不同。第一类是信息处理型典型任务是检索、总结、比对、生成报告。这类 Agent 的核心是上下文管理怎么把海量信息塞进有限的 token 窗口怎么保证召回的相关性怎么在长对话里不丢失关键约束。热搜词里提到的“LLM 的 token 三个点key 我是谁、query 我在找什么、value 我能提供什么”说的就是这个层面的问题。信息处理型 Agent 对工具调用的要求不高但对 prompt 工程和检索策略要求极高。第二类是流程执行型典型任务是操作软件、填写表单、触发审批、跨系统搬运数据。这类 Agent 的核心是 workflow 编排和工具可靠性。它不需要模型有多强的推理能力但需要每一步都稳定可复现需要失败时有明确的回滚路径。热搜里“workflow 编排”“AI workflow”这些词频繁出现反映的就是这类需求的爆发。第三类是决策辅助型典型任务是风险评估、方案推荐、异常检测。这类 Agent 的核心是领域知识的注入和推理链的可解释性。它不能只给结论还要给出依据让人类能审核、能追责。热搜里“LLM 驱动的公立医院债务风险智能预警”就是一个典型例子这类场景对准确率和可解释性的要求远高于对响应速度的要求。你在动手之前先把自己的产品归到这三类里的某一类或者明确它是哪几类的组合。分类不清楚后面所有的技术选型都是瞎猜。1.3 一个反直觉的结论先做窄再做深新手最容易犯的错误是贪大求全。一上来就想做一个“什么都能干”的通用 Agent结果每个场景都做到 60 分没有一个场景能到 90 分用户用一次就不想用第二次。我的建议是第一个版本只做一个场景而且要把这个场景做到用户愿意每天用。哪怕这个场景只是“帮我把会议录音转成结构化纪要并同步到项目管理工具”只要做得足够稳、足够准它就有价值。等你在这个窄场景里跑通了完整的技术链路——意图识别、任务拆解、工具调用、状态管理、异常处理、结果交付——你再横向扩展成本会低得多。窄场景还有一个好处你能快速拿到真实反馈。通用 Agent 的反馈是模糊的“感觉还行”“有时候不准”。窄场景的反馈是具体的“第三步调用日历 API 的时候时区错了”“生成的纪要里把张三的发言安到了李四头上”。这种具体反馈才能驱动迭代。2. 核心架构拆解一个 Agent 产品的最小闭环2.1 四层结构接入层、编排层、能力层、数据层不管你的 Agent 产品最终长什么样它的骨架都可以拆成四层。我用一个实际项目里的架构来举例说明。接入层负责和用户交互可能是 Chat 界面、可能是 API、可能是嵌入到现有系统里的一个按钮。这一层的关键决策是用户输入是纯文本还是带结构化参数如果是纯文本你需要一个意图识别模块把自然语言转成结构化指令。如果是带参数的你可以跳过意图识别直接进入编排。很多团队在这一层偷懒结果后面所有模块都在为输入的模糊性买单。编排层是 Agent 的大脑负责决定“下一步做什么”。它可以是基于规则的 workflow 引擎也可以是基于 LLM 的动态规划器还可以是两者的混合。热搜里“MCP 协议”之所以火就是因为它试图在编排层和工具层之间定义一个标准接口让编排逻辑和具体工具解耦。这个思路是对的但 MCP 不是银弹后面我会专门讲它的适用边界。能力层是 Agent 的手和脚包括各种工具、API、数据库操作、文件处理。这一层的设计原则是每个能力单元必须幂等、可观测、可回滚。幂等意味着同一个操作执行两次和执行一次的结果一样这对重试机制至关重要。可观测意味着每次调用都有日志、有耗时、有输入输出记录。可回滚意味着操作失败时能恢复到之前的状态不会留下脏数据。数据层包括短期记忆和长期知识。短期记忆是当前会话的上下文长期知识是向量库、图数据库、关系型数据库里的领域知识。热搜里“LLM wiki 知识库”反映的就是长期知识管理的需求。这一层的关键是检索策略什么时候查知识库、查多少条、怎么排序、怎么和当前上下文融合。2.2 编排层选型规则、LLM 还是混合这是 Agent 设计里最核心的一个决策我把它单独拎出来讲。纯规则编排就是用 if-else 和状态机来定义流程。优点是稳定、可预测、调试方便。缺点是僵硬用户稍微换个说法就匹配不上。适合场景固定、输入格式可控的场景比如“用户点击按钮触发一个固定流程”。纯 LLM 编排就是把所有工具描述和当前状态塞给模型让模型决定下一步调哪个工具。优点是灵活能处理开放式任务。缺点是不稳定同一个输入两次运行可能走不同的路径而且 token 消耗大、延迟高。热搜里“AI Agent 怎么扛并发”这个问题在纯 LLM 编排下会变得非常棘手因为每次决策都要调模型并发一上来成本和延迟都爆炸。混合编排是我实际项目里用得最多的方案。具体做法是用规则引擎处理高频、固定的主流程用 LLM 处理分支判断和异常情况。比如一个报销 Agent主流程是“收集票据→识别金额→匹配预算科目→提交审批”这四步用规则串起来。但“这张发票属于哪个科目”这个判断交给 LLM因为科目分类需要理解发票内容。这样既保证了主流程的稳定性又利用了 LLM 的语义理解能力。混合编排的另一个好处是降级策略好做。当 LLM 调用超时或失败时可以降级到规则兜底而不是整个流程卡死。2.3 工具设计MCP 能解决什么不能解决什么MCP 最近热度很高热搜里出现了“MCP 协议”“Playwright MCP”“Chrome DevTools MCP”“Unity MCP”等一堆相关词。我需要说几句真话。MCP 解决的核心问题是工具接口的标准化。在没有 MCP 之前你每接一个工具就要写一套适配代码工具一多维护成本指数上升。MCP 定义了一套描述工具能力、调用方式、参数格式的协议让编排层可以用统一的方式发现和调用工具。这个价值是真实的。但 MCP 不能解决的是工具本身的可靠性。一个 API 该超时还是超时该返回脏数据还是返回脏数据。MCP 只是让调用方式统一了不保证调用结果正确。我见过团队以为接了 MCP 就万事大吉结果工具返回的字段类型和文档不一致整个流程崩掉。所以工具接入之后契约测试是必须做的每个工具都要有独立的测试用例验证正常输入、边界输入、异常输入下的行为。另外MCP 目前更适合开发阶段的工具集成在生产环境的高并发场景下MCP 的发现机制和序列化开销需要额外评估。如果你的 Agent 每秒要调几百次工具直接走内部 RPC 可能比走 MCP 更合适。这不是说 MCP 不好而是说工具选型要看场景。3. 从零搭建一个可运行 Agent 的实操路径3.1 第一步定义任务边界和成功标准动手写代码之前先拿一张纸把下面三个问题写清楚。这个 Agent 要完成什么任务用一句话描述不能有“等等”“之类”这种模糊词。比如“把用户上传的 PDF 合同里的关键条款提取出来生成结构化 JSON”。什么算成功定义可量化的指标。比如“关键条款提取准确率大于 95%”“单份合同处理时间小于 30 秒”“JSON 格式校验通过率 100%”。没有成功标准的 Agent 没法迭代因为你不知道改动是变好了还是变坏了。什么算失败定义失败模式和兜底策略。比如“PDF 解析失败时返回错误码并通知人工”“条款缺失时标记为待确认而不是编造”。失败路径的设计往往比成功路径更重要因为用户对错误的容忍度远低于对功能缺失的容忍度。这一步看起来简单但我见过太多团队跳过它直接开始写 prompt结果做到一半发现大家对“成功”的定义都不一样。3.2 第二步搭建最小可运行链路不要一上来就搞复杂的架构。先用最笨的办法把链路跑通。我的做法通常是写一个 Python 脚本硬编码一个任务手动调用一次 LLM手动调一次工具把结果打印出来。这个脚本可能只有 50 行但它验证了最核心的假设模型能不能理解这个任务工具能不能返回需要的数据两者的输出能不能拼在一起。举个例子假设你要做一个“根据自然语言查询数据库”的 Agent。最小链路就是import openai def query_db(natural_language): # 第一步让模型把自然语言转成 SQL prompt f把下面的问题转成 SQL 查询语句只输出 SQL{natural_language} sql call_llm(prompt) # 第二步执行 SQL result execute_sql(sql) # 第三步让模型把结果转成自然语言 answer_prompt f根据查询结果回答用户问题。问题{natural_language}结果{result} answer call_llm(answer_prompt) return answer这个链路很粗糙没有错误处理没有安全检查没有上下文管理。但它能跑。跑通之后你才知道瓶颈在哪里是 SQL 生成不准还是数据库返回太慢还是结果转述丢失了信息。先跑通再优化这个顺序不能反。3.3 第三步加入状态管理和错误处理最小链路跑通后第一个要补的是状态管理。Agent 执行任务不是一次性的它需要记住“我已经做了什么”“当前在哪一步”“下一步该做什么”。最简单的状态管理就是一个字典state { task: 查询上个月销售额, steps: [], current_step: 0, context: {}, status: running }每执行一步就往steps里追加一条记录包含步骤名称、输入、输出、耗时、是否成功。这个记录既是调试依据也是失败重试的依据。错误处理要区分三类可重试错误网络超时、限流、不可重试错误参数错误、权限不足、未知错误。可重试错误用指数退避重试不可重试错误直接返回用户并给出明确提示未知错误记录完整上下文后兜底。这里有一个实操心得重试必须幂等。如果你的工具调用不是幂等的重试会导致重复下单、重复扣款这种严重问题。解决办法是在工具层加一个幂等键同一个键的重复请求只执行一次。3.4 第四步接入真实工具和知识库到了这一步你才需要认真考虑工具接入方式。如果工具数量少于 5 个直接写适配代码就行没必要上 MCP。如果工具数量超过 10 个或者你需要动态发现工具MCP 的价值就体现出来了。知识库的接入是另一个关键点。热搜里“LLM wiki 知识库”反映的是把领域知识结构化管理的需求。我的经验是不要把所有知识都塞进向量库。结构化程度高的知识比如产品参数、价格表放关系型数据库用 SQL 查更准。半结构化的知识比如文档、FAQ放向量库用语义检索。完全非结构化的知识比如聊天记录先做摘要再入库否则检索噪音太大。检索策略上我通常用混合检索先用关键词召回一批再用向量检索召回一批然后合并去重、重排序。纯向量检索在专有名词和数字上容易翻车加上关键词召回能显著提升准确率。4. 踩坑实录那些文档里不会写的问题4.1 上下文窗口不是越大越好很多人觉得模型支持 128K 上下文就把所有历史对话和知识库内容都塞进去。实际跑下来会发现两个问题一是成本飙升二是准确率反而下降。模型在超长上下文里会“迷失”关键信息被淹没在噪音里。我的做法是分层上下文管理。当前轮次的用户输入和最近三轮对话放在最前面确保模型优先关注。任务相关的知识库片段放在中间用明确的分隔符标记。历史摘要放在最后只保留和当前任务相关的部分。这样既控制了 token 消耗又保证了关键信息的权重。具体控制多少 token我的经验值是系统提示词不超过 500 token知识库片段不超过 2000 token历史摘要不超过 500 token留给模型输出的空间至少 1000 token。剩下的才是用户输入和模型推理的空间。这个比例不是固定的但原则是永远给输出留足空间否则模型会截断回答。4.2 工具调用的“幻觉参数”问题这是我在多个项目里反复遇到的问题模型在调用工具时会编造不存在的参数或者给参数填上看起来合理但实际错误的值。比如一个查询天气的工具定义参数是city和date。模型可能会返回{city: 北京, date: 明天, unit: celsius}其中unit是工具不支持的参数。或者日期格式返回“明天”而不是“2025-01-15”。解决办法有两个层面。第一层是 prompt 层面在工具描述里明确写清楚参数格式、取值范围、必填项并给出正例和反例。第二层是代码层面在工具调用前加一个参数校验层用 JSON Schema 校验参数不合法就返回错误让模型重新生成。不要信任模型的输出永远校验。4.3 并发下的状态污染热搜里“AI Agent 怎么扛并发”这个问题我踩过最深的坑是状态污染。多个用户同时使用同一个 Agent 实例时如果状态存在全局变量里A 用户的任务会读到 B 用户的状态导致数据串台。解决办法很简单但容易被忽略每个会话必须有独立的 state 对象用 session_id 隔离。如果 Agent 是有状态的比如需要保持数据库连接用连接池而不是全局连接。如果 Agent 是无状态的那更好每次请求独立处理。还有一个隐蔽的并发问题是工具调用的速率限制。多个会话同时调用同一个外部 API很容易触发限流。解决办法是在工具层加一个令牌桶或漏桶限流器控制调用频率。这个限流器要是全局的不能每个会话一个否则限流没意义。4.4 评测集比 prompt 更重要我见过团队花一周时间调 prompt每次改完就手动试几个 case觉得“好像好了一点”。这种做法效率极低而且容易过拟合到那几个 case 上。正确的做法是先建评测集再调 prompt。评测集至少包含 50 个真实场景的输入和期望输出覆盖正常情况、边界情况、异常情况。每次改完 prompt跑一遍评测集看准确率、召回率、平均耗时这些指标的变化。只有指标提升了才认为改动有效。评测集的构建本身也有讲究。不要用模型生成评测集因为模型生成的 case 往往过于规整缺乏真实场景的多样性。最好从真实用户日志里采样人工标注期望输出。如果冷启动阶段没有日志找几个同事模拟真实使用场景把他们的输入记录下来。5. 上线之后监控、迭代和扩展5.1 必须监控的四个指标Agent 上线不是终点而是起点。没有监控的 Agent 就像没有仪表盘的飞机你不知道它什么时候会掉下来。任务完成率成功完成的任务占总任务的比例。这个指标下降说明某个环节出了问题。平均步骤数完成一个任务平均需要多少步。步骤数突然增加说明模型在“绕路”可能是工具描述不清楚或者知识库检索不准。工具调用失败率每个工具的失败次数占总调用次数的比例。某个工具失败率上升优先排查那个工具。用户干预率用户需要手动纠正或重新输入的比例。这个指标最能反映用户体验干预率高的环节就是优先优化的环节。这四个指标我通常做成一个简单的看板每天扫一眼。异常波动会触发告警然后去查日志定位原因。5.2 迭代的优先级排序拿到监控数据后怎么决定先优化什么我的排序原则是先修失败再提准确率最后优化速度。失败是硬伤用户遇到一次失败可能就流失了。准确率是体验问题用户能感知到但不一定立刻放弃。速度是锦上添花在失败和准确率没解决好之前优化速度的收益很低。具体到失败修复优先修高频失败和高影响失败。高频失败是发生次数多的高影响失败是发生在关键路径上的。两者取交集就是最该先修的。5.3 从单 Agent 到多 Agent 的扩展时机什么时候该从单 Agent 扩展到多 Agent我的判断标准是当单个 Agent 的职责超过三个明显不同的领域时。比如一个客服 Agent如果它同时要处理“查订单”“退换货”“投诉建议”三件事而且这三件事的工具集和知识库几乎没有重叠那就该拆成三个 Agent用一个路由层来分发。拆开之后每个 Agent 的 prompt 更聚焦工具集更小准确率会明显提升。但不要为了多 Agent 而多 Agent。如果两个领域的工具集高度重叠拆开反而增加协调成本。多 Agent 的通信开销、状态同步、错误传播都是额外的复杂度能单 Agent 解决的就单 Agent 解决。6. 一些关于工具和框架的真话6.1 框架选型别被热度带偏热搜里出现了“Agent 框架”“LLM 框架”“吴恩达 Agent 教程”这些词。我的建议是新手可以从框架入手但不要依赖框架。框架的价值是帮你快速跑通一个 demo让你理解 Agent 的基本概念。但框架的抽象层会掩盖很多细节当你想优化性能或排查问题时这些抽象层会成为障碍。我见过团队用框架搭了一个 Agent上线后发现延迟很高想优化却不知道从哪下手因为框架把 LLM 调用、工具调用、状态管理都封装了。我的做法是先用框架跑通概念验证然后用原生代码重写核心链路。重写的过程你会被迫理解每一个环节这对后续的优化和排障至关重要。6.2 模型选型不是越大越好“LLM 模型”“大模型 LLM”“Open LLM Leaderboard”这些热搜词反映了大家对模型选型的关注。我的经验是在 Agent 场景里模型的指令遵循能力比知识储备更重要。Agent 需要模型严格按照格式输出、严格按照工具描述调用、严格按照约束推理。一个知识面稍窄但指令遵循好的模型比一个知识面广但经常自由发挥的模型更适合 Agent。选型时重点看模型的 function calling 能力、JSON 输出稳定性、长上下文里的指令保持能力而不是只看 benchmark 分数。另外不同环节可以用不同模型。意图识别用一个小模型就够了复杂推理用大模型结果转述用中等模型。这样能在成本和效果之间取得平衡。6.3 安全边界Agent 能做什么不能做什么热搜里“Agent 安全”是一个值得认真对待的话题。Agent 有了行动能力就意味着它可能造成真实世界的损害。一个查天气的 Agent 出错最多是信息不准一个转账的 Agent 出错就是真金白银的损失。我的原则是涉及资金、权限、不可逆操作的任务Agent 只能做建议不能做执行。Agent 可以生成转账指令但最终确认必须由人来做。Agent 可以修改配置但修改前必须备份修改后必须验证。另一个原则是最小权限。Agent 调用的每个工具只给完成当前任务所需的最小权限。查询工具只给读权限写入工具只给特定表的写权限删除操作原则上不开放给 Agent。这些边界不是技术限制而是产品设计的选择。技术上行得通不代表产品上应该做。想清楚哪些事可以让 Agent 自主做哪些事必须有人把关这是 Agent 产品设计里最重要的决策之一。7. 我个人在实际操作中的体会做了几个 Agent 产品之后我最大的体会是Agent 产品的核心竞争力不在模型而在工程细节。模型能力是公开的你能用的模型别人也能用。但工具设计的可靠性、状态管理的严谨性、错误处理的完备性、评测体系的科学性这些是别人抄不走的。我见过太多团队把 80% 的精力花在选模型和调 prompt 上只留 20% 给工程结果产品上线后问题百出。另一个体会是慢就是快。第一个版本不要追求功能多追求链路完整。把“输入→理解→执行→输出→反馈”这个闭环跑通哪怕只支持一个任务也比做十个半成品强。闭环跑通之后加新任务就是复制粘贴加微调速度会快很多。最后一个建议多和真实用户聊。不要只看日志和指标去听用户怎么说。用户抱怨“它有时候听不懂我说话”背后可能是意图识别的问题也可能是用户表达习惯和你的 prompt 假设不匹配。这些信息只有聊才能拿到看数据是看不出来的。