AI Agent 与 Java 生态

• 各框架的定位与核心能力
• 功能取舍与模型/工具/记忆抽象
• 生态成熟度与选型依据

Java 端 Agent 框架主要包括 Spring AI（含 Spring AI Alibaba）、LangChain4j 与 Agents-Flex。Spring AI Alibaba 是围绕 Spring AI 的国产化/阿里云集成版本，深度融入 Spring 生态，提供模型、工具、记忆与向量库抽象，适合已有 Spring 体系的应用。LangChain4j 是参考 LangChain 思想的 Java 实现，功能较全，提供模型、聊天、记忆、RAG、工具调用等抽象，社区活跃、模型覆盖广。Agents-Flex 是国内轻量级 Agent 框架，主打简单、易集成，功能相对精简。功能取舍上：Spring AI 胜在 Spring 整合与标准化；LangChain4j 胜在功能广度与社区；Agents-Flex 胜在轻量与上手快。生态成熟度上，LangChain4j 与 Spring AI 更成熟，Agents-Flex 相对年轻。选型应结合团队技术栈、模型支持范围与维护成本。

Agent 框架选型的关键是"整合度、功能广度、生态成熟度"的权衡：Spring 生态优先选 Spring AI，功能与社区优先选 LangChain4j，轻量场景可考虑 Agents-Flex。

• 与 Spring 生态的整合度
• 模型/工具/记忆抽象的成熟度
• 选型决策依据

Spring AI 与 Spring 生态整合度高，作为 Spring 官方项目，天然支持 Spring Boot 自动配置、依赖注入、Starter 机制，与 Spring Boot 4 的 AOT、观测性等协同良好，适合以 Spring 为技术栈的应用。LangChain4j 是独立框架，与 Spring 整合通过扩展模块实现，但功能模块更丰富，模型支持（OpenAI、Anthropic、本地模型等）与工具/记忆/RAG 抽象较为成熟，社区案例多。比较上：整合度方面 Spring AI 占优；功能广度与模型覆盖方面 LangChain4j 更全；记忆抽象两者都有会话记忆与向量记忆，成熟度相当。选型时若团队深度绑定 Spring 生态，优先 Spring AI；若需要更全的模型与功能、或跨框架适用，LangChain4j 更合适。

选型差异的核心是"生态绑定 vs 功能广度"：Spring AI 深度绑定 Spring，LangChain4j 独立且功能更全。结合团队技术栈与模型覆盖需求做决策。

• JSON Schema 生成与工具描述
• 参数校验与工具执行
• 结果回填与错误恢复

服务端实现 Function Calling 的核心是将 Java 方法转为模型可调用的工具描述。工程要点包括：1) JSON Schema 生成——将方法签名（参数名、类型、必填、描述）转换为 JSON Schema，供模型理解工具并能生成符合格式的参数；2) 参数校验——模型可能生成非法参数，执行前需校验（类型、范围、必填），并优雅处理解析失败；3) 工具执行——通过反射或注册表调用对应 Java 方法；4) 结果回填——将工具执行结果以模型可读的格式回填到对话，作为下一轮上下文；5) 错误恢复——工具执行失败时返回错误信息，让模型可调整策略或给出替代方案，同时避免无限循环（设置最大迭代次数）。还需考虑超时、并发与幂等。

Function Calling 的工程难点在于"模型与 Java 的契约"：JSON Schema 是契约，参数校验是护栏，回填与错误恢复保证多轮交互的稳定。理解这些环节才能实现可靠的工具调用。

• 工具白名单与权限控制
• 敏感操作审批流程
• 参数注入风险与超时熔断

Agent 工具调用引入外部可执行能力，安全治理至关重要。主要包括：1) 工具白名单——只暴露必要且受控的工具，未注册的工具不可被调用，从源头限制模型能力；2) 敏感操作审批——对写操作、删除、支付、外发等高危工具，采用人工审批或二次确认，避免模型越权执行；3) 参数注入——模型可能生成恶意或越界参数（如路径穿越、SQL 注入、命令注入），需对参数做校验、白名单匹配与转义；4) 超时熔断——为每次工具调用设置超时与重试上限，工具异常时熔断降级，防止模型触发长任务或故障工具拖垮服务。此外还需审计日志、调用配额与 RBAC 权限模型。

