Java 21 企业级 AI Agent：受控智能体模式实现可靠可控安全

如果只从标题看，Java 21 和 AI Agent 放在一起，最容易被忽略的是后半句：可靠、可控、安全。这几年 AI Agent 框架非常多，能调模型、能调用工具、能编排任务的项目遍地都是，但真正到了企业环境，第一道门槛根本不是“模型聪明不聪明”，而是“Agent 做完一个动作之后，出了事能不能追回、能不能解释、能不能限制住”。受控智能体模式要解决的，就是这个控制面问题。这篇文章围绕 Java 21 企业级 AI Agent 平台展开，重点讲清楚受控智能体模式在企业落地时的设计思路、实现步骤、验收标准，以及最容易踩坑的几个地方。不管你是准备在项目里引入 Agent，还是正在研究这类平台的设计，都值得顺着这套思路过一遍。

1. 受控智能体模式到底是什么，先拆开看

1.1 能跑任务的 Agent 和能上生产的 Agent，差在控制面

开发 Agent 的第一阶段，所有人关注的都是“它能不能把事做完”。给模型一个目标，注册几个工具，再配一份提示词，看起来就能自动跑任务了。这个阶段的问题通常也很集中：模型偶尔抽风、工具参数传错、输出格式不稳定。

但企业环境里的 Agent 平台，关注的不是单次任务能不能成功，而是连续 1000 次任务里有没有一次越权行为。比如：

• Agent 是否调用了不在授权范围内的工具
• 是否读取了当前用户没有权限看到的数据
• 是否执行了删除、发送、下单、转账这类高风险动作
• 是否在无人知晓的情况下完成了不可逆操作
• 每一步动作是否都可以回溯

这些问题不是模型能力能解决的。模型只负责“下一步该做什么”，至于“这一步允不允许做、做了之后怎么留痕、出问题之后怎么终止”，必须由平台层来控制。受控智能体模式的核心，就是把控制面作为独立设计，而不是让 Agent 自由发挥。

1.2 控制面到底控制哪些东西

我把控制面拆成四个维度，做企业级 Agent 平台时基本绕不开：

工具控制。

Agent 不能“理论上会调用工具”就真的直接调用。平台必须维护一份工具注册表，Agent 只能调用注册过的工具，工具的参数也必须按 Schema 校验。这样即使模型产生幻觉、生成了不存在的工具名，平台也能直接拒绝，而不是跟着错误路径走。

权限控制。

每个 Agent 任务都要有明确的用户身份和资源边界。同一个工具，普通用户只能读，管理员才能写；A 部门的数据，B 部门的 Agent 无权访问。权限控制不是加在提示词里让模型“自觉遵守”，而是在平台层强制拦截。

过程控制。

Agent 执行任务不是一条路走到黑。它应该支持暂停、恢复、取消、人工接管。遇到高风险动作时，任务可以停下来等待审批；审批通过后继续执行，拒绝则终止。整个过程是可干预的，而不是提交之后就完全失去控制。

审计控制。

每一步模型调用、工具调用、参数输入、结果输出、审批人、审批时间、耗时，都要有完整记录。审计不是事后的简单日志，而是可以还原整个决策链路的证据链。

注意：如果只做“能跑”的 Agent，控制面可以后补；但如果做“企业级”Agent 平台，控制面必须前置设计，后补的代价远高于一开始就做好。

2. Java 21 给 Agent 平台带来了什么，不只是新语法

2.1 虚拟线程：Agent 并发调度终于不别扭了

Java 21 作为 LTS 版本，最吸引人的特性之一就是虚拟线程。传统 Java 并发模型里，一个线程对应一个操作系统线程，数量上去之后，上下文切换开销明显。而 Agent 任务恰恰是典型的 IO 密集型任务：调用模型接口要等待网络响应，调用数据库要等待查询结果，遇到审批节点还要长时间等待人工操作。

这些等待场景如果用传统平台线程，要么大量线程被白白占住，要么用异步回调把代码拆得很碎。虚拟线程的特点是“轻量”，可以创建大量虚拟线程来承载阻塞任务，阻塞的时候底层载体线程可以释放出来做其他事。对企业级 Agent 平台来说，这意味着并发任务调度可以用更接近同步编程的方式实现，不用为了并发而牺牲代码可读性。

