1. 从 Demo 到生产Agent 落地的真实鸿沟做过 Agent 项目的人大概都有过这种体验本地跑 Demo 的时候工具调用丝滑流畅LLM 该调哪个函数就调哪个函数Schema 校验一次通过Token 消耗也在可接受范围内。演示给领导看掌声一片项目立项资源到位。然后进入生产环境用户量一上来各种幺蛾子全出来了——工具调用开始随机失败Schema 校验报错率飙升Token 用量失控并发一高整个链路直接雪崩。这不是个别现象。我参与过几个企业级 Agent 项目从零到一的落地也帮朋友排查过不少“Demo 惊艳、上线拉胯”的案例。说实话大部分问题在 Demo 阶段就已经埋下了只是当时被小数据量、低并发、理想输入给掩盖了。Agent 和传统后端服务最大的区别在于它的核心链路里有一个非确定性的大模型。你没法像写 CRUD 那样给定输入就一定能得到预期输出。这个本质差异决定了 Agent 的生产落地需要一套完全不同的工程方法论。这篇文章不聊虚的就围绕四个最要命的坎——工具调用的稳定性、Schema 的工程化治理、Token 的成本与性能平衡、并发场景下的架构设计——把每个坎的根因拆开给出我在实际项目中验证过的工程解法。适合正在做 Agent 项目、或者准备把 Agent 推上生产的同学参考。如果你还在写 Demo 阶段也可以提前看看少走点弯路。2. 第一道坎工具调用的稳定性治理2.1 为什么 Demo 里工具调用很稳上线就崩Demo 阶段工具调用稳定核心原因是输入分布极窄。你测试的时候用的都是精心构造的 query意图明确参数完整LLM 很容易映射到正确的工具和参数。但生产环境的用户输入是长尾的、模糊的、甚至自相矛盾的。用户可能说“帮我查一下那个东西”也可能在一句话里塞三个意图还可能用错别字、口语、方言。LLM 面对这种输入时工具调用的决策链路会变得极其脆弱。具体表现有几类工具选择错误该调 A 工具却调了 B或者该调工具却直接编造答案。参数提取失败工具选对了但参数缺了、格式错了、类型不对。调用时机错误该先查再算结果直接算该等用户确认结果直接执行。幻觉调用调了一个根本不存在的工具或者传了 Schema 里没定义的参数。这些问题的根因一半在 LLM 本身的能力边界一半在工程侧没有做好约束和兜底。Demo 阶段你只看到了 LLM 能力上限的那一面生产环境把它的下限暴露出来了。2.2 工具描述与 Schema 设计的实战原则工具调用的第一道防线是工具描述和 Schema 的设计。很多团队在这块很随意工具名用缩写描述写一句话参数用嵌套对象结果 LLM 根本理解不了。我总结了几条实战原则工具名要语义化且唯一。不要用get_data这种模糊名字用query_order_by_id、search_product_by_keyword这种一看就知道干什么的名字。工具名是 LLM 做选择时的重要信号名字越清晰选择准确率越高。工具描述要写清楚“什么时候用”和“什么时候不用”。只写“查询订单”不够要写“当用户提供了订单号需要查询订单状态、金额、物流信息时使用。如果用户没有提供订单号不要调用此工具先向用户询问订单号。”把边界条件写进去能显著降低误调用。参数 Schema 要扁平化。能用平铺参数就别用嵌套对象。LLM 对嵌套结构的解析能力明显弱于扁平结构。如果确实需要嵌套层级不要超过两层。每个参数都要有 description 和 example。这是最容易被忽略但收益最高的操作。比如order_id参数description 写“订单编号通常是 12 位数字”example 写“202405180001”。LLM 看到 example 后参数提取的准确率会有肉眼可见的提升。枚举值要显式列出。如果某个参数只接受固定几个值一定要在 Schema 里用 enum 列出来不要指望 LLM 自己猜。下面是一个对比示例左边是反面教材右边是实战优化后的版本// 反面教材 { name: query, description: 查询订单, parameters: { type: object, properties: { info: { type: object, properties: { id: {type: string}, type: {type: string} } } } } } // 实战优化 { name: query_order_detail, description: 根据订单号查询订单的详细信息包括订单状态、支付金额、商品列表、物流进度。当用户明确提供了订单号且需要查询订单相关信息时使用。如果用户没有提供订单号不要调用此工具。, parameters: { type: object, properties: { order_id: { type: string, description: 订单编号通常是 12 位数字以 2024 或 2025 开头, example: 202405180001 }, query_fields: { type: array, items: {type: string, enum: [status, amount, items, logistics]}, description: 需要查询的字段列表不传则返回全部字段 } }, required: [order_id] } }2.3 工具调用失败的重试与降级策略即使 Schema 设计得再好LLM 也有概率调用失败。生产环境必须有一套重试与降级机制。我的做法是分三层处理第一层Schema 校验失败的重试。当 LLM 返回的工具调用参数不符合 Schema 时不要直接报错给用户。把校验错误信息作为 observation 回传给 LLM让它重新生成。通常重试一次就能修正。重试时可以在 prompt 里加一句“上一次调用参数格式有误错误信息是 XXX请修正后重新调用”。第二层工具执行失败的重试。工具本身可能因为网络、超时、下游服务不稳定而失败。这类失败要用指数退避重试但要注意幂等性。查询类工具可以放心重试写入类工具必须保证幂等否则会重复下单、重复扣款。第三层降级兜底。如果重试多次仍然失败要有降级方案。比如切换到备用工具、返回缓存结果、或者直接告诉用户“当前服务繁忙请稍后再试”。最忌讳的是让 LLM 在工具失败后自由发挥它很可能会编造一个答案给用户。这里有个实操心得在工具执行层加一个统一的 wrapper所有工具调用都走这个 wrapper。wrapper 负责参数校验、超时控制、重试、日志记录、降级。这样业务代码不用关心这些横切逻辑LLM 侧也只需要面对统一的错误格式。def tool_wrapper(tool_func, max_retries2, timeout10): def wrapped(**kwargs): for attempt in range(max_retries 1): try: # 参数校验 validated validate_schema(kwargs, tool_func.schema) # 超时控制 result call_with_timeout(tool_func, validated, timeout) return {success: True, data: result} except SchemaError as e: if attempt max_retries: return {success: False, error: f参数格式错误{e}, retryable: True} return {success: False, error: f参数格式错误{e}, retryable: False} except TimeoutError: if attempt max_retries: continue return {success: False, error: 工具执行超时, retryable: False} except Exception as e: return {success: False, error: str(e), retryable: False} return wrapped注意重试次数不要太多一般 1-2 次就够了。重试次数过多会显著增加延迟和 Token 消耗而且很多错误重试也没用。3. 第二道坎Schema 的工程化治理3.1 Schema 不只是校验工具更是 LLM 的“接口文档”很多人把 Schema 仅仅当成参数校验的工具这是很大的认知偏差。在 Agent 场景里Schema 是 LLM 理解工具能力的唯一入口。LLM 看不到你的工具实现代码它只能通过 Schema 里的 name、description、parameters 来推断这个工具能做什么、需要什么参数、返回什么。所以 Schema 的质量直接决定了工具调用的准确率。我见过太多项目工具实现写得很好但 Schema 写得一塌糊涂结果 LLM 根本调不对。Schema 治理的核心目标是让 LLM 在只看 Schema 的情况下就能正确判断什么时候该调用、该传什么参数。这其实和写 API 文档是一个道理只不过读者从人类开发者变成了 LLM。3.2 用 Zod Schema 做类型安全的工具定义如果你用 TypeScript 做 Agent 开发强烈建议用Zod来定义工具 Schema。Zod 的好处是一份定义同时得到运行时校验和 TypeScript 类型推断。你不需要维护两套东西。import { z } from zod; const QueryOrderSchema z.object({ order_id: z.string() .regex(/^\d{12}$/) .describe(订单编号12位数字以2024或2025开头), query_fields: z.array( z.enum([status, amount, items, logistics]) ).optional().describe(需要查询的字段列表不传则返回全部), }); type QueryOrderParams z.infertypeof QueryOrderSchema; const queryOrderTool { name: query_order_detail, description: 根据订单号查询订单详情..., parameters: zodToJsonSchema(QueryOrderSchema), execute: async (params: QueryOrderParams) { // params 已经有完整类型提示 const { order_id, query_fields } params; // ... } };用 Zod 的另一个好处是你可以把 Zod Schema 直接转成 JSON Schema 给 LLM 用同时用同一个 Schema 做运行时校验。这样就不会出现“给 LLM 的 Schema 和实际校验的 Schema 不一致”的问题。3.3 Schema 版本管理与向后兼容生产环境的工具 Schema 一定会变。加参数、改参数名、废弃工具这些都在所难免。如果没有版本管理很容易出现“LLM 还在按旧 Schema 调用但工具已经改了”的情况。我的做法是Schema 变更必须走版本号。每个工具定义带一个version字段。LLM 侧看到的 Schema 和工具执行侧校验的 Schema 必须版本一致。新增参数要可选废弃参数要保留过渡期。不要直接删参数先标记为 deprecated在 description 里说明“此参数已废弃请使用 XXX 替代”过渡一两个版本后再删。工具废弃要分两步。先在新版本里把工具标记为 deprecateddescription 里写清楚替代方案让 LLM 逐渐不再调用。等监控数据显示调用量降到零再真正下线。下面是一个 Schema 版本管理的对照表变更类型处理方式过渡期新增可选参数直接加version 1无新增必填参数先加为可选给默认值下版本改必填1-2 个版本修改参数名新旧参数名并存旧名标记 deprecated2 个版本删除参数先标记 deprecated再删除2 个版本废弃工具标记 deprecated提供替代工具直到调用量为零提示Schema 版本管理最好和你的 CI/CD 流程打通。每次 Schema 变更都自动生成 diff人工 review 后再合并。Schema 变更比代码变更更需要谨慎因为它直接影响 LLM 的行为。4. 第三道坎Token 成本与性能的平衡术4.1 Token 用量失控的三个隐形黑洞Token 成本是 Agent 项目从 Demo 走向生产时最容易被低估的问题。Demo 阶段你只跑几条 query感觉 Token 用量还好。生产环境一天几万次调用Token 账单能吓死人。我排查过不少 Token 用量异常的案例总结下来有三个隐形黑洞黑洞一System Prompt 过长且重复。很多项目的 System Prompt 写得像论文几千个 Token每次调用都要带上。如果一天调用 10 万次光 System Prompt 就消耗几亿 Token。更离谱的是有些项目在每轮对话里都重复插入完整的工具定义而不是只在第一轮插入。黑洞二历史消息无限增长。多轮对话场景下如果不做历史消息裁剪对话越长 Token 越多。用户聊了 20 轮每轮都把前 19 轮的历史带上Token 用量是指数级增长的。黑洞三工具返回结果过大。工具返回的原始数据可能很大比如查询订单返回了完整的 JSON包含几十个字段。这些数据全部塞回给 LLMToken 消耗巨大而且大部分字段 LLM 根本用不上。4.2 上下文压缩与历史消息裁剪策略针对上面三个黑洞对应的解法是System Prompt 精简与缓存。把 System Prompt 压缩到最核心的指令工具定义只在第一轮插入。如果模型支持 prompt caching把 System Prompt 和工具定义标记为可缓存后续调用直接复用缓存成本能降一个数量级。历史消息滑动窗口 摘要。不要保留全部历史用滑动窗口保留最近 N 轮。更早的历史用 LLM 生成摘要只保留摘要而不是原文。摘要的 Token 量通常是原文的十分之一。工具返回结果裁剪。在工具 wrapper 里做结果裁剪只返回 LLM 需要的字段。比如查询订单LLM 可能只需要状态和金额那就只返回这两个字段不要返回完整订单对象。def trim_tool_result(result, needed_fields): 只保留 LLM 需要的字段 if isinstance(result, dict): return {k: v for k, v in result.items() if k in needed_fields} elif isinstance(result, list): return [trim_tool_result(item, needed_fields) for item in result] return result4.3 模型选型与 Token 成本核算不同模型的 Token 单价差异很大。生产环境不要所有任务都用最贵的模型。我的做法是分级路由简单意图识别、参数提取用便宜的小模型比如 7B 级别的模型成本是大模型的几十分之一。复杂推理、多步规划用大模型保证效果。工具结果总结用中等模型平衡成本和效果。具体怎么分级要看你的业务场景。可以先做一个评估集把历史 query 拿出来分别用不同模型跑一遍看准确率差异。如果小模型在某个任务上准确率只比大模型低 2-3 个百分点但成本低 90%那就果断用小模型。Token 成本核算的公式很简单单次调用成本 (输入 Token 数 × 输入单价) (输出 Token 数 × 输出单价) 日成本 单次调用成本 × 日调用量但实际核算时要注意Agent 场景下一次用户请求可能触发多次 LLM 调用规划、工具选择、结果总结所以要把链路里所有 LLM 调用的 Token 都算进去。模型级别适用任务相对成本准确率参考小模型7B意图识别、参数提取1x85-90%中模型中等规模工具选择、结果总结5-10x92-95%大模型旗舰多步规划、复杂推理30-50x96-98%注意上表的准确率只是参考范围具体要看你的任务难度和评估集。不要盲目相信模型榜单一定要在自己的数据上实测。5. 第四道坎并发场景下的 Agent 架构设计5.1 Agent 怎么扛并发从单机到分布式的演进“AI Agent 怎么扛并发”是最近被问得最多的问题之一。Agent 和传统后端服务在并发处理上有本质区别传统服务是无状态的加机器就能扛Agent 是有状态的而且状态在 LLM 的上下文里没法简单水平扩展。我经历过从单机到分布式的完整演进大致分三个阶段阶段一单机串行。所有请求排队一个一个处理。QPS 个位数延迟高但实现简单。适合内部工具、低流量场景。阶段二单机并发 连接池。用异步 IO 处理 LLM 调用和工具调用同时维护一个 LLM 请求的连接池。QPS 能到几十但受限于单机资源和 LLM 侧的速率限制。阶段三分布式 会话粘性。多台机器组成集群用一致性哈希把同一会话的请求路由到同一台机器保证上下文不丢失。QPS 能到几百甚至上千但架构复杂度大幅上升。5.2 会话状态管理与水平扩展方案分布式 Agent 最大的挑战是会话状态管理。LLM 的上下文是有状态的如果同一用户的请求被路由到不同机器上下文就断了。解决方案有几种方案一会话粘性路由。用一致性哈希把 session_id 映射到固定机器。优点是实现简单上下文在本地内存里读取快。缺点是机器故障时会话丢失扩容时部分会话需要迁移。方案二外部状态存储。把会话上下文存到 Redis 或数据库中每台机器都从外部存储读写。优点是无状态任意机器都能处理任意会话。缺点是每次读写都有网络开销延迟增加。方案三混合方案。热会话放本地内存冷会话放外部存储。新会话写入外部存储活跃会话缓存在本地。这样兼顾了性能和可靠性。我实际项目中用的是方案三。具体做法是会话创建时写入 Redis同时在本机内存缓存一份。后续请求优先读本地缓存缓存未命中则从 Redis 加载。会话空闲超过 30 分钟本地缓存淘汰只保留 Redis 中的持久化状态。class SessionManager: def __init__(self, redis_client, local_cache_size1000): self.redis redis_client self.local_cache LRUCache(local_cache_size) def get_session(self, session_id): # 优先读本地缓存 if session_id in self.local_cache: return self.local_cache[session_id] # 本地未命中从 Redis 加载 session_data self.redis.get(fsession:{session_id}) if session_data: self.local_cache[session_id] session_data return session_data return None def save_session(self, session_id, session_data): # 同时写本地和 Redis self.local_cache[session_id] session_data self.redis.setex(fsession:{session_id}, 3600, session_data)5.3 限流、熔断与降级在 Agent 链路的落地Agent 链路的依赖很多LLM API、工具服务、向量数据库、外部 API。任何一个依赖出问题都可能拖垮整个链路。所以限流、熔断、降级是必须的。限流要分两个维度一是对 LLM API 的调用限流防止超过速率限制被封二是对用户请求的限流防止单个用户占用过多资源。LLM 调用限流用令牌桶算法用户请求限流用滑动窗口。熔断主要针对工具服务。如果某个工具的错误率超过阈值比如 50%自动熔断后续请求直接走降级逻辑不再调用该工具。熔断后定期探测恢复后自动关闭熔断。降级要有明确的降级策略。比如 LLM API 不可用时降级到规则引擎工具服务不可用时返回缓存结果或提示用户稍后再试。降级不是失败而是有损服务保证核心功能可用。故障场景限流策略熔断阈值降级方案LLM API 限流令牌桶QPS 限制错误率 30%切换备用模型工具服务超时并发数限制错误率 50%返回缓存结果向量库不可用连接池限制连续 5 次失败降级到关键词检索外部 API 故障按用户限流错误率 40%提示用户稍后重试提示熔断阈值不要设得太敏感否则容易误熔断。建议先用监控数据跑一段时间找到正常的错误率基线再在此基础上上浮 20-30% 作为阈值。6. 常见问题与排查技巧实录6.1 工具调用报错排查速查表实际运维中工具调用报错是最常见的问题。我整理了一份速查表覆盖了大部分场景报错信息可能原因排查步骤解决方案Schema validation failed参数类型/格式不符打印 LLM 返回的原始参数优化 Schema description加重试Tool not found工具名拼写错误或未注册检查工具注册表修正工具名确保注册Timeout工具执行超时查看工具执行日志增加超时时间优化工具性能Rate limit exceededLLM API 限流查看 API 调用频率加令牌桶限流申请更高配额Token exchange failed认证 Token 失效检查 Token 有效期实现 Token 自动续签Empty responseLLM 返回空检查 prompt 和输入加兜底逻辑重试6.2 Token 失效与认证续签的工程处理“Token 失效”和“Token 续签”是 Agent 项目里另一个高频问题。这里的 Token 指的是认证用的 Token不是 LLM 的 Token。很多项目在 Token 过期后直接报错用户体验很差。正确的做法是实现自动续签。用 JWT 的话通常有 access_token 和 refresh_token 两个。access_token 有效期短比如 15 分钟refresh_token 有效期长比如 7 天。当 access_token 过期时用 refresh_token 换新的 access_token。class TokenManager: def __init__(self, refresh_token): self.access_token None self.refresh_token refresh_token self.expires_at 0 def get_token(self): # 提前 60 秒刷新避免边界情况 if time.time() self.expires_at - 60: self.refresh() return self.access_token def refresh(self): response requests.post(/auth/refresh, json{ refresh_token: self.refresh_token }) if response.status_code 200: data response.json() self.access_token data[access_token] self.expires_at time.time() data[expires_in] else: raise AuthError(Token 续签失败需要重新登录)注意refresh_token 也可能过期。如果续签失败要有明确的错误提示引导用户重新登录而不是让整个 Agent 链路卡死。6.3 并发压测与容量规划经验上线前一定要做并发压测。Agent 的压测和传统服务不太一样因为 LLM 的响应时间波动很大而且有速率限制。我的压测方法是第一步单请求基准测试。先测单请求的延迟分布P50、P95、P99 分别是多少。Agent 链路的 P99 延迟通常是 P50 的 3-5 倍要有心理预期。第二步逐步加压。从 1 QPS 开始每 5 分钟增加 1 QPS观察错误率和延迟变化。找到错误率开始上升的拐点那就是当前配置的容量上限。第三步容量规划。根据业务预估的峰值 QPS留 2-3 倍余量来配置资源。比如峰值预估 50 QPS那要按 100-150 QPS 来准备。压测时要注意LLM API 通常有速率限制压测前先确认配额避免压测把配额打满影响线上。7. 写在最后Agent 从 Demo 到生产本质上是从“理想环境”到“真实环境”的跨越。Demo 阶段你面对的是精心构造的输入、少量的并发、宽容的用户生产环境你面对的是长尾输入、高并发、严格的 SLA。这四个坎——工具调用稳定性、Schema 工程化、Token 成本控制、并发架构——每一个都需要工程手段去兜底不能指望 LLM 自己解决。我在实际项目里踩过的最大的坑是早期太相信 LLM 的能力觉得只要 prompt 写得好工具调用就不会出错。结果上线后发现prompt 优化能解决 80% 的问题但剩下 20% 的长尾问题必须靠工程手段。Schema 校验、重试降级、限流熔断这些传统后端的套路在 Agent 场景里一个都不能少。最后分享一个小技巧给每个工具调用打上 trace_id把 LLM 的输入输出、工具调用的参数和结果、耗时、Token 用量全部串起来。出问题时拿着 trace_id 一查整条链路一目了然。这个投入在排查问题时能省下大量时间强烈建议在项目早期就加上。
Agent生产落地四大工程坎：工具调用、Schema治理、Token成本与并发架构
1. 从 Demo 到生产Agent 落地的真实鸿沟做过 Agent 项目的人大概都有过这种体验本地跑 Demo 的时候工具调用丝滑流畅LLM 该调哪个函数就调哪个函数Schema 校验一次通过Token 消耗也在可接受范围内。演示给领导看掌声一片项目立项资源到位。然后进入生产环境用户量一上来各种幺蛾子全出来了——工具调用开始随机失败Schema 校验报错率飙升Token 用量失控并发一高整个链路直接雪崩。这不是个别现象。我参与过几个企业级 Agent 项目从零到一的落地也帮朋友排查过不少“Demo 惊艳、上线拉胯”的案例。说实话大部分问题在 Demo 阶段就已经埋下了只是当时被小数据量、低并发、理想输入给掩盖了。Agent 和传统后端服务最大的区别在于它的核心链路里有一个非确定性的大模型。你没法像写 CRUD 那样给定输入就一定能得到预期输出。这个本质差异决定了 Agent 的生产落地需要一套完全不同的工程方法论。这篇文章不聊虚的就围绕四个最要命的坎——工具调用的稳定性、Schema 的工程化治理、Token 的成本与性能平衡、并发场景下的架构设计——把每个坎的根因拆开给出我在实际项目中验证过的工程解法。适合正在做 Agent 项目、或者准备把 Agent 推上生产的同学参考。如果你还在写 Demo 阶段也可以提前看看少走点弯路。2. 第一道坎工具调用的稳定性治理2.1 为什么 Demo 里工具调用很稳上线就崩Demo 阶段工具调用稳定核心原因是输入分布极窄。你测试的时候用的都是精心构造的 query意图明确参数完整LLM 很容易映射到正确的工具和参数。但生产环境的用户输入是长尾的、模糊的、甚至自相矛盾的。用户可能说“帮我查一下那个东西”也可能在一句话里塞三个意图还可能用错别字、口语、方言。LLM 面对这种输入时工具调用的决策链路会变得极其脆弱。具体表现有几类工具选择错误该调 A 工具却调了 B或者该调工具却直接编造答案。参数提取失败工具选对了但参数缺了、格式错了、类型不对。调用时机错误该先查再算结果直接算该等用户确认结果直接执行。幻觉调用调了一个根本不存在的工具或者传了 Schema 里没定义的参数。这些问题的根因一半在 LLM 本身的能力边界一半在工程侧没有做好约束和兜底。Demo 阶段你只看到了 LLM 能力上限的那一面生产环境把它的下限暴露出来了。2.2 工具描述与 Schema 设计的实战原则工具调用的第一道防线是工具描述和 Schema 的设计。很多团队在这块很随意工具名用缩写描述写一句话参数用嵌套对象结果 LLM 根本理解不了。我总结了几条实战原则工具名要语义化且唯一。不要用get_data这种模糊名字用query_order_by_id、search_product_by_keyword这种一看就知道干什么的名字。工具名是 LLM 做选择时的重要信号名字越清晰选择准确率越高。工具描述要写清楚“什么时候用”和“什么时候不用”。只写“查询订单”不够要写“当用户提供了订单号需要查询订单状态、金额、物流信息时使用。如果用户没有提供订单号不要调用此工具先向用户询问订单号。”把边界条件写进去能显著降低误调用。参数 Schema 要扁平化。能用平铺参数就别用嵌套对象。LLM 对嵌套结构的解析能力明显弱于扁平结构。如果确实需要嵌套层级不要超过两层。每个参数都要有 description 和 example。这是最容易被忽略但收益最高的操作。比如order_id参数description 写“订单编号通常是 12 位数字”example 写“202405180001”。LLM 看到 example 后参数提取的准确率会有肉眼可见的提升。枚举值要显式列出。如果某个参数只接受固定几个值一定要在 Schema 里用 enum 列出来不要指望 LLM 自己猜。下面是一个对比示例左边是反面教材右边是实战优化后的版本// 反面教材 { name: query, description: 查询订单, parameters: { type: object, properties: { info: { type: object, properties: { id: {type: string}, type: {type: string} } } } } } // 实战优化 { name: query_order_detail, description: 根据订单号查询订单的详细信息包括订单状态、支付金额、商品列表、物流进度。当用户明确提供了订单号且需要查询订单相关信息时使用。如果用户没有提供订单号不要调用此工具。, parameters: { type: object, properties: { order_id: { type: string, description: 订单编号通常是 12 位数字以 2024 或 2025 开头, example: 202405180001 }, query_fields: { type: array, items: {type: string, enum: [status, amount, items, logistics]}, description: 需要查询的字段列表不传则返回全部字段 } }, required: [order_id] } }2.3 工具调用失败的重试与降级策略即使 Schema 设计得再好LLM 也有概率调用失败。生产环境必须有一套重试与降级机制。我的做法是分三层处理第一层Schema 校验失败的重试。当 LLM 返回的工具调用参数不符合 Schema 时不要直接报错给用户。把校验错误信息作为 observation 回传给 LLM让它重新生成。通常重试一次就能修正。重试时可以在 prompt 里加一句“上一次调用参数格式有误错误信息是 XXX请修正后重新调用”。第二层工具执行失败的重试。工具本身可能因为网络、超时、下游服务不稳定而失败。这类失败要用指数退避重试但要注意幂等性。查询类工具可以放心重试写入类工具必须保证幂等否则会重复下单、重复扣款。第三层降级兜底。如果重试多次仍然失败要有降级方案。比如切换到备用工具、返回缓存结果、或者直接告诉用户“当前服务繁忙请稍后再试”。最忌讳的是让 LLM 在工具失败后自由发挥它很可能会编造一个答案给用户。这里有个实操心得在工具执行层加一个统一的 wrapper所有工具调用都走这个 wrapper。wrapper 负责参数校验、超时控制、重试、日志记录、降级。这样业务代码不用关心这些横切逻辑LLM 侧也只需要面对统一的错误格式。def tool_wrapper(tool_func, max_retries2, timeout10): def wrapped(**kwargs): for attempt in range(max_retries 1): try: # 参数校验 validated validate_schema(kwargs, tool_func.schema) # 超时控制 result call_with_timeout(tool_func, validated, timeout) return {success: True, data: result} except SchemaError as e: if attempt max_retries: return {success: False, error: f参数格式错误{e}, retryable: True} return {success: False, error: f参数格式错误{e}, retryable: False} except TimeoutError: if attempt max_retries: continue return {success: False, error: 工具执行超时, retryable: False} except Exception as e: return {success: False, error: str(e), retryable: False} return wrapped注意重试次数不要太多一般 1-2 次就够了。重试次数过多会显著增加延迟和 Token 消耗而且很多错误重试也没用。3. 第二道坎Schema 的工程化治理3.1 Schema 不只是校验工具更是 LLM 的“接口文档”很多人把 Schema 仅仅当成参数校验的工具这是很大的认知偏差。在 Agent 场景里Schema 是 LLM 理解工具能力的唯一入口。LLM 看不到你的工具实现代码它只能通过 Schema 里的 name、description、parameters 来推断这个工具能做什么、需要什么参数、返回什么。所以 Schema 的质量直接决定了工具调用的准确率。我见过太多项目工具实现写得很好但 Schema 写得一塌糊涂结果 LLM 根本调不对。Schema 治理的核心目标是让 LLM 在只看 Schema 的情况下就能正确判断什么时候该调用、该传什么参数。这其实和写 API 文档是一个道理只不过读者从人类开发者变成了 LLM。3.2 用 Zod Schema 做类型安全的工具定义如果你用 TypeScript 做 Agent 开发强烈建议用Zod来定义工具 Schema。Zod 的好处是一份定义同时得到运行时校验和 TypeScript 类型推断。你不需要维护两套东西。import { z } from zod; const QueryOrderSchema z.object({ order_id: z.string() .regex(/^\d{12}$/) .describe(订单编号12位数字以2024或2025开头), query_fields: z.array( z.enum([status, amount, items, logistics]) ).optional().describe(需要查询的字段列表不传则返回全部), }); type QueryOrderParams z.infertypeof QueryOrderSchema; const queryOrderTool { name: query_order_detail, description: 根据订单号查询订单详情..., parameters: zodToJsonSchema(QueryOrderSchema), execute: async (params: QueryOrderParams) { // params 已经有完整类型提示 const { order_id, query_fields } params; // ... } };用 Zod 的另一个好处是你可以把 Zod Schema 直接转成 JSON Schema 给 LLM 用同时用同一个 Schema 做运行时校验。这样就不会出现“给 LLM 的 Schema 和实际校验的 Schema 不一致”的问题。3.3 Schema 版本管理与向后兼容生产环境的工具 Schema 一定会变。加参数、改参数名、废弃工具这些都在所难免。如果没有版本管理很容易出现“LLM 还在按旧 Schema 调用但工具已经改了”的情况。我的做法是Schema 变更必须走版本号。每个工具定义带一个version字段。LLM 侧看到的 Schema 和工具执行侧校验的 Schema 必须版本一致。新增参数要可选废弃参数要保留过渡期。不要直接删参数先标记为 deprecated在 description 里说明“此参数已废弃请使用 XXX 替代”过渡一两个版本后再删。工具废弃要分两步。先在新版本里把工具标记为 deprecateddescription 里写清楚替代方案让 LLM 逐渐不再调用。等监控数据显示调用量降到零再真正下线。下面是一个 Schema 版本管理的对照表变更类型处理方式过渡期新增可选参数直接加version 1无新增必填参数先加为可选给默认值下版本改必填1-2 个版本修改参数名新旧参数名并存旧名标记 deprecated2 个版本删除参数先标记 deprecated再删除2 个版本废弃工具标记 deprecated提供替代工具直到调用量为零提示Schema 版本管理最好和你的 CI/CD 流程打通。每次 Schema 变更都自动生成 diff人工 review 后再合并。Schema 变更比代码变更更需要谨慎因为它直接影响 LLM 的行为。4. 第三道坎Token 成本与性能的平衡术4.1 Token 用量失控的三个隐形黑洞Token 成本是 Agent 项目从 Demo 走向生产时最容易被低估的问题。Demo 阶段你只跑几条 query感觉 Token 用量还好。生产环境一天几万次调用Token 账单能吓死人。我排查过不少 Token 用量异常的案例总结下来有三个隐形黑洞黑洞一System Prompt 过长且重复。很多项目的 System Prompt 写得像论文几千个 Token每次调用都要带上。如果一天调用 10 万次光 System Prompt 就消耗几亿 Token。更离谱的是有些项目在每轮对话里都重复插入完整的工具定义而不是只在第一轮插入。黑洞二历史消息无限增长。多轮对话场景下如果不做历史消息裁剪对话越长 Token 越多。用户聊了 20 轮每轮都把前 19 轮的历史带上Token 用量是指数级增长的。黑洞三工具返回结果过大。工具返回的原始数据可能很大比如查询订单返回了完整的 JSON包含几十个字段。这些数据全部塞回给 LLMToken 消耗巨大而且大部分字段 LLM 根本用不上。4.2 上下文压缩与历史消息裁剪策略针对上面三个黑洞对应的解法是System Prompt 精简与缓存。把 System Prompt 压缩到最核心的指令工具定义只在第一轮插入。如果模型支持 prompt caching把 System Prompt 和工具定义标记为可缓存后续调用直接复用缓存成本能降一个数量级。历史消息滑动窗口 摘要。不要保留全部历史用滑动窗口保留最近 N 轮。更早的历史用 LLM 生成摘要只保留摘要而不是原文。摘要的 Token 量通常是原文的十分之一。工具返回结果裁剪。在工具 wrapper 里做结果裁剪只返回 LLM 需要的字段。比如查询订单LLM 可能只需要状态和金额那就只返回这两个字段不要返回完整订单对象。def trim_tool_result(result, needed_fields): 只保留 LLM 需要的字段 if isinstance(result, dict): return {k: v for k, v in result.items() if k in needed_fields} elif isinstance(result, list): return [trim_tool_result(item, needed_fields) for item in result] return result4.3 模型选型与 Token 成本核算不同模型的 Token 单价差异很大。生产环境不要所有任务都用最贵的模型。我的做法是分级路由简单意图识别、参数提取用便宜的小模型比如 7B 级别的模型成本是大模型的几十分之一。复杂推理、多步规划用大模型保证效果。工具结果总结用中等模型平衡成本和效果。具体怎么分级要看你的业务场景。可以先做一个评估集把历史 query 拿出来分别用不同模型跑一遍看准确率差异。如果小模型在某个任务上准确率只比大模型低 2-3 个百分点但成本低 90%那就果断用小模型。Token 成本核算的公式很简单单次调用成本 (输入 Token 数 × 输入单价) (输出 Token 数 × 输出单价) 日成本 单次调用成本 × 日调用量但实际核算时要注意Agent 场景下一次用户请求可能触发多次 LLM 调用规划、工具选择、结果总结所以要把链路里所有 LLM 调用的 Token 都算进去。模型级别适用任务相对成本准确率参考小模型7B意图识别、参数提取1x85-90%中模型中等规模工具选择、结果总结5-10x92-95%大模型旗舰多步规划、复杂推理30-50x96-98%注意上表的准确率只是参考范围具体要看你的任务难度和评估集。不要盲目相信模型榜单一定要在自己的数据上实测。5. 第四道坎并发场景下的 Agent 架构设计5.1 Agent 怎么扛并发从单机到分布式的演进“AI Agent 怎么扛并发”是最近被问得最多的问题之一。Agent 和传统后端服务在并发处理上有本质区别传统服务是无状态的加机器就能扛Agent 是有状态的而且状态在 LLM 的上下文里没法简单水平扩展。我经历过从单机到分布式的完整演进大致分三个阶段阶段一单机串行。所有请求排队一个一个处理。QPS 个位数延迟高但实现简单。适合内部工具、低流量场景。阶段二单机并发 连接池。用异步 IO 处理 LLM 调用和工具调用同时维护一个 LLM 请求的连接池。QPS 能到几十但受限于单机资源和 LLM 侧的速率限制。阶段三分布式 会话粘性。多台机器组成集群用一致性哈希把同一会话的请求路由到同一台机器保证上下文不丢失。QPS 能到几百甚至上千但架构复杂度大幅上升。5.2 会话状态管理与水平扩展方案分布式 Agent 最大的挑战是会话状态管理。LLM 的上下文是有状态的如果同一用户的请求被路由到不同机器上下文就断了。解决方案有几种方案一会话粘性路由。用一致性哈希把 session_id 映射到固定机器。优点是实现简单上下文在本地内存里读取快。缺点是机器故障时会话丢失扩容时部分会话需要迁移。方案二外部状态存储。把会话上下文存到 Redis 或数据库中每台机器都从外部存储读写。优点是无状态任意机器都能处理任意会话。缺点是每次读写都有网络开销延迟增加。方案三混合方案。热会话放本地内存冷会话放外部存储。新会话写入外部存储活跃会话缓存在本地。这样兼顾了性能和可靠性。我实际项目中用的是方案三。具体做法是会话创建时写入 Redis同时在本机内存缓存一份。后续请求优先读本地缓存缓存未命中则从 Redis 加载。会话空闲超过 30 分钟本地缓存淘汰只保留 Redis 中的持久化状态。class SessionManager: def __init__(self, redis_client, local_cache_size1000): self.redis redis_client self.local_cache LRUCache(local_cache_size) def get_session(self, session_id): # 优先读本地缓存 if session_id in self.local_cache: return self.local_cache[session_id] # 本地未命中从 Redis 加载 session_data self.redis.get(fsession:{session_id}) if session_data: self.local_cache[session_id] session_data return session_data return None def save_session(self, session_id, session_data): # 同时写本地和 Redis self.local_cache[session_id] session_data self.redis.setex(fsession:{session_id}, 3600, session_data)5.3 限流、熔断与降级在 Agent 链路的落地Agent 链路的依赖很多LLM API、工具服务、向量数据库、外部 API。任何一个依赖出问题都可能拖垮整个链路。所以限流、熔断、降级是必须的。限流要分两个维度一是对 LLM API 的调用限流防止超过速率限制被封二是对用户请求的限流防止单个用户占用过多资源。LLM 调用限流用令牌桶算法用户请求限流用滑动窗口。熔断主要针对工具服务。如果某个工具的错误率超过阈值比如 50%自动熔断后续请求直接走降级逻辑不再调用该工具。熔断后定期探测恢复后自动关闭熔断。降级要有明确的降级策略。比如 LLM API 不可用时降级到规则引擎工具服务不可用时返回缓存结果或提示用户稍后再试。降级不是失败而是有损服务保证核心功能可用。故障场景限流策略熔断阈值降级方案LLM API 限流令牌桶QPS 限制错误率 30%切换备用模型工具服务超时并发数限制错误率 50%返回缓存结果向量库不可用连接池限制连续 5 次失败降级到关键词检索外部 API 故障按用户限流错误率 40%提示用户稍后重试提示熔断阈值不要设得太敏感否则容易误熔断。建议先用监控数据跑一段时间找到正常的错误率基线再在此基础上上浮 20-30% 作为阈值。6. 常见问题与排查技巧实录6.1 工具调用报错排查速查表实际运维中工具调用报错是最常见的问题。我整理了一份速查表覆盖了大部分场景报错信息可能原因排查步骤解决方案Schema validation failed参数类型/格式不符打印 LLM 返回的原始参数优化 Schema description加重试Tool not found工具名拼写错误或未注册检查工具注册表修正工具名确保注册Timeout工具执行超时查看工具执行日志增加超时时间优化工具性能Rate limit exceededLLM API 限流查看 API 调用频率加令牌桶限流申请更高配额Token exchange failed认证 Token 失效检查 Token 有效期实现 Token 自动续签Empty responseLLM 返回空检查 prompt 和输入加兜底逻辑重试6.2 Token 失效与认证续签的工程处理“Token 失效”和“Token 续签”是 Agent 项目里另一个高频问题。这里的 Token 指的是认证用的 Token不是 LLM 的 Token。很多项目在 Token 过期后直接报错用户体验很差。正确的做法是实现自动续签。用 JWT 的话通常有 access_token 和 refresh_token 两个。access_token 有效期短比如 15 分钟refresh_token 有效期长比如 7 天。当 access_token 过期时用 refresh_token 换新的 access_token。class TokenManager: def __init__(self, refresh_token): self.access_token None self.refresh_token refresh_token self.expires_at 0 def get_token(self): # 提前 60 秒刷新避免边界情况 if time.time() self.expires_at - 60: self.refresh() return self.access_token def refresh(self): response requests.post(/auth/refresh, json{ refresh_token: self.refresh_token }) if response.status_code 200: data response.json() self.access_token data[access_token] self.expires_at time.time() data[expires_in] else: raise AuthError(Token 续签失败需要重新登录)注意refresh_token 也可能过期。如果续签失败要有明确的错误提示引导用户重新登录而不是让整个 Agent 链路卡死。6.3 并发压测与容量规划经验上线前一定要做并发压测。Agent 的压测和传统服务不太一样因为 LLM 的响应时间波动很大而且有速率限制。我的压测方法是第一步单请求基准测试。先测单请求的延迟分布P50、P95、P99 分别是多少。Agent 链路的 P99 延迟通常是 P50 的 3-5 倍要有心理预期。第二步逐步加压。从 1 QPS 开始每 5 分钟增加 1 QPS观察错误率和延迟变化。找到错误率开始上升的拐点那就是当前配置的容量上限。第三步容量规划。根据业务预估的峰值 QPS留 2-3 倍余量来配置资源。比如峰值预估 50 QPS那要按 100-150 QPS 来准备。压测时要注意LLM API 通常有速率限制压测前先确认配额避免压测把配额打满影响线上。7. 写在最后Agent 从 Demo 到生产本质上是从“理想环境”到“真实环境”的跨越。Demo 阶段你面对的是精心构造的输入、少量的并发、宽容的用户生产环境你面对的是长尾输入、高并发、严格的 SLA。这四个坎——工具调用稳定性、Schema 工程化、Token 成本控制、并发架构——每一个都需要工程手段去兜底不能指望 LLM 自己解决。我在实际项目里踩过的最大的坑是早期太相信 LLM 的能力觉得只要 prompt 写得好工具调用就不会出错。结果上线后发现prompt 优化能解决 80% 的问题但剩下 20% 的长尾问题必须靠工程手段。Schema 校验、重试降级、限流熔断这些传统后端的套路在 Agent 场景里一个都不能少。最后分享一个小技巧给每个工具调用打上 trace_id把 LLM 的输入输出、工具调用的参数和结果、耗时、Token 用量全部串起来。出问题时拿着 trace_id 一查整条链路一目了然。这个投入在排查问题时能省下大量时间强烈建议在项目早期就加上。
