Agent 第一句就 500我们查了三轮入口日志少打了一个参数带过 Agent 项目的朋友应该都有这种体会Agent 服务排查问题比普通接口要难受得多。普通接口 500查一下调用链、看下异常堆栈基本就有眉目了。Agent 不一样它背后可能串了模型调用、工具调度、记忆读写、上下文组装任何一个环节出问题最后的表现可能都是同一个 500。我最近就遇到一个典型案例项目联调阶段用户发第一句话Agent 直接回了 500。听起来是入口问题吧但我们前后查了三轮最后定位到根因的时候自己都觉得离谱——入口日志少打了一个参数转发的时候也真的漏传了那个参数。这篇就当一次复盘记录把整个排查过程和 Agent 类项目排障的方法论一起写出来给同行一个参考。1. 先还原一下现场Agent 第一句就 500 是什么概念先说下我们的项目背景。这是一个基于自研编排层 大模型接口的 Agent 服务对外暴露一个 HTTP 接口客户端把用户消息传过来服务端要完成解析请求 → 恢复会话上下文 → 组装 prompt → 调用模型 → 执行工具 → 返回结果。链路虽然不算特别长但涉及的服务不少而且用的是异步任务 回调的架构。出现问题的现象是客户端传第一句话后端接口立刻返回 500。注意是“第一句”也就是用户还没建立任何历史对话session 是全新的。这说明什么说明大概率不是模型输出解析、工具执行这种后端环节挂了而是问题发生在更靠前的位置——请求入口或者参数校验。当时我们的第一反应是看错误日志。结果发现日志里写的是空指针异常NullPointerException而且是在一个参数解析的工具类里抛出来的。这就很有意思了老项目里 NPE 十有八九是某个字段没传但问题是这个字段到底是谁没传、在哪一层没传单看堆栈根本看不出来。堆栈只能告诉你“这里空指针了”不能告诉你是谁把 null 塞进来的。而且这里有个 Agent 项目的特殊坑Agent 服务往往要走网关鉴权、用户上下文拉取、会话初始化这些前置逻辑。如果某个前置参数丢了比如 tenant_id 没传后面所有跟租户相关的逻辑都会拿到 null你根本分不清是入口的问题还是业务代码的问题。第一句 500 恰恰是最容易让人误判的场景——你以为是初始化逻辑出了问题实际上只是入口漏了东西。2. 三轮排查实录我们都查了什么这一节我把三次排查的完整过程写出来包括每一轮看了什么、得出什么结论、为什么走了弯路。这个过程比最后的根因更重要因为大多数 Agent 项目的排障思路都是这样逐步收敛的。2.1 第一轮满屏 NPE 和参数校验失败但没抓到源头第一轮排查我们理所当然地去了后端服务日志。打开日志一看好家伙全是 NPE还有一些参数校验异常比如ParameterValidationException: agent_id must not be blank。这时候第一反应是哪个调用方没传参于是我们翻出接口文档对着文档检查请求体。请求体里 Agent ID 传了用户消息传了上下文相关的字段也传了看起来都是齐的。再仔细看堆栈发现 NPE 是在一个SessionContextBuilder的类里抛出来的这个类负责根据请求参数构建会话上下文。里面有一行String userId request.getUserContext().getUserId();getUserContext()返回了 null所以再调getUserId()就直接炸了。这个信息很关键但它只告诉我们UserContext 是空的没有告诉我们为什么是空的。理论上这是个嵌套对象客户端传参的时候userContext这个节点本身就可能缺失。我们当时做的事情是去查网关层有没有把客户端请求完整透传。查下来网关日志显示请求体是完整的userContext有值。这就更奇怪了——入口是好的网关是好的后端一处理就 NPE这一轮排查的结论是问题不在客户端也不在网关而是后端某个环节在转发或构造参数时把userContext弄丢了。但具体丢在哪一步日志里没体现。2.2 第二轮怀疑下游服务逐个调用点排查因为 Agent 服务要调用模型网关、用户服务、记忆服务三个下游我们第二轮想的是“是不是下游服务返回了异常数据导致上游构造上下文时拿到 null”。于是我们对三个下游分别做了排查模型网关拉取最近 5 分钟调用记录全部正常没有 5xx没有超时。用户服务用测试请求调了一次UserContext 能正常返回数据完整。记忆服务新会话没有历史记忆返回空列表这是预期行为。下游全部正常那问题就收缩到了 Agent 服务自身。我们开始怀疑是服务内部在拿到请求后、进入业务逻辑之前经过了某个转换器或适配器把参数结构改了。于是我们把服务的入口过滤器、拦截器、切面一个个检查过去终于发现一个问题入口层打印的访问日志里根本没有userContext这个字段。也就是说入口打了日志但日志内容是不完整的——我们只能看到请求路径、Agent ID、消息内容看不到完整的参数结构。这就是标题里“入口日志少打了一个参数”的字面原因日志模板里没包含完整参数。但这还不能解释 NPE因为日志打得全不全不影响实际参数传递。真正的问题在哪还得再挖。2.3 第三轮对比正常请求与异常请求锁根因第三轮我们换了个思路不做静态检查而是直接抓真实流量做对比。从网关拉了两类请求正常的能成功进入业务逻辑的和异常的触发 500 的。对比之后发现了一个几乎被忽略的差异点正常请求里客户端传的参数经过网关转发到 Agent 服务时userContext结构是完整的而异常请求是发到 Agent 服务的另一个入口——一个内部回调接口。这个回调接口收到的参数根本不是客户端原始参数而是由入口服务组装后的一个 DTO。问题就在这个 DTO 的组装代码里。我们的入口服务在收到客户端请求后会做一步“参数转换”把 HTTP 请求体转成内部 Agent 调用 DTO。这个转换代码里有一个手写的 Map 拷贝逻辑类似这样AgentRequestDTO dto new AgentRequestDTO(); dto.setAgentId(map.get(agentId)); dto.setMessage(map.get(message)); // 顺手从 map 里取值但 key 拼错了 dto.setUserContext(parseUserContext(map.get(user_context)));关键点来了客户端传的是userContext驼峰命名但转换代码里取的是user_context下划线命名。这个取值的 key 不匹配导致map.get(user_context)永远返回 nullparseUserContext(null)最终返回一个空的 UserContext 对象后面的业务代码调getUserId()就 NPE。这里还有个更隐蔽的问题入口服务的访问日志为了迎合某些监控系统的字段规范记录的参数列表里只打了agentId、message、timestamp而userContext根本没打进日志。于是我们看到的是入口日志显示请求正常、参数没丢但实际传递过程已经丢了。日志没打全这个参数恰好把真正的问题藏起来了。这就是三轮排查的全过程。第一轮只看到了现象NPE第二轮排除了下游第三轮通过流量对比才定位到入口转换代码的 key 拼写错误 日志字段缺失。3. 为什么少一个参数就会导致 Agent 直接 500很多非 Agent 项目的朋友可能会问少一个参数最多就是功能不完整为什么直接 500这其实是 Agent 类服务和普通 CRUD 接口的一个显著差异。我拆开讲。3.1 参数在入口校验层被拦截属于预期内的“快速失败”第一种情况你的服务在入口做了严格的参数校验比如Valid注解、Spring 的 MethodArgumentNotValidException、或者自研的校验器。这时候少传一个必填参数框架会直接抛异常然后全局异常处理器把它转换成 500。这种情况严格来说不算 bug属于保护机制生效。但问题在于如果日志里没有把“哪个参数缺失”这个信息打出来你就会看到一个干巴巴的 500甚至一句ParameterValidationException根本不知道是谁漏了。我们这次遇到的情况虽然不是校验器拦截但排查时一度也怀疑过这条路径。在 Agent 项目里必填参数尤其多agentId、userId、tenantId、sessionId、requestId每个都可能直接决定后面的会话恢复、模型路由、权限校验能否执行。你少传一个tenantId多租户隔离立刻失效要么报错要么串数据都会表现为 500。3.2 空指针和类型转换异常是“第二道雷”很多 Agent 服务的参数并不是简单字符串而是嵌套结构。比如UserContext里有userId、userName、userAttributesSessionContext里有history、metadata。在反序列化和转换过程中一旦某个嵌套节点是 null后续代码几乎必然触发 NPE。这次我们遇到的问题就是这个类型。除此之外还有可能出现ClassCastException——比如某个字段在入口是 String转换后变成 Integer下游用Integer去接结果类型不符直接抛异常。这类异常的共同特点是堆栈会指向业务代码深处的某一行看起来非常像业务逻辑 bug实际上罪魁祸首在入口参数转换。这也是为什么排障时要往上游多想一步。3.3 Agent 编排层对参数的强依赖放大了“缺失”的影响Agent 项目和普通接口最大的不同在于它有一个“编排层”。编排层要做的事情包括从sessionId恢复历史消息根据tenantId确定模型路由策略和知识库配置用userId拉取用户偏好、权限范围把上述信息组装成完整的 system prompt任何一个参数缺失编排层的状态初始化就会失败。更麻烦的是编排层往往是异步执行的主线程已经把响应返回给客户端了异步任务里抛的异常很难和原始请求关联起来。你以为是“请求成功”实际上后台已经有一堆错误在刷日志。我们这次虽然 NPE 是在同步链路抛的但排查时也必须考虑异步分支的可能——因为你不知道 Agent 服务是同步返回还是先返回任务 ID 再回调。链路越长参数缺失的影响就越容易被放大这是 Agent 排障的头号难点。3.4 日志没打全为什么会让排查“绕远路”最后说回日志。访问日志是排障的第一现场尤其是 Agent 这种长链路服务。如果你入口日志只打了路径和状态码没有把关键参数打全那等于案发现场被人清理过——你知道出事了但看不到现场。这次排查三轮回过头来真正耽误时间的就是入口日志缺了userContext字段。如果我们一开始就能在日志里看到完整的参数结构直接就能发现转换代码的 key 拼错根本不用去查下游。日志打参数这件事看似是一个“加字段”的小改动实际上决定了故障排查的效率上限。别嫌日志打得多——在 Agent 项目里你永远不知道哪个参数会在什么时候消失。4. 我们最后是怎么修的不只是补一个参数定位到根因之后修复本身不难但我不建议只改那一行拼错的 key。既然这个问题暴露出了三个隐患——参数转换容错差、入口日志字段不全、错误信息不可见——那我们就把它们一次都修掉。4.1 修复一修正参数转换逻辑补上容错最直接的改法就是把 key 修正同时做一个兼容处理dto.setUserContext(parseUserContext(firstNonNull(map.get(userContext), map.get(user_context))));这样即使两种命名方式都存在也能正确取值。但这里我要多说一句这种 Map 拷贝的写法本身就很脆弱。它依赖调用方严格遵守字段命名一旦哪边拼写不一致就出隐蔽 bug。更好的方案是直接用 DTO 接收请求体让框架帮你完成反序列化而不是手写 Map 取值。我们后续把入口服务改成了强类型 DTO 接收这类问题从根上消失了一半。4.2 修复二把入口日志补完整建立日志模板规范这是这次复盘里我认为最有价值的改动。我们把入口访问日志改成了标准的 JSON 结构所有关键参数必打不允许因为“字段太多影响性能”把参数截掉。现在我们的入口日志大概长这样{ timestamp: 2025-06-12T14:23:10.128Z, trace_id: 8f3a2c9e1b7d4a6f, request_path: /v1/agent/chat, agent_id: agent_intent_v3, user_id: user_9981, tenant_id: tenant_abc, session_id: session_20250612_001, message_len: 42, http_status: 200, cost_ms: 1280 }注意几个细节user_id和tenant_id单独打出来而不是塞在一个嵌套对象里message_len记录消息长度而不是消息原文避免敏感信息落盘trace_id贯穿所有日志这是后面排查的基础。这套规范上线后同类参数问题基本能在 5 分钟内定位。4.3 修复三入口加参数校验让错误更早暴露与其等 NPE 在业务代码深处炸开不如在入口就把缺失参数拦下来。我们加了一个简单的校验过滤器检查必填参数private static final SetString REQUIRED_FIELDS Set.of(agentId, userId, tenantId); if (!REQUIRED_FIELDS.stream().allMatch(f - requestMap.containsKey(f))) { throw new InvalidParameterException(missing required fields); }这样做的价值在于错误发生在入口而不是业务深处。入口的日志会明确告诉你缺了哪个字段而不是让你对着业务层的 NPE 猜。这次如果一开始就有这道校验userContext缺失会在入口直接曝出来而不是绕到SessionContextBuilder才炸。4.4 修复四用 trace_id 把全链路串起来Agent 服务的调用链里往往有多个服务如果每个服务的日志彼此孤立排查起来会非常吃力。我们这次幸好还有一个简陋的请求 ID否则连“对比正常/异常请求”这一步都难做。修复后我们把 trace_id 从入口生成透传到所有下游服务每个日志行都带上这个 ID。这样一来一次用户请求从入口到模型网关、从用户服务到记忆服务所有日志都能按 trace_id 拉出来排障效率直接上一个台阶。5. Agent 类项目排查 500 的通用套路这次排障踩了不少坑我把沉淀下来的通用排查套路整理出来。以后再做 Agent 项目遇到“第一句就 500”这种情况不用慌按这个顺序查。5.1 先分锅入口层 / 编排层 / 模型层 / 工具层Agent 服务可以抽象成四个层次入口层HTTP 接口、参数解析、鉴权、转发编排层会话管理、上下文组装、模型选择、工具调度模型层大模型接口、prompt 组装、流式响应工具层业务工具函数、外部 API 调用、知识库检索遇到 500第一步就是判断发生在哪一层。方法很简单看堆栈的最外层是哪个模块。如果堆栈在入口层基本就是参数问题如果在编排层多半是上下文或状态问题如果在模型层优先看 prompt 和超时如果在工具层看具体工具的执行异常。Agent 项目里 80% 的“第一句 500”都发生在入口层和编排层。因为第一句还没有历史上下文模型层和工具层大概率尚未触发。搞清楚这一点能帮你节省很多时间。5.2 日志必须带的关键参数清单我整理了一份 Agent 项目入口日志必备参数清单直接抄就行参数说明缺失时的典型表现trace_id全链路追踪 ID无法关联下游日志agent_idAgent 配置标识模型路由失败user_id用户标识用户上下文 NPEtenant_id租户标识多租户隔离失败session_id会话标识无法恢复历史消息request_id请求唯一 ID无法对账重试message_len消息长度无法判断超限问题http_status响应状态码无法做质量监控注意日志里不建议打完整消息内容。一是可能包含敏感信息二是消息太长会撑爆日志存储。用message_len代替既满足排查需要又规避隐私风险。5.3 复现技巧用最小请求体做二分定位当你不确定是不是参数问题时我建议直接构造一个最小请求体来复现curl -X POST https://your-agent-service/v1/agent/chat \ -H Content-Type: application/json \ -d { agentId: test_agent, userId: test_user, message: hello }先用最少的参数试如果 500说明必填参数本身就缺如果成功再逐步补上业务字段直到复现 500最后一个加上去的字段基本就是罪魁祸首。这个办法虽然土但在参数类问题上比看代码高效得多。我们这次如果一开始就用最小请求体 逐步加参数的方式可能两轮就能定位到userContext不用绕到第三轮。5.4 踩坑总结Agent 项目特有的排障难点最后写几个 Agent 项目特有的坑这些是普通 Web 项目不会遇到的异步任务掩盖异常编排层的异步分支异常不会直接反映在 HTTP 响应里必须靠 trace_id 捞日志。模型层超时与重试LLM 接口经常超时超时后框架自动重试重试成功可能让你忽略真正的参数错误。工具调用链过长一次 Agent 请求可能调用多个工具某个工具内部吞掉了异常只向上返回一个 false500 的根源就被藏得更深。流式响应的“假成功”WebSocket 和 SSE 场景下连接建立成功不代表后续全对要注意区分“连接 500”和“消息内容 500”。我个人的体会是Agent 项目排障说到底是拼日志和拼链路。Agent 本身不复杂复杂的是它把所有环节串在一起任何一个细小的参数问题都会在长链条里被放大成 500。入口日志少打一个参数看起来是小事但它会让你在最需要线索的时候失去线索。打完这次仗我们团队定了一个规矩任何 Agent 服务的入口改动必须同步评估日志字段是否完整。这个习惯建议大家也养起来。