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开发这个方向，门槛不在入门，在深入。入门可能一周就会了，但真正做好，两年也只是刚摸到门道。
如果你现在正卡在某个环节，不妨对照这五件事自查一下，看是哪一块没打通。大部分时候，问题不在模型，在工程。把工程做扎实了，模型的能力才能真正释放出来。