实际使用中我一般会先做一个压测：同一个 Agent 任务，分别用固定线程池和虚拟线程跑，观察吞吐量、CPU 占用和等待时间。你会发现，在大量等待模型响应和审批的场景里，虚拟线程的收益非常直接。

// Java 21 虚拟线程 - Agent 任务演示 try (var executor = Executors.newVirtualThreadPerTaskExecutor()) { executor.submit(() -> agentService.execute(task)); executor.submit(() -> agentService.execute(task2)); }

2.2 记录类、模式匹配、序列化集合：工具协议更好写了

Agent 平台里最日常的操作是定义工具请求和响应。传统写法是写一堆 getter、setter，或者用 Map 传递参数，类型安全差，后期维护也痛苦。Java 21 把这些基础能力补上来之后，工具协议的定义可以做得更干净。

比如定义一个工具调用请求：

public record ToolCall( String toolName, Map<String, Object> arguments, String traceId, RiskLevel riskLevel ) {}

配合模式匹配，处理不同类型工具时不再需要一堆 if-else 和强制类型转换，代码的意图更清楚。序列化集合则让“维护一个有序、去重的工具列表”这种操作更自然。

这些特性单独看都不算惊天动地，但组合起来，对 Agent 平台这种需要大量协议定义、参数校验、分支处理的系统，确实能明显减少样板代码。

2.3 结构化并发：任务编排的治理思路在靠拢

Java 21 中的结构化并发仍然是预览特性，但它代表的思路非常有价值：并发任务的生命周期应该和代码块的生命周期一致。父任务启动子任务，子任务必须在父任务结束前完成或被取消，这样整个任务链路才有明确的边界。

Agent 任务天然适合这个模型。一个规划任务会拆出多个子任务，比如“查询订单信息”和“查询库存状态”可以并行执行，但父任务在等待所有子任务返回后统一做决策。结构化并发强调的是任务不能泄漏、不能无人认领，这和企业级 Agent 对任务生命周期的要求一致。

不过要注意，预览特性意味着 API 可能变化，生产环境要不要用，需要根据团队的接受度和项目进度单独评估。它带来的更多是设计思路参考，而不是非用不可。

3. 落地受控智能体模式：五个关键设计

3.1 工具注册表：先声明能力，再允许调用

受控智能体模式的第一条规则，是 Agent 只能调用注册表里存在的工具。工具注册表可以看作平台和模型之间的“白名单”。每个工具都要有明确的基本信息。

以下是一个工具注册配置示例：

{ "name": "query_order", "description": "根据订单号查询订单状态", "operationType": "read", "riskLevel": "low", "parametersSchema": { "type": "object", "properties": { "orderId": { "type": "string" } }, "required": ["orderId"] }, "executionMode": "direct", "timeout": 5000, "retryPolicy": "none" }

为什么必须有参数 Schema？因为大模型输出工具调用的参数时，经常出现字段名写错、类型不对、字段缺失。平台在真正执行前先校验一次，不合格的直接返回提示让模型修正，能拦截大量无效调用。

工具注册表不仅是白名单，还承担了“能力可发现”的作用。模型通过工具描述来决定调用哪个工具，因此描述必须准确、简洁，不能写成含糊的营销文案，也不能把两个工具的能力写得互相重叠。

3.2 分级放行与人工审批流

工具注册表里定义了风险等级，运行时就必须按等级执行不同的放行策略。

• low（只读）：自动执行，但记录日志。
• medium（受限写）：执行前需要确认，可以由用户在页面上点击确认，也可以自动放行但写入待确认队列。
• high（重要写）：必须人工审批，审批通过才执行。
• critical（高风险）：人工审批之外，可能还需要双人复核，执行时强制使用独立环境和独立账号。

审批流不能做成穿插在代码里的硬编码，而应该作为平台能力，让每个工具申请时指定自己的风险等级和审批策略。这样新增一个工具时，不需要改审批代码，只要在注册表里配置规则就行。

实际项目里最容易踩的坑是把审批流程从业务系统里剥离。Agent 平台如果只是发一封邮件、等一个回复，很难和现有审批体系打通。合理做法是把审批抽象成统一接口，对接钉钉、飞书、企业微信或者企业内部 OA 系统。否则审批链路人肉维护，Agent 任务一多就会堵塞。

3.3 沙箱执行与资源配额

企业级 Agent 不只会调用接口，还可能出现“生成代码并执行”的场景。这类能力非常强大，但也很危险。受控智能体模式要求这类执行必须放到沙箱里，而不是直接运行在工作机或生产服务器上。

