Java Agent 想上线，至少先补这份检查清单：超时、重试、日志、兜底

weixin_51864284

348人浏览 · 2026-04-15 14:30:00

weixin_51864284 · 2026-04-15 14:30:00 发布

做 Java Agent 最危险的阶段，不是完全没跑起来，而是“本地已经能演示了”。

因为一旦能演示，团队就会很容易说：

“差不多了，可以往线上推了。”

但 Agent 这类系统和普通 CRUD 不太一样。它看起来只是一个 /chat 接口，实际上后面经常连着：

模型调用
Prompt 模板
Tool Calling
Chat Memory
MCP
外部服务
日志和观测链路

这些东西只要少补一层，上线以后就很容易出那种最难处理的问题：

不是完全挂
但时好时坏
还很难复现

所以这篇不讲新能力，只给一份我认为上线前至少要过一遍的检查清单。

1. 先确认模型能力，不要拿不支持的模型硬上 Tool Calling

Spring AI 官方文档有 Chat Models Comparison 表，其中专门有一列 Tools/Function Calling。

这一步必须先确认。因为如果模型本身不支持 Tool Calling：

你后面所有工具链都只是摆设
项目会退回普通聊天
很多“工具怎么没触发”的问题会变成无意义排查

上线前最起码要把你最终用的模型能力写清楚，而不是只在本地某个模型上跑过。

2. Prompt 不要糊成一段大字符串

Spring AI 官方文档已经把 Prompt 设计成 message 集合，也支持模板变量和 TemplateRenderer。

所以上线前要过一遍：

system 和 user 是否拆开了
运行时上下文是否参数化
JSON 和 {} 占位符是否冲突
该不该改模板分隔符

这一步不补，越到后面越容易出现“线上偶发脏输出”，而你很难判断到底是模型问题还是 prompt 结构问题。

3. 记忆要分清 memory 还是 history

Spring AI 官方文档明确说：

ChatMemory 不是完整聊天历史
默认 ChatMemory 不是最佳历史归档位置

这意味着上线前你必须回答两个问题：

你只是要上下文连续，还是要保留完整聊天记录？
你准备怎么区分这两种存储目标？

这件事不讲清楚，后面合规、追踪、问题复盘都会很难做。

4. 默认内存记忆能跑，但不等于适合线上

Spring AI 官方文档写得很明确：

默认 repository 是 InMemoryChatMemoryRepository
默认 memory 是 MessageWindowChatMemory
默认窗口大小是 20 条消息

所以你上线前最好别再假装默认值就是最终方案。

至少要确认：

会不会跨重启丢失
多实例下会不会失忆
20 条窗口够不够
会不会因为窗口裁剪导致上下文漂移

如果这些问题还没想清楚，就别把“本地能聊两轮”当成可上线。

5. Tool Calling 的工具定义要像人话，不要像内部方法名

Spring AI Tool Calling 文档里反复强调：

工具名要唯一
工具描述要清楚
输入 schema 要让模型看得懂

上线前至少过一遍：

有没有一堆 query、execute、process 这种没语义的工具名
@Tool(description = "...") 是否足够具体
输入输出是不是简单、可序列化、稳定

很多线上“不稳定”，本质上是模型面对一堆描述模糊的工具时选择开始漂。

6. 工具签名不要超出 Spring AI 支持边界

官方文档对工具类型限制写得很明确。

方法工具不支持：

Optional
CompletableFuture / Future
Mono / Flux

函数工具还不支持 primitive 和集合类型作为输入输出。

这类限制上线前必须查一遍。因为很多 Java 团队平时写业务代码太顺手，工具层一不小心就把响应式或异步类型带进去了。

这不是“风格问题”，这是能不能稳跑的问题。

7. MCP 上线前要确认 transport、client 类型、工具名冲突

如果你的 Agent 已经接入 MCP，那上线前至少要查这几件事：

transport 到底是 STDIO、SSE 还是 Streamable-HTTP
client 是 SYNC 还是 ASYNC
MCP tools 是否真的暴露为 ToolCallbackProvider
多 server 时工具名是否冲突或被改名

Spring AI MCP 文档已经把这些点都写出来了。别等上线后才发现模型调错工具，或者启动期就因为某个 MCP 服务不可用把应用拖慢。

