1. 从“鹈鹕骑自行车”说起：为什么提示词玄学正在拖垮你的Agent
如果你最近在Agent开发圈子里混，一定见过那张“鹈鹕骑自行车”的测试图。有人拿它测模型的空间理解，有人拿它测提示词的鲁棒性，甚至有人把它当成衡量一个Agent“聪不聪明”的民间基准。但我想说的是，如果你把Agent优化的重心放在“怎么把鹈鹕骑车的提示词写得更花哨”上，那你大概率已经走偏了。
我见过太多团队，Agent效果不好，第一反应就是改提示词。加一句“你是一个专业的助手”，再加一句“请一步一步思考”，还不行就上“深呼吸，这很重要”。改了几十版，效果时好时坏，最后得出结论：提示词是玄学。这个结论本身没错，但问题在于，他们把本该花在框架优化、工具接口设计、控制逻辑上的时间，全砸在了提示词上。
Agent不是一个大号聊天机器人。一个能跑起来的Agent，至少包含四个部分：模型能力、提示词、工具接口、控制逻辑。提示词只是其中一层，而且往往是最不该被反复折腾的那一层。真正决定Agent能不能扛住并发、能不能稳定完成多步任务、能不能在长上下文里不丢记忆的，是后面三层。这篇文章我就想把这四层拆开，讲讲为什么“别把Agent优化写成提示词玄学”，以及一个从业者应该把精力放在哪里。
如果你正在做Agent项目，不管是用现成框架还是自己搭，不管你是刚入门还是已经踩过几个坑，下面这些内容应该都能帮你少走一段弯路。我会从提示词的真实作用边界讲起，然后逐层拆解框架、工具接口和控制逻辑的优化思路，最后给一些可以直接抄的实操建议。
2. 提示词的真实作用边界：它能做什么，不能做什么
2.1 提示词解决的是“表达问题”，不是“能力问题”
很多人对提示词有一个根本性误解：以为只要提示词写得足够好，模型就能完成任何任务。这个想法在单轮对话里可能还勉强成立，但在Agent场景里几乎必然翻车。
举个具体的例子。你让Agent去查一个数据库，然后根据查询结果生成一份报告。提示词可以告诉模型“你要先查数据库，再写报告”，但提示词没法让模型真的连上数据库。连接数据库这件事，靠的是工具接口。提示词也没法保证模型在查完数据库之后，一定记得把结果传给报告生成模块，这靠的是控制逻辑。提示词能做的，是让模型理解“现在该调用哪个工具”“调用时应该传什么参数”“拿到结果后该怎么组织语言”。
换句话说，提示词是Agent的“表达层”，不是“执行层”。它负责把任务意图翻译成模型能理解的指令，把模型输出翻译成下游能处理的格式。但它不负责实际的执行、状态管理和错误恢复。你把提示词写得再优雅，如果工具接口返回的是500错误，Agent照样卡死。
我自己的经验是，提示词优化有一个明显的收益递减曲线。前20%的优化能带来80%的效果提升，比如把模糊指令改成明确指令，把长段落改成结构化列表，把“请帮我”改成“你必须”。但超过这个点之后，每多改一个字，收益就急剧下降。这时候如果你还在死磕提示词，那就是在用战术上的勤奋掩盖战略上的懒惰。
2.2 那些“提示词玄学”背后的真实原因
为什么很多人会觉得提示词是玄学？因为他们在用提示词去补框架和工具的窟窿。
比如，Agent在多轮对话里忘了之前说过的话。有人就去提示词里加“请记住用户之前说的内容”。这有用吗？短期可能有点用，但根本原因是你的Agent没有做记忆管理。对话历史没有做摘要，没有做向量检索，没有做关键信息抽取，全靠模型自己在上下文窗口里硬记。上下文一长，模型必然丢信息。这时候你改提示词，就像给一个漏水的桶换了个更漂亮的盖子。
再比如，Agent调用工具时经常传错参数。有人就去提示词里加“请仔细阅读工具的参数说明”。但真实原因可能是你的工具描述写得含糊不清，参数类型没有做校验，或者工具接口的返回格式和提示词里说的不一致。模型不是不仔细，是你的工具接口本身就在误导它。
还有一种常见情况：Agent在某个步骤卡住，反复调用同一个工具。有人就去提示词里加“如果失败三次就换一种方法”。但控制逻辑里根本没有失败计数和重试策略，模型只能凭感觉判断“三次”到了没有。这种靠提示词来模拟控制逻辑的做法，在简单场景下能跑通，一旦并发上来或者任务变复杂，立刻崩盘。
所以，当你觉得提示词是玄学的时候，先别急着改提示词。去看看你的框架有没有做状态管理，你的工具接口有没有做参数校验，你的控制逻辑有没有做异常处理。这些问题不解决，提示词改出花来也没用。
2.3 提示词该管什么：意图对齐与格式约束
说了这么多提示词的局限，那它到底该管什么？我的答案是两件事：意图对齐和格式约束。
意图对齐，就是让模型明白“现在要干什么”。Agent在一个任务里会经历很多步骤，每一步的意图可能都不一样。提示词要做的，是在每个步骤开始时，把当前的目标、可用的工具、已知的上下文，清晰地告诉模型。这里的关键是“清晰”，不是“多”。很多提示词写得又臭又长，模型反而抓不住重点。我习惯把每个步骤的提示词控制在200字以内，只保留三个要素：当前目标、可用工具、输出格式。
格式约束，就是让模型的输出能被下游稳定解析。Agent不是给人看的，是给程序看的。模型的输出如果是一段自由文本，下游就没法处理。所以提示词里必须明确要求模型按特定格式输出，比如JSON、XML或者特定的标记语言。这里有个实操技巧：不要只描述格式，要给一个具体的例子。模型对例子的遵循程度远高于对描述的理解程度。
提示：如果你发现模型经常不按格式输出，先检查你的格式描述是不是太抽象。把“请输出JSON”改成“请输出如下格式的JSON：{"action": "工具名", "params": {...}}”，效果会好很多。
3. 框架优化：Agent的骨架比皮肤更重要
3.1 状态管理：别让模型自己记事情
Agent和普通聊天机器人最大的区别，就是Agent有状态。它需要记住自己执行到哪一步了，之前调用了哪些工具，拿到了什么结果，下一步该干什么。这些信息如果全靠模型在上下文里记，那你的Agent上限就是模型的上下文窗口大小。
我见过一个项目，Agent要处理一个十步左右的任务流程。开发团队没有做状态管理，全靠提示词里塞历史记录。结果任务跑到第七步，模型开始忘记第三步的结果，输出质量断崖式下降。他们以为是提示词不够好，改了两周提示词，最后发现是上下文超了。
正确的做法是，在框架层面维护一个显式的状态对象。这个状态对象至少包含：当前步骤编号、已完成步骤的结果摘要、待执行步骤列表、全局变量。每次调用模型时，只把和当前步骤相关的状态注入提示词，而不是把全部历史都塞进去。这样既能保证模型有足够的信息做决策，又不会撑爆上下文。
状态管理还有一个好处：可观测性。当Agent出问题时，你可以直接看状态对象，知道它卡在哪一步、上一步拿到了什么结果。如果全靠模型自己记，出问题了只能靠猜。
3.2 上下文工程：什么该进提示词，什么该留在外面
上下文工程是Agent框架里最容易被低估的部分。很多人把“上下文”等同于“对话历史”，这是不对的。Agent的上下文应该是一个经过筛选和压缩的信息集合，而不是原始对话的堆砌。
我的做法是把上下文分成三类：必须进提示词的、可以摘要后进提示词的、完全不进提示词的。
必须进提示词的，是当前步骤直接依赖的信息。比如当前要调用的工具的参数，上一步工具返回的关键结果，当前步骤的目标。这些信息如果不给模型，模型就没法做决策。
可以摘要后进提示词的，是历史步骤的结果。比如前面五步已经完成了数据收集，现在要生成报告。你不需要把五步的原始数据都塞进去，只需要给一个摘要：“已收集到用户基本信息、订单记录、支付记录，共三类数据”。模型知道有这些数据就够了，具体内容在需要时可以通过工具再查。
完全不进提示词的，是那些和当前任务无关的历史对话、系统日志、调试信息。这些东西留在外面，需要的时候再通过工具接口按需获取。
这样做的好处是，提示词的长度可控，模型注意力集中，而且框架的扩展性更好。你新增一个工具，不需要改提示词，只需要在状态管理里注册一下，在需要的时候把工具描述注入进去就行。
3.3 错误恢复：Agent卡住了怎么办
Agent跑着跑着卡住，是再常见不过的事。工具超时、返回格式不对、模型输出无法解析、任务目标不明确，任何一个环节出问题，Agent都可能停在那里。
提示词解决不了错误恢复。你可以在提示词里写“如果出错请重试”，但模型不知道什么叫“出错”，也不知道重试几次算够。错误恢复必须在框架层面做。
我的框架里通常有三层错误恢复机制。第一层是工具级重试：工具调用失败时，框架自动重试，最多三次，每次间隔递增。第二层是步骤级回退：如果某个步骤连续失败，框架把状态回退到上一个成功步骤，换一种策略重新执行。第三层是任务级降级：如果整个任务无法完成，框架输出一个部分结果，并标记哪些步骤失败了，让上游决定怎么处理。
这三层机制不需要模型参与，全是框架的职责。模型只需要在每一步输出“我要调用什么工具”或者“我完成了”，剩下的交给框架。这样Agent的稳定性会高很多，而且出问题时排查起来也有明确的路径。
注意：错误恢复的日志一定要打全。每次重试、回退、降级都要记录原因和上下文。不然出了问题，你连Agent为什么卡住都不知道。
4. 工具接口设计：Agent的手脚要灵活且可靠
4.1 工具描述：写给模型看的API文档
工具接口是Agent和外部世界交互的通道。工具描述写得好不好，直接决定模型能不能正确调用工具。
很多人的工具描述是写给人类开发者看的，比如“查询用户信息接口，传入用户ID，返回用户详情”。这种描述对人类够用，但对模型不够。模型需要知道：这个工具在什么场景下用，参数是什么类型，必填还是选填，返回值的结构是什么，有没有副作用。
我写工具描述时，会遵循一个模板：用途 + 触发条件 + 参数说明 + 返回说明 + 示例。用途一句话说清楚这个工具干什么。触发条件说明什么时候该用这个工具，什么时候不该用。参数说明要列出每个参数的名称、类型、是否必填、取值范围。返回说明要描述返回值的结构，最好给一个示例。示例是最重要的，模型对示例的遵循程度远高于对描述的理解。
举个例子，一个查询订单的工具，描述可以这样写：
{ "name": "query_order", "description": "根据订单号查询订单详情。当用户询问订单状态、物流信息、退款进度时使用此工具。不要用于查询用户信息或商品信息。", "parameters": { "order_id": { "type": "string", "required": true, "description": "订单号，格式为ORD开头加12位数字，例如ORD202401011234" } }, "returns": { "type": "object", "description": "订单详情对象，包含status（订单状态）、amount（金额）、create_time（创建时间）等字段", "example": { "status": "shipped", "amount": 299.00, "create_time": "2024-01-01 12:34:56" } } }这样的描述，模型一看就知道什么时候用、怎么用、会得到什么。比一句“查询订单”强太多了。
4.2 参数校验：别让模型传脏数据
模型传参出错是常态。它可能把数字传成字符串，可能漏传必填参数，可能传一个不存在的枚举值。如果你不在工具接口层做校验，这些脏数据就会流到下游，引发更难排查的问题。
我的做法是在工具接口层做严格的参数校验。每个工具在真正执行前，先过一遍校验逻辑。校验内容包括：必填参数是否存在、参数类型是否正确、参数值是否在允许范围内、参数之间是否有冲突。校验不通过时，不要直接抛异常，而是返回一个结构化的错误信息，告诉模型哪个参数错了、应该怎么改。
比如模型传了一个不合法的订单号，工具返回：
{ "error": "INVALID_PARAMETER", "message": "order_id格式不正确，应为ORD开头加12位数字", "received": "12345" }模型拿到这个错误信息后，可以自己纠正，重新调用。这比直接抛一个500错误让Agent卡死要好得多。
4.3 返回格式：让模型能读懂工具的输出
工具返回的数据格式，直接影响模型能不能正确理解结果。如果工具返回一大段自由文本，模型可能抓不住重点。如果工具返回嵌套很深的JSON，模型可能解析出错。
我一般要求工具返回扁平化的、带明确字段名的JSON。字段名要语义清晰，不要用缩写。比如用order_status而不是os，用create_time而不是ct。如果返回的是列表，要说明列表的长度和每个元素的含义。如果返回的数据量很大，要做分页或者摘要，不要把全部数据一次性塞给模型。
还有一个细节：工具返回的时间格式要统一。不要一会儿用时间戳，一会儿用字符串。我习惯统一用ISO 8601格式，比如2024-01-01T12:34:56Z。这样模型理解起来不会有歧义。
5. 控制逻辑：Agent的大脑不能只靠模型
5.1 流程编排：什么时候该让模型决策，什么时候该走固定流程
Agent的一个常见误区是，把所有决策都交给模型。模型说下一步干什么就干什么，模型说调用哪个工具就调用哪个工具。这种做法在简单任务里能跑通，但在复杂任务里，模型很容易跑偏。
我的原则是：能走固定流程的，不要交给模型决策。比如一个任务有明确的步骤顺序，第一步查数据，第二步处理数据，第三步生成报告。这个顺序是固定的，不需要模型来判断。框架直接按顺序执行，每一步只让模型做该步骤内的决策。
只有那些真正需要灵活判断的地方，才交给模型。比如“根据用户的问题，判断应该查订单还是查物流”，这种分支决策适合模型来做。但“查完订单之后要生成报告”这种固定流程，框架直接编排就行。
这样做的好处是，Agent的行为可预测、可测试、可调试。如果全交给模型决策，每次运行的结果可能都不一样，出了问题也很难复现。
5.2 并发控制：Agent扛不住并发，往往是控制逻辑的锅
“AI Agent怎么扛并发”是最近的热词，很多人关心这个问题。我的观察是，Agent扛不住并发，很少是因为模型本身，更多是因为控制逻辑没设计好。
Agent的并发瓶颈通常出现在三个地方：工具调用、状态管理、上下文构建。工具调用如果同步阻塞，一个请求卡住，后面的请求全排队。状态管理如果用了全局锁，并发一高就互相等待。上下文构建如果每次都重新计算，CPU和内存都会爆。
我的做法是：工具调用全部异步化，用消息队列解耦；状态管理按会话隔离，每个会话独立的状态对象，互不干扰；上下文构建做缓存，相同步骤的上下文只构建一次，后续请求直接复用。
还有一个容易被忽略的点：限流和降级。Agent的并发能力是有上限的，超过上限之后，与其让所有请求都变慢，不如主动拒绝一部分请求，保证剩下的请求能正常处理。这需要在控制逻辑里做限流，比如令牌桶或者滑动窗口。降级策略也要提前设计好，比如模型调用超时了，是返回缓存结果还是返回错误提示。
5.3 可观测性：Agent出问题了，你怎么知道
Agent系统最让人头疼的地方是，出问题了不知道哪里出的。模型输出不对，是提示词的问题？是工具返回的问题？还是控制逻辑的问题？如果没有可观测性，你只能靠猜。
我在框架里会记录三类日志：决策日志、工具日志、状态日志。决策日志记录模型每一步的输入和输出，包括提示词、模型返回、解析结果。工具日志记录每次工具调用的参数、返回值、耗时、是否成功。状态日志记录状态对象的每次变更，包括变更前后的值、变更原因。
这三类日志结合起来，就能完整还原Agent的执行过程。出问题时，你可以直接看日志，定位到具体是哪一步、哪个环节出的问题。这比改提示词试错要高效得多。
提示：日志要结构化，方便检索和分析。我一般用JSON格式，每条日志包含timestamp、session_id、step、event_type、data等字段。这样可以直接导入日志系统做聚合分析。
6. 实操建议：从今天开始，把Agent优化拉回正轨
6.1 先做框架，再做提示词
如果你刚开始做Agent项目，我的建议是先把框架搭好，再调提示词。框架包括状态管理、工具接口、控制逻辑、日志系统。这些基础设施做好了，提示词只需要做意图对齐和格式约束，工作量小很多，效果也稳定很多。
具体来说，你可以先定义一个状态对象的结构，然后实现一个简单的流程编排引擎，再注册几个工具接口，最后加上日志。这套东西搭起来大概需要几天时间，但后面会省下你几周甚至几个月的调试时间。
6.2 提示词版本管理：别把提示词当一次性消耗品
提示词是需要迭代的，但迭代不等于乱改。我建议把提示词当成代码来管理：用版本控制工具管理，每次修改记录原因和效果，做A/B测试对比不同版本的表现。
具体操作上，我会把提示词拆成模板和变量。模板是固定的部分，比如“你是一个专业的助手，当前步骤是{{step_name}}，可用工具是{{tools}}”。变量是动态注入的部分，比如当前步骤的名称、可用工具列表、上下文摘要。这样修改提示词时，只需要改模板，不需要动变量注入的逻辑。
A/B测试也很重要。同一个任务，用两个版本的提示词各跑100次，对比成功率、平均耗时、工具调用次数。数据说话，比凭感觉改提示词靠谱得多。
6.3 工具接口的测试：别等上线了才发现工具调不通
工具接口是Agent和外部世界的边界，也是最容易出问题的地方。我建议每个工具接口都要有单元测试和集成测试。单元测试验证参数校验逻辑，集成测试验证工具在真实环境下的表现。
测试用例要覆盖正常情况、边界情况、异常情况。比如查询订单的工具，正常情况是传一个合法订单号，边界情况是传一个不存在的订单号，异常情况是传一个格式错误的订单号。每种情况都要验证工具返回的结果是否符合预期。
还有一个实操技巧：在开发阶段，给每个工具加一个mock模式。mock模式下，工具不真正调用外部服务，而是返回预设的测试数据。这样你可以在不依赖外部服务的情况下，快速测试Agent的完整流程。
6.4 性能优化：从工具调用和上下文构建入手
Agent的性能优化，优先级最高的是工具调用和上下文构建。工具调用如果慢，整个Agent就慢。上下文构建如果每次都重新计算，CPU和内存都会成为瓶颈。
工具调用的优化手段包括：异步化、批量调用、缓存结果、设置超时。异步化让多个工具可以并行调用，批量调用减少网络往返，缓存结果避免重复查询，设置超时防止单个工具拖垮整个Agent。
上下文构建的优化手段包括：缓存、增量更新、懒加载。缓存让相同步骤的上下文只构建一次，增量更新只更新变化的部分，懒加载在需要时才构建上下文。这些手段结合起来，可以显著降低上下文构建的开销。
6.5 一个真实的踩坑案例：提示词改了三十版，最后发现是工具返回格式的问题
最后分享一个我自己的踩坑经历。之前做一个Agent项目，任务是让Agent根据用户问题查询数据库并生成回答。上线后发现，Agent经常答非所问，或者把查询结果搞混。团队第一反应是改提示词，前后改了三十多版，效果时好时坏。
后来我接手排查，发现根本原因在工具接口。数据库查询工具返回的是一个嵌套很深的JSON，字段名用的是数据库的原始列名，比如usr_nm、ord_st。模型根本看不懂这些缩写，只能靠猜。猜对了就答对，猜错了就答非所问。
我把工具返回格式改成扁平化的、语义清晰的JSON，字段名改成user_name、order_status，并且加了一个summary字段，用自然语言概括查询结果。改完之后，提示词一个字没动，Agent的准确率从60%多直接拉到90%以上。
这个案例让我深刻体会到，Agent优化不是提示词玄学，而是系统工程。提示词只是冰山一角，水面下的框架、工具接口、控制逻辑才是决定Agent表现的关键。希望这篇文章能帮你把精力放在正确的地方，少走一些我走过的弯路。