沙箱至少要做到：

• 文件系统隔离：容器只能看到临时目录，不能访问宿主机敏感路径
• 网络限制：默认禁止外联，按需开放
• 资源限制：CPU、内存、磁盘、执行时间上限
• 镜像只读：每次运行使用干净镜像，结束后销毁

在资源配额方面，每个 Agent 任务都应该有独立的预算限制。比如单次任务最多调多少次模型接口、累计消耗多少 token、最长执行多少分钟。这样可以避免模型进入死循环或者被恶意构造的任务拖垮整个平台。

注意：不要一上来就追求“全自动 Agent”。先把沙箱和配额做好，再逐步放开自动执行的范围。全自动的前提是出了问题能兜住，否则就只是把风险从人工转移到了机器人手里。

3.4 审计日志：不是打印几行就完事了

很多团队做审计，就是在执行工具时打一条 log。等到真的出了事故，你会发现信息根本不够：当时用户的身份是什么、任务的完整上下文是什么、模型输出过什么内容、工具入参和出参是什么、有没有经过审批、审批人是谁，全都对不齐。

合规的审计设计应该满足两个要求：

• 可还原：拿到一个 trace_id，能把一次任务的完整链路拉出来。
• 防篡改：审计数据单独存储，普通应用没有删除和修改权限。

每次模型调用和工具调用都应该输出审计事件，内容包括：

{ "traceId": "task-001", "timestamp": "2025-01-01T10:00:00.000Z", "userId": "user-01", "taskType": "order_query", "modelCallId": "model-call-001", "toolCalls": [ { "toolName": "query_order", "arguments": { "orderId": "A1001" }, "result": "success", "riskLevel": "low" } ], "approvalInfo": null }

审计事件不要和业务日志混在一起。业务日志可以随时清理，审计数据需要有独立的生命周期管理，保存周期要能满足企业合规需求。不要用模型名称或生成规则作为敏感标识，日志里也不要携带未脱敏的密钥和凭据。

3.5 人工接管与任务回滚

Agent 不是万无一失的。就算有注册表、审批流、沙箱，还是会出现模型判断错误、工具状态异常、上游接口数据不准等情况。平台必须提供“喊停”能力。

任务状态机至少应该包含：pending、running、waiting_approval、paused、cancelled、completed、failed。

当操作被判定为高风险，或者用户主动暂停，任务应该立即进入可干预状态。Agent 主动执行的动作，如果涉及可逆性差的操作，平台应该支持“撤销”或“补偿”。比如先创建了一个资源，如果后续步骤失败，应该有对应的清理逻辑。这就是幂等设计的意义：同一个任务重复执行，或者执行到一半被终止，数据仍然是一致的。

4. 从零到一：受控 Agent 的实操路径

4.1 环境准备

不管你是想把 Agent 集成到现有 Java 系统，还是从零搭新平台，环境准备先确认这几项：

• JDK 21（LTS 版本），安装后确认JAVA_HOME指向正确
• Maven 或 Gradle，注意 Java 21 对构建工具的版本有要求，Maven 建议 3.9+，Gradle 建议 8.5+
• 一个人可以使用的模型接口，可以是本地模型服务，也可以是云厂商接口，关键是确认网络连通、鉴权配置合法、密钥不要硬编码到代码里
• Redis 或内存队列，用于任务异步化；如果只是本地学习，先用并发集合代替也行
• 一个数据库，用于存任务、工具注册表、审计日志；生产环境建议 PostgreSQL 或 MySQL，本地可以用 H2

环境准备好之后，不要急着写一堆业务代码。先创建一个最简单的工程，引入 Web 框架和 HTTP 客户端，跑通一次模型接口调用。模型接口返回了你才能继续后面的事，连返回都拿不到，后面全是白搭。

java -version # 输出中包含 21 或者 21.0.x 即可确认 JDK 版本

4.2 先跑通一个单 Agent 最小闭环

最小闭环不应该是“完整企业功能”，而是“模型能根据用户指令输出一个可解析的工具调用动作”。流程可以拆成四步：

1. 用户输入问题，比如“帮我查一下 A1001 订单状态”。
2. 平台把问题、可用工具列表、调度提示词一起发给模型。
3. 模型返回一个工具调用结构，比如query_order(orderId="A1001")。
4. 平台解析结构，先不真正执行，把结果打印出来。

