1. 为什么“五件事”这个说法值得认真对待做了近两年的Agent开发我最大的感受是这个领域表面上热闹得不行新框架、新概念、新论文几乎每周都在刷屏但真正落到工程里能决定一个Agent项目是死是活的来来回回就那么几件事。你去看招聘要求、去看那些真正跑在生产环境里的项目、去跟做过完整落地的人聊最后都会收敛到同一个答案——Agent开发不是学一堆API而是掌握一套工程化的思维方式。这篇文章想聊的就是我在两年里反复验证过的五个核心能力点。它们不是某个框架的教程而是无论你用LangChain、LangGraph还是自己手写编排都绕不开的底层功夫。如果你刚开始接触Agent开发这五件事能帮你少走大半年的弯路如果你已经做过几个Demo但总觉得“差点意思”那大概率就是这五件事里有某一件没打通。先说清楚定位这不是一篇“LangChain入门教程”也不是“LangGraph API速查”。市面上这类内容已经够多了缺的是把框架背后的工程逻辑讲透的东西。我会用从业者的视角把每个能力点为什么重要、怎么练、踩过哪些坑都摊开来讲。读完你应该能判断自己现在卡在哪一层以及下一步该往哪使劲。2. 第一件事把“编排”当成核心能力而不是框架的附属品2.1 编排到底在解决什么问题很多人对Agent开发的理解停留在“调个大模型加几个工具让它自己跑”。真做起来才发现最难的从来不是单次调用而是多步骤之间的状态流转和决策控制。一个稍微像样的Agent至少要处理什么时候该调用工具、工具返回的结果怎么塞回上下文、多轮对话里哪些信息要保留哪些要丢弃、某一步失败了是重试还是换路径、多个子任务之间怎么串行或并行。这些问题本质上都是编排问题。LangChain早期用Chain把步骤串起来后来发现线性Chain不够用才有了LangGraph这种基于图结构的编排方案。这个演进本身就说明了一件事Agent的复杂度不在模型在流程控制。我见过太多项目Demo阶段用一条Chain跑得挺欢一上真实场景就崩。原因很简单真实场景的分支太多了。用户问一句话可能触发三种完全不同的处理路径每条路径又有各自的失败模式。线性结构根本表达不了这种复杂度硬写就是一堆if-else堆成屎山。2.2 LangChain和LangGraph的区别别只记结论网上搜“LangChain和LangGraph的区别”答案大多是“LangChain是链式LangGraph是图式”。这话没错但太浅了。真正要理解的是它们各自适合什么场景。LangChain的Chain适合流程确定、步骤固定的任务。比如一个RAG问答检索→拼接→生成三步走完没有分支用Chain就很干净。它的心智模型是“管道”数据从一头进从另一头出。LangGraph的心智模型是“状态机”。你定义一个共享的State然后定义若干节点每个节点读取State、做点事、写回State节点之间通过条件边决定下一步走哪。这个模型天然适合有循环、有分支、有中断恢复需求的场景。比如一个需要反复调用工具直到满足条件的Agent或者一个需要人工介入审批的流程用LangGraph表达起来就自然得多。我自己的判断标准很简单如果你画流程图的时候发现需要画箭头回指循环或者分叉条件分支那就别硬用Chain直接上LangGraph。反过来如果流程是一条直线用LangGraph就是杀鸡用牛刀反而增加理解成本。2.3 编排能力怎么练练编排我的建议是先别碰框架用最原始的方式手写一遍。找一个具体场景比如“根据用户问题决定是查知识库还是调计算器拿到结果后判断是否需要再查一次”然后用纯Python写一个while循环加状态字典把它实现出来。写完你再去用LangGraph会发现它帮你解决的其实就是状态管理和流程可视化这两件事理解会深很多。手写一遍还有个好处你会真正体会到“状态该存什么”这个问题的难度。状态存少了节点之间信息不够用存多了上下文爆炸模型被无关信息干扰。这个平衡感看文档是看不出来的必须自己踩。提示编排设计里最容易犯的错是把“对话历史”和“任务状态”混在一起。对话历史是给模型看的任务状态是给流程控制用的两者生命周期和用途完全不同建议分开管理。3. 第二件事工具调用不是“注册个函数”那么简单3.1 工具描述的质量决定Agent的上限工具调用看起来是最没技术含量的部分——写个函数加个装饰器注册进去完事。但我可以负责任地说大部分Agent表现差根因都在工具描述上。模型决定调不调某个工具、怎么填参数全靠你给的描述。描述写得含糊模型就瞎调参数说明不清楚模型就填错。我见过一个查天气的工具描述写的是“获取天气信息”结果模型在用户问“明天适合跑步吗”的时候纠结了半天要不要调因为它不确定这个工具能不能回答“适不适合”这种判断性问题。好的工具描述应该包含三部分这个工具做什么、什么时候该用、参数是什么含义。还是查天气的例子改成“查询指定城市指定日期的天气状况返回温度、降水、风力等信息。当用户询问某地天气、或需要根据天气做判断时使用。参数city为城市名date为日期格式YYYY-MM-DD”。这样模型调用准确率会明显提升。3.2 参数校验和错误处理是必答题模型填参数是会出错的。日期格式填错、枚举值填成近义词、必填项漏填这些在真实场景里天天发生。如果你不在工具层做校验错误就会一路传到下游最后变成一个莫名其妙的报错。我的做法是每个工具入口都做三件事类型校验、范围校验、友好报错。类型不对直接返回“参数date格式应为YYYY-MM-DD你提供的是xxx”范围不对返回“city参数不支持空值”。关键是报错信息要能被模型读懂并自我纠正。你返回一个Python的traceback模型看不懂你返回一句人话模型下一轮就能改对。LangGraph里工具调用还有个细节工具执行失败后是让整个图崩掉还是把错误作为状态传下去让模型决定下一步我倾向于后者。把错误信息写进State让模型看到“上次调用失败了原因是xxx”它往往能自己换个方式重试。这比直接抛异常中断流程健壮得多。3.3 工具的数量要克制新手容易犯的错是工具越加越多觉得功能全就是好。实际上工具超过一定数量后模型的选择准确率会下降。我实测下来单个Agent的工具数量控制在10个以内比较稳超过15个就开始出现明显的误选。如果业务确实需要很多工具解法是分层上层用少量“路由工具”做粗分类每个路由指向一组细分工具。或者干脆拆成多个专职Agent各管一摊。这又回到了编排的问题——工具管理和流程编排是耦合的不能分开设计。4. 第三件事上下文工程Agent开发真正的深水区4.1 上下文不是越多越好“把相关信息都塞进prompt”是新手最常见的直觉也是效果最差的做法。上下文窗口再大塞进去的无关信息都会稀释模型的注意力。我做过对比测试同一个任务上下文从2000token加到8000token准确率不升反降因为模型被干扰信息带偏了。上下文工程的核心是在正确的时机给模型正确的信息。这包括几个层面系统提示词里放什么角色、规则、输出格式、每轮对话带多少历史全带还是滑动窗口还是摘要、工具返回结果怎么裁剪原始返回还是提取关键字段、检索到的文档怎么排序和截断。4.2 历史管理的三种策略对话历史管理是上下文工程里最实操的部分。我总结下来有三种策略各有适用场景。全量保留把所有历史都带上。适合短对话、对连贯性要求极高的场景。缺点是token消耗随轮次线性增长十几轮之后就爆了。滑动窗口只保留最近N轮。实现简单token可控。缺点是会丢失早期的重要信息比如用户第一轮说的偏好到第十轮就忘了。摘要压缩把早期历史用模型总结成一段话和最近几轮原文一起带上。这是效果和成本平衡得最好的方案但实现复杂而且摘要本身可能丢信息。我的经验是摘要prompt要明确要求“保留用户的所有明确偏好和已确认的事实”否则模型总结时会把这些细节当废话删掉。LangGraph里做历史管理通常是在State里维护一个messages列表然后在调用模型前用一个节点做裁剪或摘要。这个节点放在哪、什么时候触发是要根据业务调的。我的习惯是设一个token阈值超过就触发摘要而不是按轮次因为每轮长度差异很大。4.3 检索增强里的上下文陷阱做RAG的Agent检索回来的文档怎么放进上下文坑特别多。最常见的是直接拼接top-k文档结果模型被重复信息和低相关内容干扰。我的做法是三步先去重相似度高的只留一条、再重排用rerank模型按相关性排序、最后按相关性截断相关性低于阈值的直接丢哪怕k没凑够。宁可少给几条高相关的也不要凑数给一堆低相关的。还有个细节是文档的呈现格式。给模型看的文档最好带上来源标识和段落编号这样模型引用的时候能说清楚“根据文档A的第2段”方便你排查它是不是在胡编。这个格式设计看着小但对调试帮助极大。5. 第四件事评估和可观测性没有它就是在盲飞5.1 为什么Agent比普通LLM应用更难评估普通LLM应用输入输出基本确定评估相对直接。Agent不一样它有多步决策中间任何一步偏了最后结果就偏了。你看到最终答案错了但错在哪一步是工具选错了、参数填错了、还是上下文给少了没有中间过程的记录根本无从查起。所以Agent开发必须从一开始就建可观测性。每一步的输入、输出、耗时、token消耗、工具调用记录都要能追溯。LangGraph在这方面有天然优势因为它的图结构本身就定义了清晰的节点边界每个节点的进出都可以打点。LangChain的callback机制也能做但粒度粗一些。5.2 评估集怎么建评估集不是随便找几个问题就行。我的做法是按失败模式分类建集。先跑一批真实case把失败的挑出来归类是工具选择错误、参数错误、上下文不足、还是推理链断裂。然后每类失败模式设计5-10个测试用例形成一个有针对性的评估集。这个评估集要能自动化跑。每次改了prompt、换了模型、调了编排逻辑都跑一遍看各类失败模式的数量变化。没有这个你的每次改动都是凭感觉改好了不知道为什么好改坏了也不知道哪坏了。5.3 关键指标盯什么Agent的评估指标除了最终准确率我还会盯几个过程指标工具调用准确率该调的时候调了没、调对没、平均步数步数突然变多往往意味着模型在绕圈、单步失败率哪类工具最容易失败、token消耗分布钱花在哪了。这些指标里平均步数是最灵敏的。一个健康的Agent处理同类任务的步数应该稳定。如果某次突然多了好几步大概率是某一步没走通在反复试。这个信号比最终结果更早暴露问题。提示可观测性建设要趁早。等项目上线了再补历史数据就没了而且那时候改造成本高得多。前期多花两天打点后期省两周排查。6. 第五件事把安全边界设计进架构而不是事后打补丁6.1 Agent的安全问题和普通应用不一样普通应用的安全边界相对清晰输入校验、权限控制、输出过滤套路成熟。Agent的麻烦在于它有自主决策能力你没法穷举它所有可能的行为路径。它可能调用一个你没预料到的工具组合可能生成一段你没预料到的内容可能在循环里越走越偏。所以Agent的安全不能靠“堵”要靠“设计”。核心思路是最小权限 关键节点卡口 行为可回滚。最小权限好理解每个工具只给完成它职责所需的最小能力。查数据的工具就别给写权限读文件的工具就限定目录。关键节点卡口是指在流程的关键决策点加人工确认或规则校验比如涉及资金、涉及对外发送的操作必须过一道确认。行为可回滚是指每个有副作用的操作都要能撤销或者至少在执行前留好快照。6.2 循环失控是最常见的坑Agent跑着跑着陷入死循环是新手最容易遇到的严重问题。表现是token哗哗烧任务永远不结束。根因通常是工具一直返回模型不满意的结果模型就一直重试或者两个节点互相触发形成环。防御手段有三层。第一层是硬性步数上限超过就强制终止并返回当前状态。这个必须有是最后的安全网。第二层是重复检测如果连续几步的工具调用和参数高度相似就判定为绕圈主动中断。第三层是状态进展检查每步之后看State有没有实质变化没变化就说明卡住了。LangGraph里做这些相对方便因为循环是显式定义的你可以在边上加条件判断。但即便如此硬性步数上限也不能省因为条件判断本身也可能被绕过。6.3 输出内容的兜底Agent生成的最终内容尤其是要直接展示给用户或对外发送的必须过一道兜底检查。这不是不信任模型而是工程上必须有这道防线。检查什么取决于业务但通用的是格式是否符合预期、有没有明显的事实性错误能自动校验的部分、有没有不该出现的内容。我的做法是加一个“终审”节点放在流程最后。它不改变内容只做校验和标记。校验不过的要么打回重走要么降级到人工处理。这个节点看着多余但真出事的时候它是唯一能拦住的地方。7. 这五件事的练习顺序和常见误区7.1 建议的学习路径如果让我给一个从零开始的路径我会这么排先练编排再练工具然后上下文接着评估最后安全。编排是骨架没有它其他都是散的。工具是手脚编排搭好了自然要接工具。上下文是血液流程跑起来了才会遇到上下文管理的问题。评估是眼睛前面都跑通了才谈得上优化。安全是底线等前面都稳了再系统性地加固。这个顺序不是绝对的但大体上符合认知曲线。反过来先学安全你会觉得全是抽象规则没有体感先学评估你连个能跑的东西都没有评什么。7.2 几个我踩过的误区误区一追新框架。每隔几个月就有新框架出来看着很诱人。但框架是工具底层能力才是根本。把LangGraph吃透换个框架你也能快速上手只会调API换框架就归零。误区二Demo跑通就以为成了。Demo和生产的差距在Agent领域比任何领域都大。Demo里模型表现好是因为场景简单、边界清晰。生产里什么妖魔鬼怪都有必须用评估集反复磨。误区三忽视成本。Agent的token消耗是普通LLM应用的几倍甚至几十倍因为多步调用。不盯成本项目跑着跑着预算就没了。从第一天就要把token消耗纳入监控。误区四一个人闷头做。Agent开发涉及编排、prompt、工具、评估多个方面一个人容易有盲区。多跟做过的人聊很多坑别人已经踩过了一句话能省你一周。7.3 面试里这五件事怎么体现如果你在准备Agent开发相关的面试这五件事就是最好的答题框架。面试官问“你怎么设计一个Agent”你可以从编排结构讲起然后讲工具设计、上下文策略、评估方案、安全边界一套下来逻辑完整比背API强得多。面试官问“你遇到过什么难题”挑一个具体的失败模式讲你怎么通过可观测性定位、怎么改、改完评估指标怎么变。这种有细节、有数据、有反思的回答比空谈“我用了LangGraph”有说服力得多。8. 关于工程化落地的一点个人观察最近行业里有个说法2026年是工业智能体从概念演示走向工程化落地的分水岭。我认同这个判断而且觉得分水岭的标志就是大家不再比谁的Demo炫而是比谁的系统稳、成本可控、能持续迭代。这三样恰好对应上面五件事里的编排、评估和安全。我自己的项目从Demo到上线最大的转变就是从“让它能跑”变成“让它跑得稳、跑得省、跑得可解释”。这个转变过程中上面五件事反复出现每一件都值得单独花时间深挖。Agent开发这个方向门槛不在入门在深入。入门可能一周就会了但真正做好两年也只是刚摸到门道。如果你现在正卡在某个环节不妨对照这五件事自查一下看是哪一块没打通。大部分时候问题不在模型在工程。把工程做扎实了模型的能力才能真正释放出来。