我前前后后带团队搭过好几套所谓“AI 产品”最深的感受是用大模型接口做个聊天框那叫 Demo让这个系统能自主接单、查数据、调工具、做决策并且能稳定跑在业务线上才配叫 Agent。而这个从 Demo 到 Agent 平台的过程恰恰是大多数人卡住的地方。这篇文章我想用“造同事”这个视角把从 0 到 1 搭建 AI Agent 平台的完整路径讲透——它是什么、和 LLM / AI 模型有什么区别、该怎么设计、用什么技术栈落地、踩过哪些坑尽量让你看完就能动手。无论你是后端工程师、技术负责人还是刚入门 AI 应用开发的爱好者这篇都适用。我会用真实项目中沉淀下来的方案和代码片段说话不整虚的。1. AI Agent 到底是什么先搞清它和 LLM、普通 AI 模型的边界1.1 别再混为一谈Agent、LLM、AI 模型的三角关系热搜里有个高频问题“Agent 和 LLM、AI 模型有什么区别”这问题我在面试里几乎必问能答清楚的人真不多。很多人的理解是“Agent 就是接了大模型 API 的程序”这个认知太浅了会直接导致后面架构设计跑偏。简单说AI 模型是“大脑的神经细胞”LLM大语言模型是“经过训练的大脑”而 Agent 是“一个有手有脚、会自己想办法干活的完整的人”。用生活化类比就是——LLM 像一个知识渊博但只能坐在那里说话的学者你问他什么他答什么Agent 则像你招来的员工你给他一个目标他会自己拆解任务、查资料、调用系统、分析结果、调整方案最后把活干完交给你。举个具体例子你问 LLM “帮我查一下这个客户的上月账单并分析异常项”它只能告诉你“你需要先登录 CRM 和 billing 系统然后导出数据再对比……”——它知道方法但不会做。而一个接入了 CRM 和 billing 工具 API 的 Agent会自己去查询客户 ID、调账单接口、把数据拉回来后做比对分析最终输出一份带结论的报告。前者是“大脑”后者才是“员工”。从技术构成上看LLM 是 Agent 的核心推理引擎但 Agent 还包含规划Planning、记忆Memory、工具调用Tool Calling、行动反馈Action Observation这些模块。这也是为什么很多人用同一个 DeepSeek 或 GPT 模型有人只能做出聊天机器人有人却能做出自动化运维助手——差异不在模型而在模型外围那套工程体系。1.2 DeepSeek 属于哪一层为什么有模型不等于有 Agent热搜里有“deepseek 是属于哪个”这个问题答案是DeepSeek 是 LLM也就是大语言模型。它是一个“大脑”是你可以拿来即用的推理引擎。你可以基于 DeepSeek 去构建 Agent但 DeepSeek 本身不是一个开箱即用的 Agent。这个区分特别重要因为它决定了你的工作重心。如果你以为“接个 DeepSeek API 就拥有 Agent 了”那你做出来的东西最多算个智能问答机器人。真正的 Agent 平台是把模型当成可替换的“CPU”然后在 CPU 外面搭建主板、内存、硬盘、外设接口——也就是规划器、记忆库、工具层、权限控制和应用编排。所以在开始动手前先把自己的心态摆正你不是在“接模型”你是在“用人”。你会招聘一个员工选模型给他培训写 System Prompt给他发电脑和权限接工具 API让他记笔记Memory给他定工作流程编排与规划最后还要给他配主管评估与干预机制。只有把这一整套体系搭起来你才算真正在“造同事”。1.3 Agent 的“五件套”模型、规划、记忆、工具、行动我在设计和评审 Agent 架构时习惯用“五件套”来拆解缺一样都算不上完整的 Agent第一是模型Model负责理解和生成是推理的核心。它解决的是“听懂问题、想清楚怎么办”的问题。第二是规划Planning负责把复杂目标拆解成可执行步骤。最简单的实现是 ReAct 模式Reason Act复杂一些可以用 Plan-and-Execute 或 Tree of Thoughts。规划能力决定了 Agent 是“一锤子买卖”还是“能分步搞定难题”。第三是记忆Memory负责保存上下文和长期知识。短期记忆就是会话窗口里的对话历史长期记忆一般用向量数据库存 Embedding支持语义检索。没有记忆的 Agent 像金鱼聊完就忘。第四是工具Tool负责连接外部系统。API、数据库、代码解释器、浏览器、内部系统都算工具。工具层是 Agent 最核心的工程重点——它决定了 Agent 能不能“动手干活”而不仅仅是“动嘴聊天”。第五是行动与反馈Action Observation负责执行工具调用、观察返回结果、决定下一步动作。这里面包含了解析工具返回、异常处理、终止条件判断等逻辑。这五件套里面模型是你可以直接采购的OpenAI、DeepSeek、Qwen 等剩下四件才是你真正要开发和设计的。理解了这一点后面整个架构就有方向了。2. 平台化设计先画图纸再搬砖2.1 从写脚本到造平台差在哪很多人最初接触 Agent 都是写 Python 脚本定义一个工具函数列表把 LLM 的输出解析一下调工具再把结果拼回去。这种脚本在 Demo 阶段完全够用但一旦要接多个场景、多个业务线脚本就会变成一坨绕不开的 spaghetti code。我见过一个项目把 30 多个工具函数全写在一个文件里每个场景的 Prompt 写在另一个 JSON 文件里记忆逻辑散落在各处后来加了两个人维护都费劲。问题不是代码写得多烂而是没有平台化的抽象。平台化的核心是“分层”。底层是模型接入层统一封装各家模型 APIDeepSeek、GPT、Qwen、本地模型上层调用方不关心具体厂商中间是 Agent 核心引擎层包含规划器、记忆管理器、工具注册中心再往上是场景编排层不同业务场景客服、运营、数据分析助手复用同一套引擎只配置不同的 Prompt、工具集和记忆策略最上面是接口层提供 REST API 或消息队列接口给业务系统调用。这样设计的好处有三第一模型可以随时切换不会被厂商锁定第二每个新场景只需要加配置和工具开发量大幅缩水第三故障排查时能按层定位不会牵一发而动全身。另外还要考虑“平台”这个词的另一层含义是不是要给业务方提供一个可视化的配置界面让运营人员自己维护 Agent 的 Prompt 和知识库而不是每次改动都找研发我的建议是先把这个需求放在 v2 再做。第一版只要把配置外部化用 YAML / JSON不要让业务人员直接改代码就行。2.2 单 Agent 还是多智能体不是越多越好热搜词里“多智能体”出现频率很高很多初学一上来就设计 CEO Agent、HR Agent、财务 Agent……好几个 Agent 互相聊天看起来特别酷但实际跑起来问题成堆上下文互相打架、Token 消耗成倍增长、排查问题极其痛苦。我的原则是能用单 Agent 解决的坚决不拆。单 Agent 在绝大多数业务场景下够用它同样可以调用不同工具、处理多步骤任务。什么时候才拆成多智能体三个条件子任务边界清晰、子任务需要不同的模型能力或 Prompt 策略、子任务之间有明确的输入输出交接协议。举个例子做一个“招聘助手”平台。初筛阶段需要从简历里提取结构化信息这个任务用专门的小模型比如 Qwen-Turbo性价比就很高面试评估阶段需要深度推理和判断用更强的大模型更合适。这时候拆成两个 Agent分别负责“简历解析”和“面试评估”才是有意义的拆分。多智能体架构如果要做我最推荐的是“主管-员工”模式一个 Supervisor Agent 负责任务调度和结果汇总多个 Worker Agent 各自专注自己的子领域。注意Worker 之间尽量不要直接通信所有消息都通过 Supervisor 中转不然很容易出现两个 Agent 你一句我一句聊起来最后完全偏离原始目标。2.3 技术选型框架、协议与编程语言选型是很多团队纠结的地方。我的建议是优先考虑团队的技术栈和项目的维护成本不要盲目追新。Python 方向快速原型推荐 LangChain 或 LlamaIndex生产级项目更推荐 LangGraph 这类显式状态机框架因为流程可控、可追踪调试体验远好于 LangChain 的链式抽象。不过 LangChain 类框架有个通病抽象层级太多出了问题要翻好几层源码才能定位学习曲线陡峭。Java 方向如果你所在团队是标准企业级 Java 技术栈Spring Cloud、Spring Boot那 Spring AI 是绕不开的选择。Spring AI 把模型接入、Prompt 模板、结构化输出、工具调用都做了统一抽象配合 Spring Boot 的自动装配和 Spring Cloud 的服务治理几乎无缝集成。热搜里“spring cloud spring ai 开发自己的 agent”“企业级 java ai agent 应用平台”这些需求最落地的路径就是用 Spring AI Spring Cloud 搭微服务化的 Agent 平台。除了框架协议层次也要关注。2024 年底到 2025 年MCPModel Context Protocol模型上下文协议已经成了事实标准。它是 Anthropic 提出的开放协议目标是让模型和外部工具之间建立标准化的连接方式——相当于给工具装上了“USB-C 接口”。任何支持 MCP 的 Agent 客户端都可以通过标准协议连接任何支持 MCP 的工具服务端不需要为每个工具写集成代码。这个协议影响很大下面实操部分我会演示怎么用。另外很多企业的现状是“已有大量 Spring Boot 微服务”这些服务本身就是天然的 Agent 工具来源。先用 Spring AI 把内部服务包装成 Agent 可调用的工具再逐步把 Agent 平台搭起来这是最平滑的路径不推荐一上来就推翻重来。3. 实操从 0 到 1 搭建一个能干活的企业级 Agent3.1 第一件事不是写代码是定义你的“数字同事”岗位 JD我踩过最大的坑就是一上来写代码。先把业务想清楚再动键盘能省一半的返工时间。造一个 Agent 前一定要像招聘一样写一份岗位 JD职位描述里面至少包含四块内容岗位目标这个 Agent 是干什么的成功的标准是什么职责边界哪些事归它管哪些事绝对不碰避免它过度发挥所需工具与权限需要读取哪些系统、写哪些数据交互规范什么情况下必须寻求人工确认什么语气和格式输出。举一个实操中的例子。假设我们要做一个“产品售后智能助手”岗位 JD 可以这么写岗位目标处理用户在售后流程中的常见问题包括订单查询、退款进度、物流跟踪、退换货政策咨询。目标是把 80% 的重复性问题自动化解决降低人工客服压力。职责边界不承诺任何超出系统记录的赔偿不修改订单状态只输出查询结果和操作指引涉及投诉升级、法律风险、敏感情绪时直接转人工。所需工具与权限订单查询 API只读、物流查询 API只读、退款进度 API只读、知识库检索政策文档。没有写权限无需修改任何业务数据。交互规范回答必须基于工具返回的真实数据禁止编造订单信息遇到不确定的情况必须明确道歉并转人工默认用简洁、礼貌的中文回复。有了这份 JD后面写 System Prompt、选工具、定权限就都顺理成章了。这比任何技术选型都重要。3.2 搭建核心骨架模型封装、推理循环与工具注册下面我用 Python 给一个最经典也最容易改造成工程项目的单 Agent 骨架。这个骨架的核心是一个可复用的推理循环让大模型思考、决定调用哪个工具、拿到结果后再思考直到它能给出最终回答。先看模型封装。为了不绑定具体厂商我建议定义一个统一的调用接口DeepSeek、GPT、Qwen 都可以用 OpenAI 兼容接口暴露出来所以一个函数就能兼容import os from openai import OpenAI client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL, https://api.deepseek.com) ) def chat(messages, toolsNone, modeldeepseek-chat, temperature0.3): resp client.chat.completions.create( modelmodel, messagesmessages, toolstools, # 工具描述列表模型据此决定是否调用 temperaturetemperature, ) return resp.choices[0].message注意temperature0.3Agent 执行任务时我们更希望它有确定性、不过度发散所以温度调低如果是闲聊场景再调高到 0.8 也不迟。接下来是关键的工具注册机制。每个工具需要提供名称、描述、参数 JSON Schema这样模型才能“知道”有这些工具、什么时候用、参数怎么填TOOLS [ { type: function, function: { name: query_order, description: 根据订单号查询订单状态、商品明细和当前进度, parameters: { type: object, properties: { order_id: {type: string, description: 用户提供的订单号} }, required: [order_id] } } }, { type: function, function: { name: query_logistics, description: 根据订单号查询物流轨迹和当前配送位置, parameters: { type: object, properties: { order_id: {type: string, description: 订单号} }, required: [order_id] } } } ] def call_tool(name, arguments): if name query_order: return query_order_from_db(arguments[order_id]) elif name query_logistics: return query_logistics_from_api(arguments[order_id]) raise ValueError(funknown tool: {name})这里有个很实用的经验工具描述一定要写清楚“什么场景下用”模型通过描述来做工具选择描述写得含糊模型就会乱调。比如 query_order 的描述我特意写了“订单状态、商品明细和当前进度”而不是简单写“查询订单”实测准确率能提升不少。核心推理循环是 Agent 的心脏。最基础也最可靠的是 ReAct 循环模型产生一个推理步骤 → 调用工具 → 观察结果 → 再次调用模型如此往复直到模型给出最终答案或达到最大轮数def run_agent(user_input, max_steps8): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for step in range(max_steps): message chat(messages, toolsTOOLS) messages.append(message) if message.tool_calls: # 有工具调用需求逐个执行并把结果追加进对话 for tool_call in message.tool_calls: result call_tool(tool_call.function.name, json.loads(tool_call.function.arguments)) messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse) }) continue # 继续下一轮思考 # 没有工具调用说明模型已经给出最终回答 return message.content return 抱歉任务过于复杂已超出我的处理能力。这里最需要注意的细节是消息格式工具调用的结果必须以roletool追加回去并且要带上tool_call_id否则模型无法把结果和之前的调用请求对齐整个链路就会断掉。好多新手第一次跑通这个循环时就卡在这个格式问题上。max_steps必须设置否则模型陷入循环时会把你的 Token 烧光。我遇到过一次模型反复查同一个订单查了十几轮就是因为没有步数上限。3.3 给 Agent 安装记忆短期会话与长期知识分开设计记忆模块是 Agent 平台最容易做烂的部分。我的设计原则是分层短期记忆管当前会话长期记忆管领域知识和历史经验。短期记忆最简单的方式是直接把对话历史放进 messages 数组LLM 上下文窗口会自动处理。但问题是上下文窗口有限对话一长最早的信息会被挤掉Token 成本也会直线上升。解决思路是消息压缩当消息条数超过阈值比如 20 条就用模型对历史做一次摘要用一条 summary 消息替换掉旧消息。这个策略便宜、有效代码也不复杂def compress_messages(messages, max_tokens2000): if estimate_tokens(messages) max_tokens: return messages history [m for m in messages if m[role] in (user, assistant)] summary_prompt 请用简洁的要点概括以下对话的完整信息包括用户意图、已确认的事实和未完成事项\n json.dumps(history[-10:], ensure_asciiFalse) summary chat([{role: user, content: summary_prompt}], modeldeepseek-chat) return [{role: system, content: f以下是之前的对话摘要务必参考{summary.content}}] messages[-4:]长期记忆一般用向量库做。把历史工单、FAQ、产品文档切片后 Embedding用户提问时做语义相似度检索把最相关的几条上下文注入到 System Prompt 里。这块的工程重点在切片策略一般 300~500 个字符切一块相邻块保留 50 字符重叠检索效果最好。切片太大检索不精准太小则上下文碎片化。3.4 通过 MCP 接入企业工具省掉 80% 的对接工作量很多企业已有的内部系统都是 REST API如果每接一个系统就为 Agent 写一个工具适配器成本很高。MCP 就是解决这个问题的。MCP 的核心思想是用一个标准协议把“Agent 客户端”和“工具服务端”连接起来。工具服务端只需要实现 MCP 协议把内部 API 包装成标准化的工具暴露出去Agent 客户端通过 MCP 客户端库连接就能自动发现和调用这些工具不需要为每个系统单独写调用代码。用 Python 快速实现一个 MCP Server 也很直接下面是接入内部订单查询接口的最小示例from mcp.server.fastmcp import FastMCP mcp FastMCP(order-service) mcp.tool() def query_order(order_id: str) - dict: 根据订单号查询订单状态、商品明细和当前进度 # 这里调用你企业内部的订单服务接口 resp requests.get( fhttp://internal-order-service/api/orders/{order_id}, headers{X-Internal-Token: secret}, timeout5 ) resp.raise_for_status() return resp.json() if __name__ __main__: mcp.run(transportstdio)Agent 侧的 MCP 客户端连接后只需要配置工具服务端的启动命令或地址Agent 就能自动发现这些工具并加入可调用列表。这样加新工具几乎是零代码的业务系统开发一个 MCP ServerAgent 平台重启一下配置就能用。不过在实际落地时要留个心眼MCP 的便利不等于安全。工具一旦暴露给模型模型就有可能误调用或越权调用。安全设计上一定要有“最小权限”和“审批流”两个机制。在 Agent 平台里每个 MCP 工具都要标注权限级别——只读工具可以直接调用写操作必须经过人工审批。比如“查询订单”可以直接调“修改订单备注”则要等用户确认。这个机制在工程上不复杂但非常关键。4. 部署、成本与稳定性别让 Agent 在测试环境里风光无限4.1 并发与限流模型调用变慢会拖垮整个业务线Agent 平台的稳定性瓶颈往往不在你的应用服务器而在大模型 API 的延迟和限流。一个复杂的多步任务可能要串行调 5~8 次模型 API每次 2~5 秒总耗时能到 20~40 秒。如果业务侧用同步 HTTP 调用用户会等到崩溃如果调用方没有超时控制大量请求堆积在 Agent 服务里直接把内存打爆。我的处理方案是三板斧第一按用户粒度做并发隔离。Agent 服务同时跑多个用户的会话每个会话是独立的执行单元。如果单个用户的请求量过大优先保证其他用户不受影响。可以用信号量或令牌桶限制每个用户的并发执行数量超出直接排队。第二工具调用必须设置超时。MCP 工具调用和模型调用都要有独立的超时时间。模型调用我一般设 30 秒工具调用设 5~8 秒。不要用全局超时不然一个慢工具会把整轮循环拖死。第三做好削峰。把 Agent 执行做成异步任务前端通过轮询或 WebSocket 获取结果。这么做还有一个隐性好处复杂的 Agent 任务执行中途如果模型 API 报错可以自动重试用户无感知。同步接口在这种场景下几乎没有重试的余地。4.2 上下文窗口与 Token 成本先学会算这笔账Token 成本是 Agent 上线前必须算清的一笔账。Agent 和普通聊天机器人的成本差异非常大原因在于每轮推理都要携带完整上下文包括 System Prompt、对话历史、工具定义、工具返回结果。一个简单的任务处理完消耗的 Token 可能是直接问答的好几倍。举一个实际测算例子假设 System Prompt 工具定义约 1500 Token对话历史约 1000 Token工具返回结果约 800 Token。每一轮模型调用约消耗 3300 Token。一个典型的三步任务第一次规划调用、一次工具调用后的分析、最终回答需要 3 次模型调用加起来大约 10000 Token。按 deepseek-chat 百万 Token 十几块钱的定价算单次任务成本在 0.1~0.2 元左右。如果每天处理 10 万次任务日成本就是一到两万元这个量级必须被认真对待。控制成本的思路有很多用便宜的小模型做简单任务用强模型做复杂推理对工具返回结果做截断只保留关键字段对历史消息做压缩而不是全量携带给每个 Agent 设置单次任务最大轮数和每日调用预算。另外可以给系统加缓存——同一类查询问题比如查订单物流的结果几分钟内可以直接复用不用每次现查。4.3 日志、审计与可观测性Agent 出错了怎么复盘Agent 系统的排查难度比普通系统高一个量级。传统系统出错了看报错堆栈基本能定位Agent 出错了问题可能出在模型幻觉、Prompt 写得含糊、工具结果被模型误解、上下文被污染任何一环都可能导致最终回答错误。所以在设计平台的第一天就要把日志和可观测性做进去。我要求所有 Agent 任务都必须落结构化日志至少包含以下字段会话 ID、用户 ID、完整消息链条模型思考、工具调用、工具结果按顺序记录、每轮 Token 消耗、模型名称、耗时、最终回答、是否转人工。有了这些日志出问题时就能按时间线回放 Agent 的每一步行动定位到底哪一步出了问题。还建议做一个简单的评估集Evaluation Set。挑 30~50 个典型业务问题每次修改 Prompt、换模型或者调整工具之后把评估集跑一遍看通过率和质量的趋势。这个机制能防止“修好一个问题、弄坏三个功能”的回归问题。5. 踩坑实录与常见问题速查5.1 实测中最容易翻车的五个点第一个翻车点是工具参数格式错误。模型返回的工具调用参数是 JSON 字符串但偶尔会返回不合法 JSON比如少了一个引号。我用过两种方案一种是解析失败时把原始参数返回给模型让它修正重试更稳妥的是在工具定义里用强制 Enum、Regex 约束参数让模型可选范围变小。第二种方案效果明显更好。第二个翻车点是模型幻觉导致乱调工具。比如用户问“我的洗衣机保修期多久”模型没调用查询工具直接凭训练数据编了一个保修期。解决办法是在 System Prompt 里强约束“所有业务事实必须来自工具返回禁止推测”同时在回复模板里要求模型标注信息来源。实测下来这两个手段能把幻觉率降到一个可接受的水平。第三个翻车点是超时重试导致重复操作。工具接口响应慢客户端超时报错后自动重试结果用户下了两次单。解决方式是工具接口尽量设计成幂等的并在 Agent 平台里对同类型工具做去重。如果工具确实无法幂等宁可让用户手动重试也不要自动重试。第四个翻车点是 Memory 无限膨胀。不加压缩机制跑了几百轮的长会话最后 Token 消耗会涨到离谱。很多线上事故就是这么来的——Token 账单直接超预算。必须从一开始就设计压缩策略并且定期清理长期记忆中的过期数据。第五个翻车点是多智能体死循环。两个 Agent 互相转发消息谁也不推进主流程。我在一次多智能体协作开发中踩到过最后方案是“质疑 Agent”和分析逻辑的输入输出全部经 Supervisor 中转禁止 Worker 之间直接通信。事实证明调度集中化是多智能体稳定性的基石。5.2 排查问题的通用方法排查 Agent 问题时不要凭感觉猜先看日志。先回放消息链看模型每一步的思考、它选择了什么工具、拿到了什么结果、最终怎么回的。90% 的问题在消息链里就能看出端倪。如果日志显示模型反复调用同一个工具多半是工具返回的内容无法满足任务要求模型只能反复重试。解决办法是看返回内容里缺什么字段补全它或者调整 Prompt 让模型换个策略。如果模型的回答很自信但与事实不符多半是幻觉检查 System Prompt 约束是否足够强以及工具返回的信息是否真的被模型读取了——有时候模型根本没调用工具就直接答了。如果错误只在特定用户身上出现且无法复现考虑是不是上下文被污染了——历史会话里有敏感或错误信息干扰了判断。这种情况清理长期记忆即可。5.3 常见问题速查表下面这张表是我在实操中整理出来的问题速查表对应的解决方案基本都经过验证现象可能根因解决方案模型不调用工具直接凭记忆回答System Prompt 未强调必须先查工具在 Prompt 中强制要求“所有事实必须来自工具返回禁止推测”工具返回有效但模型说找不到工具结果被截断或格式太复杂简化工具返回 JSON只保留关键字段必要时将结果转成人类可读文本模型乱调不相关的工具工具描述不清晰优化工具 description写明使用场景和触发条件同一工具反复调用不推进流程工具返回不满足任务需求或缺少关键信息补全工具返回字段在 Prompt 中限定最多调用同工具 N 次任务中途 Token 耗尽或超时上下文过长、步骤过多启用历史压缩缩短工具返回限制最大步数多 Agent 互相回复形成死循环缺少集中调度改用 Supervisor 中转模式Worker 之间禁止直接通信线上偶发错误且无法复现模型 API 不稳定或上下文被污染接入重试机制排查该用户历史会话数据并清理长期记忆MCP 工具新加后无法发现未配置工具服务端地址或未重启客户端检查 MCP 服务端运行状态与客户端 Config 变更生效最后再分享一点我在实际项目里的体会Agent 平台最核心的壁垒从来不是模型选得多新而是你有没有一套扎实的工程体系来约束模型的行为。把权限做细、把日志做全、把评估集做起来这三件事比多接一个牛模型重要得多。记住一个原则——你是在给公司招一位“数字员工”管理员工的那些方法论职责边界、权限最小化、考核评估在这里全部适用。沿着这个思路走你搭出来的 Agent 平台才能真正从“玩具”变成“生产力”。
