AI智能体项目的开发最近聊的人特别多但能把一个Agent从需求文档一路推到线上稳定运行的确实不多。我前阵子刚完成一个企业内部工单场景的智能体项目用户发一句自然语言智能体自动判断工单类型、查询订单状态、校验操作权限甚至在条件满足时直接拉起退款流程。这类项目看起来就是“调接口写提示词”但真正落地时需求边界怎么定、工具怎么抽象、记忆怎么管理、评测怎么做每一步都会直接影响最终能否上线可用。这篇内容就把整个开发过程中最核心的部分完整拆一遍从概念到架构、从选型到实现、从踩坑到排查适合正在计划做AI智能体项目、但还没找到清晰切入点的开发者、产品和技术负责人。1. 先想清楚你的项目到底需不需要Agent1.1 智能体和“聊天机器人”的本质区别很多人把AI智能体当成一个更智能的聊天窗口这是个非常危险的认知偏差。聊天机器人的核心是“生成回复”用户问一句它答一句答得好不好主要看语言表达。智能体的核心则是“完成任务”它要能理解目标、拆解步骤、调用外部工具、观察执行结果并根据结果调整下一步动作。我用一个例子来说明。传统客服机器人收到“我要退款”时它大概率会背一段话术请您提供订单号、说明退款原因。这不算错但也到此为止。AI智能体收到同样的请求会先检索会话历史里的订单号再调用订单查询工具核实订单状态是否符合退款条件然后调用退款申请工具最后把退款结果返回给用户。也就是说智能体不只会说还会做做完还要验证。这个区别决定了整个项目的设计方式。如果你需要的只是“把文档知识库做得更友好”那做一个检索增强问答系统就够了没有必要上智能体。真正的Agent项目一定要有一个核心判断标准任务链条里是否存在需要系统主动发起的动作。有动作才是Agent的主场。1.2 需求边界前置条件清单在动手写任何代码之前我建议先做一道判断题你手头的场景适不适合用智能体解决。我总结过一个前置条件清单命中越多项目越值得做。任务本身有明确目标且可以拆成多个子步骤步骤之间会随中间结果发生变化而非固定写死的流程系统里有现成的接口或数据源可以被调用用户输入是开放式的自然语言而不是点击按钮的选择题容错度允许模型在监督下做尝试而不是永远不允许一步出错反过来如果某个业务场景是强规则、强合规、每步操作都需要严格审计且不允许模型自由发挥的那智能体并不是最优解规则引擎加工作流反而更可靠。我见过一个团队硬把报销审批流程做成Agent结果模型偶尔把审批权限理解错最后不得不退回传统表单流程项目白折腾了两个月。智能体擅长处理的是“长尾的、动态的、需要理解语义的任务”而不是“固定的、线性的、每一步都写死的流程”。1.3 从一句话开始拆解系统把需求想清楚之后我会习惯用一句话拆解整个系统用户输入自然语言智能体通过大模型理解意图并规划步骤调用工具完成动作利用记忆维持多轮上下文最后通过结果验证确认任务收口。这句话翻译成工程结构就是五个模块入口层承接用户输入做基础清洗和上下文加载规划层由大模型完成意图识别、任务拆解、工具选择工具层把各类系统能力封装成模型可理解的接口记忆层管理短期对话上下文和长期数据记忆执行与验证层真正调用工具并判断结果是否达到预期后续所有开发工作基本都是围绕这五个模块展开。先把结构画出来后面不容易乱。2. 智能体项目的核心模块与实现逻辑2.1 规划模块ReAct循环和任务拆解规划模块是智能体区别于普通对话系统的灵魂而目前最稳定、最通用的实现方式就是ReAct循环。ReAct的核心思想是让模型交替执行“思考”和“行动”先根据当前状态判断该做什么然后产生一条工具调用指令接着读取工具返回结果再继续思考下一步该做什么。这个循环看起来简单但它解决了一个很实际问题复杂任务一次推理搞不定。比如用户说“帮我查一下上周所有异常的订单并统计退款原因”模型不可能在一个瞬间给出正确答案它需要先查询订单列表、筛选异常状态、逐个获取退款原因、再做汇总。ReAct循环允许模型一步一步逼近结果每次只做一个小决策风险被分散到每一步里。我在实际项目里会让系统提示词明确约束规划节奏大约是下面这样你是一个工单处理助手。面对用户请求时请先分析需求再确定需要调用哪个工具调用后检查工具返回结果。如果结果不足继续调用下一个工具直到获得完整答案。禁止在未调用工具的情况下编造数据。这里有个设计要点不要把任务拆解交给模型自由发挥太多。如果业务链路相对固定我会在提示词里给出明确的“步骤偏好”比如“先查用户身份再查订单状态”如果任务完全开放则让模型自行决定。两者对模型的推理能力要求差别很大建议从固定链路开始做。2.2 工具调用Function Calling与工具协议工具是智能体的“手”而Function Calling是让模型学会用“手”的关键机制。从模型侧来看它在生成回复时不再只输出纯文本而是可以选择输出一个结构化的工具调用请求包含工具名称和参数JSON。系统收到这个结构后自行执行对应函数再把结果返回给模型继续推理。设计工具时需要特别注意两点。第一工具描述越准确模型的调用准确率越高。不要写“处理订单”这种模糊描述要写“根据订单号查询订单当前状态返回状态码、金额、下单时间”。模型是根据描述来做选择的描述质量直接影响效果。第二参数设计必须严格遵守JSON Schema规范。我给每个工具定义结构时会用类似下面的方式来约束TOOL_SCHEMAS [ { type: function, function: { name: get_order_status, description: 根据订单号查询订单当前状态返回状态码、金额、下单时间, parameters: { type: object, properties: { order_id: { type: string, description: 订单号例如 ORD202405001 } }, required: [order_id] } } } ]如果项目里的工具数量很多推荐引入基于消息的工具调用协议来统一接入方式。这套协议的作用是把不同工具封装成标准格式让模型层不必关心每个工具背后的实现细节类似把各种电器统一成标准插座。工具多了以后这套标准化能省掉大量联调成本。2.3 记忆体系短期、长期与向量检索记忆是Agent项目里最容易做砸的部分。我先分清楚两个概念短期记忆是当前任务上下文长期记忆是跨会话的业务信息。短期记忆本质上就是模型API里的messages数组。每一轮对话、每一次工具调用结果都要追加进去。但这里有个直接矛盾上下文越长模型输入越长token成本越高响应速度越慢而且超过一定长度后模型还会“遗忘”早期内容。所以不能无限堆历史必须做窗口管理。我的做法是保留最近几轮完整对话更早的内容则用大模型生成摘要压缩成一段话替代原始历史。长期记忆通常用向量检索实现。所谓向量检索就是把文本转成向量然后按语义相似度去库里找相关内容。比如用户上次投诉过某个物流问题这次再发起咨询时系统先从向量库中把相关历史记录捞出来作为背景信息放入提示词。这样智能体就有了“跨会话记住你”的能力。长期记忆里还有一个容易被忽视的部分实体记忆。用户的身份、订单号、当前操作状态这类结构化信息不适合用向量检索更适合放到一个独立的KV存储中。当用户说“刚才那个事怎么样了”智能体通过实体记忆知道“刚才那个事”具体指什么。记忆管理本质上是在做资源的取舍什么信息必须留存什么信息可以丢弃什么信息需要压缩这个决策直接影响智能体的使用体验和运行成本。2.4 多智能体编排高级场景要不要上很多人一听到智能体就想去搞多智能体协作觉得让几个AI互相讨论、分工合作非常酷。但我的经验是多智能体不是默认选项而是复杂场景的最终手段。单智能体处理不了的局面主要有三类一是需要两种完全不同的专业能力比如一个懂法律、一个懂财务硬塞进一个上下文里容易互相干扰二是单个模型上下文窗口装不下全部信息三是任务天然存在隔离需求不同角色需要不同的权限边界。一旦决定上多智能体常用编排模式有三种主管-执行者模式主管Agent负责理解总目标、拆分任务、派发给执行Agent再汇总结果流水线模式任务按固定顺序经过多个Agent每个Agent只处理自己环节协作模式多个Agent共享信息在一个公共账本上读写共同推进任务多智能体会让调试难度成倍上升因为问题可能出现在任何一个环节的推理上。我的建议是先把单Agent做到稳定如果确实遇到瓶颈再按最小代价引入第二种角色不要一开始就铺开一个Agent团队。3. 技术选型与开发环境准备3.1 三条技术路线的取舍目前做AI智能体项目基本有三条路线可走。第一条路线用代码级Agent编排框架。这类框架把对话循环、工具调用、记忆管理等通用能力封装好开发者在代码里配置模型和工具。优点是灵活、可控、方便定制适合业务逻辑复杂、需要深度定制的项目。缺点是学习成本高且框架的抽象层在出现问题时会掩盖细节排查相对困难。第二条路线用可视化流程平台。业务同学可以在界面上拖拽配置Agent流程不用怎么写代码就能搭出原型。优点是快适合内部工具、MVP验证缺点是复杂逻辑表达受限定制能力较弱项目做到后期容易撞到平台的天花板。第三条路线从零实现一个轻量Agent框架。我之前做的工单项目就走这条路。核心循环就几十行代码工具就是普通函数记忆就是列表加一个向量库。优点是逻辑完全透明出问题知道去哪查缺点是要自己处理很多边缘情况比如重试策略、并发控制。三条路线没有绝对好坏看项目阶段。我对团队的建议是验证期从零实现或低代码平台快速跑通闭环规模期切换代码级框架或自研核心保证可控性。模型是另一个关键选型。主流的做法是优先选择Function Calling能力强的商用大模型接口稳定性和意图识别效果都有保障如果数据合规要求高、必须私有化部署就选择开源模型但要做更充分的工具调用能力测试。需要权衡的指标我整理如下指标说明优先级工具调用准确率模型能否按格式输出正确的工具名和参数最高多轮一致性长时间任务中是否会遗忘目标高推理成本每任务平均token消耗高响应延迟从请求到首次输出的时间中私有化能力是否支持内网部署和数据隔离视场景3.2 开发环境与项目结构抛开具体框架一个可维护的Agent项目我建议按下面的目录结构组织代码agent_project/ ├── agent/ │ ├── planner.py # 规划与循环控制 │ ├── memory.py # 短期与长期记忆管理 │ ├── executor.py # 工具执行与结果解析 │ └── prompts.py # 系统提示词 ├── tools/ │ ├── order_tools.py # 订单类工具 │ ├── user_tools.py # 用户类工具 │ └── common.py # 通用工具注册表 ├── api/ │ ├── gateway.py # HTTP接口入口 │ └── schemas.py # 请求与响应结构 └── tests/这种分层的核心思路是模型调度逻辑和业务工具完全解耦。以后要换模型、换工具、换记忆存储都只动对应模块不会把代码搅成一团。开发环境方面Python是当前Agent生态最舒服的语言建议直接使用Python 3.10以上版本。需要安装的依赖很少一个HTTP客户端库、一个配置读取库、一个向量数据库客户端即可。不需要追求大而全的框架先把核心跑起来再说。4. 从0到1开发一个工单智能体4.1 把需求翻译成提示词与工作流前面的架构都是铺垫从这一节开始进入真正的实现环节。我以工单智能体为例完整演示一遍开发过程。需求描述很简单用户用自然语言查询订单状态、申请退款、修改收货信息。系统要判断用户意图调用对应工具处理完返回结果。首先要写系统提示词。提示词是给模型的“岗位说明书”它决定了模型的行为边界。我第一版写的提示词包含四部分角色定义你是一个电商平台的工单客服助手工作流约束先识别用户需求再选择工具根据工具结果回复关键禁令不得编造订单信息不得在未确认时执行退款操作输出要求回复简洁、使用中文、信息以工具返回为准工作流部分比想象中还重要。如果不做约束模型可能跳过查询工具直接回答一个编造的订单状态这在生产环境是不可接受的。所以我在提示词里明确要求“凡是涉及数据的内容必须先调用对应工具获取”。4.2 设计第一版工具集工单场景第一版只需要四个工具TOOL_SCHEMAS [ { type: function, function: { name: get_user_info, description: 根据用户ID查询用户基础信息和会员等级, parameters: { type: object, properties: { user_id: {type: string, description: 用户ID} }, required: [user_id] } } }, { type: function, function: { name: get_order_status, description: 查询订单当前状态返回待支付/已发货/已完成/已退款等状态, parameters: { type: object, properties: { order_id: {type: string, description: 订单号} }, required: [order_id] } } }, { type: function, function: { name: apply_refund, description: 为订单发起退款申请仅允许状态为已完成且金额大于0的订单退款, parameters: { type: object, properties: { order_id: {type: string, description: 订单号}, reason: {type: string, description: 退款原因} }, required: [order_id, reason] } } } ]每个工具的实现就是一个普通Python函数。注意工具内部要做参数校验和幂等处理模型传进来的参数偶尔会缺字段或者格式不对函数本身必须能优雅处理不能直接抛异常把整个对话打崩。这个阶段的关键经验是工具数量从少到多。第一版尽量控制在五六个以内因为工具越多模型选错的概率就越高。等观察到稳定的调用模式后再逐步扩大工具集。4.3 核心循环让智能体真正动起来工具定义好了接下来写核心循环。这是整个Agent最关键的几十行代码。import json import time import requests MAX_STEPS 8 LLM_BASE http://your-llm-service/api def call_llm(messages): payload { model: agent-model-v1, messages: messages, tools: TOOL_SELECTOR, tool_choice: auto, temperature: 0 } for attempt in range(3): try: resp requests.post(f{LLM_BASE}/chat/completions, jsonpayload, timeout60) resp.raise_for_status() return resp.json()[choices][0][message] except Exception as e: time.sleep(1.5 * attempt) raise RuntimeError(LLM调用失败) def run_agent(user_message, user_id): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: f用户ID: {user_id}\n用户问题: {user_message}} ] for step in range(MAX_STEPS): msg call_llm(messages) messages.append(msg) tool_calls msg.get(tool_calls) if not tool_calls: return msg[content] for call in tool_calls: fn_name call[function][name] fn_args json.loads(call[function][arguments]) print(f[Step {step}] 调用 {fn_name}: {fn_args}) result TOOL_REGISTRY[fn_name](**fn_args) messages.append({ role: tool, tool_call_id: call[id], content: json.dumps(result, ensure_asciiFalse) }) return 抱歉这个问题比较复杂我无法在有限步骤内处理完成已转接人工。这个循环有几个设计点想说明一下。temperature设置为0是因为工具调用需要确定性不需要创造性。MAX_STEPS设置为8是防止模型陷入无限循环。每次工具执行后结果都以tool角色回填到messages里模型下一步推理就能看到工具返回的真实数据。这套循环不依赖任何第三方Agent框架但已经具备了智能体的完整闭环。实际生产时还可以加上日志追踪、步骤超时、工具并发等能力但核心骨架就是这样。4.4 上线前必做的评测Agent项目最怕的就是“当时好用一上线就乱”。所以我强烈建议上线前准备一套固定评测集用同一批用例反复跑确认改动不会让效果倒退。评测集怎么造从真实历史工单里抽取或模拟二十到五十条典型用户请求覆盖四类场景常规查询、多步操作、边界情况、恶意输入。对我来说一条用例至少要包含“用户原始输入”“预期工具调用序列”“预期最终回复的关键信息”三个要素。评估指标方面我关注四个数字指标定义达标线任务完成率最终正确完成目标的用例占比80%以上工具调用准确率正确选择和调用工具的占比90%以上平均步数完成任务平均调用工具次数越低越好安全拒绝率对越权/高危操作正确拒绝的占比100%评测过程中即使任务完成率达标也要翻一下失败的case。我之前遇到过一种情况模型没有调用工具而是直接根据用户输入里的订单号编了一个订单状态虽然回答看起来顺滑但数据是假的。这类“虚假完成”比直接失败更隐蔽评测时必须人工阅读回复内容来辨别。上线后还要持续做回归评测。每次调整提示词、更换模型版本、新增工具都要拿同一套评测集重新跑一遍。否则很容易出现“这个场景修好了那个场景坏了”的回归问题。5. 开发中的常见问题与排查实录5.1 上下文污染导致答非所问运行一段时间后最常遇到的现象是智能体答非所问甚至答到一半开始说无关内容。排查后基本都是同一个原因上下文被污染了。上下文污染有两种。第一种是历史消息里包含大量无关内容挤占了模型的注意力第二种更隐蔽是工具调用结果里包含了大量噪声比如一次查询返回几百行明细模型在生成最终回复时反而被这些信息带偏。我的解决办法分三步。第一步控制输入长度只保留最近几轮完整对话更早的历史用摘要替换。第二步工具返回结果做裁剪只把对当前决策有用的字段注入上下文而不是一股脑全部返回。第三步在系统提示词里加一句“回复只引用与当前问题直接相关的信息”。5.2 死循环和工具滥用模型在推理过程中会偶尔陷入循环反复调用同一个工具、反复得到同一个结果却不终止。这不是模型“变笨了”而是推理路径缺少终止条件。我在实战中主要靠三层防线控制。第一层是代码硬限制设置最大执行步数到点强制结束并转人工。第二层是语义检测如果连续三次调用同一个工具且参数没有变化判定为循环主动中断。第三层是在提示词里加约束例如“如果工具返回结果与上一轮相同说明信息不足请换一种方式处理或直接询问用户”。工具滥用的情况更头疼尤其是高风险的退款类工具。我的做法是需要执行的敏感工具必须二次确认。模型先输出一个“确认申请”的回复等用户回复“确认”才真正调用执行工具。这个机制虽然多了一次交互但避免了大量误操作。5.3 成本、延迟与并发压力智能体项目上线后成本往往会比预期涨得快。原因很简单一次简单问答背后可能是多轮工具调用每轮都是完整的模型请求。用户看到的是一个回答模型背后可能已经跑了五六次推理。控制成本我常用的手段有四个。第一任务路由简单问题交给轻量小模型复杂问题才交给推理强的大模型。第二结果缓存相同或相近的查询请求命中缓存直接返回不再调用模型。第三记忆压缩上下文长度减少token成本直接下降。第四异步化不需要实时返回的长任务放后台跑避免同步等待占用资源。延迟问题一般出现在工具调用链路变长时。一个任务如果串行调用四五个工具每个工具耗时几百毫秒整体体验就会变卡。可以在工具调用部分做并行优化无依赖的工具请求同时发出而不是一个个排队等。5.4 工具参数错误与联调排查速查开发期间最高频的报错类型就是工具参数错误比如模型把函数名拼错、参数类型不对、必填字段缺失。遇到这类问题我把排查思路整理成一张速查表现象可能原因排查方法解决方案模型调用不存在的工具工具描述不清晰或函数名拼写复杂查看日志中tool_calls的输出简化函数名增加描述里的关键词参数类型错误JSON Schema类型定义不严谨使用调用日志回放严格定义property类型服务端校验兜底必填字段缺失模型没有理解描述中的依赖关系检查参数描述文案在description中写明参数来源工具执行抛异常函数未做入参容错检查日志堆栈所有工具函数统一try-except包装返回结构解析失败返回内容不符合预期打印原始返回报文用JSON Schema校验返回结构这个表格基本上覆盖了智能体联调阶段绝大部分问题。出现错误时切记先看日志把模型的原始输出完整打出来。很多团队喜欢看单测结果但工具调用环节的问题往往在真实输出里才会暴露测试里往往测不出来。6. 一点个人经验AI智能体项目开发和传统后端开发最大的不同在于你面对的是一个概率系统而不是确定系统。同样一段提示词、同样一个工具集这次调用可能完全正确下次调用就可能出错。所以整个开发思路都要围绕“如何把不可控性控制住”展开给模型清晰的工具边界给执行循环设置步数上限给敏感操作加人工确认给每次升级加回归评测。我做完这个工单智能体后最深的体会是不要一上来就追求大而全的智能体平台先把一条核心任务链路跑通把工具的准确率打磨到可接受水平再逐步扩展。一个能在十个场景里稳定运行的Agent远胜于一个在五十个场景里时好时坏的Agent。模型能力在快速进步但工程能力才是让智能体真正落地可用的那层地基。