工具调用的安全本质是"给模型能力但不能失控"：白名单控制能力面、审批控制高危操作、参数校验防注入、超时熔断防拖垮。四者结合形成纵深防御。

• 虚拟线程在工具调用链中的价值
• StructuredTaskScope 的编排能力
• 与 CompletableFuture 的对比

Agent 工具调用链常需并行调用多个工具（如并行检索、并行查询多个数据源）再聚合结果。虚拟线程让每个工具调用可以独立线程/虚拟线程执行，无需维护线程池，阻塞 IO 时自动让渡载体线程，代码以同步顺序写法表达，可读性高。StructuredTaskScope 提供结构化并发：并行派生多个工具调用任务，join 统一等待，任一失败可取消其余任务，避免任务泄漏与悬空。相比 CompletableFuture 的链式 thenCompose、handle 等复杂回调与异常传播，虚拟线程 + StructuredTaskScope 让并发工具调用更直观、更易维护、更易取消。工程价值在于降低并发编排的复杂度与出错率。

虚拟线程 + 结构化并发将"并发编排"从回调式变为同步式，工具调用链的并行、聚合、取消都更清晰。这是它替代 CompletableFuture 复杂性的核心价值。

• FFM API 的能力
• 安全沙箱与原生交互
• 在 MCP Server/Tool Runtime 中的应用

FFM（Foreign Function & Memory API）允许 Java 安全地调用原生函数、访问原生内存，替代了高风险且易崩溃的 Unsafe 与部分 JNI。在 Agent 沙箱与 MCP Server、Tool Runtime 中，FFM 可用于：1) 执行需要原生能力的工具（如调用系统库、加密库、高性能计算库）；2) 管理受限的堆外内存，避免 GC 压力；3) 与原生插件/协议栈交互。安全方面，FFM 提供受限的方法句柄与内存访问控制，可结合沙箱限制工具可访问的原生符号与内存范围，降低越权风险。与 JNI 相比，FFM 更安全（类型安全、可管理生命周期）、更易用，且无需写 C 代码。工程价值在于让 Agent 工具安全地扩展原生能力，同时保持可控。

FFM 的价值是"安全地做原生交互"：替代 Unsafe/JNI 的脆弱点，提供类型安全与生命周期管理。在 Agent 沙箱中它既扩展能力又提供控制边界。

• 会话记忆的存储与组织
• 多轮工具调用的幂等设计
• 超时重试策略

Agent 应用的会话记忆需要持久化会话上下文（对话历史、工具结果、用户状态），常用方案包括内存 Map、Redis 或数据库，并需控制上下文长度（裁剪/摘要）。多轮工具调用的幂等设计：同一工具调用可能被重试或重复执行，需为工具调用生成唯一调用 ID，服务端对幂等 key 去重，写操作（发消息、扣减）需支持幂等。超时重试策略：为单次工具调用与整体多轮循环设置超时，重试需带退避（exponential backoff）与最大次数，并对"请求失败"与"结果失败"区分处理，避免无限重试耗尽资源。状态管理中需考虑并发写、会话隔离与清理过期会话。

Agent 状态管理的关键是"可恢复、可幂等、有界"：会话记忆持久化保证可恢复，幂等保证重试安全，超时重试有界避免失控。这是 Agent 可靠运行的基础。

• MCP SDK 的选型
• 工具注册与协议对接
• 并发模型取舍（虚拟线程 vs 阻塞 IO）

MCP（Model Context Protocol）是模型与工具/资源交互的开放协议。Java 侧接入 MCP 可选择官方/社区 MCP Java SDK（如 io.modelcontextprotocol.sdk），或通过 Spring AI 等框架的 MCP 集成。工具注册方面，将 Java 方法注册为 MCP 工具（描述、参数 Schema），通过 tools/list、tools/call 协议暴露给模型端。并发模型取舍：MCP Server 常需处理多个并发工具调用，虚拟线程适合"每工具调用一个虚拟线程"的阻塞式编程，简单直观且可承载大量并发；而阻塞 IO 若用平台线程池则线程数受限。对高并发工具调用，推荐虚拟线程 + 阻塞式工具实现，配合结构化并发编排；对需要精细背压与流式控制的场景，可考虑响应式。取舍依据是"并发规模、工具是否阻塞、与现有技术栈的匹配"。