8. 至少把日志和 observability 补上

这一步是硬要求，不是“有空再说”。

Spring AI 官方文档里已经给了两套抓手：

SimpleLoggerAdvisor
Observability + Actuator

其中 Observability 文档还明确说明：

ChatClient
Advisor
ChatModel
Tool Calling

都有对应的 observations。

上线前至少要有下面这几样：

本地 / 测试环境能打开 request / response 日志
生产环境有基础指标和 trace
能看到 tool call 和 advisor 链的关键行为

否则出了问题你只能靠最终文本猜。

9. prompt / completion 默认不记录，开之前先做敏感信息评估

这个点官方文档也写得很明确：

prompt / completion 默认不导出
开启日志和 observability 时要注意敏感信息风险

这一步很多团队要么完全不开，导致根本没法排障；要么一股脑全开，结果把敏感数据全打进日志。

正确做法不是二选一，而是上线前先明确：

哪些环境能看完整 prompt
哪些字段必须脱敏
哪些工具结果不能直接落日志

10. 超时、重试、兜底别只靠模型自己“稳”

这里我分成两层说。

第一层，Spring AI 官方文档已经给到一些很明确的基础能力：

MCP client 有 request-timeout
Observability 能帮你看延迟和调用分布
ToolCalling、Advisor、ChatModel 都能被观测

第二层，这里是我的工程建议：

外部工具调用要有超时
幂等工具要有重试策略
非幂等工具要有兜底与熔断思路
模型回答失败时，要有可接受的 fallback

这些不一定都由 Spring AI 本身提供一键开关，但它们必须在你的上线方案里有位置。

如果没有，线上一旦慢、抖、偶发失败，你会发现 Agent 没法像普通接口那样优雅退化。

11. 会话 ID 和多用户边界要提前定死

很多 Agent 上线之后最尴尬的问题不是模型错答，而是“串台”。

Spring AI Advisors 文档里给了很明确的 conversationId 传参方式。上线前要定清楚：

会话 ID 怎么生成
同一用户多窗口怎么区分
接口重试时会不会误串到旧会话

这一步别留给前端和后端上线前最后一天“再对一下”。

12. 上线前至少做一次完整链路演练

我说的完整链路，不是“让模型回答一个你好”，而是最少跑一条真正的 Agent 路径：

带 system prompt
带运行时变量
带 memory
带 tool call
如果有 MCP，就带 MCP
全链路带日志和观测

你不跑这条链，很多问题永远在单点测试里看不出来。

最后给一份上线速查版

模型是否支持你需要的 Tool Calling 能力？
Prompt 是否已经结构化，而不是糊成大字符串？
模板变量、JSON、渲染器规则是否一致？
memory 和 history 的边界是否清楚？
默认内存实现是否已经替换成合适的线上方案？
conversationId 策略是否确定？
工具描述和 schema 是否清晰？
工具方法类型是否在 Spring AI 支持范围内？
MCP transport / type / naming 是否核对过？
日志、Actuator、observability 是否已经补齐？
prompt / completion 日志的敏感信息风险是否评估过？
外部工具的超时、重试、兜底是否已经设计？

结尾

Java Agent 想上线，最怕的不是功能少，而是“每一层都只做了一半”。因为只做一半的系统，本地看着像能跑，线上一抖就开始露底。

到这里，这一轮 8 篇的第一批系列稿就齐了。你接下来最适合做的事，不是立刻再扩选题，而是先选 2-3 篇发出去，看阅读、收藏和评论反馈，再决定第二轮内容往哪里压。

参考资料

Spring AI Chat Models Comparison: https://docs.spring.io/spring-ai/reference/2.0/api/chat/comparison.html
Spring AI Chat Client API: https://docs.spring.io/spring-ai/reference/api/chatclient.html
Spring AI Prompts Reference: https://docs.spring.io/spring-ai/reference/api/prompt.html
Spring AI Chat Memory Reference: https://docs.spring.io/spring-ai/reference/api/chat-memory.html
Spring AI Tool Calling Reference: https://docs.spring.io/spring-ai/reference/api/tools.html
Spring AI MCP Overview: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html
Spring AI MCP Client Boot Starter: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html
Spring AI Observability: https://docs.spring.io/spring-ai/reference/observability/index.html