AI Agent构建全攻略从技术原理到工程实践程序员必备指南建议收藏做了几年LLM应用开发我越来越确定一件事2024年之前大家聊的是“怎么把大模型接进业务”2024年以后大家聊的是“怎么让大模型自己把活儿干完”。这中间的跨越就是从写Prompt到构建Agent的跨越。很多程序员朋友问我Agent到底难不难学我的回答是原理不难工程很难。难在工具调用怎么稳定、记忆怎么不崩、循环怎么不死、成本怎么可控。这篇东西我想一次性把这些讲透。文章会从Agent的底层组成讲到工程落地既有原理拆解也有能直接抄的代码片段最后还有我在实际项目里踩过的坑和排查思路。无论你是刚接触LLM的初级工程师还是已经在做RAG应用想往Agent方向升级的开发者这篇都值得你花20分钟看完建议先收藏再慢慢对照实操。1. 先从“数字员工”的视角理解Agent1.1 从“问答机器人”到“数字员工”的认知跃迁我一直觉得很多人在Agent上栽跟头不是因为代码写得不好而是因为脑子里对Agent的认知模型还是错的。普通的ChatBot是“一问一答”用户说一句模型回一句上下文全靠聊天记录硬撑。Agent完全不是这个逻辑。Agent更像一个拿到了任务就自己去拆解、自己找工具、自己执行、自己检查结果的数字员工。你给的不是问题而是目标。举个例子。传统问答应用用户问“帮我看看这个月的销售数据”你做的就是把数据库里的数据查出来往Prompt里一塞让模型总结。Agent场景下用户说的是“帮我分析一下本月销售异常并且生成一份可分享的报告”。这个任务需要Agent自己完成几步先定位数据源再调SQL查询接口拿到数据后做统计分析发现异常点然后调用文档生成工具最后把报告链接返回给用户。这里面每一环都需要模型做决策每一步决策都可能出错。所以Agent工程的核心不是把模型跑起来而是把模型跑对、跑稳、跑得可追溯。1.2 现在入局Agent时机刚好有人问现在Agent技术成熟了吗我的回答是不那么成熟但恰恰是这种“没完全定型”的阶段最适合程序员切入。你看底层模型的能力2023年的时候调用工具还不稳定经常模型说“我要调用工具”结果参数给你传错。现在的开源和闭源模型在Function Calling上的准确率已经能从“勉强能用”进化到“基本可靠”了。再加上各种支持流式输出、结构化输出的推理框架越来越成熟对话记忆、向量检索、权限控制这些基础设施也都有现成的轮子。所以我的判断是现在不上车再过一年框架又会叠一层概念又会包装出好几个新词再学成本只会更高。Agent的技术壁垒不在“理解概念”而在工程经验——这种东西只有踩坑才能积累越早踩坑越早成为优势。1.3 这篇文章能帮你打通什么这篇内容我按照我自己做项目的思路来排先讲清楚一个Agent到底由哪些部分组成每个部分在系统里承担什么职责再讲技术选型包括模型、编排框架、工具定义方式怎么取舍然后给出可落地的代码配置和核心环节实现包括工具调用、记忆管理、执行循环最后是我真正想分享的部分——常见问题、排查套路、成本治理和上线心得。看完之后你至少能具备独立搭建一个中等到复杂程度Agent系统的能力。2. Agent的五个核心组件缺一不可Agent系统不管怎么包装拆开来看永远是五块东西大脑、规划器、工具箱、记忆、反馈机制。2.1 大脑LLM是推理核心但它不是万能的所有Agent的“智力”都来自大语言模型但这颗“大脑”负责的是理解和推理不是存储和计算。很多初学者把什么都往模型里塞让模型既当数据库又当计算器这是最典型的错误。我习惯把LLM在Agent里的作用分成三层意图理解层把用户的自然语言请求解析成机器可执行的任务描述。决策规划层根据当前状态决定下一步该调用哪个工具、给什么参数。结果解释层把工具返回的结构化数据整理成用户能看懂的结论。这三层用到的推理策略不一样。意图理解要稳规划决策要快结果解释要准。如果在工程上你把这三件事混在一起写后面调试的时候一定会疯——因为你会分不清到底是哪个环节出了错。2.2 工具箱Function Calling是Agent的“双手”没有工具的Agent只是个聊天机器人有了工具的Agent才是个执行者。工具的本质是把外部能力封装成模型可调用的函数接口。这些函数可以是一个查询数据库的SQL、一个调用内部API的HTTP请求、一个执行Python代码的沙箱、一个发邮件的SMTP封装等等。关键在于工具的“接口描述”必须足够清晰让模型能理解这个工具是干嘛的、需要什么参数、会返回什么。我在工程实践中发现工具描述写得好不好直接决定Agent的调用成功率。一个模糊的描述模型就敢瞎传参数一个明确的描述模型往往一次就能给对。后面第4节我会给一个详细规范这里先记住工具定义是Agent工程里投入产出比最高的事情值得你花最多时间打磨。2.3 记忆短期记忆和长期记忆必须分开管理Agent和人一样记忆力决定它能做多复杂的事。短期记忆指的是当前任务执行过程中的上下文通常通过把对话历史塞进模型上下文窗口来实现。它的特点是快、直接但窗口有限塞多了不仅贵模型还可能“忘”了前面更重要的信息。长期记忆则是把有价值的信息持久化存储在需要的时候检索出来塞回上下文。最常见的实现方式是向量数据库做语义检索也有用结构化数据库存关键事实的。我在项目里一般用“两级记忆”方案当前任务的所有中间输出都放在短期记忆里一旦任务完成就把结构性结论抽取出来存进长期记忆下次类似任务来了先检索长期记忆再开工。这个方法极大提升了Agent在多轮复杂任务里的稳定性。2.4 行动周期感知-规划-行动-观察的循环Agent执行任务时本质上是在跑一个循环感知获取用户输入和当前状态。规划决定下一步做什么是直接回答还是调用工具。行动调用对应工具拿到结果。观察把工具返回的观察结果放回上下文。再规划基于新的观察结果决定下一步直到任务完成。这个循环就是Agent之所以是“智能体”而不是“接口调用”的原因——它能根据中间结果动态调整自己的下一步而不是走一条写死的链路。但循环也有致命问题循环如果失控Agent就会反复调用同一个失败的工具浪费算力也不出结果。所以工程上必须给循环设置上限比如最大轮次默认10轮超过就强制中断把“部分结果异常状态”返回给用户。2.5 反馈机制让Agent知道自己干得怎么样最后一个容易被忽略的组件是反馈机制。Agent执行完一个动作之后怎么知道这件事干成了没有怎么知道结果是好的还是不合理的我在实践中总结了一套“双重校验法”硬校验检查工具调用是否成功、返回格式是否符合预期、数据是否完整。这是程序层面的校验写起来很机械但必须有。软校验把工具返回结果再交给模型做一次“自评”让模型判断这个结果是否符合任务目标、有没有异常值、需不需要补充信息。软校验比较费token但对于高价值的任务环节比如数据分析、报告生成特别值得因为它能帮Agent在交付结果之前自我纠错。2.6 组件之间的协作关系一句话总结把五块组件串起来的架构大概是这样的用户请求进来短期记忆记录上下文规划器结合记忆和工具列表决定行动工具执行并返回结果结果经过校验后回写记忆循环继续直到任务完成最后把关键结论存入长期记忆。理解了这张“协作图”你就不会再被各种新概念带偏。什么“Plan-and-Execute”、“ReAct”、“多Agent协作”本质上都只是这个基本架构的变体。3. 技术选型框架、模型和基础设施怎么取舍3.1 编排框架选一个生态成熟的别再造轮子现在市面上有大量Agent编排框架有的偏轻量、有的偏重量有的适合做实验、有的适合做生产。我个人的选型标准有三条生态成熟度框架的文档全不全、社区活跃不活跃、踩坑案例多不多。我不会选一个刚发布一个月的框架来做生产系统。可观测性框架能不能方便地输出每一步的调用日志、token消耗、耗时。这一点极度重要但很多框架做得并不好。可控性你可以方便地自定义循环逻辑、记忆策略和错误处理而不是只能按框架预设的流程走。我自己在生产项目里用得最多的是LangGraph风格的状态图编排方式因为它把Agent循环建模成一张图节点是“模型调用”、“工具执行”、“条件判断”边是状态流转调试和可视化都比较直观。3.2 模型选择参数不是越大越好关键是匹配任务很多人一上来就选最大参数的商业模型觉得越强越好。但做Agent工程你不能只看模型“聪明不聪明”还要看以下这几个维度维度选择逻辑备注指令遵循稳定性模型能否严格按照工具描述传参这是Agent的命门上下文长度需要容纳多少短期记忆长度大不等于效果好还要看长文本下的注意力质量推理速度Token首字延迟和生成速度Agent是串行循环每一步延迟都会叠加成本单次任务平均消耗token数长任务要按全循环估算部署方式API调用还是私有化部署数据合规场景慎用外部API我的建议是任务的核心推理环节用一个中等偏上的模型外围的简单分类、提炼、格式化用一个小模型。这种“大小模型混合”的方案能把单任务的成本降低40%到60%而体验几乎不打折。还有一个容易被忽略的点模型版本要固定。生产环境里模型一升级Prompt可能就失效了。所以线上必须锁定模型版本新版本先在测试环境跑一轮回归再切流量。3.3 工具定义JSON Schema是通行语言无论你选哪个框架工具定义最终都会被序列化成JSON Schema格式给模型识别。一个标准的工具定义通常长这样{ name: query_sales_data, description: 查询指定日期范围内的销售数据返回按日期聚合的订单量和销售额。, parameters: { type: object, properties: { start_date: { type: string, description: 起始日期格式为YYYY-MM-DD }, end_date: { type: string, description: 结束日期格式为YYYY-MM-DD }, region: { type: string, enum: [华东, 华北, 华南, 西南], description: 区域不传则查询全国 } }, required: [start_date, end_date] } }注意几个细节description要写清楚这个工具是干嘛的、什么时候该用它、什么时候不该用它。模型是靠描述来选工具的描述含糊它就会乱选。参数要尽量用enum限定取值范围模型在提供选项时出错的概率远低于自由生成。required字段只把真正必需的参数放进去非必需的不要写给模型更多泛化空间。3.4 基础设施向量库、缓存和沙箱最后简单说说基础设施层。向量数据库用于长期记忆和知识检索。选型时我比较关注检索质量、写入吞吐量、有没有过滤条件比如按用户ID过滤。缓存层非常关键。同样的工具请求如果结果是一样的没必要让Agent重复调用。按请求参数哈希做一层结果缓存能大幅降低延迟和成本。安全沙箱很必要凡是Agent要执行代码或者操作外部资源都必须放进受限环境里不能让Agent裸奔在你的生产服务器上。4. 工程化实操从零配置一个完整Agent说完了原理和选型这一节直接上代码。我以Python生态为例搭建的是一个“数据分析Agent”它能理解用户请求、写SQL查询数据库、做简单分析、生成报告。4.1 搭建基础环境假设你已经有Python 3.10环境先安装核心依赖。这里我以一款主流的开源Agent编排库为例pip install agent-framework langchain-openai pandas提示框架名称我做了泛化处理实际选型时你用你熟悉的编排库即可核心概念大同小异。然后是初始化模型客户端。注意把API Key放到环境变量里不要硬编码在代码中import os from openai import OpenAI client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL) # 如果走代理网关或者私有化模型接口 ) model_name your-main-model-name4.2 定义Agent的工具集数据分析Agent最核心的工具是“查询数据表”和“生成图表报告”。我拿查询工具举例import json import sqlite3 from typing import Any def query_sales_data(start_date: str, end_date: str, region: str 全国) - str: 查询指定日期范围内的销售数据。 Args: start_date: 起始日期格式YYYY-MM-DD end_date: 结束日期格式YYYY-MM-DD region: 区域可选华东/华北/华南/西南默认全国 Returns: JSON格式的聚合结果 conn sqlite3.connect(sales.db) cur conn.cursor() if region 全国: cur.execute( SELECT date, region, SUM(order_amount) as total_amount, COUNT(*) as order_count FROM sales WHERE date BETWEEN ? AND ? GROUP BY date, region, (start_date, end_date) ) else: cur.execute( SELECT date, region, SUM(order_amount) as total_amount, COUNT(*) as order_count FROM sales WHERE date BETWEEN ? AND ? AND region ? GROUP BY date, region, (start_date, end_date, region) ) rows cur.fetchall() conn.close() return json.dumps([{ date: r[0], region: r[1], total_amount: r[2], order_count: r[3] } for r in rows], ensure_asciiFalse)这个函数很简单但注意我在docstring里把每个参数的含义都写清楚了。模型会读取这个docstring来决定怎么调用所以写工具就是在写面向模型的文档不是面向人的注释。接着把这个工具注册进Agent的“工具箱”from agent_framework import Tool query_tool Tool( namequery_sales_data, description查询指定日期范围内的销售数据返回按日期和区域聚合的订单量和销售额。适用于销售分析、趋势查看、异常排查等场景。, funcquery_sales_data ) tools [query_tool]4.3 构建Agent主循环核心循环就是“模型决定调哪个工具执行工具把结果返回模型模型再决定下一步”。代码写出来是这样的from agent_framework import Agent # 定义系统提示词 system_prompt 你是数据分析助手。你拥有查询销售数据的工具。 你的职责是 1. 理解用户的业务问题。 2. 当需要数据时调用query_sales_data工具获取数据。 3. 基于数据结果进行推理给出清晰的分析结论。 4. 如果数据不足以回答问题明确说明缺失信息并给出建议。 操作规范 - 工具调用失败时仔细阅读错误信息修正参数后重试。 - 当数据返回结果为空时不要编造数据要如实告知用户。 - 最终回答必须基于工具返回的真实数据。 agent Agent( modelmodel_name, system_promptsystem_prompt, toolstools, max_steps10, memory_kindwindow, memory_window_size20 )然后启动一次任务response agent.run(分析一下2024年11月华东区的销售趋势和10月相比变化如何) print(response)执行过程中框架会自动完成这样的循环Agent判断需要调用query_sales_data传入start_date2024-10-01、end_date2024-11-30、region华东。工具执行返回两个月的聚合数据。Agent拿到数据后分析11月销售额环比下滑还是增长哪个品类的变化最明显。如果数据粒度不够Agent可能再次调用工具查询明细。最后组织语言输出分析结论。4.4 记忆管理从“一次性”到“可持续”上面这个Agent每次run都是全新的没有记忆。真实业务里用户可能连续追问或者隔几天回来继续聊同一个话题。所以要在Agent外面套一层记忆管理。我的方案是双轨制短期记忆——用ConversationBufferWindowMemory保留最近N轮对话这个N根据模型上下文和业务复杂度来定我一般设20到40轮之间。太小了用户多问几句就断片太大了token成本飙升。长期记忆——每次任务结束后LLM提炼出三条以内的关键结论存进向量数据库用向量检索的方式把相似历史任务的结果捞回来填充上下文。代码如下from agent_framework import VectorMemory def extract_and_store_summary(agent_run_id, user_query, final_answer): summary client.chat.completions.create( modelsmall-model, messages[ {role: system, content: 从回答中提炼不超过3条可复用的核心结论输出JSON数组每个元素是{fact: 结论内容, topic: 主题标签}}, {role: user, content: f用户问题{user_query}\n回答{final_answer}} ] ) facts parse_json(summary.choices[0].message.content) memory VectorMemory(embedding_modelyour-embedding-model) for fact in facts: memory.add(fact[fact], metadata{topic: fact[topic], agent_run: agent_run_id}) # 任务完成后调用 extract_and_store_summary(agent_run_id, user_query, response)这套机制跑起来之后Agent会表现出一种“越用越聪明”的感觉——因为每次任务总结的结论会在下次任务里作为参考上下文被召回。4.5 错误处理和循环保护Agent最让人头疼的问题之一是“死循环”。我建议在框架层做这三个保护最大步数限制max_steps10超过直接终止返回当前已完成的步骤和终止原因。重复工具调用检测如果模型连续三次用相同的参数调用同一个工具说明它陷入死循环了强制打断并提示模型换策略。工具异常兜底工具函数里任何异常都要捕获返回结构化的错误信息给模型而不是抛出堆栈让模型懵掉。def safe_call_tool(tool, arguments: dict) - str: try: result tool(**arguments) return json.dumps({status: success, data: result}, ensure_asciiFalse) except TypeError as e: return json.dumps({status: error, error: f参数类型错误: {str(e)}}) except Exception as e: return json.dumps({status: error, error: f执行异常: {str(e)}})注意我把错误信息用JSON返回给模型模型读到之后可以自行判断是重新传参还是换一个工具。如果错误信息是纯文本裸堆栈模型往往不知道下一步该干嘛。4.6 日志与可观测性Agent不像传统API一次请求内部可能跑了几十个步骤每一步的输入输出都要留痕。我的做法是在Agent的每个节点埋日志输出结构化JSON{ timestamp: 2024-12-01T10:23:45Z, agent_run_id: run_12345, step: 3, node: model_call, input: 用户问题..., output: 调用工具query_sales_data参数..., cost: {prompt_tokens: 1200, completion_tokens: 150}, latency_ms: 850 }有了这种日志后面排查问题就变得非常高效——用户说“回答错了”你把run_id拿来一查每一步干了啥一目了然。没有日志的Agent项目出问题就像在深山里找一只迷路的猫。5. 高频踩坑与排查方案5.1 工具描述含糊模型传参全靠猜现象模型频繁把工具参数传错比如把日期格式从YYYY-MM-DD传成YYYY/MM/DD或者把“华东”传成大写的“华东”。排查首先看工具描述里有没有明确示例。只写“日期”是不够的要写“日期格式为YYYY-MM-DD例如2024-11-01”。我的标准做法是在参数描述里给一个明确的示例值。模型对示例的敏感度远高于抽象描述。另外能用enum的地方坚决用enum模型在封闭集合里做选择准确率比开放生成高很多。5.2 上下文爆炸导致“记忆错乱”现象任务执行到一半模型开始重复问已经知道的信息或者把前面的结论搞混了。原因短期记忆的窗口管理太粗暴所有中间结果都在上下文里堆积模型注意力被冗余信息干扰。解决做“关键信息压缩”。在每步工具执行完之后用一个小模型把这一步的输出压缩成“一句话摘要”再放回上下文。这样长期运行也不会把上下文塞爆。这个操作看似多了几次小模型调用但和主模型动辄上万token的上下文相比成本低得多。5.3 Agent“嘴硬”没数据也敢胡说现象工具返回空数据但Agent在最终回答里编了一段“分析结论”。这是幻觉在Agent场景下的经典表现。规避办法有两个维度第一在System Prompt里明确写“如果没有数据支撑直接说明数据缺失禁止推测。”第二在工具结果里做标记让模型明确感知“这是空结果”。if not rows: return json.dumps({status: empty, message: 查询范围内无数据}, ensure_asciiFalse)模型看到status: empty就会更好地说“该时间段没有数据”而不是自己编一堆趋势分析。5.4 循环卡死成本持续燃烧现象Agent反复调用同一个工具或者在一个决策点上反复横跳token消耗以肉眼可见的速度增长。解决我上面提到的“重复调用检测”就是我踩过坑之后加上去的。具体实现是维护一个最近五步的“调用指纹”列表如果当前步骤的模型输出和最近某一步相同直接给模型返回一个警告“你已经尝试过相同操作请换一种方式或终止任务。”这条警告非常有效。加了之后我的Agent项目死循环率降了大约80%。5.5 外部接口的不稳定现象Agent调第三方API第三方偶尔超时或者返回502Agent直接崩溃。解决包一层带超时和重试的封装。注意重试策略要写退避逻辑不要瞬间疯狂重试因为第三方服务恢复也需要时间。import time def call_with_retry(func, max_retry3): for i in range(max_retry): try: return func() except TimeoutError: time.sleep(2 ** i) return json.dumps({status: error, error: 外部接口多次超时请稍后重试})5.6 问题排查速查表症状可能原因优先排查点工具参数频繁传错工具描述不完善、缺示例检查JSON Schema里的description和enum答非所问短期记忆窗口被冗余信息占满加关键信息压缩、裁剪无关工具输出死循环、重复调用决策条件不够明确加重复调用检测和最大步数限制数据为空还硬编结论幻觉、缺少空结果标记工具返回空状态Prompt强调禁止推测外部调用超时第三方API不稳定加超时重试和退避策略上下文越来越慢上下文过长、模型注意力退化启用长期记忆、减少单步输出体积6. 从Demo到线上性能优化与平稳落地6.1 评估体系Agent也要有“单元测试”传统软件的单元测试在Agent世界里对应的是一组“评测用例集”。每个用例包含模拟的用户输入、预期的工具调用序列、可接受的结果范围。我自己维护了一个eval_suite.json里面放了三十多类业务问题的期望行为。每次改Prompt、换模型版本、调工具描述我都先在评测集上跑一遍回归看通过率有没有下降。Agent的“评测通过率”就是你的上线安全网。有个细节评测不能只看最终答案对不对还要看中间的工具调用序列是否合理。一个Agent虽然最终答对了但中间绕了弯路、多调了几次没必要的工具说明它的规划能力还有问题。我通常同时记录“工具调用次数成本”作为优化指标。6.2 降低延迟的四个小技巧Agent是串行循环每一步模型调用都是几百毫秒几步下来轻松超过三五秒。用户等不了。我在线上常用的降延迟手段并行工具调用当模型明确需要多个独立数据时让框架自动并行调用工具而不是串行等。这个优化能把总耗时压缩一半。小模型前置分类在大模型进入之前用一个极快的小模型判断用户需求类型走不同的Prompt和工具集减少大模型的无效规划。结果缓存热门查询比如“今天销售额多少”如果数据源分钟级更新完全可以直接走缓存返回让Agent只处理真正需要动态规划的任务。流式输出先让模型输出“分析框架”给用户看再做工具调用这样用户在等待的过程中有反馈体感会好很多。6.3 成本治理别让Agent成为吞金兽Agent的成本和ChatBot不是一个量级。一个复杂任务动辄调三五次工具每次工具调用都涉及一次模型推理单任务成本可能是普通问答的十倍。我的成本控制三板斧每一步都记账。日志里记token消耗按用户、按会话、按任务类型聚合看清楚钱到底烧在哪个环节。能省则省的模型选择。不是所有决策都需要大模型“深度思考”工具结果整理、摘要提炼、格式转换这些脏活累活全丢给小模型干。任务分级限流。高价值、复杂的任务用完整Agent流程简单任务走预设流程和小模型别让所有流量都挤进“豪华版”Agent。6.4 多Agent协作的演进方向如果单个Agent的业务复杂度继续上升你会碰到一个尴尬时刻Prompt越长越乱工具列表越多越容易选错。这时候就该考虑拆分多Agent了。我的拆分思路是“按专业分工”一个负责理解需求的主Agent叫它Planner。一个负责数据查询的工具Agent叫它Tool Executor。一个负责报告生成的写作Agent叫它Writer。主Agent把任务拆解成一个个子任务分发给对应的专业Agent再由主Agent汇总结果。这种架构的好处是每个Agent的Prompt和工具集都可以保持精简模型的选择也更有针对性——数据Agent用小模型精确工具写作Agent用优质模型清晰模板。代价当然是系统复杂度上了一个台阶通信协议、子任务状态管理、结果合并都会多出来一堆活。所以我的建议是单Agent能解决的坚决不要上多Agent。拆分的时机是你发现性能瓶颈已经无法通过Prompt优化解决的时候。6.5 上线前最后一道检查最后有一个“上线自查清单”是我每次发布Agent前都会过一遍的System Prompt是否清晰定义了“禁止做的事”工具描述里每个参数是否都有示例和取值范围最大循环步数是否设置每一步的日志是否结构化可查是否有失败时的用户兜底回复是否做过评测集回归是否对单用户单任务的成本上限做了限制第七条特别重要。我在线上项目里给每个用户单次Agent任务的token消耗设了上限防止极端情况下一个坏循环把整个项目的预算烧穿。超限自动降级到“基础问答模式”体验损失可控但成本风险被彻底锁住。7. 几个值得收藏的实操经验文章最后两条分享我觉得最值钱的工程经验。第一Agent项目的开发周期里70%的时间在打磨工具描述和评测集20%在修循环逻辑只有10%在写业务代码。如果你发现自己在疯狂堆业务代码那说明方向偏了。工具描述才是Agent的根根扎稳了上面的枝叶自然而然会长出来。第二做Agent一定要克制。能三步走完的任务不要设计五步能两个工具解决的不要挂五个工具能用规则的不要硬上模型。Agent不是越复杂越高级而是越精准越有价值的。我见过太多项目模型能力没瓶颈被自己的“过度设计”搞成了一团乱麻。如果你能把这篇文章里的核心架构、工具定义规范、循环保护、记忆管理、成本控制这几件事踏踏实实落地你的Agent项目已经在绝大多数团队之上了。后续的方向也无非是两条往上做更复杂的规划能力往下做更稳定的执行能力。无论哪条路记住一点——让Agent成为可靠的工具而不是炫技的玩具这才是一个工程师应该有的追求。 
长河君 · 2026/10/20 12:23:21 · 阅读 1.2k AI Agent构建全攻略：从技术原理到工程实践
AI Agent构建全攻略从技术原理到工程实践程序员必备指南建议收藏做了几年LLM应用开发我越来越确定一件事2024年之前大家聊的是“怎么把大模型接进业务”2024年以后大家聊的是“怎么让大模型自己把活儿干完”。这中间的跨越就是从写Prompt到构建Agent的跨越。很多程序员朋友问我Agent到底难不难学我的回答是原理不难工程很难。难在工具调用怎么稳定、记忆怎么不崩、循环怎么不死、成本怎么可控。这篇东西我想一次性把这些讲透。文章会从Agent的底层组成讲到工程落地既有原理拆解也有能直接抄的代码片段最后还有我在实际项目里踩过的坑和排查思路。无论你是刚接触LLM的初级工程师还是已经在做RAG应用想往Agent方向升级的开发者这篇都值得你花20分钟看完建议先收藏再慢慢对照实操。1. 先从“数字员工”的视角理解Agent1.1 从“问答机器人”到“数字员工”的认知跃迁我一直觉得很多人在Agent上栽跟头不是因为代码写得不好而是因为脑子里对Agent的认知模型还是错的。普通的ChatBot是“一问一答”用户说一句模型回一句上下文全靠聊天记录硬撑。Agent完全不是这个逻辑。Agent更像一个拿到了任务就自己去拆解、自己找工具、自己执行、自己检查结果的数字员工。你给的不是问题而是目标。举个例子。传统问答应用用户问“帮我看看这个月的销售数据”你做的就是把数据库里的数据查出来往Prompt里一塞让模型总结。Agent场景下用户说的是“帮我分析一下本月销售异常并且生成一份可分享的报告”。这个任务需要Agent自己完成几步先定位数据源再调SQL查询接口拿到数据后做统计分析发现异常点然后调用文档生成工具最后把报告链接返回给用户。这里面每一环都需要模型做决策每一步决策都可能出错。所以Agent工程的核心不是把模型跑起来而是把模型跑对、跑稳、跑得可追溯。1.2 现在入局Agent时机刚好有人问现在Agent技术成熟了吗我的回答是不那么成熟但恰恰是这种“没完全定型”的阶段最适合程序员切入。你看底层模型的能力2023年的时候调用工具还不稳定经常模型说“我要调用工具”结果参数给你传错。现在的开源和闭源模型在Function Calling上的准确率已经能从“勉强能用”进化到“基本可靠”了。再加上各种支持流式输出、结构化输出的推理框架越来越成熟对话记忆、向量检索、权限控制这些基础设施也都有现成的轮子。所以我的判断是现在不上车再过一年框架又会叠一层概念又会包装出好几个新词再学成本只会更高。Agent的技术壁垒不在“理解概念”而在工程经验——这种东西只有踩坑才能积累越早踩坑越早成为优势。1.3 这篇文章能帮你打通什么这篇内容我按照我自己做项目的思路来排先讲清楚一个Agent到底由哪些部分组成每个部分在系统里承担什么职责再讲技术选型包括模型、编排框架、工具定义方式怎么取舍然后给出可落地的代码配置和核心环节实现包括工具调用、记忆管理、执行循环最后是我真正想分享的部分——常见问题、排查套路、成本治理和上线心得。看完之后你至少能具备独立搭建一个中等到复杂程度Agent系统的能力。2. Agent的五个核心组件缺一不可Agent系统不管怎么包装拆开来看永远是五块东西大脑、规划器、工具箱、记忆、反馈机制。2.1 大脑LLM是推理核心但它不是万能的所有Agent的“智力”都来自大语言模型但这颗“大脑”负责的是理解和推理不是存储和计算。很多初学者把什么都往模型里塞让模型既当数据库又当计算器这是最典型的错误。我习惯把LLM在Agent里的作用分成三层意图理解层把用户的自然语言请求解析成机器可执行的任务描述。决策规划层根据当前状态决定下一步该调用哪个工具、给什么参数。结果解释层把工具返回的结构化数据整理成用户能看懂的结论。这三层用到的推理策略不一样。意图理解要稳规划决策要快结果解释要准。如果在工程上你把这三件事混在一起写后面调试的时候一定会疯——因为你会分不清到底是哪个环节出了错。2.2 工具箱Function Calling是Agent的“双手”没有工具的Agent只是个聊天机器人有了工具的Agent才是个执行者。工具的本质是把外部能力封装成模型可调用的函数接口。这些函数可以是一个查询数据库的SQL、一个调用内部API的HTTP请求、一个执行Python代码的沙箱、一个发邮件的SMTP封装等等。关键在于工具的“接口描述”必须足够清晰让模型能理解这个工具是干嘛的、需要什么参数、会返回什么。我在工程实践中发现工具描述写得好不好直接决定Agent的调用成功率。一个模糊的描述模型就敢瞎传参数一个明确的描述模型往往一次就能给对。后面第4节我会给一个详细规范这里先记住工具定义是Agent工程里投入产出比最高的事情值得你花最多时间打磨。2.3 记忆短期记忆和长期记忆必须分开管理Agent和人一样记忆力决定它能做多复杂的事。短期记忆指的是当前任务执行过程中的上下文通常通过把对话历史塞进模型上下文窗口来实现。它的特点是快、直接但窗口有限塞多了不仅贵模型还可能“忘”了前面更重要的信息。长期记忆则是把有价值的信息持久化存储在需要的时候检索出来塞回上下文。最常见的实现方式是向量数据库做语义检索也有用结构化数据库存关键事实的。我在项目里一般用“两级记忆”方案当前任务的所有中间输出都放在短期记忆里一旦任务完成就把结构性结论抽取出来存进长期记忆下次类似任务来了先检索长期记忆再开工。这个方法极大提升了Agent在多轮复杂任务里的稳定性。2.4 行动周期感知-规划-行动-观察的循环Agent执行任务时本质上是在跑一个循环感知获取用户输入和当前状态。规划决定下一步做什么是直接回答还是调用工具。行动调用对应工具拿到结果。观察把工具返回的观察结果放回上下文。再规划基于新的观察结果决定下一步直到任务完成。这个循环就是Agent之所以是“智能体”而不是“接口调用”的原因——它能根据中间结果动态调整自己的下一步而不是走一条写死的链路。但循环也有致命问题循环如果失控Agent就会反复调用同一个失败的工具浪费算力也不出结果。所以工程上必须给循环设置上限比如最大轮次默认10轮超过就强制中断把“部分结果异常状态”返回给用户。2.5 反馈机制让Agent知道自己干得怎么样最后一个容易被忽略的组件是反馈机制。Agent执行完一个动作之后怎么知道这件事干成了没有怎么知道结果是好的还是不合理的我在实践中总结了一套“双重校验法”硬校验检查工具调用是否成功、返回格式是否符合预期、数据是否完整。这是程序层面的校验写起来很机械但必须有。软校验把工具返回结果再交给模型做一次“自评”让模型判断这个结果是否符合任务目标、有没有异常值、需不需要补充信息。软校验比较费token但对于高价值的任务环节比如数据分析、报告生成特别值得因为它能帮Agent在交付结果之前自我纠错。2.6 组件之间的协作关系一句话总结把五块组件串起来的架构大概是这样的用户请求进来短期记忆记录上下文规划器结合记忆和工具列表决定行动工具执行并返回结果结果经过校验后回写记忆循环继续直到任务完成最后把关键结论存入长期记忆。理解了这张“协作图”你就不会再被各种新概念带偏。什么“Plan-and-Execute”、“ReAct”、“多Agent协作”本质上都只是这个基本架构的变体。3. 技术选型框架、模型和基础设施怎么取舍3.1 编排框架选一个生态成熟的别再造轮子现在市面上有大量Agent编排框架有的偏轻量、有的偏重量有的适合做实验、有的适合做生产。我个人的选型标准有三条生态成熟度框架的文档全不全、社区活跃不活跃、踩坑案例多不多。我不会选一个刚发布一个月的框架来做生产系统。可观测性框架能不能方便地输出每一步的调用日志、token消耗、耗时。这一点极度重要但很多框架做得并不好。可控性你可以方便地自定义循环逻辑、记忆策略和错误处理而不是只能按框架预设的流程走。我自己在生产项目里用得最多的是LangGraph风格的状态图编排方式因为它把Agent循环建模成一张图节点是“模型调用”、“工具执行”、“条件判断”边是状态流转调试和可视化都比较直观。3.2 模型选择参数不是越大越好关键是匹配任务很多人一上来就选最大参数的商业模型觉得越强越好。但做Agent工程你不能只看模型“聪明不聪明”还要看以下这几个维度维度选择逻辑备注指令遵循稳定性模型能否严格按照工具描述传参这是Agent的命门上下文长度需要容纳多少短期记忆长度大不等于效果好还要看长文本下的注意力质量推理速度Token首字延迟和生成速度Agent是串行循环每一步延迟都会叠加成本单次任务平均消耗token数长任务要按全循环估算部署方式API调用还是私有化部署数据合规场景慎用外部API我的建议是任务的核心推理环节用一个中等偏上的模型外围的简单分类、提炼、格式化用一个小模型。这种“大小模型混合”的方案能把单任务的成本降低40%到60%而体验几乎不打折。还有一个容易被忽略的点模型版本要固定。生产环境里模型一升级Prompt可能就失效了。所以线上必须锁定模型版本新版本先在测试环境跑一轮回归再切流量。3.3 工具定义JSON Schema是通行语言无论你选哪个框架工具定义最终都会被序列化成JSON Schema格式给模型识别。一个标准的工具定义通常长这样{ name: query_sales_data, description: 查询指定日期范围内的销售数据返回按日期聚合的订单量和销售额。, parameters: { type: object, properties: { start_date: { type: string, description: 起始日期格式为YYYY-MM-DD }, end_date: { type: string, description: 结束日期格式为YYYY-MM-DD }, region: { type: string, enum: [华东, 华北, 华南, 西南], description: 区域不传则查询全国 } }, required: [start_date, end_date] } }注意几个细节description要写清楚这个工具是干嘛的、什么时候该用它、什么时候不该用它。模型是靠描述来选工具的描述含糊它就会乱选。参数要尽量用enum限定取值范围模型在提供选项时出错的概率远低于自由生成。required字段只把真正必需的参数放进去非必需的不要写给模型更多泛化空间。3.4 基础设施向量库、缓存和沙箱最后简单说说基础设施层。向量数据库用于长期记忆和知识检索。选型时我比较关注检索质量、写入吞吐量、有没有过滤条件比如按用户ID过滤。缓存层非常关键。同样的工具请求如果结果是一样的没必要让Agent重复调用。按请求参数哈希做一层结果缓存能大幅降低延迟和成本。安全沙箱很必要凡是Agent要执行代码或者操作外部资源都必须放进受限环境里不能让Agent裸奔在你的生产服务器上。4. 工程化实操从零配置一个完整Agent说完了原理和选型这一节直接上代码。我以Python生态为例搭建的是一个“数据分析Agent”它能理解用户请求、写SQL查询数据库、做简单分析、生成报告。4.1 搭建基础环境假设你已经有Python 3.10环境先安装核心依赖。这里我以一款主流的开源Agent编排库为例pip install agent-framework langchain-openai pandas提示框架名称我做了泛化处理实际选型时你用你熟悉的编排库即可核心概念大同小异。然后是初始化模型客户端。注意把API Key放到环境变量里不要硬编码在代码中import os from openai import OpenAI client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL) # 如果走代理网关或者私有化模型接口 ) model_name your-main-model-name4.2 定义Agent的工具集数据分析Agent最核心的工具是“查询数据表”和“生成图表报告”。我拿查询工具举例import json import sqlite3 from typing import Any def query_sales_data(start_date: str, end_date: str, region: str 全国) - str: 查询指定日期范围内的销售数据。 Args: start_date: 起始日期格式YYYY-MM-DD end_date: 结束日期格式YYYY-MM-DD region: 区域可选华东/华北/华南/西南默认全国 Returns: JSON格式的聚合结果 conn sqlite3.connect(sales.db) cur conn.cursor() if region 全国: cur.execute( SELECT date, region, SUM(order_amount) as total_amount, COUNT(*) as order_count FROM sales WHERE date BETWEEN ? AND ? GROUP BY date, region, (start_date, end_date) ) else: cur.execute( SELECT date, region, SUM(order_amount) as total_amount, COUNT(*) as order_count FROM sales WHERE date BETWEEN ? AND ? AND region ? GROUP BY date, region, (start_date, end_date, region) ) rows cur.fetchall() conn.close() return json.dumps([{ date: r[0], region: r[1], total_amount: r[2], order_count: r[3] } for r in rows], ensure_asciiFalse)这个函数很简单但注意我在docstring里把每个参数的含义都写清楚了。模型会读取这个docstring来决定怎么调用所以写工具就是在写面向模型的文档不是面向人的注释。接着把这个工具注册进Agent的“工具箱”from agent_framework import Tool query_tool Tool( namequery_sales_data, description查询指定日期范围内的销售数据返回按日期和区域聚合的订单量和销售额。适用于销售分析、趋势查看、异常排查等场景。, funcquery_sales_data ) tools [query_tool]4.3 构建Agent主循环核心循环就是“模型决定调哪个工具执行工具把结果返回模型模型再决定下一步”。代码写出来是这样的from agent_framework import Agent # 定义系统提示词 system_prompt 你是数据分析助手。你拥有查询销售数据的工具。 你的职责是 1. 理解用户的业务问题。 2. 当需要数据时调用query_sales_data工具获取数据。 3. 基于数据结果进行推理给出清晰的分析结论。 4. 如果数据不足以回答问题明确说明缺失信息并给出建议。 操作规范 - 工具调用失败时仔细阅读错误信息修正参数后重试。 - 当数据返回结果为空时不要编造数据要如实告知用户。 - 最终回答必须基于工具返回的真实数据。 agent Agent( modelmodel_name, system_promptsystem_prompt, toolstools, max_steps10, memory_kindwindow, memory_window_size20 )然后启动一次任务response agent.run(分析一下2024年11月华东区的销售趋势和10月相比变化如何) print(response)执行过程中框架会自动完成这样的循环Agent判断需要调用query_sales_data传入start_date2024-10-01、end_date2024-11-30、region华东。工具执行返回两个月的聚合数据。Agent拿到数据后分析11月销售额环比下滑还是增长哪个品类的变化最明显。如果数据粒度不够Agent可能再次调用工具查询明细。最后组织语言输出分析结论。4.4 记忆管理从“一次性”到“可持续”上面这个Agent每次run都是全新的没有记忆。真实业务里用户可能连续追问或者隔几天回来继续聊同一个话题。所以要在Agent外面套一层记忆管理。我的方案是双轨制短期记忆——用ConversationBufferWindowMemory保留最近N轮对话这个N根据模型上下文和业务复杂度来定我一般设20到40轮之间。太小了用户多问几句就断片太大了token成本飙升。长期记忆——每次任务结束后LLM提炼出三条以内的关键结论存进向量数据库用向量检索的方式把相似历史任务的结果捞回来填充上下文。代码如下from agent_framework import VectorMemory def extract_and_store_summary(agent_run_id, user_query, final_answer): summary client.chat.completions.create( modelsmall-model, messages[ {role: system, content: 从回答中提炼不超过3条可复用的核心结论输出JSON数组每个元素是{fact: 结论内容, topic: 主题标签}}, {role: user, content: f用户问题{user_query}\n回答{final_answer}} ] ) facts parse_json(summary.choices[0].message.content) memory VectorMemory(embedding_modelyour-embedding-model) for fact in facts: memory.add(fact[fact], metadata{topic: fact[topic], agent_run: agent_run_id}) # 任务完成后调用 extract_and_store_summary(agent_run_id, user_query, response)这套机制跑起来之后Agent会表现出一种“越用越聪明”的感觉——因为每次任务总结的结论会在下次任务里作为参考上下文被召回。4.5 错误处理和循环保护Agent最让人头疼的问题之一是“死循环”。我建议在框架层做这三个保护最大步数限制max_steps10超过直接终止返回当前已完成的步骤和终止原因。重复工具调用检测如果模型连续三次用相同的参数调用同一个工具说明它陷入死循环了强制打断并提示模型换策略。工具异常兜底工具函数里任何异常都要捕获返回结构化的错误信息给模型而不是抛出堆栈让模型懵掉。def safe_call_tool(tool, arguments: dict) - str: try: result tool(**arguments) return json.dumps({status: success, data: result}, ensure_asciiFalse) except TypeError as e: return json.dumps({status: error, error: f参数类型错误: {str(e)}}) except Exception as e: return json.dumps({status: error, error: f执行异常: {str(e)}})注意我把错误信息用JSON返回给模型模型读到之后可以自行判断是重新传参还是换一个工具。如果错误信息是纯文本裸堆栈模型往往不知道下一步该干嘛。4.6 日志与可观测性Agent不像传统API一次请求内部可能跑了几十个步骤每一步的输入输出都要留痕。我的做法是在Agent的每个节点埋日志输出结构化JSON{ timestamp: 2024-12-01T10:23:45Z, agent_run_id: run_12345, step: 3, node: model_call, input: 用户问题..., output: 调用工具query_sales_data参数..., cost: {prompt_tokens: 1200, completion_tokens: 150}, latency_ms: 850 }有了这种日志后面排查问题就变得非常高效——用户说“回答错了”你把run_id拿来一查每一步干了啥一目了然。没有日志的Agent项目出问题就像在深山里找一只迷路的猫。5. 高频踩坑与排查方案5.1 工具描述含糊模型传参全靠猜现象模型频繁把工具参数传错比如把日期格式从YYYY-MM-DD传成YYYY/MM/DD或者把“华东”传成大写的“华东”。排查首先看工具描述里有没有明确示例。只写“日期”是不够的要写“日期格式为YYYY-MM-DD例如2024-11-01”。我的标准做法是在参数描述里给一个明确的示例值。模型对示例的敏感度远高于抽象描述。另外能用enum的地方坚决用enum模型在封闭集合里做选择准确率比开放生成高很多。5.2 上下文爆炸导致“记忆错乱”现象任务执行到一半模型开始重复问已经知道的信息或者把前面的结论搞混了。原因短期记忆的窗口管理太粗暴所有中间结果都在上下文里堆积模型注意力被冗余信息干扰。解决做“关键信息压缩”。在每步工具执行完之后用一个小模型把这一步的输出压缩成“一句话摘要”再放回上下文。这样长期运行也不会把上下文塞爆。这个操作看似多了几次小模型调用但和主模型动辄上万token的上下文相比成本低得多。5.3 Agent“嘴硬”没数据也敢胡说现象工具返回空数据但Agent在最终回答里编了一段“分析结论”。这是幻觉在Agent场景下的经典表现。规避办法有两个维度第一在System Prompt里明确写“如果没有数据支撑直接说明数据缺失禁止推测。”第二在工具结果里做标记让模型明确感知“这是空结果”。if not rows: return json.dumps({status: empty, message: 查询范围内无数据}, ensure_asciiFalse)模型看到status: empty就会更好地说“该时间段没有数据”而不是自己编一堆趋势分析。5.4 循环卡死成本持续燃烧现象Agent反复调用同一个工具或者在一个决策点上反复横跳token消耗以肉眼可见的速度增长。解决我上面提到的“重复调用检测”就是我踩过坑之后加上去的。具体实现是维护一个最近五步的“调用指纹”列表如果当前步骤的模型输出和最近某一步相同直接给模型返回一个警告“你已经尝试过相同操作请换一种方式或终止任务。”这条警告非常有效。加了之后我的Agent项目死循环率降了大约80%。5.5 外部接口的不稳定现象Agent调第三方API第三方偶尔超时或者返回502Agent直接崩溃。解决包一层带超时和重试的封装。注意重试策略要写退避逻辑不要瞬间疯狂重试因为第三方服务恢复也需要时间。import time def call_with_retry(func, max_retry3): for i in range(max_retry): try: return func() except TimeoutError: time.sleep(2 ** i) return json.dumps({status: error, error: 外部接口多次超时请稍后重试})5.6 问题排查速查表症状可能原因优先排查点工具参数频繁传错工具描述不完善、缺示例检查JSON Schema里的description和enum答非所问短期记忆窗口被冗余信息占满加关键信息压缩、裁剪无关工具输出死循环、重复调用决策条件不够明确加重复调用检测和最大步数限制数据为空还硬编结论幻觉、缺少空结果标记工具返回空状态Prompt强调禁止推测外部调用超时第三方API不稳定加超时重试和退避策略上下文越来越慢上下文过长、模型注意力退化启用长期记忆、减少单步输出体积6. 从Demo到线上性能优化与平稳落地6.1 评估体系Agent也要有“单元测试”传统软件的单元测试在Agent世界里对应的是一组“评测用例集”。每个用例包含模拟的用户输入、预期的工具调用序列、可接受的结果范围。我自己维护了一个eval_suite.json里面放了三十多类业务问题的期望行为。每次改Prompt、换模型版本、调工具描述我都先在评测集上跑一遍回归看通过率有没有下降。Agent的“评测通过率”就是你的上线安全网。有个细节评测不能只看最终答案对不对还要看中间的工具调用序列是否合理。一个Agent虽然最终答对了但中间绕了弯路、多调了几次没必要的工具说明它的规划能力还有问题。我通常同时记录“工具调用次数成本”作为优化指标。6.2 降低延迟的四个小技巧Agent是串行循环每一步模型调用都是几百毫秒几步下来轻松超过三五秒。用户等不了。我在线上常用的降延迟手段并行工具调用当模型明确需要多个独立数据时让框架自动并行调用工具而不是串行等。这个优化能把总耗时压缩一半。小模型前置分类在大模型进入之前用一个极快的小模型判断用户需求类型走不同的Prompt和工具集减少大模型的无效规划。结果缓存热门查询比如“今天销售额多少”如果数据源分钟级更新完全可以直接走缓存返回让Agent只处理真正需要动态规划的任务。流式输出先让模型输出“分析框架”给用户看再做工具调用这样用户在等待的过程中有反馈体感会好很多。6.3 成本治理别让Agent成为吞金兽Agent的成本和ChatBot不是一个量级。一个复杂任务动辄调三五次工具每次工具调用都涉及一次模型推理单任务成本可能是普通问答的十倍。我的成本控制三板斧每一步都记账。日志里记token消耗按用户、按会话、按任务类型聚合看清楚钱到底烧在哪个环节。能省则省的模型选择。不是所有决策都需要大模型“深度思考”工具结果整理、摘要提炼、格式转换这些脏活累活全丢给小模型干。任务分级限流。高价值、复杂的任务用完整Agent流程简单任务走预设流程和小模型别让所有流量都挤进“豪华版”Agent。6.4 多Agent协作的演进方向如果单个Agent的业务复杂度继续上升你会碰到一个尴尬时刻Prompt越长越乱工具列表越多越容易选错。这时候就该考虑拆分多Agent了。我的拆分思路是“按专业分工”一个负责理解需求的主Agent叫它Planner。一个负责数据查询的工具Agent叫它Tool Executor。一个负责报告生成的写作Agent叫它Writer。主Agent把任务拆解成一个个子任务分发给对应的专业Agent再由主Agent汇总结果。这种架构的好处是每个Agent的Prompt和工具集都可以保持精简模型的选择也更有针对性——数据Agent用小模型精确工具写作Agent用优质模型清晰模板。代价当然是系统复杂度上了一个台阶通信协议、子任务状态管理、结果合并都会多出来一堆活。所以我的建议是单Agent能解决的坚决不要上多Agent。拆分的时机是你发现性能瓶颈已经无法通过Prompt优化解决的时候。6.5 上线前最后一道检查最后有一个“上线自查清单”是我每次发布Agent前都会过一遍的System Prompt是否清晰定义了“禁止做的事”工具描述里每个参数是否都有示例和取值范围最大循环步数是否设置每一步的日志是否结构化可查是否有失败时的用户兜底回复是否做过评测集回归是否对单用户单任务的成本上限做了限制第七条特别重要。我在线上项目里给每个用户单次Agent任务的token消耗设了上限防止极端情况下一个坏循环把整个项目的预算烧穿。超限自动降级到“基础问答模式”体验损失可控但成本风险被彻底锁住。7. 几个值得收藏的实操经验文章最后两条分享我觉得最值钱的工程经验。第一Agent项目的开发周期里70%的时间在打磨工具描述和评测集20%在修循环逻辑只有10%在写业务代码。如果你发现自己在疯狂堆业务代码那说明方向偏了。工具描述才是Agent的根根扎稳了上面的枝叶自然而然会长出来。第二做Agent一定要克制。能三步走完的任务不要设计五步能两个工具解决的不要挂五个工具能用规则的不要硬上模型。Agent不是越复杂越高级而是越精准越有价值的。我见过太多项目模型能力没瓶颈被自己的“过度设计”搞成了一团乱麻。如果你能把这篇文章里的核心架构、工具定义规范、循环保护、记忆管理、成本控制这几件事踏踏实实落地你的Agent项目已经在绝大多数团队之上了。后续的方向也无非是两条往上做更复杂的规划能力往下做更稳定的执行能力。无论哪条路记住一点——让Agent成为可靠的工具而不是炫技的玩具这才是一个工程师应该有的追求。