MCP 接入的核心是"协议对接 + 并发承载"：SDK 抽象协议，工具注册映射能力，虚拟线程提供高并发低成本的阻塞式模型。理解并发模型取舍是服务端 MCP 的关键。

• ChatClient 的调用方式
• 工具注册（@Tool 注解）
• 工具调用链的编排

Spring AI 的 ChatClient 提供统一对话 API，支持同步/流式调用。Tool Calling 通过 @Tool 注解将 Java 方法注册为工具，模型在生成时可按需调用工具。ChatClient 支持 .tools() 指定可用的工具 Bean/方法，运行时会将其转为工具描述发送给模型，模型返回工具调用请求，Spring AI 执行对应方法并把结果回填，形成"模型→工具→回填→再生成"的调用链。调用链可配合 Advisors 做记忆注入、日志与拦截，也可通过虚拟线程与结构化并发编排多个工具调用。工程上需注册工具描述、处理工具异常、控制工具数量与调用轮次。

Spring AI 的工具调用链是"声明式注册 + 自动执行回填"：@Tool 声明、ChatClient 编排、框架执行与回填。理解这一闭环是使用 Spring AI 构建 Agent 的基础。

• ReAct 模式（思考-行动-观察循环）
• Plan-and-Execute 模式（先规划再执行）
• 在 Java 侧的实现方式

ReAct 模式让模型交替进行"思考（Reasoning）→ 行动（Action，调用工具）→ 观察（Observation，结果）"循环，直到得到答案。在 Java 侧可通过循环调用 ChatClient：让模型输出是否要调用工具、选用哪个工具及参数，执行工具后把结果作为观察回填，继续下一轮，并设置最大轮次防止死循环。Plan-and-Execute 则先让模型生成一个执行计划（多个步骤），再逐步执行每个步骤（可调用工具），按计划推进。Java 侧实现可定义 Plan 数据结构（步骤列表）、执行器（逐步骤执行并收集结果）与重规划逻辑。落地时需抽象"模型调用 + 工具执行 + 状态维护"的通用循环，并配合结构化并发提升并行度。选择上，ReAct 更灵活但轮次多，Plan-and-Execute 更可控但需要规划能力。

编排模式的核心是"模型如何决定行动序列"：ReAct 是逐轮决策，Plan-and-Execute 是先行规划。Java 侧落地重点是封装通用循环与状态，并设置轮次与容错边界。

• 文档加载与切分策略
• Embedding 生成与向量存储
• 向量检索与重排序

RAG（检索增强生成）管线包括：1) 文档切分——将文档按语义/段落切分成 Chunk，避免过大或过小，Chunk 需保留上下文边界（如标题、元数据）；2) Embedding——将 Chunk 文本转为向量，Java 侧可调用 Embedding API 或本地模型，Spring AI 提供 EmbeddingModel 抽象；3) 向量存储——把向量存入向量数据库（PGVector、Milvus、Redis、Elasticsearch 等），Spring AI 的 VectorStore 抽象统一了存取；4) 向量检索——按用户问题向量做相似度检索，取 Top-k；5) 重排序——对检索结果用重排序模型/规则（如 RRF、RRF 融合、交叉编码器）重新排序，提升相关性；6) 生成——将检索结果注入 Prompt 交给 LLM 生成答案。工程上需处理 Chunk 大小与重叠、向量索引、检索阈值与缓存。

RAG 是将"知识注入"LLM 的方式，管线质量决定回答质量：切分影响召回、Embedding 影响相似度、重排序提升相关性。各环节需结合检索效果迭代调优。

• MCP 协议的核心方法
• 工具与资源的抽象
• Java SDK 实现要点

