说实话过去一年多我几乎把所有精力都砸在了Agentic AI的开发与落地上踩过的坑比写出来的代码还多。从最初只会调API做一个聊天机器人到如今把Agent真正部署到业务系统里处理真实工单最大的认知转变就一句话Agent不是一个模型而是一套系统。这篇秘籍想讲清楚的正是从模型到系统的那道坎——工具调用、记忆管理、规划循环、安全护栏以及最容易被忽略的落地工程化问题。内容主要面向已经跑通过LLM接口、想往Agent方向深入的技术同学也适合正在做技术选型的团队参考。看完之后你能对Agent的核心机制有一个完整的判断框架并且可以直接把这套架构搬到自己的场景里去。很多同学上来就问我“Agent和普通的AI对话接口到底区别在哪”我会用一句话回答普通的对话接口是在答Agent是在做。它会为了完成一个目标自己决定调用什么工具、查什么数据、确认什么结果甚至主动修正自己的行动方案——这背后是一整套工程架构在支撑不是一个模型单独能完成的。1. 先想清楚再动手Agent的本质到底是什么1.1 从Chat到Agent多出来的那三步早期做聊天机器人核心工作就是“输入—上下文—输出”。你给模型一段系统提示词再加上用户的问题它给你一段回答流程就结束了。文本生成得再漂亮它也只停留在“建议”层面不会去执行任何操作。Agent则完全不同。它在生成文本之外多了三步关键动作理解目标、规划路径、执行工具。比如用户对一个客服Agent说“帮我查一下上周的退款工单处理到哪一步了”普通Chat会给你一段话“建议您在工单系统里查看退款状态。”但一个真正的Agent会自己去调用工单查询接口拉取数据判断退款处于审批、打款还是失败状态然后返回一个基于真实数据的结论。这三步动作拆开来看核心多出来的就是工具调用Tool Use、任务规划Planning、记忆管理Memory。这也是Agentic AI开发里最基础也最重要的骨架。1.2 拆开看这套系统里每个零件负责什么大模型本身做决策的“大脑”负责理解意图、拆解任务、生成调用指令。它不是一个执行引擎而是一个推理和决策引擎。工具层让Agent能够“动手”的接口。包括API调用、数据库查询、代码执行、文件操作等相当于给模型装上了手和脚。记忆层分为短期记忆本次会话的上下文和长期记忆跨会话的知识、偏好、历史记录。没有记忆的Agent每轮对话都是“失忆状态”。规划层把一个大目标拆解成若干子任务决定先做什么后做什么。复杂场景下还需要根据执行结果的反馈动态调整规划。执行层把模型的决策落成真实的动作并把工具返回的结果回传给模型进入下一轮推理。理解了这几个零件的分工后面做技术选型和架构设计就有了判断基准。比如你的场景根本不需要跨会话记忆就不用花大力气去接向量数据库你的业务主要是单步骤工具查询也就不用上复杂的规划框架。1.3 哪些场景真正需要Agent做技术选型时最忌讳“为了Agent而Agent”。我的经验是可以从两个维度判断判断维度说明不需要Agent的情况是否需要操作外部系统要查数据库、调API、改配置只需要生成文本建议是否需要动态决策要根据中间结果决定下一步用户意图单一且固定如果一个流程只需要一次模型调用、不需要访问外部数据和系统那直接写死普通对话接口就行。反之如果牵涉到多步决策、多个系统联动比如“根据工单内容给客户回邮件并把处理状态同步给财务系统”Agent才真正有发挥空间。2. 五个核心组件逐一拆解从原理到选型2.1 工具调用让模型拥有“手脚”的关键机制工具调用Function Calling是Agent区别于普通对话最核心的能力。它的工作逻辑非常直观系统先告诉模型“你可以用哪些工具每个工具接收什么参数”然后模型在推理时自动选择要不要调用、调用哪个、传什么参数最后由你的工程代码来真正执行这个工具并把执行结果返回给模型继续推理。工具定义里最要紧的是参数说明要写得足够细。模型没有“常识”去猜测你的接口需要什么格式它只能根据你给的描述来做判断。举个例子定义一个“查询订单”工具如果只写“查询订单”模型可能把时间参数传成ISO格式、把订单号传成字符串如果你写清楚“时间格式为YYYY-MM-DD订单号是纯数字字符串”准确率会大幅提升。工具描述写得越精确模型调用就越少出错——这个细节对落地效果影响极大。当前主流的模型厂商都原生支持工具调用从接口层面就能返回结构化的工具调用请求不需要自己去解析非结构化的文本。如果你的模型不支持也可以让模型输出JSON格式的指令再解析但稳定性和准确率会差一截。做技术选型时优先选支持原生工具调用的模型。2.2 记忆系统短期与长期要分开设计记忆是Agent开发和落地里最容易踩坑的模块。很多初次尝试的朋友把“把所有历史消息都塞进上下文”等同于记忆结果很快就撞上上下文窗口的瓶颈又慢又贵。正确的做法是把记忆分成两个层面。短期记忆就是当前任务执行过程中的上下文相对好办通常就是维护一个消息列表配合摘要和压缩来控制长度。长期记忆则需要接入持久化存储比如向量数据库把重要的用户偏好、历史决策、业务数据按语义存储下来需要时再检索召回。这里有个实操上的建议不要一股脑把记忆内容全部塞给模型。我的做法是先让模型判断“当前这次请求需要哪些历史信息”再根据判断结果去检索相关片段上下文质量和token成本都好得多。做记忆设计时要区分清楚哪些信息值得存、哪些信息只是临时状态记忆并不是存得越多越好。2.3 规划能力从单步到多步的关键跨越单工具的Agent做多了以后你会发现很多真实业务场景根本不是一步能完成的。比如“分析客户反馈并生成周报摘要”至少需要两个动作先把原始反馈数据拉出来然后调用分析模块做汇总。这就涉及任务规划。规划能力的实现方式有很多种。最简单的做法是让模型自己在每一步推理中决定下一个动作走一步看一步这是ReAct范式Reasoning Acting 的结合即边推理边行动适合大多数业务场景。复杂一点的做法是引入规划器允许模型先把一个目标拆成多个子任务再逐一执行。后者适合步骤比较固定、子任务可以并行处理的场景但实现复杂度也更高。我的经验是先从走一步看一步的ReAct开始不要一上来就上复杂规划框架。跑通了以后再去考虑是不是有一些步骤可以固定成流水线。现实中大多数Agent用ReAct加简单的呼吸设计就能达到很好的效果盲目堆复杂度只会让调试难度指数上升。2.4 执行循环把决策跑成一个闭环有了大模型、工具、记忆和规划还需要一个把它们串起来的执行循环。这个循环是整个Agent运行的“生命线”可分为四步获取用户输入整理成系统提示词和上下文。模型进行推理输出两种结果之一要么直接生成最终回答要么生成一组工具调用请求。如果是调用工具工程代码负责实际执行拿到执行结果后回传给模型重复第2步。到达终止条件无工具调用、达到最大步骤数、用户中断后返回最终结果。这里最关键的是循环容忍度的设计。默认最多让Agent连续执行多少步必须提前定好。不然Agent在某个工具返回异常格式时有可能反复重试既耗时又烧token。我通常把默认步数限制在8到10步特定复杂场景再单独调高。2.5 安全护栏落地前必须考虑的边界任何Agent只要接入了工具和外部系统就必须考虑安全边界。这块如果前期不做上线后的每一个事故都会让你后悔当初的偷懒。最基础的护栏有六个方面权限最小化给Agent的工具权限只能覆盖当前业务所需绝不能用管理员权限跑所有操作。比如客服Agent只能查工单、不能删工单。敏感操作人工确认涉及发送消息、删除数据、转账付款这类不可逆操作要设置人工审批节点。输入过滤与提示注入防护用户的输入可能包含恶意指令要防止攻击者把Agent“带偏”关键动作前加校验。输出内容审核生成的内容需要经过合规扫描或敏感词过滤才能对外展示。操作审计日志Agent每一步调用了什么工具、传了什么参数、拿到了什么结果全部留痕。超时与熔断工具调用的超时时间要设置好外部接口大概率比你想的要不稳定提前兜住。安全防线做得越早成本越低等出了事故再回头补代价往往十倍不止。3. 从零跑通一个Agent账务查询Demo全程手记3.1 场景与工具设计为了让你能把上面讲的理论直接落成代码我在这里复盘一个真实的Demo——某公司内部用的“账务查询Agent”。这个Agent要做的事很简单用户用自然语言描述查账需求Agent自己决定查哪张表、按什么条件查然后把结果整理成可读结论。整套结构里模型调用使用OpenAI-compatible的接口方式工具层就是几个标准化的查库函数执行循环用Python管理整体的复杂度是可控的适合作为入门复刻的模版。工具层我设计了三个函数函数名称功能关键参数query_sales按月份查询销售额month格式YYYY-MMquery_expense按月份查询支出month格式YYYY-MMlist_months列出有数据的月份无参数为什么要把计算逻辑都写在工具函数里因为工具函数让Agent只需关注“选哪个工具、传什么参数”而不是自己去做复杂的日期计算和数据聚合。这样的活模型干不了也不该干工具层才是真正干重活的地方。还有一件事让查询类工具只接受“月份类别”这类结构化参数可以有效避免用户用自然语言发起工具调用时带来的混乱。比如用户说“看看七月的花费多不多”模型会根据工具描述把“七月”转成“2024-07”再传给query_expense。这样做的好处是整个Agent的关键数据操作逻辑都是可测试、可追踪的。3.2 代码实现与逐段解读# agent_core.py # 依赖openai1.0, python-dotenv import json import os from openai import OpenAI client OpenAI(api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL)) # 工具函数实现 def query_sales(month: str) - str: 按月份查询销售额 data { 2024-06: {amount: 235000, orders: 186}, 2024-07: {amount: 278000, orders: 224} } if month in data: return json.dumps(data[month], ensure_asciiFalse) return json.dumps({error: f{month}没有销售数据可先调用list_months查看可用月份}) def query_expense(month: str) - str: 按月份查询支出 data { 2024-06: {amount: 142000, items: 36}, 2024-07: {amount: 168000, items: 41} } if month in data: return json.dumps(data[month], ensure_asciiFalse) return json.dumps({error: f{month}没有支出数据可先调用list_months查看可用月份}) def list_months() - str: 列出有财务数据的月份 return json.dumps([2024-06, 2024-07], ensure_asciiFalse) TOOLS [ { type: function, function: { name: query_sales, description: 按月份查询销售额数据。月份格式为YYYY-MM。, parameters: { type: object, properties: { month: {type: string, description: 月份格式YYYY-MM} }, required: [month] } } }, { type: function, function: { name: query_expense, description: 按月份查询支出数据。月份格式为YYYY-MM。, parameters: { type: object, properties: { month: {type: string, description: 月份格式YYYY-MM} }, required: [month] } } }, { type: function, function: { name: list_months, description: 列出系统中有财务数据的全部月份列表。, parameters: {type: object, properties: {}} } } ] TOOL_MAP { query_sales: query_sales, query_expense: query_expense, list_months: list_months, } SYSTEM_PROMPT 你是一个财务查询助手。用户会询问公司财务数据你应当调用合适的工具来查询。如果用户没有明确月份先调用list_months查看可用月份。 def execute_tool_call(tool_call): 实际执行工具调用返回工具结果 fn_name tool_call.function.name args json.loads(tool_call.function.arguments) print(f - 调用工具: {fn_name}, 参数: {args}) if fn_name not in TOOL_MAP: return json.dumps({error: f未知工具: {fn_name}}) try: result TOOL_MAP[fn_name](**args) except TypeError as e: result json.dumps({error: f参数错误: {e}}) return result def run_agent(user_input, max_steps8): 主循环推理 - 调用工具 - 回传结果 - 再推理 messages [{role: system, content: SYSTEM_PROMPT}] messages.append({role: user, content: user_input}) for step in range(max_steps): print(f--- Step {step 1} ---) response client.chat.completions.create( modelos.getenv(LLM_MODEL, gpt-4o-mini), messagesmessages, toolsTOOLS, tool_choiceauto, ) message response.choices[0].message if message.tool_calls: messages.append(message) for tool_call in message.tool_calls: result execute_tool_call(tool_call) messages.append({ role: tool, tool_call_id: tool_call.id, content: result, }) continue # 没有工具调用直接返回最终回答 final_answer message.content print(f - 最终回答: {final_answer}) return final_answer return 已达到最大执行步数任务终止。请检查是否缺少必要的工具或参数。 if __name__ __main__: while True: user_input input(请输入想查询的问题输入 q 退出) if user_input.strip().lower() q: break answer run_agent(user_input) print(f\n最终输出\n{answer}\n)这段代码就是上面讲的执行循环的最小实现大概100多行。它不依赖任何重框架调用原生接口就能跑通“推理—调用—反射”—整个核心闭环。关键词在于tool_choiceauto让模型自主决定要不要调、调哪个工具。3.3 实际运行与日志观察我实测了几组输入把Agent的行为记录下来方便你做比照输入一“看一下2024年7月的销售额和支出。”运行日志节选--- Step 1 --- - 调用工具: query_sales, 参数: {month: 2024-07} - 调用工具: query_expense, 参数: {month: 2024-07} --- Step 2 --- - 最终回答: 2024年7月销售额为278,000元共224笔订单支出为168,000元共41项。本月毛利率约为39.6%。这里有个细节值得注意模型在一步之内同时调用了两个工具这在原生工具调用下是支持的。两边的结果一起返回后它才做汇总。也就是说步骤限制指的不是“模型调用次数”而是“推理轮数”只要工具是在同一轮里并行调用的不会额外占步数。输入二“看看六月的利润状况。”--- Step 1 --- - 调用工具: query_sales, 参数: {month: 2024-06} - 调用工具: query_expense, 参数: {month: 2024-06} --- Step 2 --- - 最终回答: 2024年6月销售额为235,000元支出为142,000元利润为93,000元利润率为39.6%。模型自己完成了“利润销售额-支出”的简单推理不需要专门的工具。这种推理能力是模型自带的Agent开发的很大一部分工作就是引导模型用好这个能力而不是把所有计算都硬编码成工具。输入三“哪个季度赚得最多我想比较一下。”我没有在工具里提供季度汇总函数这正好是个压力测试。日志显示--- Step 1 --- - 调用工具: list_months, 参数: {} --- Step 2 --- - 调用工具: query_sales, 参数: {month: 2024-06} - 调用工具: query_sales, 参数: {month: 2024-07} --- Step 3 --- - 调用工具: query_expense, 参数: {month: 2024-06} - 调用工具: query_expense, 参数: {month: 2024-07} --- Step 4 --- - 最终回答: 根据现有数据6月和7月的销售分别为235,000元和278,000元支出分别为142,000元和168,000元。仅看这两个月7月的净利润110,000元高于6月93,000元如需要全年对比请补充更多月份数据。这个案例很有代表性。Agent在发现没有季度汇总工具后自动改为按月查询再自行比较。虽然结果有轻微局限——说“7月净利润110,000元”其实是“278,000-168,000”这里是正确的但整个决策路径是合理的。这也说明了为什么要给Agent足够清晰的工具描述模型能自己变通但前提是你告诉它有什么可用。3.4 关键参数与取舍细节这部分有几个直接影响在线效果的参数值得单独拿出来说max_steps我设置为8对这类查询Agent足够了。如果设置过小复杂任务会频繁提示“达到最大步骤限制”影响体验设置过大则可能让坏Agent反复空转浪费token。model选择这个Demo用轻量模型就可以跑得很好因为工具逻辑简单、参数说明写得清楚。但是如果你的Agent要处理长文档推理建议直接用支持更大上下文窗口的模型。tool_choice设为auto表示让模型自己判断。如果业务上每一步都强制必须调工具也可以设置成required但我不建议这么做因为它会剥夺模型的“终结权”让简单问题也绕一圈工具。temperature模型随机度对Agent场景我建议设置在0到0.3之间。Agent需要稳定地输出工具调用JSON参数值过高会导致格式不稳定如果任务很标准且API的默认值为1.0务必调低。上下文管理上的一个实践教训我试过在每轮都把所有历史工具结果全量传回模型结果长会话很快就触达上下文上限。后来改为“只保留最近两轮的工具结果更早的压缩成摘要”准确率和成本都明显改善。记忆不是越多越好能支撑当前决策的才是有用的上下文。4. 落地避坑指南高频问题与排查实录4.1 上下文越拖越长最后又慢又贵这几乎是每个做Agent的人都会撞上的问题。会话一旦拉长历史消息里包含所有的工具结果、中间推理过程上下文长度呈线性膨胀。原因很好理解但解决方案需要提前设计。我的做法是分层管理第一步工具结果不直接全量塞回上下文而是先在日志里格式化、截断长的内容第二步较早的对话轮次做一个“摘要总结”把原始消息替换成一段概括第三步设置合理的上下文长度上限到达阈值时强制清洗。分层设计之后长会话场景下token成本能降一半以上响应速度也有明显提升。4.2 模型一本正经地编造工具执行结果这是一个危险的场景。有些情况下模型会不调用工具而是直接在回答里“假装”它已经查了数据给出一个看起来很像样的结果。我排查下来通常有三个原因一是工具描述得太模糊模型没意识到必须调用这个工具才能拿到数据二是系统提示词里没有强调“必须通过工具获取数据”三是模型本身质量不够对工具的感知能力比较弱。解决办法是双管齐下。提示词层面明确写上一句“你只能使用工具返回的数据回答用户不得编造任何数据。”代码层面增加一层校验逻辑检查回答中出现的数字是否都在工具结果中有所依据。把这两个护栏加上之后编造结果的情况基本可以消除。4.3 Agent陷入死循环反复调用同一个工具工具返回了一条看似正常、但Agent无法处理的数据时比如查出来的结果为空或者字段格式不符合预期Agent就可能一遍又一遍地尝试同一种方法步数耗尽也不停止。排查方向首先看工具返回的提示信息是否足够明确。比如查询没有数据时如果工具只是返回{}模型不知道下一步怎么走就容易原地打转如果返回“暂无2024-05的支出数据可用月份为2024-06、2024-07”模型就会转而查询可用月份。工具返回的信息质量直接决定Agent下一步的决策质量。所以写工具函数时要考虑“如果数据为空我该给模型一个什么提示才能引导它走上正确的下一步”。再配合程序层的最大步数与重复动作检测——如果在连续步骤里工具名和参数完全相同我就直接中断进入人工处理。双保险后死循环基本能拦在用户感知之前。4.4 延迟和成本双双失控Agent天生比普通的单轮对话要贵、要慢——每次决策都有好几次模型调用而且每一步都是真实成本的累积。优化方向无外乎提前拦、省步数、降context这几条。一个行之有效的办法是在简单问题上“短路”。比如用户只问“有哪些月份有数据”让模型直接回答即可根本不需要走工具调用。我在系统提示词里明确写了“如果问题可以仅凭已知知识回答不要调用工具”这样能拦下一部分无关调用。另一个办法是给工具调用加超时和重试策略防止外部接口超时拖垮整个Agent。技术选型时也可以考虑“双模型策略”用小模型做意图识别和路由把简单请求直接处理复杂请求才交给大模型完整运行Agent循环。实测这一步能省下30%到50%的成本。4.5 工具参数传错模型“理解”不了你的业务这类问题集中在工具描述和大模型理解之间的落差。比如你定义的参数是英文名order_id但用户的表达是“单号”“流水号”模型如果没有逻辑上的关联提示就可能传错参数或直接不调用。解决办法就是在工具描述里写全同义词和格式样例。不要吝啬那几十个字的描述它直接影响准确率。比如订单号参数可以写成订单号(order_id)用户可能会说单号、订单ID、流水号格式为18位数字字符串。看似啰嗦实测对准确率的提升非常显著。5. 从Demo到产品工程化落地的几条铁律5.1 没有评估体系Agent就没法上线很多人Demo跑通了就急着上线这是最大的误区。LLM本身的随机性意味着每个Agent版本都是一次实验没有统一的评估标准你无法判断新提示词到底改好了还是改坏了。我的做法是搭建一个评估集准备50到100条覆盖典型场景的测试用例每一条都标注好“标准正确动作”和“标准最终回答的关键要素”。每次修改提示词、工具描述或模型参数都跑一遍评估集对比通过率。这个习惯能帮你避开绝大多数线上事故也是迭代速度的保证。评估维度建议分四层工具调用准确率该调的工具是否调用了、不该调的有没有乱调、参数是否全部正确。最终回答正确率数字、结论是否来自工具结果。安全合规通过率是否输出了不合规的内容。无效步数占比平均每个任务空转多少步这个指标直接反映效率。5.2 日志和可观测性Debug的救命稻草Agent的调试难度比传统代码高出不少因为它每一步都是模型自主决策的结果不留下完整日志出了问题你根本无从回溯。我的建议是尽早从第一行代码开始就记录完整日志。每条日志需要包含完整的时间戳、用户输入、系统提示词、模型返回的完整消息内容、工具名称与参数、工具返回结果、当前步数、本轮token用量。上线后配合监控面板实时看每轮的token消耗和失败率。没有这套东西Agent出问题时你连“它在哪一步走错的”都看不出来。5.3 从小范围场景切入快速验证再扩展最后一个落地层面的经验是要克制住“做一个全能Agent”的冲动。第一版只覆盖一到两个高频场景把这两个场景做到“能稳定跑100次不出错”再往外扩展。这个策略从两个角度都验证有效——团队研发效率高业务方也愿意配合。任何Agentic系统都是边跑边调的。你不可能在发布前预见到所有用户输入的方式。所以与其花两个月做完美规划不如在一个小范围场景里让它真实地跑起来用线上数据指导迭代。跑通一条完整的业务链路之后再复制到其他场景速度和成功率都会明显提升。6. 最后分享两点实操体会第一点Agent开发与传统软件工程有一个微妙区别传统代码错在哪里一查便知Agent出错往往不是一个单点错误造成的而是工具描述、提示词、上下文管理、模型选择几个因素叠加的结果。所以出了问题建议不要急着改代码而是看一下完整日志从整个循环链条里找原因。你会惊讶地发现大部分问题都出在工具的边界情况和描述的清晰度上。第二点这个Demo后续可以延伸的方向非常多接上正式的长期记忆存储、把工具函数升级成标准化的API服务、引入多Agent分工协作、增加离线评测的自动化流程。每一步都是独立且值得深入的主题等后续有精力我再逐个展开把踩坑的细节都记录成笔记分享给同好。 
长河君 · 2026/10/22 21:42:46 · 阅读 1.2k Agentic AI开发秘籍：从模型到系统的完整工程实践
说实话过去一年多我几乎把所有精力都砸在了Agentic AI的开发与落地上踩过的坑比写出来的代码还多。从最初只会调API做一个聊天机器人到如今把Agent真正部署到业务系统里处理真实工单最大的认知转变就一句话Agent不是一个模型而是一套系统。这篇秘籍想讲清楚的正是从模型到系统的那道坎——工具调用、记忆管理、规划循环、安全护栏以及最容易被忽略的落地工程化问题。内容主要面向已经跑通过LLM接口、想往Agent方向深入的技术同学也适合正在做技术选型的团队参考。看完之后你能对Agent的核心机制有一个完整的判断框架并且可以直接把这套架构搬到自己的场景里去。很多同学上来就问我“Agent和普通的AI对话接口到底区别在哪”我会用一句话回答普通的对话接口是在答Agent是在做。它会为了完成一个目标自己决定调用什么工具、查什么数据、确认什么结果甚至主动修正自己的行动方案——这背后是一整套工程架构在支撑不是一个模型单独能完成的。1. 先想清楚再动手Agent的本质到底是什么1.1 从Chat到Agent多出来的那三步早期做聊天机器人核心工作就是“输入—上下文—输出”。你给模型一段系统提示词再加上用户的问题它给你一段回答流程就结束了。文本生成得再漂亮它也只停留在“建议”层面不会去执行任何操作。Agent则完全不同。它在生成文本之外多了三步关键动作理解目标、规划路径、执行工具。比如用户对一个客服Agent说“帮我查一下上周的退款工单处理到哪一步了”普通Chat会给你一段话“建议您在工单系统里查看退款状态。”但一个真正的Agent会自己去调用工单查询接口拉取数据判断退款处于审批、打款还是失败状态然后返回一个基于真实数据的结论。这三步动作拆开来看核心多出来的就是工具调用Tool Use、任务规划Planning、记忆管理Memory。这也是Agentic AI开发里最基础也最重要的骨架。1.2 拆开看这套系统里每个零件负责什么大模型本身做决策的“大脑”负责理解意图、拆解任务、生成调用指令。它不是一个执行引擎而是一个推理和决策引擎。工具层让Agent能够“动手”的接口。包括API调用、数据库查询、代码执行、文件操作等相当于给模型装上了手和脚。记忆层分为短期记忆本次会话的上下文和长期记忆跨会话的知识、偏好、历史记录。没有记忆的Agent每轮对话都是“失忆状态”。规划层把一个大目标拆解成若干子任务决定先做什么后做什么。复杂场景下还需要根据执行结果的反馈动态调整规划。执行层把模型的决策落成真实的动作并把工具返回的结果回传给模型进入下一轮推理。理解了这几个零件的分工后面做技术选型和架构设计就有了判断基准。比如你的场景根本不需要跨会话记忆就不用花大力气去接向量数据库你的业务主要是单步骤工具查询也就不用上复杂的规划框架。1.3 哪些场景真正需要Agent做技术选型时最忌讳“为了Agent而Agent”。我的经验是可以从两个维度判断判断维度说明不需要Agent的情况是否需要操作外部系统要查数据库、调API、改配置只需要生成文本建议是否需要动态决策要根据中间结果决定下一步用户意图单一且固定如果一个流程只需要一次模型调用、不需要访问外部数据和系统那直接写死普通对话接口就行。反之如果牵涉到多步决策、多个系统联动比如“根据工单内容给客户回邮件并把处理状态同步给财务系统”Agent才真正有发挥空间。2. 五个核心组件逐一拆解从原理到选型2.1 工具调用让模型拥有“手脚”的关键机制工具调用Function Calling是Agent区别于普通对话最核心的能力。它的工作逻辑非常直观系统先告诉模型“你可以用哪些工具每个工具接收什么参数”然后模型在推理时自动选择要不要调用、调用哪个、传什么参数最后由你的工程代码来真正执行这个工具并把执行结果返回给模型继续推理。工具定义里最要紧的是参数说明要写得足够细。模型没有“常识”去猜测你的接口需要什么格式它只能根据你给的描述来做判断。举个例子定义一个“查询订单”工具如果只写“查询订单”模型可能把时间参数传成ISO格式、把订单号传成字符串如果你写清楚“时间格式为YYYY-MM-DD订单号是纯数字字符串”准确率会大幅提升。工具描述写得越精确模型调用就越少出错——这个细节对落地效果影响极大。当前主流的模型厂商都原生支持工具调用从接口层面就能返回结构化的工具调用请求不需要自己去解析非结构化的文本。如果你的模型不支持也可以让模型输出JSON格式的指令再解析但稳定性和准确率会差一截。做技术选型时优先选支持原生工具调用的模型。2.2 记忆系统短期与长期要分开设计记忆是Agent开发和落地里最容易踩坑的模块。很多初次尝试的朋友把“把所有历史消息都塞进上下文”等同于记忆结果很快就撞上上下文窗口的瓶颈又慢又贵。正确的做法是把记忆分成两个层面。短期记忆就是当前任务执行过程中的上下文相对好办通常就是维护一个消息列表配合摘要和压缩来控制长度。长期记忆则需要接入持久化存储比如向量数据库把重要的用户偏好、历史决策、业务数据按语义存储下来需要时再检索召回。这里有个实操上的建议不要一股脑把记忆内容全部塞给模型。我的做法是先让模型判断“当前这次请求需要哪些历史信息”再根据判断结果去检索相关片段上下文质量和token成本都好得多。做记忆设计时要区分清楚哪些信息值得存、哪些信息只是临时状态记忆并不是存得越多越好。2.3 规划能力从单步到多步的关键跨越单工具的Agent做多了以后你会发现很多真实业务场景根本不是一步能完成的。比如“分析客户反馈并生成周报摘要”至少需要两个动作先把原始反馈数据拉出来然后调用分析模块做汇总。这就涉及任务规划。规划能力的实现方式有很多种。最简单的做法是让模型自己在每一步推理中决定下一个动作走一步看一步这是ReAct范式Reasoning Acting 的结合即边推理边行动适合大多数业务场景。复杂一点的做法是引入规划器允许模型先把一个目标拆成多个子任务再逐一执行。后者适合步骤比较固定、子任务可以并行处理的场景但实现复杂度也更高。我的经验是先从走一步看一步的ReAct开始不要一上来就上复杂规划框架。跑通了以后再去考虑是不是有一些步骤可以固定成流水线。现实中大多数Agent用ReAct加简单的呼吸设计就能达到很好的效果盲目堆复杂度只会让调试难度指数上升。2.4 执行循环把决策跑成一个闭环有了大模型、工具、记忆和规划还需要一个把它们串起来的执行循环。这个循环是整个Agent运行的“生命线”可分为四步获取用户输入整理成系统提示词和上下文。模型进行推理输出两种结果之一要么直接生成最终回答要么生成一组工具调用请求。如果是调用工具工程代码负责实际执行拿到执行结果后回传给模型重复第2步。到达终止条件无工具调用、达到最大步骤数、用户中断后返回最终结果。这里最关键的是循环容忍度的设计。默认最多让Agent连续执行多少步必须提前定好。不然Agent在某个工具返回异常格式时有可能反复重试既耗时又烧token。我通常把默认步数限制在8到10步特定复杂场景再单独调高。2.5 安全护栏落地前必须考虑的边界任何Agent只要接入了工具和外部系统就必须考虑安全边界。这块如果前期不做上线后的每一个事故都会让你后悔当初的偷懒。最基础的护栏有六个方面权限最小化给Agent的工具权限只能覆盖当前业务所需绝不能用管理员权限跑所有操作。比如客服Agent只能查工单、不能删工单。敏感操作人工确认涉及发送消息、删除数据、转账付款这类不可逆操作要设置人工审批节点。输入过滤与提示注入防护用户的输入可能包含恶意指令要防止攻击者把Agent“带偏”关键动作前加校验。输出内容审核生成的内容需要经过合规扫描或敏感词过滤才能对外展示。操作审计日志Agent每一步调用了什么工具、传了什么参数、拿到了什么结果全部留痕。超时与熔断工具调用的超时时间要设置好外部接口大概率比你想的要不稳定提前兜住。安全防线做得越早成本越低等出了事故再回头补代价往往十倍不止。3. 从零跑通一个Agent账务查询Demo全程手记3.1 场景与工具设计为了让你能把上面讲的理论直接落成代码我在这里复盘一个真实的Demo——某公司内部用的“账务查询Agent”。这个Agent要做的事很简单用户用自然语言描述查账需求Agent自己决定查哪张表、按什么条件查然后把结果整理成可读结论。整套结构里模型调用使用OpenAI-compatible的接口方式工具层就是几个标准化的查库函数执行循环用Python管理整体的复杂度是可控的适合作为入门复刻的模版。工具层我设计了三个函数函数名称功能关键参数query_sales按月份查询销售额month格式YYYY-MMquery_expense按月份查询支出month格式YYYY-MMlist_months列出有数据的月份无参数为什么要把计算逻辑都写在工具函数里因为工具函数让Agent只需关注“选哪个工具、传什么参数”而不是自己去做复杂的日期计算和数据聚合。这样的活模型干不了也不该干工具层才是真正干重活的地方。还有一件事让查询类工具只接受“月份类别”这类结构化参数可以有效避免用户用自然语言发起工具调用时带来的混乱。比如用户说“看看七月的花费多不多”模型会根据工具描述把“七月”转成“2024-07”再传给query_expense。这样做的好处是整个Agent的关键数据操作逻辑都是可测试、可追踪的。3.2 代码实现与逐段解读# agent_core.py # 依赖openai1.0, python-dotenv import json import os from openai import OpenAI client OpenAI(api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL)) # 工具函数实现 def query_sales(month: str) - str: 按月份查询销售额 data { 2024-06: {amount: 235000, orders: 186}, 2024-07: {amount: 278000, orders: 224} } if month in data: return json.dumps(data[month], ensure_asciiFalse) return json.dumps({error: f{month}没有销售数据可先调用list_months查看可用月份}) def query_expense(month: str) - str: 按月份查询支出 data { 2024-06: {amount: 142000, items: 36}, 2024-07: {amount: 168000, items: 41} } if month in data: return json.dumps(data[month], ensure_asciiFalse) return json.dumps({error: f{month}没有支出数据可先调用list_months查看可用月份}) def list_months() - str: 列出有财务数据的月份 return json.dumps([2024-06, 2024-07], ensure_asciiFalse) TOOLS [ { type: function, function: { name: query_sales, description: 按月份查询销售额数据。月份格式为YYYY-MM。, parameters: { type: object, properties: { month: {type: string, description: 月份格式YYYY-MM} }, required: [month] } } }, { type: function, function: { name: query_expense, description: 按月份查询支出数据。月份格式为YYYY-MM。, parameters: { type: object, properties: { month: {type: string, description: 月份格式YYYY-MM} }, required: [month] } } }, { type: function, function: { name: list_months, description: 列出系统中有财务数据的全部月份列表。, parameters: {type: object, properties: {}} } } ] TOOL_MAP { query_sales: query_sales, query_expense: query_expense, list_months: list_months, } SYSTEM_PROMPT 你是一个财务查询助手。用户会询问公司财务数据你应当调用合适的工具来查询。如果用户没有明确月份先调用list_months查看可用月份。 def execute_tool_call(tool_call): 实际执行工具调用返回工具结果 fn_name tool_call.function.name args json.loads(tool_call.function.arguments) print(f - 调用工具: {fn_name}, 参数: {args}) if fn_name not in TOOL_MAP: return json.dumps({error: f未知工具: {fn_name}}) try: result TOOL_MAP[fn_name](**args) except TypeError as e: result json.dumps({error: f参数错误: {e}}) return result def run_agent(user_input, max_steps8): 主循环推理 - 调用工具 - 回传结果 - 再推理 messages [{role: system, content: SYSTEM_PROMPT}] messages.append({role: user, content: user_input}) for step in range(max_steps): print(f--- Step {step 1} ---) response client.chat.completions.create( modelos.getenv(LLM_MODEL, gpt-4o-mini), messagesmessages, toolsTOOLS, tool_choiceauto, ) message response.choices[0].message if message.tool_calls: messages.append(message) for tool_call in message.tool_calls: result execute_tool_call(tool_call) messages.append({ role: tool, tool_call_id: tool_call.id, content: result, }) continue # 没有工具调用直接返回最终回答 final_answer message.content print(f - 最终回答: {final_answer}) return final_answer return 已达到最大执行步数任务终止。请检查是否缺少必要的工具或参数。 if __name__ __main__: while True: user_input input(请输入想查询的问题输入 q 退出) if user_input.strip().lower() q: break answer run_agent(user_input) print(f\n最终输出\n{answer}\n)这段代码就是上面讲的执行循环的最小实现大概100多行。它不依赖任何重框架调用原生接口就能跑通“推理—调用—反射”—整个核心闭环。关键词在于tool_choiceauto让模型自主决定要不要调、调哪个工具。3.3 实际运行与日志观察我实测了几组输入把Agent的行为记录下来方便你做比照输入一“看一下2024年7月的销售额和支出。”运行日志节选--- Step 1 --- - 调用工具: query_sales, 参数: {month: 2024-07} - 调用工具: query_expense, 参数: {month: 2024-07} --- Step 2 --- - 最终回答: 2024年7月销售额为278,000元共224笔订单支出为168,000元共41项。本月毛利率约为39.6%。这里有个细节值得注意模型在一步之内同时调用了两个工具这在原生工具调用下是支持的。两边的结果一起返回后它才做汇总。也就是说步骤限制指的不是“模型调用次数”而是“推理轮数”只要工具是在同一轮里并行调用的不会额外占步数。输入二“看看六月的利润状况。”--- Step 1 --- - 调用工具: query_sales, 参数: {month: 2024-06} - 调用工具: query_expense, 参数: {month: 2024-06} --- Step 2 --- - 最终回答: 2024年6月销售额为235,000元支出为142,000元利润为93,000元利润率为39.6%。模型自己完成了“利润销售额-支出”的简单推理不需要专门的工具。这种推理能力是模型自带的Agent开发的很大一部分工作就是引导模型用好这个能力而不是把所有计算都硬编码成工具。输入三“哪个季度赚得最多我想比较一下。”我没有在工具里提供季度汇总函数这正好是个压力测试。日志显示--- Step 1 --- - 调用工具: list_months, 参数: {} --- Step 2 --- - 调用工具: query_sales, 参数: {month: 2024-06} - 调用工具: query_sales, 参数: {month: 2024-07} --- Step 3 --- - 调用工具: query_expense, 参数: {month: 2024-06} - 调用工具: query_expense, 参数: {month: 2024-07} --- Step 4 --- - 最终回答: 根据现有数据6月和7月的销售分别为235,000元和278,000元支出分别为142,000元和168,000元。仅看这两个月7月的净利润110,000元高于6月93,000元如需要全年对比请补充更多月份数据。这个案例很有代表性。Agent在发现没有季度汇总工具后自动改为按月查询再自行比较。虽然结果有轻微局限——说“7月净利润110,000元”其实是“278,000-168,000”这里是正确的但整个决策路径是合理的。这也说明了为什么要给Agent足够清晰的工具描述模型能自己变通但前提是你告诉它有什么可用。3.4 关键参数与取舍细节这部分有几个直接影响在线效果的参数值得单独拿出来说max_steps我设置为8对这类查询Agent足够了。如果设置过小复杂任务会频繁提示“达到最大步骤限制”影响体验设置过大则可能让坏Agent反复空转浪费token。model选择这个Demo用轻量模型就可以跑得很好因为工具逻辑简单、参数说明写得清楚。但是如果你的Agent要处理长文档推理建议直接用支持更大上下文窗口的模型。tool_choice设为auto表示让模型自己判断。如果业务上每一步都强制必须调工具也可以设置成required但我不建议这么做因为它会剥夺模型的“终结权”让简单问题也绕一圈工具。temperature模型随机度对Agent场景我建议设置在0到0.3之间。Agent需要稳定地输出工具调用JSON参数值过高会导致格式不稳定如果任务很标准且API的默认值为1.0务必调低。上下文管理上的一个实践教训我试过在每轮都把所有历史工具结果全量传回模型结果长会话很快就触达上下文上限。后来改为“只保留最近两轮的工具结果更早的压缩成摘要”准确率和成本都明显改善。记忆不是越多越好能支撑当前决策的才是有用的上下文。4. 落地避坑指南高频问题与排查实录4.1 上下文越拖越长最后又慢又贵这几乎是每个做Agent的人都会撞上的问题。会话一旦拉长历史消息里包含所有的工具结果、中间推理过程上下文长度呈线性膨胀。原因很好理解但解决方案需要提前设计。我的做法是分层管理第一步工具结果不直接全量塞回上下文而是先在日志里格式化、截断长的内容第二步较早的对话轮次做一个“摘要总结”把原始消息替换成一段概括第三步设置合理的上下文长度上限到达阈值时强制清洗。分层设计之后长会话场景下token成本能降一半以上响应速度也有明显提升。4.2 模型一本正经地编造工具执行结果这是一个危险的场景。有些情况下模型会不调用工具而是直接在回答里“假装”它已经查了数据给出一个看起来很像样的结果。我排查下来通常有三个原因一是工具描述得太模糊模型没意识到必须调用这个工具才能拿到数据二是系统提示词里没有强调“必须通过工具获取数据”三是模型本身质量不够对工具的感知能力比较弱。解决办法是双管齐下。提示词层面明确写上一句“你只能使用工具返回的数据回答用户不得编造任何数据。”代码层面增加一层校验逻辑检查回答中出现的数字是否都在工具结果中有所依据。把这两个护栏加上之后编造结果的情况基本可以消除。4.3 Agent陷入死循环反复调用同一个工具工具返回了一条看似正常、但Agent无法处理的数据时比如查出来的结果为空或者字段格式不符合预期Agent就可能一遍又一遍地尝试同一种方法步数耗尽也不停止。排查方向首先看工具返回的提示信息是否足够明确。比如查询没有数据时如果工具只是返回{}模型不知道下一步怎么走就容易原地打转如果返回“暂无2024-05的支出数据可用月份为2024-06、2024-07”模型就会转而查询可用月份。工具返回的信息质量直接决定Agent下一步的决策质量。所以写工具函数时要考虑“如果数据为空我该给模型一个什么提示才能引导它走上正确的下一步”。再配合程序层的最大步数与重复动作检测——如果在连续步骤里工具名和参数完全相同我就直接中断进入人工处理。双保险后死循环基本能拦在用户感知之前。4.4 延迟和成本双双失控Agent天生比普通的单轮对话要贵、要慢——每次决策都有好几次模型调用而且每一步都是真实成本的累积。优化方向无外乎提前拦、省步数、降context这几条。一个行之有效的办法是在简单问题上“短路”。比如用户只问“有哪些月份有数据”让模型直接回答即可根本不需要走工具调用。我在系统提示词里明确写了“如果问题可以仅凭已知知识回答不要调用工具”这样能拦下一部分无关调用。另一个办法是给工具调用加超时和重试策略防止外部接口超时拖垮整个Agent。技术选型时也可以考虑“双模型策略”用小模型做意图识别和路由把简单请求直接处理复杂请求才交给大模型完整运行Agent循环。实测这一步能省下30%到50%的成本。4.5 工具参数传错模型“理解”不了你的业务这类问题集中在工具描述和大模型理解之间的落差。比如你定义的参数是英文名order_id但用户的表达是“单号”“流水号”模型如果没有逻辑上的关联提示就可能传错参数或直接不调用。解决办法就是在工具描述里写全同义词和格式样例。不要吝啬那几十个字的描述它直接影响准确率。比如订单号参数可以写成订单号(order_id)用户可能会说单号、订单ID、流水号格式为18位数字字符串。看似啰嗦实测对准确率的提升非常显著。5. 从Demo到产品工程化落地的几条铁律5.1 没有评估体系Agent就没法上线很多人Demo跑通了就急着上线这是最大的误区。LLM本身的随机性意味着每个Agent版本都是一次实验没有统一的评估标准你无法判断新提示词到底改好了还是改坏了。我的做法是搭建一个评估集准备50到100条覆盖典型场景的测试用例每一条都标注好“标准正确动作”和“标准最终回答的关键要素”。每次修改提示词、工具描述或模型参数都跑一遍评估集对比通过率。这个习惯能帮你避开绝大多数线上事故也是迭代速度的保证。评估维度建议分四层工具调用准确率该调的工具是否调用了、不该调的有没有乱调、参数是否全部正确。最终回答正确率数字、结论是否来自工具结果。安全合规通过率是否输出了不合规的内容。无效步数占比平均每个任务空转多少步这个指标直接反映效率。5.2 日志和可观测性Debug的救命稻草Agent的调试难度比传统代码高出不少因为它每一步都是模型自主决策的结果不留下完整日志出了问题你根本无从回溯。我的建议是尽早从第一行代码开始就记录完整日志。每条日志需要包含完整的时间戳、用户输入、系统提示词、模型返回的完整消息内容、工具名称与参数、工具返回结果、当前步数、本轮token用量。上线后配合监控面板实时看每轮的token消耗和失败率。没有这套东西Agent出问题时你连“它在哪一步走错的”都看不出来。5.3 从小范围场景切入快速验证再扩展最后一个落地层面的经验是要克制住“做一个全能Agent”的冲动。第一版只覆盖一到两个高频场景把这两个场景做到“能稳定跑100次不出错”再往外扩展。这个策略从两个角度都验证有效——团队研发效率高业务方也愿意配合。任何Agentic系统都是边跑边调的。你不可能在发布前预见到所有用户输入的方式。所以与其花两个月做完美规划不如在一个小范围场景里让它真实地跑起来用线上数据指导迭代。跑通一条完整的业务链路之后再复制到其他场景速度和成功率都会明显提升。6. 最后分享两点实操体会第一点Agent开发与传统软件工程有一个微妙区别传统代码错在哪里一查便知Agent出错往往不是一个单点错误造成的而是工具描述、提示词、上下文管理、模型选择几个因素叠加的结果。所以出了问题建议不要急着改代码而是看一下完整日志从整个循环链条里找原因。你会惊讶地发现大部分问题都出在工具的边界情况和描述的清晰度上。第二点这个Demo后续可以延伸的方向非常多接上正式的长期记忆存储、把工具函数升级成标准化的API服务、引入多Agent分工协作、增加离线评测的自动化流程。每一步都是独立且值得深入的主题等后续有精力我再逐个展开把踩坑的细节都记录成笔记分享给同好。