这一步的核心是验证模型能不能稳定输出结构化工具调用。我建议用一个小型测试集，至少 20 条覆盖不同表达方式的输入，看模型返回的 JSON 结构有多少次是合法可解析的。如果失败率太高，先调整提示词或者工具描述，而不是急着往下做。

public record ModelResponse(String content, List<ToolCall> toolCalls) {} public record ToolCall(String name, Map<String, Object> arguments) {}

方法调用示例：

public void runMinimalLoop(String userInput) { List<ToolDefinition> tools = toolRegistry.listTools(); ModelResponse resp = modelClient.chat(userInput, tools, systemPrompt); if (resp.toolCalls().isEmpty()) { log.info("模型直接返回答案: {}", resp.content()); return; } for (ToolCall call : resp.toolCalls()) { log.info("模型请求调用工具: {}", call); // 当前阶段不执行，只输出 } }

4.3 把工具调用从“直接执行”改成“受控执行”

最小闭环跑通之后，开始加控制逻辑。核心变化是：模型说“调用工具”不算数，平台校验完再决定是否执行。

受控执行的步骤如下：

• 解析模型返回的ToolCall
• 到注册表查工具是否存在
• 校验参数是否符合 Schema
• 读取当前用户上下文和权限
• 根据风险等级判断自动放行、等待确认还是进入审批
• 如果放行，再决定直接执行还是进入沙箱
• 记录审计日志

这部分最容易出错的是权限和风险等级的判断顺序。我一般先校验工具存在性和参数格式，再查权限，最后才看风险等级。原因是权限查询需要耗时，如果工具本身不存在，就直接短路了，没必要再走权限系统。

在 Java 实现里，可以用一个调度器按顺序处理：

public ExecutionResult executeTool(ToolCall call, UserContext user) { ToolDefinition def = toolRegistry.get(call.name()) .orElseThrow(() -> new ToolNotFoundException("工具未注册: " + call.name())); JsonNode validArgs = schemaValidator.validate(def.parametersSchema(), call.arguments()); SecurityDecision decision = securityPolicy.decide(user, def, validArgs); if (decision.requiresApproval()) { approvalService.submit(call, decision.approver()); return ExecutionResult.pendingApproval(); } if (decision.requiresSandbox()) { return sandboxExecutor.execute(def, validArgs); } return directExecutor.execute(def, validArgs); }

4.4 从单 Agent 到任务队列和批量化

单条任务跑稳之后，再考虑批量。批量任务的核心不是“并发越来越高”，而是“稳定的队列 + 失败重试 + 结果可追踪”。

建议按以下顺序扩展：

• 引入任务表，把每次 Agent 任务持久化，状态字段记录整个生命周期
• 任务提交后不进线程池直接执行，而是先入队
• 消费者从队列里拿任务，执行完写结果，失败写失败原因并决定是否重试
• 每个任务保存 traceId，日志、审计、结果都通过 traceId 关联

并发调度这块，Java 21 的虚拟线程很适合做“每个任务一个虚拟线程”的模型。但要注意，虚拟线程也不是无限创建的，任务量大的时候仍然要看数据库连接池、下游接口吞吐量、模型服务并发上限。虚拟线程解决的是阻塞调度成本，不是下游服务的承载能力。

批量化之后，一定要有失败重试和死信队列概念。一个 Agent 任务失败了，可能是模型接口超时、工具参数错误、审批被拒绝、下游业务异常。不同的失败原因重试策略完全不同：

5. 可靠、可控、安全怎么验收

5.1 成功率：看的不只是 Demo 能不能跑

Agent 平台要定一个明确的“任务成功”标准。对我个人来说，标准不是“模型把答案生成了”，而是“任务的业务目标达成了，且所有中间动作都符合权限和审批要求”。

验收时建议看两个指标：

• 单任务成功率：随机抽取 100 条真实任务，看最终成功完成的比例
• 批量任务兜底率：100 条任务批量提交，有多少条因为超时、报错、重试机制最终被正确归置到终态

如果批量任务跑完，有几十条挂在中间状态，这种系统就不能叫可靠。

5.2 并发：先确认瓶颈在平台还是下游

并发能力验收不是简单压测 Agent 平台本身，而是要看整条链路。你可以用虚拟线程把并发调到很高，但如果模型接口只能同时处理 10 个请求，或者数据库连接池只有 20 个连接，瓶颈根本不在 Agent 平台。

压测建议：

• 先压单机单任务，看响应时间基线
• 再逐步加并发，观察平台线程状态、数据库连接、下游接口耗时
• 出现失败时，先判断是平台资源不够，还是下游服务被压垮
• 加限流和熔断，不能让一个下游服务的抖动拖垮整个平台

虚拟线程带来的好处是提高阻塞容忍度，但你在配置线程池大小的思维要变。Java 21 虚拟线程可以让任务数远超平台线程数，但下游连接池、数据库连接池仍然是共享资源，必须单独做限制。

5.3 审计完整度：随便抽一条任务验证

验收审计系统最简单的方式是：随机抽一个已完成的 Agent 任务，尝试还原完整链路。

要能回答这些问题：

• 谁在什么时间发起了这个任务
• 模型被调用了几次，每次输入输出是什么
• Agent 最终调用了几次工具，每个工具的参数和结果
• 哪些动作经过了审批，审批人是谁，耗时多久
• 任务是否发生过重试、暂停、取消
• 最终结果是什么，是否和业务系统记录一致

如果这些问题里有一个答不上来，审计就是不完整的。不要等到出事才去补，审计在平台上线验收阶段就应该作为硬性指标。

5.4 异常降级：模型挂了、审批超时了怎么办

企业级平台必须有降级预案。模型服务不可用的时候，任务不能无限等待，要么快速失败并通知用户，要么进入重试队列。审批节点超时的时候，要有明确策略：自动拒绝、自动通过只读操作，或者转交备选审批人。

我见过不少 Agent 平台，功能演示时很流畅，一遇到模型接口抖动，任务就全部堆积在中间状态。原因通常是超时设置不合理、队列没有消费进度监控、失败重试逻辑没有分类。真正的可靠性，是异常场景下的恢复能力。

6. 常见误区和排查顺序

6.1 误区：模型越强，平台就越强

模型能力提升确实能让 Agent 理解更复杂的指令、生成更准确的工具调用，但平台能力是另一回事。一个不控制权限、不记录审计、没有审批流的平台，哪怕接上最强模型，也不可能直接变成企业级方案。

反过来，受控智能体模式的优势在于：即使模型判断错了，平台仍然有四道拦截。工具注册表拦掉“不存在的工具”，Schema 校验拦掉“错误的参数”，权限模型拦掉“越权的操作”，审批流拦掉“高风险的动作”。每一层都多一次纠错机会。

6.2 误区：权限控制可以后面再补

权限体系如果前期不设计，后期改造非常痛苦。工具调用、审批流、数据访问、审计日志，每一样都和权限模型耦合。前期的技术债会在批量任务上线、多个部门接入时集中爆发。

落地建议是先定义角色和权限矩阵，再开发业务功能。至少要把“用户角色、数据范围、工具操作类型、风险等级”四者的关系梳理清楚。

6.3 排查顺序：先看状态，再看日志，最后才动代码

Agent 任务出问题时，按照这个顺序排查：

1. 看任务状态：任务在哪个状态卡住了，是等待审批、等待模型响应，还是已经失败
2. 看日志：根据 traceId 捞任务全链路日志，确认是模型调用阶段、工具调用阶段还是审批阶段出错
3. 看工具注册：确认调用的工具是否已注册、参数 Schema 是否正确
4. 看参数配置：超时时间、重试次数、并发额度是否合理
5. 最后才看代码和提示词：大部分线上问题都不是代码逻辑写错，而是状态、配置、依赖、输入数据有偏差

举个例子，任务卡在 pending 状态，很多人第一反应是改代码。实际最常见的两个原因是：审批流没有配置审批人，或者消费者线程池被占满。这两种问题，通过看任务状态和日志就能定位。

回到最开始的问题：Java 21 企业级 AI Agent 平台的核心竞争力，不在于把 Agent 做得“多聪明”，而在于把边界画得“多清楚”。受控智能体模式本质上是把模型当做生产环节中的一个组件，而不是把控制权全部交给模型。你可以在模型层做得简单一些，再用工具注册、审批流、沙箱、审计这些平台能力把它围起来。

如果只是学习，完全可以从最小闭环开始，一条任务、一个工具、一段审计日志，先把链路走通。如果要做到企业级，就要耐心把控制面一层层补上。等到你真正上线跑一批任务，再回头看，就会发现当初那些“看起来麻烦”的控制设计，全是帮平台兜底的关键。