MCP（Model Context Protocol）基于 JSON-RPC，核心方法包括：initialize（客户端与服务端握手，协商协议版本与能力）、tools/list（列出可用工具）、tools/call（调用工具）、resources/list/resources/read（列出与读取资源）、prompts/get（获取提示词模板）等。双向通信还支持通知（notifications）。Java SDK 实现要点：实现 Transport（stdio/HTTP/SSE）与 JSON-RPC 消息编解码；提供服务端/客户端抽象，将工具注册为 CallTool 处理器；管理会话与并发（虚拟线程承载工具调用）；处理错误与超时。实现时需注意协议版本协商、消息 id 关联、以及流式/分页的规范。

MCP 是"标准化的工具/资源协议"，核心是 initialize 协商与 tools/call 执行。Java SDK 实现要点是传输层、消息层与工具注册层的解耦，以及并发与错误处理。

• OpenAI 兼容协议适配
• 流式 SSE 的解析与处理
• 鉴权与安全

多数国产大模型（如通义、文心、智谱、DeepSeek 等）提供 OpenAI 兼容的 REST API，Java 侧可用 Spring AI 的 OpenAI 兼容客户端或直接调用 HTTP。适配要点：构造符合 OpenAI 格式的 /chat/completions 请求（messages、model、参数），解析响应格式。流式 SSE（Server-Sent Events）处理：请求开启 stream: true，响应为 data: 分块事件，逐块解析 delta.content 增量内容，Java 侧用 WebClient/SseEmitter/响应式流消费，实时推送并处理 [DONE] 结束标记。鉴权：通过 Authorization: Bearer <key> 传递密钥，密钥应存于配置中心/环境变量而非硬编码；私有化部署常需内网出口、加密传输（TLS）与 IP 白名单。工程细节还包括超时、重试、token 计费与错误码映射。

国产大模型接入的关键是"协议兼容 + 流式解析 + 鉴权安全"：OpenAI 兼容协议降低适配成本，SSE 流式优化体验，鉴权与传输安全保障合规。理解这些细节是稳定接入的前提。

• 记忆抽象的实现差异
• RAG 支持的成熟度
• 多模型切换的灵活性

记忆方面，两者都提供会话记忆（对话历史）与向量记忆（长期记忆），LangChain4j 的 ChatMemory 抽象成熟、策略多（token 窗口、摘要），Spring AI 的 ChatMemory 与 Message 体系也较完整。RAG 方面，LangChain4j 的 RAG 组件（切分、Embedding、检索、重排序）更系统、功能更全，Spring AI 的 VectorStore 抽象统一但组件相对精简。多模型切换方面，两者都支持多模型，Spring AI 通过统一的 ChatModel 接口与自动配置切换，与 Spring 集成更顺滑；LangChain4j 通过 ChatLanguageModel 抽象覆盖更多模型 Provider。差异本质：LangChain4j 功能深度与灵活性略优，Spring AI 与 Spring 生态整合与配置体验更优。选型结合团队技术栈与对 RAG 深度需求。

选型差异根植于"深度 vs 整合"：LangChain4j 在记忆/RAG/多模型的功能深度上更全，Spring AI 在 Spring 整合与配置上更优。按项目需求权衡。

• 会话记忆（短期记忆）的实现
• 向量库（长期语义记忆）
• 结构化存储（业务状态）的取舍

Agent 记忆可分为三类。会话记忆（短期记忆）：对话历史，按时间顺序存储，可用内存 Map 或 Redis，需控制长度（裁剪/摘要/摘要压缩）。向量库记忆（长期语义记忆）：将历史对话/知识转向量存储，检索相关记忆注入上下文，适合"跨会话回忆"与个性化，用向量数据库实现。结构化存储（业务状态）：用户的偏好、订单、任务状态等结构化数据，用数据库/缓存存储，按需查询。取舍上：会话记忆轻量但易失，向量记忆适合语义检索但需 Embedding 与索引成本，结构化存储适合精确状态但需 Schema 设计。实际 Agent 常组合三者：会话记忆保上下文、向量记忆做长期回忆、结构化存储记录业务状态。

