1. 项目概述为什么工具链设计是Agent成败的关键最近在折腾各种AI Agent项目从简单的自动化脚本到复杂的多智能体协作系统踩过的坑能写满一本错题集。我发现一个特别有意思的现象很多团队在构建Agent时往往把90%的精力都花在了模型选型、Prompt工程和业务逻辑编排上却对“工具链”这个看似基础的部分草草了事。结果就是Agent看起来聪明绝顶能说会道但一到动真格需要调用外部工具执行具体任务时就频频掉链子——要么找不到合适的工具要么用错了参数要么在复杂的工具组合调用中迷失方向。这感觉就像给一位顶尖外科医生配了一套生锈的、不顺手的手术器械他空有满腹理论和一双巧手却无法高效、精准地完成手术。这个项目标题“工具链设计——让LLM用对工具的五个原则”恰恰点中了当前Agent开发中最隐秘也最关键的痛点。它讨论的不是如何造更锋利的“刀”工具本身而是如何设计一套“刀架”、“使用说明书”和“协同工作流”让LLM这位“主刀医生”能准确、安全、高效地使用每一把“刀”。这里的“工具链”远不止是一个简单的API列表它是一个包含了工具发现、描述、调用、编排、容错和安全保障的完整体系。设计得好Agent的能力边界将被极大拓展从“纸上谈兵”的聊天机器人蜕变为真正能解决实际问题的智能体设计得不好Agent就会变成一个眼高手低的“理论家”空有理解力缺乏执行力。基于我过去在多个实际Agent项目中总结的经验以及观察到的行业最佳实践我将这“五个原则”视为构建健壮Agent工具能力的基石。它们不仅适用于基于大语言模型的Agent对于任何需要将“思考”与“行动”结合起来的智能系统都有极高的参考价值。接下来我们就深入拆解这五个原则背后的设计哲学、具体实现方案以及那些只有踩过坑才知道的实操细节。2. 核心原则一意图与工具的精确对齐让LLM用对工具的第一步是确保它能准确理解用户的意图并将这个意图映射到最恰当的一个或一组工具上。这听起来像是简单的“检索”或“匹配”问题但在动态、开放的真实场景中实现“精确对齐”充满了挑战。2.1 超越关键词匹配基于语义与上下文的工具发现最原始的工具调用方式是硬编码或基于关键词的规则匹配。例如用户说“查天气”就固定调用get_weather函数。这种方式在封闭场景下有效但极度脆弱。一旦用户换种说法比如“明天需不需要带伞”或“下午的降水概率如何”规则系统就可能失效。现代Agent的工具发现机制核心是利用LLM自身的语义理解能力。我们不再直接匹配关键词而是将用户的查询Query和所有可用工具的“描述”一起交给LLM让它来判断哪个工具最相关。这里的关键在于如何撰写工具的“描述”。一个糟糕的描述是“calculate一个计算函数”。这种描述信息量几乎为零。一个优秀的描述应该包含功能这个工具是做什么的用自然语言清晰说明。输入它需要什么参数每个参数的类型、格式、可选/必选、示例是什么输出它会返回什么数据结构是怎样的适用场景在什么情况下应该优先考虑使用这个工具限制与前提使用它需要什么前提条件它有哪些已知限制例如对于一个查询股票价格的工具其描述应该这样写工具名称get_stock_price 功能获取指定上市公司股票在特定交易日的开盘价、收盘价、最高价、最低价和交易量。 输入 - symbol (字符串必填)股票代码例如 ‘AAPL’ 代表苹果公司‘00700.HK’ 代表腾讯控股。 - date (字符串格式 ‘YYYY-MM-DD’可选)查询日期默认为最近一个交易日。 输出一个JSON对象包含 ‘open’, ‘close’, ‘high’, ‘low’, ‘volume’ 字段。 适用场景当用户询问某只股票的价格、当日行情或历史某天行情时使用。 注意该工具数据延迟约15分钟不提供实时盘口数据。对于A股股票请使用‘000001.SZ’格式。当用户提问“苹果公司昨天的股价表现怎么样”时LLM会将这个问题与所有工具描述进行语义相似度计算可以是嵌入向量比较也可以是让LLM直接判断。由于描述中包含了“苹果公司”可关联到‘AAPL’、“昨天”关联到date参数、“股价表现”关联到开盘价、收盘价等输出字段LLM就能高置信度地选中get_stock_price工具并尝试填充symbol‘AAPL’和date‘2023-10-26’假设当天是27号。实操心得描述即契约工具描述是LLM理解工具的唯一窗口。务必用清晰、无歧义的语言编写并包含丰富的示例。我习惯为每个工具编写3-5个不同的用户查询示例及其对应的正确调用参数将这些示例作为描述的一部分或单独提供给LLM作为Few-shot学习样本能显著提升意图对齐的准确率。2.2 处理模糊意图与工具组合用户的意图常常是模糊或复杂的单一工具可能无法满足。这时就需要LLM具备“规划”能力将一个高层意图分解为多个子任务每个子任务对应一个工具。例如用户说“帮我分析一下特斯拉和比亚迪最近一个月的股价走势并总结一下。”这个意图至少涉及以下几个工具get_stock_price(多次调用)获取TSLA和BYDDY或对应A股/港股代码过去30天的每日价格。calculate_statistics计算两只股票在这段时间内的平均价格、波动率等。plot_chart生成股价走势对比图。generate_summary基于数据和图表生成文字分析报告。实现这种组合的关键在于设计一个“规划器”Planner。这个规划器可以是一个特定的LLM调用其Prompt模板专门用于任务分解。输入是用户意图和工具列表输出是一个有序的工具调用计划Plan。这个计划需要明确执行顺序、工具间的数据流例如工具1的输出是工具2的输入。# 规划器Prompt示例简化 你是一个任务规划专家。请根据用户的请求和可用的工具列表将复杂请求分解为一系列可顺序执行的工具调用步骤。 用户请求{user_query} 可用工具{tool_descriptions} 请输出一个JSON数组每个元素是一个步骤包含 {“step_id”: 1, “tool_name”: “xxx”, “reasoning”: “为什么用这个工具”, “inputs”: {…}, “depends_on”: [步骤ID] }。避坑指南规划中的幻觉与循环LLM在规划时可能产生“幻觉”发明出不存在的工具或参数。务必在规划步骤后加入“验证”环节检查计划中的每个工具是否真实存在所需参数是否都能从用户输入或上游工具输出中获得。另一个常见问题是“循环依赖”或“死循环”例如计划中要求工具A的输出作为工具B的输入但工具B的输出又是工具A的输入。需要在设计时加入循环检测和最大步数限制。3. 核心原则二结构化与自描述的接口LLM是文本的王者但对非结构化的、隐含的接口信息理解能力有限。因此提供给LLM的工具接口必须是高度结构化和自描述的。3.1 从函数签名到JSON Schema在传统编程中我们通过函数名、参数类型和文档来理解一个函数。对于LLM我们需要将这种信息转化为它更容易消化的格式即JSON Schema。许多Agent框架如LangChain、LlamaIndex都要求工具以符合OpenAPI规范或类似JSON Schema的形式进行定义。一个完整的工具定义JSON Schema应该包含name: 工具的唯一标识符。description: 上文提到的详细自然语言描述。parameters: 一个JSON Schema对象明确定义每个参数的属性type,description,enum等。required: 必填参数列表。returns: 返回值的描述或Schema。{ “name”: “send_email”, “description”: “向指定的一个或多个收件人发送电子邮件。”, “parameters”: { “type”: “object”, “properties”: { “recipients”: { “type”: “array”, “items”: {“type”: “string”, “format”: “email”}, “description”: “收件人邮箱地址列表” }, “subject”: { “type”: “string”, “description”: “邮件主题” }, “body”: { “type”: “string”, “description”: “邮件正文支持纯文本” }, “cc”: { “type”: “array”, “items”: {“type”: “string”, “format”: “email”}, “description”: “抄送人邮箱地址列表可选” } }, “required”: [“recipients”, “subject”, “body”] }, “returns”: { “description”: “返回一个对象包含 ‘success’ (布尔值表示是否发送成功) 和 ‘message_id’ (字符串成功时返回邮件ID)。” } }LLM在决定调用此工具时会参考这个Schema来构建一个符合格式的JSON对象作为调用参数。清晰的description和严格的type、format约束能极大减少参数格式错误。3.2 动态参数与枚举值提示有些工具的参数可能依赖于运行时状态。例如一个文件管理工具中的path参数其有效值取决于当前的工作目录。一个数据库查询工具的table_name参数有效值取决于数据库中有哪些表。对于这类情况不能只提供一个静态的Schema。我们需要设计“动态参数获取”机制。有两种常见模式预检查询在LLM正式调用工具前先调用一个“参数建议”工具。例如list_current_directory工具返回当前目录下的文件列表供LLM在后续调用read_file时作为filename参数的候选值。枚举值内联在工具描述或Schema中直接说明如何获取有效值。例如在描述中写明“table_name参数必须是当前数据库中存在的表名。你可以先调用list_tables工具来获取所有表名列表。”对于有固定枚举值的参数如status可以是[‘open’ ‘closed’ ‘in_progress’]一定要在Schema的enum字段中明确列出并配上简要说明。这比让LLM去“猜”一个有效值要可靠得多。注意事项Schema的严谨性与灵活性平衡虽然严格的Schema能减少错误但过度严格也可能限制LLM的发挥。例如如果一个参数描述为“城市名”类型是stringLLM可能会输入“New York City”。但后端接口可能只接受“new_york”这样的代码。这时更好的做法是在Schema中提供示例或者在后端工具实现中加入一个轻量的“参数规范化”层将LLM生成的友好名称映射到内部代码。不要把所有的格式校验压力都留给LLM。4. 核心原则三安全、可控的执行沙箱工具调用意味着赋予LLM操作外部系统的能力这必然带来安全风险。一个设计不当的工具链可能让LLM无意中删除重要文件、发送垃圾邮件、或查询敏感数据。因此必须为工具执行构建一个安全、可控的“沙箱”。4.1 权限分级与最小权限原则不是所有工具都应该对所有Agent开放。应根据工具的危险程度和Agent的信任等级实施严格的权限控制。无害工具如信息查询天气、股票、计算、文本处理。可以默认开放。敏感操作工具如读取本地文件、查询数据库仅限特定表、发送通知。需要经过更严格的意图审核或限制在特定的安全上下文中使用。高危工具如写入文件、执行系统命令、发送邮件/消息、进行金融交易。必须施加额外的安全护栏例如需要人工确认Human-in-the-loop或仅允许在完全隔离的测试环境中使用。在架构设计上可以实现一个“工具网关”或“策略执行点”。所有工具调用请求都经过这里网关根据预定义的安全策略哪个Agent在什么情况下可以调用哪个工具进行校验。策略可以基于角色Role、上下文Context甚至动态风险评估来决定。4.2 输入验证与输出过滤即使LLM生成的调用参数符合Schema在真正执行前仍需进行业务逻辑层面的验证。输入验证检查参数值是否在合理范围内。例如date参数不能是未来日期amount参数不能是负数user_id参数必须对应一个真实存在的用户。这部分验证最好在工具的后端实现内部完成并返回清晰的错误信息。输出过滤工具返回的数据可能包含敏感信息如用户手机号、身份证号。在将结果返回给LLM或最终用户前需要进行脱敏处理。例如一个查询用户详情的工具其返回的JSON中的phone字段在传递给LLM前应被替换为“[REDACTED]”。这防止了敏感信息在后续的LLM处理或对话中被泄露。4.3 资源隔离与执行限制对于执行代码、命令或访问网络的工具必须进行严格的资源隔离。时间限制为每个工具调用设置超时如30秒防止某个工具陷入死循环或长时间等待阻塞整个Agent。资源限制限制工具可以使用的内存、CPU和网络带宽。对于代码执行类工具应运行在容器如Docker或轻量级沙箱中。网络隔离限制工具可以访问的网络端点。禁止访问内部管理网络或敏感系统。实操心得默认拒绝显式允许在安全策略上务必采用“默认拒绝”原则。所有工具默认都是不可用的只有经过明确授权通过策略配置后特定的Agent才能在特定的会话中使用它。定期审计工具调用日志检查是否有异常模式。同时为每个工具调用生成唯一的追踪ID并记录完整的请求和响应脱敏后这对于问题排查和安全审计至关重要。5. 核心原则四鲁棒的交互与错误处理LLM和工具之间的交互不可能一帆风顺。工具可能暂时不可用、参数错误、或者返回意外结果。一个鲁棒的工具链必须能优雅地处理这些错误并引导LLM进行恢复。5.1 清晰的错误反馈机制当工具调用失败时后端返回的错误信息不应该是一串晦涩的技术栈追踪Stack Trace。应该设计一套对LLM友好的错误码和错误信息格式。一个糟糕的错误返回{“error”: “Internal Server Error: Connection timeout to database ‘prod-db’“}。这个错误对LLM来说信息不够明确它可能不知道该如何处理“数据库连接超时”。一个优秀的错误返回应该结构化并包含可操作的指导{ “success”: false, “error_code”: “TOOL_EXECUTION_TIMEOUT”, “error_message”: “在执行‘query_database’工具时连接数据库超时超过10秒。这可能是因为数据库负载过高或网络问题。”, “suggested_action”: “请稍后重试此操作。如果问题持续存在可能需要检查数据库状态。”, “retryable”: true, “original_error”: “{…}” // 可选的原始错误详情用于开发者调试 }LLM在收到这样的错误后可以理解错误类型TOOL_EXECUTION_TIMEOUT知道原因连接超时并且获得了明确的建议稍后重试。retryable字段尤其重要它直接告诉LLM这个操作是否值得重试。对于非重试性错误如权限不足PERMISSION_DENIEDLLM就应该放弃重试转而向用户报告失败或尝试替代方案。5.2 重试、降级与备选方案基于清晰的错误反馈我们可以为Agent设计错误处理策略自动重试对于标记为retryable的错误如网络超时、临时性服务不可用Agent可以自动重试1-2次每次重试间隔稍作延长。降级处理当主要工具失败时尝试使用功能相近但可能精度稍差或范围较窄的备选工具。例如当精确的地理编码服务失败时可以降级使用一个基于关键词的简单地点搜索工具。向用户求助当自动处理无法解决时LLM应该坦诚地向用户说明遇到了什么问题并可能询问更多信息或请求人工介入。例如“我尝试为您查询航班但订票系统目前暂时无法访问。您是希望我稍后再试还是您有已查好的航班号我可以为您记录”实现这些策略需要在Agent的决策循环中加入“错误处理”这个专门的状态或步骤。当工具调用返回错误时不是直接失败而是触发错误处理逻辑由另一个专门的LLM调用或规则引擎来决定下一步行动。避坑指南避免无限重试和错误传播一定要为自动重试设置上限如最多3次。否则一个持续失败的工具可能导致Agent陷入死循环。另外要小心处理“错误链”。工具A失败导致降级到工具B工具B又因为输入格式不对而失败……最终呈现给用户的可能是一个与根源问题无关的令人困惑的错误。好的做法是在降级或更换工具前评估当前错误的根本原因是否会影响备选工具并尽可能重置到清晰的初始状态。6. 核心原则五上下文感知与状态管理工具调用不是孤立的事件。一次复杂的任务往往涉及多个工具的连续调用且后一个工具的调用可能依赖于前一个工具的结果或更早的对话历史。因此工具链必须与Agent的上下文和状态管理深度集成。6.1 维护工具调用历史Agent需要记住它已经做了什么。这不仅仅是记录日志而是要将工具调用的“输入-输出”对以一种结构化的方式纳入到后续LLM推理的上下文中。常见的做法是维护一个“对话历史”或“工作记忆”其中交替存放着用户消息、LLM的思考、工具调用请求和工具调用结果。对话历史示例 [ {“role”: “user”, “content”: “帮我查一下北京今天和明天的天气然后推荐一下穿什么衣服。”}, {“role”: “assistant”, “content”: “我需要先获取北京今明两天的天气数据然后根据气温和天气状况给出穿衣建议。”}, {“role”: “tool_call”, “name”: “get_weather”, “arguments”: {“city”: “北京” “date”: “2023-10-27”}}, {“role”: “tool_result”, “content”: “{‘date’: ‘2023-10-27’ ‘city’: ‘北京’ ‘condition’: ‘晴’ ‘max_temp’: 18 ‘min_temp’: 8}”}, {“role”: “tool_call”, “name”: “get_weather”, “arguments”: {“city”: “北京” “date”: “2023-10-28”}}, {“role”: “tool_result”, “content”: “{‘date’: ‘2023-10-28’ ‘city’: ‘北京’ ‘condition’: ‘多云转小雨’ ‘max_temp’: 15 ‘min_temp’: 10}”}, {“role”: “assistant”, “content”: “根据查询结果今天北京晴8-18度明天多云转小雨10-15度。建议今天可以穿单衣加外套明天因为有雨最好穿防风外套并带伞。”} ]当LLM进行下一步推理时这段完整的历史会被作为上下文输入。这样它就知道已经查过天气了不必重复查询并且可以直接引用max_temp、condition等具体数据来生成穿衣建议。6.2 管理长期状态与会话边界有些任务可能跨越多次用户对话。例如用户第一次说“开始为我规划一个北京三日游行程”Agent调用了一系列工具查询景点、酒店、交通。用户第二天又说“把第二天行程里的故宫换成国家博物馆”。这时Agent需要能关联到之前的“规划会话”并记得之前生成的行程状态。这就需要引入“会话”Session和“长期状态”Long-term State的概念。每个用户会话有一个唯一IDAgent可以将复杂的、多步骤的任务状态如已规划的行程草案、已选中的商品列表持久化存储到数据库或缓存中。当用户再次发起相关请求时Agent通过会话ID加载之前的状态从而在正确的上下文中继续工作。工具链设计需要支持这种状态管理。例如某些工具如save_itinerary_draftload_itinerary_draft本身就是用来读写持久化状态的。更重要的是工具调用逻辑需要能访问和修改当前会话的上下文状态。6.3 工具结果的摘要与精炼工具返回的数据可能是庞大且杂乱的如一个包含数十个字段的数据库查询结果或一个冗长的网页内容。如果直接将所有原始数据塞进上下文会迅速耗尽LLM的上下文窗口并引入噪音。因此需要在将工具结果返回给LLM主循环前对其进行“摘要”或“精炼”。这可以通过一个轻量级的LLM调用来实现有时被称为“工具结果处理器”。这个处理器的任务是从原始结果中提取出与当前任务最相关的关键信息并以简洁、结构化的格式呈现。例如一个搜索工具返回了10条网页摘要。结果处理器可以分析这10条结果去重、排序并总结出3条最相关的要点再交给主LLM。这样既保留了关键信息又节省了上下文空间还提高了主LLM处理信息的效率。实操心得上下文窗口的权衡艺术维护丰富的上下文固然有利于连贯性但成本也高更长的Prompt更高的API费用和延迟。需要根据任务复杂度做权衡。对于简单任务可以只保留最近几轮交互对于复杂任务则需要精心设计状态管理。一个技巧是“分层摘要”随着对话进行定期将早期的详细历史总结成一段简短的背景描述替换掉原来的冗长记录从而在有限的窗口内保留更长时间跨度的信息。另一个技巧是“选择性上下文”在调用LLM进行下一步推理前动态地从历史中选取与当前问题最相关的片段作为上下文而不是总是传入全部历史。 AI Agent工具链设计：五大核心原则提升LLM工具调用能力
1. 项目概述为什么工具链设计是Agent成败的关键最近在折腾各种AI Agent项目从简单的自动化脚本到复杂的多智能体协作系统踩过的坑能写满一本错题集。我发现一个特别有意思的现象很多团队在构建Agent时往往把90%的精力都花在了模型选型、Prompt工程和业务逻辑编排上却对“工具链”这个看似基础的部分草草了事。结果就是Agent看起来聪明绝顶能说会道但一到动真格需要调用外部工具执行具体任务时就频频掉链子——要么找不到合适的工具要么用错了参数要么在复杂的工具组合调用中迷失方向。这感觉就像给一位顶尖外科医生配了一套生锈的、不顺手的手术器械他空有满腹理论和一双巧手却无法高效、精准地完成手术。这个项目标题“工具链设计——让LLM用对工具的五个原则”恰恰点中了当前Agent开发中最隐秘也最关键的痛点。它讨论的不是如何造更锋利的“刀”工具本身而是如何设计一套“刀架”、“使用说明书”和“协同工作流”让LLM这位“主刀医生”能准确、安全、高效地使用每一把“刀”。这里的“工具链”远不止是一个简单的API列表它是一个包含了工具发现、描述、调用、编排、容错和安全保障的完整体系。设计得好Agent的能力边界将被极大拓展从“纸上谈兵”的聊天机器人蜕变为真正能解决实际问题的智能体设计得不好Agent就会变成一个眼高手低的“理论家”空有理解力缺乏执行力。基于我过去在多个实际Agent项目中总结的经验以及观察到的行业最佳实践我将这“五个原则”视为构建健壮Agent工具能力的基石。它们不仅适用于基于大语言模型的Agent对于任何需要将“思考”与“行动”结合起来的智能系统都有极高的参考价值。接下来我们就深入拆解这五个原则背后的设计哲学、具体实现方案以及那些只有踩过坑才知道的实操细节。2. 核心原则一意图与工具的精确对齐让LLM用对工具的第一步是确保它能准确理解用户的意图并将这个意图映射到最恰当的一个或一组工具上。这听起来像是简单的“检索”或“匹配”问题但在动态、开放的真实场景中实现“精确对齐”充满了挑战。2.1 超越关键词匹配基于语义与上下文的工具发现最原始的工具调用方式是硬编码或基于关键词的规则匹配。例如用户说“查天气”就固定调用get_weather函数。这种方式在封闭场景下有效但极度脆弱。一旦用户换种说法比如“明天需不需要带伞”或“下午的降水概率如何”规则系统就可能失效。现代Agent的工具发现机制核心是利用LLM自身的语义理解能力。我们不再直接匹配关键词而是将用户的查询Query和所有可用工具的“描述”一起交给LLM让它来判断哪个工具最相关。这里的关键在于如何撰写工具的“描述”。一个糟糕的描述是“calculate一个计算函数”。这种描述信息量几乎为零。一个优秀的描述应该包含功能这个工具是做什么的用自然语言清晰说明。输入它需要什么参数每个参数的类型、格式、可选/必选、示例是什么输出它会返回什么数据结构是怎样的适用场景在什么情况下应该优先考虑使用这个工具限制与前提使用它需要什么前提条件它有哪些已知限制例如对于一个查询股票价格的工具其描述应该这样写工具名称get_stock_price 功能获取指定上市公司股票在特定交易日的开盘价、收盘价、最高价、最低价和交易量。 输入 - symbol (字符串必填)股票代码例如 ‘AAPL’ 代表苹果公司‘00700.HK’ 代表腾讯控股。 - date (字符串格式 ‘YYYY-MM-DD’可选)查询日期默认为最近一个交易日。 输出一个JSON对象包含 ‘open’, ‘close’, ‘high’, ‘low’, ‘volume’ 字段。 适用场景当用户询问某只股票的价格、当日行情或历史某天行情时使用。 注意该工具数据延迟约15分钟不提供实时盘口数据。对于A股股票请使用‘000001.SZ’格式。当用户提问“苹果公司昨天的股价表现怎么样”时LLM会将这个问题与所有工具描述进行语义相似度计算可以是嵌入向量比较也可以是让LLM直接判断。由于描述中包含了“苹果公司”可关联到‘AAPL’、“昨天”关联到date参数、“股价表现”关联到开盘价、收盘价等输出字段LLM就能高置信度地选中get_stock_price工具并尝试填充symbol‘AAPL’和date‘2023-10-26’假设当天是27号。实操心得描述即契约工具描述是LLM理解工具的唯一窗口。务必用清晰、无歧义的语言编写并包含丰富的示例。我习惯为每个工具编写3-5个不同的用户查询示例及其对应的正确调用参数将这些示例作为描述的一部分或单独提供给LLM作为Few-shot学习样本能显著提升意图对齐的准确率。2.2 处理模糊意图与工具组合用户的意图常常是模糊或复杂的单一工具可能无法满足。这时就需要LLM具备“规划”能力将一个高层意图分解为多个子任务每个子任务对应一个工具。例如用户说“帮我分析一下特斯拉和比亚迪最近一个月的股价走势并总结一下。”这个意图至少涉及以下几个工具get_stock_price(多次调用)获取TSLA和BYDDY或对应A股/港股代码过去30天的每日价格。calculate_statistics计算两只股票在这段时间内的平均价格、波动率等。plot_chart生成股价走势对比图。generate_summary基于数据和图表生成文字分析报告。实现这种组合的关键在于设计一个“规划器”Planner。这个规划器可以是一个特定的LLM调用其Prompt模板专门用于任务分解。输入是用户意图和工具列表输出是一个有序的工具调用计划Plan。这个计划需要明确执行顺序、工具间的数据流例如工具1的输出是工具2的输入。# 规划器Prompt示例简化 你是一个任务规划专家。请根据用户的请求和可用的工具列表将复杂请求分解为一系列可顺序执行的工具调用步骤。 用户请求{user_query} 可用工具{tool_descriptions} 请输出一个JSON数组每个元素是一个步骤包含 {“step_id”: 1, “tool_name”: “xxx”, “reasoning”: “为什么用这个工具”, “inputs”: {…}, “depends_on”: [步骤ID] }。避坑指南规划中的幻觉与循环LLM在规划时可能产生“幻觉”发明出不存在的工具或参数。务必在规划步骤后加入“验证”环节检查计划中的每个工具是否真实存在所需参数是否都能从用户输入或上游工具输出中获得。另一个常见问题是“循环依赖”或“死循环”例如计划中要求工具A的输出作为工具B的输入但工具B的输出又是工具A的输入。需要在设计时加入循环检测和最大步数限制。3. 核心原则二结构化与自描述的接口LLM是文本的王者但对非结构化的、隐含的接口信息理解能力有限。因此提供给LLM的工具接口必须是高度结构化和自描述的。3.1 从函数签名到JSON Schema在传统编程中我们通过函数名、参数类型和文档来理解一个函数。对于LLM我们需要将这种信息转化为它更容易消化的格式即JSON Schema。许多Agent框架如LangChain、LlamaIndex都要求工具以符合OpenAPI规范或类似JSON Schema的形式进行定义。一个完整的工具定义JSON Schema应该包含name: 工具的唯一标识符。description: 上文提到的详细自然语言描述。parameters: 一个JSON Schema对象明确定义每个参数的属性type,description,enum等。required: 必填参数列表。returns: 返回值的描述或Schema。{ “name”: “send_email”, “description”: “向指定的一个或多个收件人发送电子邮件。”, “parameters”: { “type”: “object”, “properties”: { “recipients”: { “type”: “array”, “items”: {“type”: “string”, “format”: “email”}, “description”: “收件人邮箱地址列表” }, “subject”: { “type”: “string”, “description”: “邮件主题” }, “body”: { “type”: “string”, “description”: “邮件正文支持纯文本” }, “cc”: { “type”: “array”, “items”: {“type”: “string”, “format”: “email”}, “description”: “抄送人邮箱地址列表可选” } }, “required”: [“recipients”, “subject”, “body”] }, “returns”: { “description”: “返回一个对象包含 ‘success’ (布尔值表示是否发送成功) 和 ‘message_id’ (字符串成功时返回邮件ID)。” } }LLM在决定调用此工具时会参考这个Schema来构建一个符合格式的JSON对象作为调用参数。清晰的description和严格的type、format约束能极大减少参数格式错误。3.2 动态参数与枚举值提示有些工具的参数可能依赖于运行时状态。例如一个文件管理工具中的path参数其有效值取决于当前的工作目录。一个数据库查询工具的table_name参数有效值取决于数据库中有哪些表。对于这类情况不能只提供一个静态的Schema。我们需要设计“动态参数获取”机制。有两种常见模式预检查询在LLM正式调用工具前先调用一个“参数建议”工具。例如list_current_directory工具返回当前目录下的文件列表供LLM在后续调用read_file时作为filename参数的候选值。枚举值内联在工具描述或Schema中直接说明如何获取有效值。例如在描述中写明“table_name参数必须是当前数据库中存在的表名。你可以先调用list_tables工具来获取所有表名列表。”对于有固定枚举值的参数如status可以是[‘open’ ‘closed’ ‘in_progress’]一定要在Schema的enum字段中明确列出并配上简要说明。这比让LLM去“猜”一个有效值要可靠得多。注意事项Schema的严谨性与灵活性平衡虽然严格的Schema能减少错误但过度严格也可能限制LLM的发挥。例如如果一个参数描述为“城市名”类型是stringLLM可能会输入“New York City”。但后端接口可能只接受“new_york”这样的代码。这时更好的做法是在Schema中提供示例或者在后端工具实现中加入一个轻量的“参数规范化”层将LLM生成的友好名称映射到内部代码。不要把所有的格式校验压力都留给LLM。4. 核心原则三安全、可控的执行沙箱工具调用意味着赋予LLM操作外部系统的能力这必然带来安全风险。一个设计不当的工具链可能让LLM无意中删除重要文件、发送垃圾邮件、或查询敏感数据。因此必须为工具执行构建一个安全、可控的“沙箱”。4.1 权限分级与最小权限原则不是所有工具都应该对所有Agent开放。应根据工具的危险程度和Agent的信任等级实施严格的权限控制。无害工具如信息查询天气、股票、计算、文本处理。可以默认开放。敏感操作工具如读取本地文件、查询数据库仅限特定表、发送通知。需要经过更严格的意图审核或限制在特定的安全上下文中使用。高危工具如写入文件、执行系统命令、发送邮件/消息、进行金融交易。必须施加额外的安全护栏例如需要人工确认Human-in-the-loop或仅允许在完全隔离的测试环境中使用。在架构设计上可以实现一个“工具网关”或“策略执行点”。所有工具调用请求都经过这里网关根据预定义的安全策略哪个Agent在什么情况下可以调用哪个工具进行校验。策略可以基于角色Role、上下文Context甚至动态风险评估来决定。4.2 输入验证与输出过滤即使LLM生成的调用参数符合Schema在真正执行前仍需进行业务逻辑层面的验证。输入验证检查参数值是否在合理范围内。例如date参数不能是未来日期amount参数不能是负数user_id参数必须对应一个真实存在的用户。这部分验证最好在工具的后端实现内部完成并返回清晰的错误信息。输出过滤工具返回的数据可能包含敏感信息如用户手机号、身份证号。在将结果返回给LLM或最终用户前需要进行脱敏处理。例如一个查询用户详情的工具其返回的JSON中的phone字段在传递给LLM前应被替换为“[REDACTED]”。这防止了敏感信息在后续的LLM处理或对话中被泄露。4.3 资源隔离与执行限制对于执行代码、命令或访问网络的工具必须进行严格的资源隔离。时间限制为每个工具调用设置超时如30秒防止某个工具陷入死循环或长时间等待阻塞整个Agent。资源限制限制工具可以使用的内存、CPU和网络带宽。对于代码执行类工具应运行在容器如Docker或轻量级沙箱中。网络隔离限制工具可以访问的网络端点。禁止访问内部管理网络或敏感系统。实操心得默认拒绝显式允许在安全策略上务必采用“默认拒绝”原则。所有工具默认都是不可用的只有经过明确授权通过策略配置后特定的Agent才能在特定的会话中使用它。定期审计工具调用日志检查是否有异常模式。同时为每个工具调用生成唯一的追踪ID并记录完整的请求和响应脱敏后这对于问题排查和安全审计至关重要。5. 核心原则四鲁棒的交互与错误处理LLM和工具之间的交互不可能一帆风顺。工具可能暂时不可用、参数错误、或者返回意外结果。一个鲁棒的工具链必须能优雅地处理这些错误并引导LLM进行恢复。5.1 清晰的错误反馈机制当工具调用失败时后端返回的错误信息不应该是一串晦涩的技术栈追踪Stack Trace。应该设计一套对LLM友好的错误码和错误信息格式。一个糟糕的错误返回{“error”: “Internal Server Error: Connection timeout to database ‘prod-db’“}。这个错误对LLM来说信息不够明确它可能不知道该如何处理“数据库连接超时”。一个优秀的错误返回应该结构化并包含可操作的指导{ “success”: false, “error_code”: “TOOL_EXECUTION_TIMEOUT”, “error_message”: “在执行‘query_database’工具时连接数据库超时超过10秒。这可能是因为数据库负载过高或网络问题。”, “suggested_action”: “请稍后重试此操作。如果问题持续存在可能需要检查数据库状态。”, “retryable”: true, “original_error”: “{…}” // 可选的原始错误详情用于开发者调试 }LLM在收到这样的错误后可以理解错误类型TOOL_EXECUTION_TIMEOUT知道原因连接超时并且获得了明确的建议稍后重试。retryable字段尤其重要它直接告诉LLM这个操作是否值得重试。对于非重试性错误如权限不足PERMISSION_DENIEDLLM就应该放弃重试转而向用户报告失败或尝试替代方案。5.2 重试、降级与备选方案基于清晰的错误反馈我们可以为Agent设计错误处理策略自动重试对于标记为retryable的错误如网络超时、临时性服务不可用Agent可以自动重试1-2次每次重试间隔稍作延长。降级处理当主要工具失败时尝试使用功能相近但可能精度稍差或范围较窄的备选工具。例如当精确的地理编码服务失败时可以降级使用一个基于关键词的简单地点搜索工具。向用户求助当自动处理无法解决时LLM应该坦诚地向用户说明遇到了什么问题并可能询问更多信息或请求人工介入。例如“我尝试为您查询航班但订票系统目前暂时无法访问。您是希望我稍后再试还是您有已查好的航班号我可以为您记录”实现这些策略需要在Agent的决策循环中加入“错误处理”这个专门的状态或步骤。当工具调用返回错误时不是直接失败而是触发错误处理逻辑由另一个专门的LLM调用或规则引擎来决定下一步行动。避坑指南避免无限重试和错误传播一定要为自动重试设置上限如最多3次。否则一个持续失败的工具可能导致Agent陷入死循环。另外要小心处理“错误链”。工具A失败导致降级到工具B工具B又因为输入格式不对而失败……最终呈现给用户的可能是一个与根源问题无关的令人困惑的错误。好的做法是在降级或更换工具前评估当前错误的根本原因是否会影响备选工具并尽可能重置到清晰的初始状态。6. 核心原则五上下文感知与状态管理工具调用不是孤立的事件。一次复杂的任务往往涉及多个工具的连续调用且后一个工具的调用可能依赖于前一个工具的结果或更早的对话历史。因此工具链必须与Agent的上下文和状态管理深度集成。6.1 维护工具调用历史Agent需要记住它已经做了什么。这不仅仅是记录日志而是要将工具调用的“输入-输出”对以一种结构化的方式纳入到后续LLM推理的上下文中。常见的做法是维护一个“对话历史”或“工作记忆”其中交替存放着用户消息、LLM的思考、工具调用请求和工具调用结果。对话历史示例 [ {“role”: “user”, “content”: “帮我查一下北京今天和明天的天气然后推荐一下穿什么衣服。”}, {“role”: “assistant”, “content”: “我需要先获取北京今明两天的天气数据然后根据气温和天气状况给出穿衣建议。”}, {“role”: “tool_call”, “name”: “get_weather”, “arguments”: {“city”: “北京” “date”: “2023-10-27”}}, {“role”: “tool_result”, “content”: “{‘date’: ‘2023-10-27’ ‘city’: ‘北京’ ‘condition’: ‘晴’ ‘max_temp’: 18 ‘min_temp’: 8}”}, {“role”: “tool_call”, “name”: “get_weather”, “arguments”: {“city”: “北京” “date”: “2023-10-28”}}, {“role”: “tool_result”, “content”: “{‘date’: ‘2023-10-28’ ‘city’: ‘北京’ ‘condition’: ‘多云转小雨’ ‘max_temp’: 15 ‘min_temp’: 10}”}, {“role”: “assistant”, “content”: “根据查询结果今天北京晴8-18度明天多云转小雨10-15度。建议今天可以穿单衣加外套明天因为有雨最好穿防风外套并带伞。”} ]当LLM进行下一步推理时这段完整的历史会被作为上下文输入。这样它就知道已经查过天气了不必重复查询并且可以直接引用max_temp、condition等具体数据来生成穿衣建议。6.2 管理长期状态与会话边界有些任务可能跨越多次用户对话。例如用户第一次说“开始为我规划一个北京三日游行程”Agent调用了一系列工具查询景点、酒店、交通。用户第二天又说“把第二天行程里的故宫换成国家博物馆”。这时Agent需要能关联到之前的“规划会话”并记得之前生成的行程状态。这就需要引入“会话”Session和“长期状态”Long-term State的概念。每个用户会话有一个唯一IDAgent可以将复杂的、多步骤的任务状态如已规划的行程草案、已选中的商品列表持久化存储到数据库或缓存中。当用户再次发起相关请求时Agent通过会话ID加载之前的状态从而在正确的上下文中继续工作。工具链设计需要支持这种状态管理。例如某些工具如save_itinerary_draftload_itinerary_draft本身就是用来读写持久化状态的。更重要的是工具调用逻辑需要能访问和修改当前会话的上下文状态。6.3 工具结果的摘要与精炼工具返回的数据可能是庞大且杂乱的如一个包含数十个字段的数据库查询结果或一个冗长的网页内容。如果直接将所有原始数据塞进上下文会迅速耗尽LLM的上下文窗口并引入噪音。因此需要在将工具结果返回给LLM主循环前对其进行“摘要”或“精炼”。这可以通过一个轻量级的LLM调用来实现有时被称为“工具结果处理器”。这个处理器的任务是从原始结果中提取出与当前任务最相关的关键信息并以简洁、结构化的格式呈现。例如一个搜索工具返回了10条网页摘要。结果处理器可以分析这10条结果去重、排序并总结出3条最相关的要点再交给主LLM。这样既保留了关键信息又节省了上下文空间还提高了主LLM处理信息的效率。实操心得上下文窗口的权衡艺术维护丰富的上下文固然有利于连贯性但成本也高更长的Prompt更高的API费用和延迟。需要根据任务复杂度做权衡。对于简单任务可以只保留最近几轮交互对于复杂任务则需要精心设计状态管理。一个技巧是“分层摘要”随着对话进行定期将早期的详细历史总结成一段简短的背景描述替换掉原来的冗长记录从而在有限的窗口内保留更长时间跨度的信息。另一个技巧是“选择性上下文”在调用LLM进行下一步推理前动态地从历史中选取与当前问题最相关的片段作为上下文而不是总是传入全部历史。