1. 从“玩具”到“工具”我对AI Agent认知的两次转变刚接触AI Agent那会儿我跟大多数人一样觉得这东西就是个高级版的自动补全。你给它一句话它回你一段话仅此而已。直到有一次我让它帮我处理一个跨三个仓库的代码重构任务它居然自己规划了步骤、调用了终端、跑了测试、发现失败后又回滚重来——那一刻我才意识到这东西跟聊天框里的对话完全不是一回事。AI Agent的核心价值在于自主性和工具调用能力。普通对话模型是你问一句它答一句Agent则是你给一个目标它自己拆解任务、选择工具、执行动作、观察结果、调整策略直到目标达成或确认无法达成。这个循环在业界通常被称为“感知-规划-行动-观察”回路听起来很学术但说白了就是它像一个刚入职的实习生你告诉它“把这份数据整理成报表”它会自己去找数据、选工具、做表格、检查格式中间遇到问题还会来问你。我写这篇东西的出发点很简单过去大半年里我在不同项目里反复搭建和调试Agent踩过的坑足够填满一个中型项目的issue列表。有些坑是工具链本身的限制有些是我自己对Agent能力边界理解不到位还有些纯粹是配置层面的低级错误。这些经验散落在各种聊天记录和笔记里趁这次机会系统整理一下给正在或准备上手Agent的朋友们省点时间。这篇文章适合三类人一是刚听说Agent概念、想动手试试但不知道从哪开始的新手二是在搭建过程中遇到具体问题、需要排查思路的开发者三是想了解Agent实际能力边界、评估是否值得引入团队的技术决策者。我会尽量少讲抽象概念多讲具体操作和踩坑经验代码和配置能贴就贴参数能解释就解释。2. 搭建第一个Agent前先把这几个概念理清楚2.1 Agent、Workflow和Chatbot到底差在哪很多人把这三个东西混为一谈包括我刚开始的时候。简单区分一下Chatbot你输入它输出。没有记忆或只有短期对话记忆没有工具没有自主决策。典型代表就是网页版对话模型。Workflow你预先定义好流程比如“先调A接口再调B接口最后合并结果”。流程是固定的模型只在特定节点做判断。典型代表是各种低代码平台里的自动化流程。Agent你给目标它自己决定用什么工具、按什么顺序、要不要循环。流程是动态生成的每次执行可能都不一样。这个区分很重要因为很多人在需要Workflow的场景用了Agent结果发现又慢又不稳定或者在需要Agent的场景用了Workflow结果发现根本覆盖不了所有分支。我的经验是如果任务步骤可以穷举用Workflow如果任务步骤取决于中间结果用Agent。2.2 工具调用是Agent的手和脚Agent之所以能“做事”全靠工具调用。工具可以是一个函数、一个API、一个命令行指令甚至是一个子Agent。模型本身只能输出文本但通过工具调用协议它可以“说”出“我要执行这个函数参数是这些”然后由外部运行时去实际执行再把结果喂回给模型。这里有个容易忽略的点工具的描述质量直接决定Agent的调用准确率。我见过太多人写工具描述就写一句“查询用户信息”然后抱怨Agent老是调错。正确的做法是把工具描述当成给新人的说明书来写——输入是什么格式、输出是什么格式、什么情况下该用、什么情况下不该用、有没有副作用全部写清楚。2.3 记忆机制决定了Agent能走多远没有记忆的Agent每次对话都是重新开始。这在简单任务里没问题但一旦任务需要多轮交互或者需要参考历史信息记忆就成了刚需。记忆分几种短期记忆当前对话的上下文、长期记忆跨对话持久化的信息、工作记忆当前任务执行过程中的中间状态。大多数框架只提供了短期记忆长期记忆需要自己接向量数据库或键值存储。我的建议是初期不要碰长期记忆先把短期记忆和工作记忆用明白。长期记忆引入的复杂度检索准确性、更新策略、冲突处理会指数级上升新手很容易在这里迷失。3. 工具链选型别一上来就追求“全家桶”3.1 模型选择不是越贵越好选模型这件事我的原则是先看任务复杂度再看成本最后看响应速度。简单任务分类、提取、格式化用轻量模型就够了便宜且快。复杂任务多步推理、代码生成、长文档分析才需要上大模型。我实测下来很多团队用最贵的模型跑最简单的任务成本翻了好几倍效果却没区别。另外要注意模型的工具调用能力差异很大。有些模型天生擅长结构化输出和函数调用有些则经常格式出错。选型时一定要用你的实际任务做一轮测试别只看跑分。3.2 框架选型轻量优先按需扩展市面上Agent框架很多我的建议是从最轻量的开始遇到瓶颈再换。轻量框架的好处是透明你能清楚看到每一步发生了什么出问题好排查。重型框架封装了很多东西上手快但调试难一旦出问题你都不知道是哪一层导致的。我自己的路径是先用原生API加几十行代码跑通最小闭环确认任务可行后再引入框架。这样你对底层机制有感知后面用框架时也知道它在帮你做什么。3.3 开发环境准备Git和基础工具链不管你用什么框架Git都是必须的。Agent项目迭代快没有版本控制你会疯掉。Git安装和配置网上教程很多这里只提几个Agent项目里特别有用的点分支策略主分支保持可运行每个实验性功能开独立分支。Agent调参过程会产生大量中间状态分支能帮你随时回退。提交粒度每次调整Prompt或工具描述都单独提交。Prompt的微小改动可能导致行为剧变细粒度提交方便你定位是哪次改动引入的问题。忽略文件API密钥、本地缓存、日志文件一定要加进.gitignore。我见过有人把密钥提交到仓库后果很严重。# 典型的Agent项目.gitignore .env *.log __pycache__/ .venv/ node_modules/ .cache/4. 提示词工程在Agent场景下的特殊玩法4.1 系统提示词是Agent的“岗位说明书”普通对话里系统提示词影响的是语气和风格。但在Agent场景下系统提示词直接决定它的行为模式。我通常会把系统提示词分成几个模块来写角色定义你是谁你的职责边界在哪。能力说明你能调用哪些工具每个工具大概什么时候用。行为约束什么绝对不能做遇到不确定的情况怎么办。输出规范最终结果用什么格式呈现。这里有个反直觉的经验系统提示词不是越长越好。我试过写了两千字的系统提示词结果模型反而抓不住重点。后来精简到五百字左右把最关键的三条规则加粗强调效果明显提升。模型对提示词的注意力是有限的信息密度比信息总量更重要。4.2 工具描述要写成“使用手册”前面提过工具描述的重要性这里展开说具体怎么写。一个好的工具描述应该包含功能一句话概括让模型快速判断这个工具是否相关。参数说明每个参数的类型、是否必填、取值范围、默认值。返回值说明成功返回什么失败返回什么。使用场景什么情况下应该调用什么情况下不应该。注意事项有没有副作用调用频率限制依赖关系。举个例子一个查询天气的工具差的描述是“查询天气”好的描述是“根据城市名称查询当前天气状况。参数city为城市中文名如‘北京’。返回温度、湿度、天气描述。仅当用户明确询问天气时调用不要主动调用。”4.3 少样本示例比长篇解释更有效如果你发现Agent某个行为总是不对与其写一大段解释不如给两三个正确示例。模型对示例的模仿能力远强于对规则的理解能力。我处理过一个场景Agent总是把用户的问题原封不动地传给搜索工具而不是先提取关键词。我在系统提示词里加了一段解释没用。后来加了两个示例用户帮我查一下最近有什么好看的科幻电影 正确做法调用搜索工具参数query2025 科幻电影 推荐 错误做法调用搜索工具参数query帮我查一下最近有什么好看的科幻电影加上这两个示例后问题立刻解决。示例的力量就是这么直接。5. 调试Agent的完整排查链路5.1 先看日志再看代码Agent出问题时第一反应不应该是改代码而是看日志。完整的日志应该包含每次模型调用的输入输出、每次工具调用的参数和结果、每一步的耗时。没有这些信息你就是在盲猜。我习惯在开发阶段把日志级别调到最详细每个中间状态都打出来。虽然日志量大但排查问题时能省大量时间。上线前再调回正常级别。5.2 常见问题分类与定位Agent的问题大致分几类每类的排查思路不同问题类型典型表现排查方向工具调用错误调了不该调的工具或参数格式错检查工具描述是否清晰参数定义是否明确循环卡死反复调用同一个工具不推进检查是否有终止条件工具返回是否被正确解析输出格式错最终结果不符合预期格式检查输出规范是否明确是否给了示例上下文溢出长任务后期行为异常检查上下文长度是否该做摘要或截断响应过慢单步耗时过长检查模型选择、工具执行时间、是否串行调用5.3 一个真实的排查案例有次我搭了一个代码审查Agent它的任务是读取Git diff分析变更给出审查意见。测试时发现它经常漏掉一些明显的bug。排查过程先看日志发现它确实读取了完整的diff但分析时只关注了新增行忽略了删除行和上下文。再看系统提示词我写的是“分析代码变更”没有明确说要关注删除行。问题定位到了。修复方案在系统提示词里明确“分析时需同时关注新增行、删除行和上下文行删除行可能意味着功能移除或逻辑变更需要特别留意”。同时加了一个示例展示如何分析一个包含删除行的diff。修复后漏报率明显下降。这个案例的教训是Agent不会自动理解你的隐含意图所有要求都要显式写出来。6. 让Agent稳定运行的几个工程化手段6.1 超时和重试是必须的Agent执行过程中工具调用可能超时模型调用可能失败。没有超时和重试机制一个偶发故障就会导致整个任务失败。我的配置通常是模型调用超时30秒重试2次工具调用超时根据工具类型定查询类10秒写入类30秒重试1次。重试时要加退避策略避免瞬间大量重试打垮下游服务。6.2 状态持久化让任务可恢复长任务执行到一半失败了如果状态没持久化只能从头再来。状态持久化就是把Agent执行过程中的关键状态存下来失败后可以从最近的检查点恢复。实现方式很简单每完成一个步骤就把当前状态已完成步骤、中间结果、下一步计划写进数据库或文件。恢复时读取最近状态从那里继续。这个机制在调试阶段也很有用你可以手动修改状态来测试特定分支。6.3 人工介入点要提前设计完全自主的Agent在现阶段还不现实关键决策点需要人工确认。我的做法是在系统提示词里定义“需要确认的情况”比如涉及删除操作、涉及外部支付、涉及敏感数据访问时Agent必须暂停并请求确认。人工介入点的设计原则是宁可多确认不可少确认。初期可以设置得频繁一些随着对Agent行为的信任度提升再逐步减少确认点。7. 成本控制别让Agent变成烧钱机器7.1 Token消耗的主要来源Agent的Token消耗比普通对话高得多因为每次工具调用都要把完整上下文重新发给模型。一个十步的任务上下文可能被重复发送十次。如果上下文有一万字那就是十万字的消耗。控制成本的核心是控制上下文长度。几个实用手段及时摘要把早期的详细对话压缩成摘要只保留关键信息。按需加载不要一次性把所有工具描述都塞进上下文根据任务阶段动态加载。结果截断工具返回的结果如果很长只保留关键部分其余截断或存到外部。7.2 缓存能省的钱比你想的多很多模型服务支持提示词缓存相同的系统提示词和工具描述部分可以缓存只对变化的部分计费。Agent场景下系统提示词通常很长且固定缓存能省不少钱。开启缓存的方式各平台不同但思路一致把固定不变的部分放在前面变化的部分放在后面。这样缓存命中率最高。7.3 监控和告警不能省上线后一定要监控Token消耗和调用次数设置告警阈值。我见过因为一个死循环导致一夜之间消耗大量额度的情况。监控指标至少包括单次任务平均Token消耗、单次任务平均工具调用次数、失败率、平均耗时。这些指标异常时及时告警能避免很多意外损失。8. 一些零散但实用的经验关于Prompt版本管理Prompt一定要版本化跟代码一起提交。我习惯把Prompt存在单独的文件里每次修改都写清楚改了什么、为什么改。这样出问题时能快速回滚到上一个稳定版本。关于测试Agent的测试比普通代码难因为输出不确定。我的做法是准备一组标准任务每次修改后跑一遍人工检查结果是否合理。同时记录每次的Token消耗和耗时作为回归指标。关于工具粒度工具不要设计得太细也不要太粗。太细会导致调用次数多、上下文膨胀太粗会导致灵活性差、难以复用。我的经验是一个工具对应一个完整的原子操作比如“发送邮件”是一个工具“填写收件人”和“填写正文”就不该拆成两个工具。关于错误处理工具返回错误时不要直接把原始错误信息丢给模型。原始错误信息往往包含技术细节模型看不懂。应该包装成模型能理解的格式比如“查询失败原因目标服务暂时不可用建议稍后重试”。关于并发如果任务中有多个独立子任务可以考虑并发执行。但要注意模型调用通常有速率限制并发数不要超过限制。另外并发执行时状态管理会更复杂初期建议串行稳定后再考虑并发。关于模型切换不要把模型名称硬编码在代码里用配置项管理。这样切换模型时不用改代码。同时要注意不同模型的工具调用格式可能不同切换时需要做适配。关于日志脱敏日志里可能包含用户数据或密钥上线前一定要做脱敏处理。我习惯在日志输出前统一过一遍脱敏函数把敏感字段替换成占位符。关于文档Agent的行为逻辑往往散落在Prompt、工具描述、代码注释里新人很难快速理解。建议维护一份单独的文档说明这个Agent能做什么、不能做什么、有哪些已知限制、出问题找谁。这份文档在交接时价值巨大。9. 从练手项目到生产可用的距离很多人用Agent做了几个demo就觉得可以上线了实际上从demo到生产还有很长的路。我总结几个关键的差距点稳定性demo可以容忍偶尔失败生产不行。需要完善的错误处理、重试机制、降级方案。可观测性demo不需要监控生产需要。需要日志、指标、追踪三件套能快速定位问题。安全性demo不用考虑权限生产需要。需要控制Agent能访问哪些资源、能执行哪些操作、能看哪些数据。成本可控demo不计成本生产需要。需要预算控制、用量监控、优化手段。用户体验demo只给自己用生产要给他人用。需要处理各种边界情况、提供清晰的反馈、支持中断和恢复。我的建议是先用一个真实但低风险的任务练手比如自动整理会议纪要、自动分类邮件。跑通全流程并稳定运行一段时间后再逐步扩展到更复杂的任务。不要一上来就做核心业务Agent的不确定性在核心业务里可能是灾难。10. 我目前的工作流和工具组合说一下我现在的日常配置供参考。模型方面简单任务用轻量模型复杂任务用大模型通过配置切换。框架方面用轻量框架加自研的状态管理保持透明可控。工具方面常用的有文件读写、命令行执行、HTTP请求、数据库查询这几类每个都写了详细的描述和示例。开发流程上我先在本地用脚本跑通最小闭环确认可行后再封装成服务。Prompt和工具描述存在单独文件里跟代码一起版本控制。每次修改后跑标准测试集对比Token消耗和结果质量。上线前做一轮压力测试确认并发和超时配置合理。这套配置不是最优的但对我来说够用且可控。Agent这个领域变化很快今天的最佳实践明天可能就过时了。保持学习、保持实验、保持记录比追求一套“标准答案”更重要。最后分享一个我踩过的坑有次我为了让Agent更“聪明”给它加了十几个工具结果它反而不知道该用哪个了经常调错。后来砍到五个核心工具准确率立刻回升。工具不是越多越好够用就行。这个教训让我在后来的项目里始终坚持“最小工具集”原则需要新能力时先想能不能用现有工具组合实现实在不行再加新工具。