Agent 记忆的取舍是"时效、语义、精确"的权衡：会话记忆即时、向量记忆语义、结构化存储精确。按记忆的用途分层设计，是 Agent 状态管理的关键。

• 流式生成的实现（SSE）
• 工具调用（Function Calling）
• 框架抽象与使用

Spring AI 与 LangChain4j 都提供流式与工具调用能力。流式方面，Spring AI 通过 ChatClient.stream() 返回 Flux<String>，LangChain4j 通过 StreamingChatLanguageModel 回传 TokenStream，都基于底层 SSE 流式解析，支持逐 token 推送。工具调用方面，Spring AI 用 @Tool 注解注册 Java 方法，ChatClient 自动执行模型请求的工具并回填；LangChain4j 用 @Tool 注解或 ToolSpecification 注册，ChatLanguageModel 支持工具调用。两者都处理工具描述（JSON Schema）、参数解析、结果回填与多轮工具循环。差异在 API 风格与 Spring 集成度。工程上需处理流式错误、中断、工具调用轮次限制与 token 计算。

两者的流式与工具调用能力高度相似，差异在抽象风格与生态整合。理解"SSE 流式 + 工具描述/执行/回填"的通用机制，可跨框架迁移。

• 工具调用权限校验
• 沙箱隔离机制
• 越权与资源限制

Java Agent 的安全边界分为权限校准与沙箱隔离。权限校验：对每个工具调用做基于用户的授权（RBAC/ABAC），检查调用者是否有权调用该工具、操作该资源；敏感操作需审批与审计。沙箱隔离：将工具执行隔离在受限环境，可限制可执行命令白名单、文件系统访问范围、网络访问、内存/CPU 配额；Java 侧可用 SecurityManager（已弃用）或更现代的容器/进程级隔离、java.lang 限制、Seccomp（容器）、或 FFM 的内存访问控制。对高风险工具（任意命令、文件写、网络外发），应运行在独立进程/容器沙箱中，并对输出做脱敏。还需防止工具调用无限循环、资源耗尽与数据泄露。

Agent 安全边界的本质是"最小权限 + 纵深隔离"：权限校验控制"谁能做什么"，沙箱隔离控制"执行环境的边界"。两者结合才能安全地暴露工具能力。

• 会话级 trace 与链路追踪
• 工具调用成功率指标
• 成本归因与计费

Agent 的可观测需覆盖会话级 trace：将一次 Agent 会话（含多轮模型调用与工具调用）作为一条完整链路，记录每个模型的输入输出、每个工具的调用参数与结果、耗时与 token 消耗，便于定位问题与复盘。可用 OpenTelemetry 的 span 关联日志与指标。工具调用成功率：统计工具调用次数、成功/失败/超时、错误类型，作为质量指标，发现工具定义或执行问题。成本归因：按模型、按会话、按租户/用户归因 token 消耗与费用，支持预算控制与降级模型。工程上需打通 traceId 贯穿模型调用与工具调用，统一 metrics 与 Dashboard，并做采样治理控制存储成本。

Agent 可观测的核心是"端到端可追踪 + 质量可量化 + 成本可归因"：trace 定位问题、成功率衡量质量、成本归因控制支出。这是 Agent 从演示到生产的关键。

• 多模型路由策略
• token 预算控制
• 降级模型与熔断

多模型路由是根据任务复杂度、成本、延迟、质量需求，将请求路由到不同模型（如复杂推理用大模型、简单任务用小模型、本地模型做兜底）。路由策略可基于 prompt 类型、预估困难度、用户等级或历史效果。成本控制包括：token 预算——为会话/用户/租户设置 token 上限，超限降级或截断；用量监控——按模型统计 token 与费用；降级模型——主模型超时/失败/超预算时自动降级到更便宜或更快的模型，保证可用性。工程上还需缓存常用响应、压缩上下文、控制工具调用轮次以节省 token。目标是"在质量与成本间平衡"。

多模型路由与成本控制是 Agent 划算运行的关键：路由按需选模型，token 预算防超支，降级模型保可用。工程核心是"成本可计量、可限制、可降级"。