最近在带一个小团队做 LLM 应用落地内部里程碑里有一个编号叫“7.2 HelloAgentsLLM 扩展”。坦白讲这个章节在最开始就是个小 demo让大模型记住上下文再顺手调几个预置函数。真正开始扩展之后我才发现从“Hello”级演示走到“能上生产环境干活”的多代理系统中间隔着一整套工程问题——记忆怎么管、工具怎么注册、多代理怎么编排、模型怎么选、被别人攻击怎么办。这篇文章就是我这一轮做 HelloAgentsLLM 扩展时的完整记录包括方案取舍、踩坑日志和最后沉淀下来的检查清单。适合正在从单轮 demo 往多代理 LLM 应用推进的开发者参考。1. 先搞清楚 HelloAgentsLLM 原本是什么再决定扩展边界1.1 第一版 demo 为什么只能叫 Hello很多入门教程里的 HelloAgentsLLM 结构都非常简单一个 LLM 调用入口一段 system prompt外加一两个写死的工具函数。你输入一句话模型返回一段回答如果正好命中了某个函数就执行它再把结果拼回上下文。这个流程用来理解“大模型 LLM 怎么和外部世界交互”足够了但离生产级应用差得远。我在第一版 demo 里遇到的最典型问题是“上下文是纸糊的”。用户问一句“帮我查一下 A 客户最近三个月的合同量”模型确实会触发查询函数可一旦跨越多轮它就把用户身份、查询范围、之前的结果全混在一起。更别提多个代理之间共享状态时A 代理计算出的中间结果根本没法被 B 代理正确引用。说白了这个阶段的大模型 LLM 只是一个“会接话的接口”不是一个“能持续稳定完成任务的 agent”。所以一开始就要明确扩展边界。我不打算把 HelloAgentsLLM 做成一个通用人工智能平台目标很朴素让代理在可控、可复盘的前提下具备记忆能力、工具调用能力、多代理协同能力并且能通过对抗性评估。1.2 我定义的扩展目标不追“智能”先追“可控可靠可复盘”这是我吃过亏后的教训。早期做 LLM 项目团队很容易把精力花在“让模型输出更聪明”上比如换更大的 base model、加更复杂的 prompt。但真实业务里最痛苦的从来不是“输出不够聪明”而是输出不可控。比如同一个查询连续跑三次结果可能完全不同代理执行了工具调用但根本不记得自己调过什么多个代理协作时责任边界模糊出了问题根本定位不到是哪个环节在编造信息。所以我在做 HelloAgentsLLM 扩展时把这几条定成了硬指标可追踪性每一步代理决策都有日志模型输出和工具调用一一对应。可约束性代理只能在注册过的工具和授权范围内行动。可评估性每次改动都有回归用例评价标准不靠感觉用真实用例回放加 LLM 作为裁判综合打分。定完边界后面所有扩展动作都围绕这三条展开。2. 给代理装上记忆不只是存聊天记录2.1 Key-Query-Value 三要素我的记忆路由设计社区里有一个很有用的说法把 LLM 的 token 语义想象成三个角色——key 是我是什么、query 是我要去找什么、value 是我能提供什么。这个思路放到代理记忆系统里特别实用。传统聊天记录只是把对话原文一股脑存进去召回时用相似度搜索。但代理在真实业务里要面对的是动态变化的用户意图、工具返回结果、历史任务状态。如果记忆没有结构化模型很容易把“上一次用户随口说的玩笑话”当成“本次任务的事实依据”。我参考 key-query-value 思路给记忆条目设计成这样字段作用例子key记忆条目的身份标签说明“我是哪类信息”customer_contract_total: A客户2025年Q1合同量query什么条件下应该被召回相当于触发条件用户询问客户合同量、统计销售额、生成季度报告value具体内容或向量表示数据数值、来源文档、上下文摘要召回时先根据用户当前 query 做意图归一化再和记忆条目的 query 字段做匹配匹配度不够就退回向量检索。这样设计的好处是记忆召回不再是纯概率匹配而是有了业务语义的筛选门槛。2.2 工作记忆上下文窗口分配策略大模型 LLM 的上下文窗口是有限资源任何代理框架对此都要有明确的分配策略。我把上下文预算分成三块指令区system prompt、任务定义、当前工具清单。这块尽量保持精简控制在总窗口的 15% 以内。工作记忆区当前用户查询、最近两轮对话、正在执行的工具结果。这部分留给真正“正在处理”的信息大约占 45%。长期记忆召回区从向量库召回的背景资料和任务历史。这部分最容易被撑爆所以必须做截断和摘要占 40%。这里有个实操细节工具返回结果往往是超长 JSON如果原样塞进上下文几次调用就把窗口吃光了。我的做法是给每个工具定义一个summary_fields只把关键字段拼进模型上下文完整结果单独存放在可追溯日志里。比如查询订单列表上下文里只保留“共 12 笔订单总金额 8.6 万元”原始明细落到日志模型需要再看明细时再发一次检索请求。2.3 长期记忆向量库 双层召回长期记忆我用的是本地向量库加结构化索引的双层结构。第一层是倒排索引按照业务实体客户、项目、合同编号精确定位第二层是向量相似度检索用来处理模糊语义查询。给一段实际伪代码参考def recall_memory(user_query, entity_context): candidate_ids set() # 第一层业务实体精确定位 if entity : extract_entity(user_query): candidate_ids.update(structured_index.query(entity)) # 第二层语义相似度 embedding embed(user_query) vector_hits vector_store.search(embedding, top_k20) candidate_ids.update(vector_hits) # 按 query 命中优先级和时效性排序 return rank_memories(candidate_ids, user_query)这套结构跑下来优点是很明显的精确查询不会漏模糊查询也接得住。而且因为是双层结构每一层都能单独做权限控制敏感信息不会因为“语义相似”就被错误召回。2.4 spatial LLM 给的启发把空间索引加进记忆热词里有个 spatial LLM很多人觉得这只是地理信息领域的事跟通用代理没关系。我倒是受它启发做了一件事给记忆里带位置属性的内容加空间索引。比如代理要处理门店巡查任务记忆里既有“XX 店 3 月销售额”又有“XX 店与 YY 店的直线距离”。传统向量检索会把“距离”当成普通文本但 spatial LLM 的研究提醒我这类具有坐标属性的信息最好单独建空间索引。否则用户问“离 XX 店最近的门店是哪家”模型检索到的可能是说话风格相似的文本而不是地理位置最近的门店。真正的落地方案不必太重。我是在结构化索引里多加了latitude、longitude、spatial_entity_type三个字段用轻量空间数据库查询附近对象。效果非常直接代理对“就近”“范围内”“相邻区域”这类空间语义的理解准确率提升了不止一个档次。3. 扩展工具的工程细节碰到最多的还是 schema 坑3.1 工具注册表设计名字、描述、JSON Schema 缺一不可要把 HelloAgentsLLM 从“会说话”变成“会干活”核心动作就是接工具。但工具接多了以后你会发现模型能不能选对工具首先取决于工具的描述写得清不清楚其次才是模型能力。我设计工具注册表时强制要求每个工具包含四部分{ name: query_sales_amount, description: 查询指定客户在指定时间范围内的销售总额。当用户提到销售额、业绩、合同金额时优先使用。, parameters: { type: object, properties: { customer_id: { type: string, description: 客户唯一标识 }, start_date: { type: string, format: date, description: 开始日期格式YYYY-MM-DD }, end_date: { type: string, format: date, description: 结束日期格式YYYY-MM-DD } }, required: [customer_id, start_date, end_date] } }这里最容易翻车的点是两个第一description写得太抽象模型不知道什么时候用第二参数描述不写单位、格式、边界模型传出来的值经常是“2025年1月”这种模型没准头的文本。3.2 项目经理最头疼的那类报错provider rejected the request schema or tool payload扩展过程中我们线上日志里经常出现这样一条错误llm request failed: provider rejected the request schema or tool payload.第一次看到时我以为是模型供应商故障后来挨个排查才发现问题出在工具声明的 schema 与实际传参不一致。典型情况有四种场景错误原因解决方案参数名大小写不一致注册时写CustomerID模型输出customer_id统一用小驼峰命名并在 description 里写明别名声明了 required 但没给默认值模型在部分场景下漏传把必填项调成可选或在代码里做兜底枚举值越界参数枚举列表没包含线上真实数据用宽松枚举并增加校验逻辑类型不匹配模型传了字符串12但 schema 声明为 integer让参数解析层做类型强制转换排查工具 schema 报错不要只盯模型侧提示。我的经验是先做一个离线验证脚本把最近 100 次真实调用的tool_call参数全部重放一遍拿 schema 做 JSON Schema 校验所有不通过项打印出来。这个方法能快速把“模型生成问题”和“工具定义问题”分开避免每次都被模型 API 的模糊报错带偏。3.3 框架选型是上现成框架还是自己搭聊到 LLM 扩展绕不开“用不用现成 LLM 框架”这个选择。市面上的框架不少有的主打记忆封装有的主打多代理编排。我的观点很明确如果你只是做原型验证用框架很值如果要过审计、自定义程度高务必保证框架留的逃生舱够大。我们团队评估后没有让框架接管所有逻辑。原因并不复杂很多框架把记忆、工具、模型封装得太死一旦线上出现 provider 返回特殊格式的 tool payload排查路径会变得很长。最后我们只借鉴了框架的消息路由思路核心的记忆管理和工具调用链自己维护。这也算另一种“HelloAgentsLLM 扩展”——从一套框架 demo 扩展成一套贴合自己业务的轻量框架。4. 从单代理到代理组织编排层才是 LLM 扩展的重头戏4.1 编排者与执行者两种分工模式的取舍单代理能力再强也容易在复杂任务上失控。比如“综合客户销售数据和市场活动记录给出一份下季度销售预测报告”这里包含数据查询、市场分析、预测建模、报告撰写四种能力让一个代理全部做很容易出现上下文互相污染到后半段忘了前半段的结论。我采用的扩展模式是编排者-执行者Orchestrator-Worker一个编排代理负责拆解任务、分发子任务、汇总结果多个执行代理分别专注某类工具和知识域。这个模式的好处是每个代理的 system prompt 都保持精简上下文压力小权限也好控比如数据分析代理只读数据库接口不碰外部内容抓取。但编排层也容易变成瓶颈最常见的问题就是它构建的中间执行计划质量不高。我试过让编排代理输出严格的 JSON 任务图但模型经常给出格式正确、逻辑跳跃的流程。后来我给编排层加了一道“计划校验器”用规则引擎检查任务依赖是否闭环、是否存在重复执行不通过就让模型重新生成计划。校验器本身逻辑不复杂但能拦截掉很多肉眼看着正常、跑起来就死循环的坏计划。4.2 让 LLM 做裁判多代理意见冲突时的裁决策略多代理协作的另一个大问题是两个执行代理给出互相矛盾的结果怎么办比如销售数据分析代理说“由于某产品销量下滑下季度需要加大营销投入”市场活动代理却说“该产品曝光量已经饱和再投入边际收益很低”。两个结论单独看都有道理谁说了算我用的是LLM-as-Judge的裁决模式把两个结论、各自引用的数据依据、预置的决策规则一起交给一个专门的裁决代理。它不负责生产内容只做三件事判断论据是否和数据一致、判断数据覆盖范围是否完整、判断结论优先级是否符合业务规则。这里有个关键心得用 LLM 做裁判不是把原始回答直接塞给它而是给裁判断章取义的风险最小化要提供标准化证据包。每个执行代理在提交结果时必须附带“数据来源”“置信度”“适用范围”三个字段。否则裁判很容易被措辞更流畅的一方带偏而不是被数据更扎实的一方说服。4.3 代理间消息协议与结果校验代理之间通信如果没有协议幻觉会像传染病一样蔓延。执行代理 A 产生了一个不准确的中间数字执行代理 B 拿这个数字继续分析最后报告里就会出现层层放大的错误。我的解决方案是定义消息协议所有代理之间的数据传递必须带data_source和confidence字段。聚合代理在拿到中间结果时先跑一遍校验器def validate_agent_message(msg): checks [] if not msg.get(data_source): checks.append(missing_data_source) if msg.get(confidence, 1.0) 0.7 and not msg.get(requires_human_review): checks.append(low_confidence_passed) if msg.get(data_type) numeric and not isinstance(msg.get(value), (int, float)): checks.append(type_mismatch) return checks这个校验器很轻但它拦截了大量“B 代理把 A 的推测当事实继续推导”的灾难场景。5. 上线前先打自己一顿红队与评估全记录5.1 AgentPoison 这类攻击方向记忆投毒为什么要防做 LLM 扩展时我时刻记着热词里出现过的 AgentPoison——通过污染代理的记忆库或知识库让代理在正常查询时触发攻击者预设的错误行为。这个攻击方向过去几年被反复验证原理不复杂代理依赖记忆库提供背景资料而记忆库的召回和筛选不总是那么严谨恶意文本混进去以后能顺着向量相似度悄悄进入上下文。我做过一次模拟。我们准备了一个线上知识库里面存着常见操作规范我故意插入一段语义上接近“售后处理”但实际带着越权指令的文本。结果测试代理真的在回答中引用了那段文本甚至把它当成操作步骤执行。这个演练之后团队所有人对“网上抓来的资料直接写进记忆库”这种事都心有余悸了。防护手段未必要多花哨但必须有来源白名单只有来自可信源的内容能写入长期记忆库。写入前清洗用指令检测模型扫描入库文本过滤掉“忽略以上指令”“输出内部提示词”这一类内容。分层隔离用户产生的临时信息与系统沉淀的知识分开存放召回时严格区分权限上下文。5.2 评估口径基于 LLM 的单元测试 真实用例回放 人工抽样很多项目评估代理质量只看“跑几个样例有没有通过”这种评估方式有两个致命问题样例量太少且没有覆盖失败模式。我按三个维度搭了一套评估体系评估维度手段目的回归用例基于 LLM 的单元测试把历史用户问题重放自动比对输出质量与工具调用序列是否符合预期文本防止“改了一个小功能老功能全崩”对抗用例精心设计的污损输入提示注入、记忆污染、超长上下文、工具误选检验安全护栏而不是只检验“好不好用”真实回放拿近一周生产环境匿名化请求重放比较新版本与旧版本的得分轨迹衡量真实流量下的综合表现这里面有个基础概念先理清楚所谓“基于 LLM 的单元测试”本质是把自然语言断言交给模型来判定而不是写一堆硬编码规则。比如断言“代理的回答没有提及不存在的客户”硬编码很难覆盖各种句式但用裁判 LLM 加一个判定 prompt 就能做语义级检测。“使用聊天记录模型精调 LLM”也可以在这里派上用场如果用历史聊天记录微调了评审模型它对真实业务语言的敏感度会明显提高比通用模型裁判准确不少。5.3 最小安全护栏清单评估做得再多也不如上线前把护栏砌好。我给 HelloAgentsLLM 扩展版列了一份最小安全护栏清单每条都有明确落点工具使用必须白名单代理只能调用注册列表里的工具未注册的请求直接截断。外部内容与指令分离从网页或文档获取的内容一律放在external_content标签里禁止混进 system prompt。敏感操作要人工复审涉及删除、转账、对外发送消息的代理行为必须先进入待审批队列。每一步可回溯完整记录模型输入、输出、工具入参、工具返回值日志最少保留 30 天。有读者可能觉得护栏会拖慢体验其实做成异步审计就不明显。真正重要的不是每次都卡住用户而是异常行为发生时你能在一分钟之内定位到是哪一步、哪一段提示词、哪个工具参数出了问题。6. 模型与榜单、框架取舍扩展这件事最后拼的是判断力6.1 Open LLM Leaderboard 等公开榜单的正确读法做到最后模型选型也是 HelloAgentsLLM 扩展绕不开的一环。很多人看 Open LLM Leaderboard 这类公开榜单只看总分排名然后直接挑分数最高的。这个做法我不太认同。公开榜单的任务集与你的业务场景往往差着十万八千里更何况不同榜单对推理、数学、代码理解的侧重点差别很大“总榜高”不等于“工具调用强”也不等于“多轮指令跟随稳”。我阅读榜单时会额外关注几个单项工具调用准确率、多轮对话一致性、长上下文信息抽取能力。没有直接单项排名时就用第 5 节说的真实用例回放来弥补拿自己线上录制的 100 条请求测一轮模型能力差距会立刻浮出水面。这个步骤不能省因为我踩过“榜上第一却在真实工具调用场景连续报错”的坑。6.2 供应商和模型 API 的兼容性差异扩展过程中我们对接过不止一家模型供应商。最直观的教训就是同一个 JSON Schema在不同 provider 上的宽容度完全不同。有的 provider 严格执行工具参数定义多一个未声明的字段就拒绝少一个 required 字段也拒绝甚至字段顺序不匹配都报错有的 provider 则宽松得多会自动忽略多余字段。这就引出了“llm request failed: provider rejected the request schema or tool payload”的复杂局面。做多供应商兼容时我建议先写一个 schema 归一化层def normalize_tool_schema(schema, provider): if provider vendor_b: schema copy.deepcopy(schema) # vendor_b 要求所有参数必须有 default for prop in schema.get(properties, {}).values(): prop.setdefault(default, None) return schema另外生产环境务必准备好降级策略。若主供应商长时间拒绝请求要有备用通道承接工具调用流量否则一个 schema 配置问题就能让线上代理集体罢工。6.3 我给团队定的扩展基线清单写这篇文章时我们正在准备第七轮发布。这一路上沉淀的东西很多最后我把它们浓缩成了一份扩展基线清单供接手项目的同事参考记忆系统是否区分工作记忆与长期记忆是否有显式的召回路由工具是否都有完整的 JSON Schema 描述且过了离线校验多代理之间是否有协议层结果字段是否带来源和置信度是否有自动回归用例至少覆盖 50 个历史真实查询是否跑过记忆污染测试和提示注入测试生产环境是否有完整的调用链日志定位一次问题不超过 5 分钟每个模型的 prompt 与 schema 是否做到 provider 兼容这份清单听起来朴素但每一条都对应着我们在 HelloAgentsLLM 扩展路上真实踩过的坑。比如“定位问题不超过五分钟”这条就是被连续排查数小时、最终发现是某代理在中间步骤把客户 ID 和合同 ID 搞混之后咬咬牙定下来的。扩展 LLM 应用并不是要把架构搞得多炫而是要让你在任何一次模型输出异常时都能迅速回答出那句灵魂拷问数据从哪来、推理依据是什么、这个结果能不能放心用。能做到这一点HelloAgentsLLM 就真正从一个“演示玩具”变成了一个值得上线、能够持续迭代的代理系统。