最近在做一个企业级 AI Agent 平台的技术选型时团队里争论最多的不是模型能力而是“怎么保证 Agent 不乱调工具、不乱访问数据”。模型再强一旦放给业务跑可控性和安全边界就成了第一优先级。我们最终基于 Java 21 设计了一套受控智能体模式的落地框架核心思路是模型负责理解和规划平台负责控制和审计所有工具调用必须经过校验、授权和记录。这篇文章会把我们这套从零搭建企业级 Aiagent 平台核心模块的过程完整拆解出来包括受控智能体模式的设计思路、Java 21 虚拟线程在任务调度中的应用、工具白名单与审批机制、审计日志以及一套可以直接复制运行的最小实现。适合正在做 AI Agent 应用落地的后端开发者也适合准备把 Java 21 引入 AI 项目的团队参考。1. 背景与核心概念1.1 为什么企业级 AI Agent 需要“受控”近两年 Agent智能体的概念非常火各种开源项目、商业平台层出不穷。但从实际项目角度来看直接把一个大模型接入业务系统让它自由调用工具是非常危险的。举个最简单的例子你给 Agent 配了一个“查询客户信息”的工具模型在理解用户问题时可能会尝试调用“删除订单”“修改库存”之类的接口或者因为提示词注入被恶意用户引导去执行越权操作。这些都是真实发生过的问题不是危言耸听。企业级 AI Agent 平台和个人玩具项目的最大区别就在这三点可靠同一个问题不能这次返回正确、下次返回错误工具调用结果要可预期。可控Agent 每一步操作都要在平台设定的边界内不能越权、不能绕过审批。安全数据不能泄露操作要有审计敏感动作要有二次确认。所以我们在设计平台时提出了“受控智能体模式”这个概念核心思想就是模型只负责生成意图和参数平台负责决定这个意图能不能执行、怎么执行、执行结果如何处理。1.2 什么是受控智能体模式受控智能体模式不是某个具体开源项目的专有名词而是一套工程化的设计范式。它把 Agent 从“模型直接调用工具”变成“模型提出请求、平台审批放行、工具执行、结果回传”的闭环。整个流程可以拆成下面几个阶段用户输入任务。Agent 平台将任务交给大模型让模型输出结构化的工具调用计划。平台校验计划中的每个工具是否在白名单内、当前用户是否有权限、是否需要人工审批。校验通过的工具调用才被真正执行。执行结果返回给模型由模型生成最终答复。整个过程完整记录到审计日志包括入参、出参、耗时、审批人。与传统 Agent 模式相比受控模式的差异非常明显对比维度传统 Agent受控智能体模式工具调用模型自行决定平台校验后放行权限控制弱通常只做接口鉴权每个工具、每个用户独立授权敏感操作无拦截二次确认或人工审批审计追踪日志散落全链路结构化审计故障影响模型出错可能导致业务受损边界内失败可回滚可追溯1.3 Java 21 在 AI Agent 开发中的位置说到 AI Agent 开发很多人第一反应是 Python。确实 Python 在模型生态上有优势但在企业级后端系统中Java 依然是核心业务系统的中流砥柱。尤其是 Java 21 发布之后很多特性非常适合做 Agent 平台的底座。Java 21 带来的几个关键能力虚拟线程Virtual Threads海量任务并发执行时不再受“一个线程一个系统线程”的限制。Agent 任务往往需要等待模型响应虚拟线程非常适合这种 IO 密集场景。Record 类型定义工具元数据、任务信息、调用结果等不可变数据结构非常简洁。Sealed Interface密封接口可以严格限定工具调用的结果类型增强类型安全。Pattern Matching for switch根据不同类型路由处理逻辑代码可读性提升明显。结构化并发Java 21 中StructuredTaskScope可以统一管理多个子任务的生命周期非常适合并行调用多个验证器或服务。我们最终确定的方案是Java 21 Spring Boot 3.x JDK 内置 HttpClient Jackson模型接口统一走兼容 OpenAI 格式的网关。这套组合的好处是依赖少、上手快、企业落地阻力小。2. 受控智能体模式的核心设计2.1 任务生命周期管理受控智能体模式下一个任务从提交到完成应该经历明确的状态流转。我们在项目中设计了如下状态机PENDING - PLANING - APPROVING - EXECUTING - COMPLETED | | v v REJECTED FAILEDPENDING任务已提交等待处理。PLANING模型正在生成工具调用计划。APPROVING平台校验权限和审批策略。EXECUTING工具调用执行中。COMPLETED整个任务成功完成。REJECTED权限校验不通过或审批被驳回。FAILED执行过程中出现异常。这个状态机的好处是任务在任何阶段出现问题都能明确知道卡在哪里方便排查和恢复。后续做任务重试、人工介入也都有据可依。2.2 工具调用的白名单与审批机制受控模式最关键的一层是工具调用治理。我们在设计时完全抛弃了“模型说调哪个就调哪个”的信任假设所有工具调用必须经过三层校验第一层工具白名单校验。模型的输出会被解析成ToolCall对象平台先检查工具名是否在已注册的工具集中。如果模型“编造”了一个不存在的工具直接拦截。第二层权限校验。当前用户是否被授权使用该工具。这一层不是简单检查角色而是细化到具体工具与用户、部门、资源维度的绑定。第三层动态审批。对于删除、变更、转账、发送通知这类敏感操作平台会触发审批流程等待人工确认后才真正执行。审批机制用一句话总结就是默认拒绝显式放行。宁可在审批上多一步也不能让模型自由发挥。2.3 审计、追踪与可观测性企业级平台如果没有审计就等于没做安全。我们的审计日志记录所有关键节点包含任务 ID、用户 ID、会话 ID。模型产出的完整计划内容。每个工具调用的入参、出参、耗时。审批人、审批结果、审批时间。异常堆栈和错误信息。审计数据不仅用于安全追溯还可以用来做模型效果评估。我们定期把历史任务中的失败案例汇总成评估集用来验证新的模型版本和提示词模板是否比旧版本更好这个环节对线上质量提升非常明显。3. 环境准备与项目结构3.1 环境说明本文示例以常见环境为准具体的版本需要根据你项目的实际情况调整JDKJava 21必须示例中使用了虚拟线程和 Record。构建工具Maven 3.8 或 Gradle 8。框架Spring Boot 3.x要求 Java 17 以上Java 21 完全兼容。模型服务任意兼容 OpenAI Chat Completions 格式的接口自建 vLLM、企业模型网关均可配置好 Base URL 和 API Key 就行。数据库示例不依赖数据库任务和日志存储可以使用内存 Map生产环境建议替换为 PostgreSQL 或 MySQL配合 Redis 做任务状态缓存。3.2 项目结构为了便于阅读我们按功能模块做了分包src/main/java/com/example/agent/ ├── AgentApplication.java ├── core/ │ ├── AgentTask.java │ ├── AgentContext.java │ ├── ToolCall.java │ ├── ToolResult.java │ ├── ToolSpec.java │ ├── AgentTool.java │ ├── ToolRegistry.java │ └── ControlledAgentEngine.java ├── model/ │ ├── ModelGateway.java │ └── OpenAiCompatibleGateway.java ├── security/ │ ├── ToolAccessDecider.java │ └── ApprovalService.java ├── audit/ │ └── AuditService.java ├── tool/ │ ├── OrderQueryTool.java │ └── OrderUpdateTool.java └── web/ └── AgentController.java本文会把这些文件的关键实现完整贴出来核心代码不依赖具体业务可以直接照着跑通整个链路。4. 实战Java 21 实现最小受控 AI Agent4.1 定义领域模型我们用 Record 定义任务、上下文、工具调用等核心模型简洁且不可变非常适合在多线程、虚拟线程环境中传递。// 文件路径src/main/java/com/example/agent/core/AgentTask.java public record AgentTask( String taskId, String userId, String sessionId, String instruction ) { }// 文件路径src/main/java/com/example/agent/core/AgentContext.java public record AgentContext( String userId, String sessionId ) { }AgentTask是用户提交的完整任务AgentContext则包含后续工具执行所需的上下文信息。两者分开的原因是审计、权限判断、工具执行需要的信息粒度不同。接下来定义工具调用和工具结果// 文件路径src/main/java/com/example/agent/core/ToolCall.java public record ToolCall( String toolName, String arguments ) { }// 文件路径src/main/java/com/example/agent/core/ToolResult.java public record ToolResult( boolean success, String message, String data ) { }这里arguments和data都用 JSON 字符串表示好处是不需要依赖具体反序列化框架解析时统一交给 Jackson 处理。4.2 实现工具注册中心工具注册中心是整个平台的“插件底座”。所有 Agent 可调用的工具都需要先在这里注册模型输出中出现的工具如果不在注册表里会直接被拦截。先定义工具元信息和统一接口// 文件路径src/main/java/com/example/agent/core/ToolSpec.java public record ToolSpec( String name, String description, String parametersJsonSchema, boolean requiresApproval ) { }// 文件路径src/main/java/com/example/agent/core/AgentTool.java public interface AgentTool { ToolSpec spec(); ToolResult execute(ToolCall call, AgentContext context); }ToolSpec中的parametersJsonSchema用来约束模型生成的参数格式既会传给大模型作为生成依据也会在校验阶段用于参数合法性检查。requiresApproval标记该工具是否属于敏感操作。然后是注册中心// 文件路径src/main/java/com/example/agent/core/ToolRegistry.java Component public class ToolRegistry { private final MapString, AgentTool toolMap new ConcurrentHashMap(); public void register(AgentTool tool) { toolMap.put(tool.spec().name(), tool); } public OptionalAgentTool get(String name) { return Optional.ofNullable(toolMap.get(name)); } public ListToolSpec listSpecs() { return toolMap.values().stream() .map(AgentTool::spec) .toList(); } }注意这里listSpecs返回的是ToolSpec列表这个列表会传给模型让模型知道当前可用的工具范围。4.3 实现受控执行引擎引擎是平台的核心负责把整个任务串起来生成结构化计划。逐项校验工具调用。执行允许调用的工具。记录审计日志。先定义模型网关接口把模型调用和平台解耦// 文件路径src/main/java/com/example/agent/model/ModelGateway.java public interface ModelGateway { /** * 根据用户指令和可用工具列表生成需要调用的工具列表。 * 如果不需要调用工具返回空列表。 */ ListToolCall plan(String instruction, ListToolSpec availableTools); }再定义权限决策器// 文件路径src/main/java/com/example/agent/security/ToolAccessDecider.java Component public class ToolAccessDecider { private final MapString, SetString userToolPermissions new ConcurrentHashMap(); public ToolAccessDecider() { // 示例初始化管理员拥有全部权限普通用户仅允许查询类工具 userToolPermissions.put(admin, Set.of(queryOrder, updateOrder)); userToolPermissions.put(normal, Set.of(queryOrder)); } /** * 校验用户是否有权限使用指定工具。 */ public boolean hasPermission(String userId, String toolName) { return userToolPermissions.getOrDefault(userId, Set.of()).contains(toolName); } }接着是审批服务// 文件路径src/main/java/com/example/agent/security/ApprovalService.java Service public class ApprovalService { /** * 模拟人工审批。生产环境可以接入工单系统、钉钉/企微审批流。 */ public boolean approve(ToolCall call, AgentContext context) { System.out.println(需要人工审批: user context.userId() , tool call.toolName() , args call.arguments()); // 这里为了方便示例默认自动通过生产环境必须替换为真实审批回调 return true; } }最后是受控引擎的核心实现// 文件路径src/main/java/com/example/agent/core/ControlledAgentEngine.java Service public class ControlledAgentEngine { private final ToolRegistry toolRegistry; private final ModelGateway modelGateway; private final ToolAccessDecider accessDecider; private final ApprovalService approvalService; private final AuditService auditService; private final ExecutorService executor Executors.newVirtualThreadPerTaskExecutor(); public ControlledAgentEngine(ToolRegistry toolRegistry, ModelGateway modelGateway, ToolAccessDecider accessDecider, ApprovalService approvalService, AuditService auditService) { this.toolRegistry toolRegistry; this.modelGateway modelGateway; this.accessDecider accessDecider; this.approvalService approvalService; this.auditService auditService; } /** * 提交任务异步执行。 */ public CompletableFutureAgentResult submit(AgentTask task) { // 使用 Java 21 虚拟线程执行任务 return CompletableFuture.supplyAsync(() - executeTask(task), executor); } private AgentResult executeTask(AgentTask task) { // 记录任务开始 auditService.record(TASK_START, task.taskId(), task.userId(), null, null); // 1. 模型生成计划 ListToolSpec specs toolRegistry.listSpecs(); ListToolCall plan; try { plan modelGateway.plan(task.instruction(), specs); } catch (Exception e) { auditService.record(PLAN_FAILED, task.taskId(), task.userId(), null, e.getMessage()); return AgentResult.failure(模型生成计划失败: e.getMessage()); } if (plan.isEmpty()) { auditService.record(COMPLETED, task.taskId(), task.userId(), null, 无需调用工具); return AgentResult.success(模型判断无需调用工具); } // 2. 逐步校验并执行工具调用 AgentContext context new AgentContext(task.userId(), task.sessionId()); ListString results new ArrayList(); for (ToolCall call : plan) { // 第一层工具白名单校验 OptionalAgentTool toolOpt toolRegistry.get(call.toolName()); if (toolOpt.isEmpty()) { auditService.record(BLOCKED, task.taskId(), task.userId(), call.toolName(), 工具不存在); return AgentResult.failure(工具不存在: call.toolName()); } AgentTool tool toolOpt.get(); ToolSpec spec tool.spec(); // 第二层权限校验 if (!accessDecider.hasPermission(task.userId(), spec.name())) { auditService.record(BLOCKED, task.taskId(), task.userId(), spec.name(), 无权限); return AgentResult.failure(无权调用工具: spec.name()); } // 第三层敏感操作审批 if (spec.requiresApproval()) { boolean approved approvalService.approve(call, context); auditService.record(APPROVAL, task.taskId(), task.userId(), spec.name(), approved ? 通过 : 拒绝); if (!approved) { return AgentResult.failure(审批未通过: spec.name()); } } // 执行工具 try { ToolResult result tool.execute(call, context); auditService.record(TOOL_EXEC, task.taskId(), task.userId(), spec.name(), result.success() ? 成功: result.message() : 失败: result.message()); results.add(result.message()); if (!result.success()) { return AgentResult.failure(工具执行失败: spec.name() - result.message()); } } catch (Exception e) { auditService.record(TOOL_ERROR, task.taskId(), task.userId(), spec.name(), e.getMessage()); return AgentResult.failure(工具异常: spec.name() - e.getMessage()); } } auditService.record(COMPLETED, task.taskId(), task.userId(), null, String.join(;, results)); return AgentResult.success(String.join(;, results)); } }这里有几个工程细节需要解释Executors.newVirtualThreadPerTaskExecutor()是 Java 21 的新特性每个任务一个虚拟线程在等待模型响应、等待工具返回时几乎不消耗系统线程资源。任务通过CompletableFuture异步返回主线程不会被阻塞。每层校验都记录审计日志一旦出现问题可以完整还原调用链。为了代码完整补上AgentResult和AuditService// 文件路径src/main/java/com/example/agent/core/AgentResult.java public record AgentResult( boolean success, String summary ) { public static AgentResult success(String summary) { return new AgentResult(true, summary); } public static AgentResult failure(String summary) { return new AgentResult(false, summary); } }// 文件路径src/main/java/com/example/agent/audit/AuditService.java Service public class AuditService { private final ListAuditEvent events Collections.synchronizedList(new ArrayList()); public void record(String type, String taskId, String userId, String toolName, String detail) { AuditEvent event new AuditEvent(type, taskId, userId, toolName, detail, Instant.now()); events.add(event); // 生产环境请替换为可靠日志通道例如写入 Kafka / 数据库 System.out.println([AUDIT] event); } public ListAuditEvent list() { return List.copyOf(events); } public record AuditEvent( String type, String taskId, String userId, String toolName, String detail, Instant timestamp ) { } }4.4 模型网关实现模型网关是受控模式中的“翻译层”。它负责把平台的结构化约束传递给模型并解析模型返回的工具调用。为了让示例可以直接运行我们用 JDK 内置 HttpClient 实现 OpenAI 兼容接口调用。这里需要提醒一下不同模型服务商的接口细节可能不同示例思路可以复用但请求参数需要按实际网关调整。// 文件路径src/main/java/com/example/agent/model/OpenAiCompatibleGateway.java Component public class OpenAiCompatibleGateway implements ModelGateway { private final HttpClient httpClient HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build(); private final ObjectMapper objectMapper new ObjectMapper(); Value(${agent.model.base-url}) private String baseUrl; Value(${agent.model.api-key}) private String apiKey; Value(${agent.model.name}) private String modelName; Override public ListToolCall plan(String instruction, ListToolSpec availableTools) { try { // 构造系统提示词强调受控约束 String systemPrompt 你是一个受控智能体只能调用平台提供的工具。 你必须按照 JSON 格式返回工具调用计划格式为 {calls: [{toolName: 工具名, arguments: JSON 字符串参数}]} 如果不需要调用工具返回 {calls: []} 禁止编造不存在的工具禁止修改参数值。 ; // 构造工具信息列表 ListMapString, Object tools availableTools.stream().map(spec - { MapString, Object tool new HashMap(); tool.put(name, spec.name()); tool.put(description, spec.description()); tool.put(parameters, spec.parametersJsonSchema()); return tool; }).toList(); MapString, Object requestBody new HashMap(); requestBody.put(model, modelName); requestBody.put(temperature, 0); requestBody.put(messages, List.of( Map.of(role, system, content, systemPrompt), Map.of(role, user, content, instruction \n可用工具: objectMapper.writeValueAsString(tools)) )); String body objectMapper.writeValueAsString(requestBody); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(baseUrl /chat/completions)) .header(Content-Type, application/json) .header(Authorization, Bearer apiKey) .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpResponseString response httpClient.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() ! 200) { throw new RuntimeException(模型接口返回异常: response.statusCode() response.body()); } JsonNode root objectMapper.readTree(response.body()); String content root.path(choices).path(0).path(message).path(content).asText(); String cleaned content.replaceAll(json, ).replaceAll(, ).trim(); JsonNode planNode objectMapper.readTree(cleaned).path(calls); ListToolCall calls new ArrayList(); for (JsonNode item : planNode) { calls.add(new ToolCall( item.path(toolName).asText(), item.path(arguments).asText() )); } return calls; } catch (Exception e) { throw new RuntimeException(模型调用失败: e.getMessage(), e); } } }这里有几个需要注意的点temperature设置为 0尽量让模型输出稳定。系统提示词明确要求模型“只能调用平台提供的工具”并返回固定 JSON 结构。对模型返回内容做了 Markdown 代码块清理避免模型输出带json包裹导致解析失败。4.5 工具实现接下来实现两个示例工具一个只读查询一个写操作。前者普通用户可用后者需要审批。// 文件路径src/main/java/com/example/agent/tool/OrderQueryTool.java Component public class OrderQueryTool implements AgentTool { Override public ToolSpec spec() { MapString, Object schema new HashMap(); schema.put(type, object); schema.put(properties, Map.of( orderId, Map.of(type, string, description, 订单ID) )); schema.put(required, List.of(orderId)); return new ToolSpec( queryOrder, 根据订单ID查询订单状态, schema.toString(), false ); } Override public ToolResult execute(ToolCall call, AgentContext context) { try { JsonNode args new ObjectMapper().readTree(call.arguments()); String orderId args.path(orderId).asText(); if (orderId.isBlank()) { return new ToolResult(false, 参数缺失: orderId, null); } // 模拟查询结果 String data {\orderId\:\ orderId \,\status\:\已发货\,\amount\:199.00}; return new ToolResult(true, 订单查询成功, data); } catch (Exception e) { return new ToolResult(false, 参数解析失败: e.getMessage(), null); } } }// 文件路径src/main/java/com/example/agent/tool/OrderUpdateTool.java Component public class OrderUpdateTool implements AgentTool { Override public ToolSpec spec() { MapString, Object schema new HashMap(); schema.put(type, object); schema.put(properties, Map.of( orderId, Map.of(type, string, description, 订单ID), status, Map.of(type, string, description, 目标状态) )); schema.put(required, List.of(orderId, status)); return new ToolSpec( updateOrder, 修改订单状态属于敏感操作需要审批, schema.toString(), true ); } Override public ToolResult execute(ToolCall call, AgentContext context) { try { JsonNode args new ObjectMapper().readTree(call.arguments()); String orderId args.path(orderId).asText(); String status args.path(status).asText(); // 模拟更新逻辑 String data {\orderId\:\ orderId \,\newStatus\:\ status \}; return new ToolResult(true, 订单状态更新成功, data); } catch (Exception e) { return new ToolResult(false, 参数解析失败: e.getMessage(), null); } } }4.6 注册工具与启动入口工具类通过Component注入容器但我们还需要在启动时把工具注册到ToolRegistry。这里我在启动类中完成注入和注册// 文件路径src/main/java/com/example/agent/AgentApplication.java SpringBootApplication public class AgentApplication implements ApplicationRunner { private final ToolRegistry toolRegistry; private final OrderQueryTool orderQueryTool; private final OrderUpdateTool orderUpdateTool; public AgentApplication(ToolRegistry toolRegistry, OrderQueryTool orderQueryTool, OrderUpdateTool orderUpdateTool) { this.toolRegistry toolRegistry; this.orderQueryTool orderQueryTool; this.orderUpdateTool orderUpdateTool; } public static void main(String[] args) { SpringApplication.run(AgentApplication.class, args); } Override public void run(ApplicationArguments args) { toolRegistry.register(orderQueryTool); toolRegistry.register(orderUpdateTool); System.out.println(工具注册完成: toolRegistry.listSpecs().stream().map(ToolSpec::name).toList()); } }4.7 提供 HTTP 接口最后写一个 Controller方便通过 HTTP 提交任务并查看结果。// 文件路径src/main/java/com/example/agent/web/AgentController.java RestController RequestMapping(/api/agent) public class AgentController { private final ControlledAgentEngine engine; public AgentController(ControlledAgentEngine engine) { this.engine engine; } PostMapping(/task) public CompletableFutureAgentResult submit(RequestBody AgentTask task) { return engine.submit(task); } }配置文件# 文件路径src/main/resources/application.yml server: port: 8080 agent: model: base-url: ${MODEL_BASE_URL:http://localhost:8000/v1} api-key: ${MODEL_API_KEY:sk-test} name: ${MODEL_NAME:qwen2.5}到这里一个最小可运行的受控 AI Agent 平台就完成了。启动 Spring Boot 项目后向/api/agent/task发送 POST 请求即可验证整体流程。4.8 运行验证示例假设你的模型网关已经就绪用 curl 提交一个任务curl -X POST http://localhost:8080/api/agent/task \ -H Content-Type: application/json \ -d { taskId: task-001, userId: admin, sessionId: session-001, instruction: 请查询订单 ORDER-2025-001 的状态 }如果你用的是 OpenAI 兼容接口但没有现成环境可以用 Mock 方式验证自己写一个固定返回{calls: [{toolName: queryOrder, arguments: {\orderId\:\ORDER-2025-001\}}]}的假网关实现替换Component即可。这样整个受控链路不依赖真实模型也能测试。5. 安全与可靠性加固5.1 敏感操作的二次确认上面的示例中审批服务为了演示默认自动通过生产环境绝对不能这么写。真实场景建议审批任务进入独立的工单表状态为WAITING_APPROVAL。通过钉钉、企微、飞书或内部审批平台推送审批通知。审批通过后回调 Agent 引擎继续执行审批拒绝则任务终止。审批要设置超时时间超时自动拒绝或升级避免任务长时间悬挂。审批记录要和工具执行绑定同一个 taskId确保一个任务对应一条完整链路。5.2 虚拟线程与超时治理Java 21 虚拟线程解决了并发度问题但随之而来的新问题是如果一个工具调用迟迟不返回任务会一直挂着。我们在工具层和 HTTP 层都加了超时控制。对于耗时不可控的工具建议在线程池之上再做一层超时// 示例给工具执行增加超时保护 ToolResult result CompletableFuture .supplyAsync(() - tool.execute(call, context), executor) .get(15, TimeUnit.SECONDS);这里用CompletableFuture.get配合超时。一旦超时按失败处理并记录审计同时可以考虑是否要对工具做熔断。5.3 模型输出的 JSON 安全解析大模型输出的 JSON 经常不按格式来我们在项目中遇到过多套一层 JSON、字段名被翻译成中文、带 Markdown 代码块、参数里混入多余逗号等。建议双层保障第一层在提示词中严格约束格式并给 one-shot 示例。第二层在解析代码中做容错。解析失败时不要直接抛出异常而是把原始输出记录下来用于后续分析同时向用户返回“模型响应异常”的友好提示。// 示例容错解析 try { return objectMapper.readTree(cleaned); } catch (JsonProcessingException e) { // 记录原始输出便于后续分析 auditService.record(PARSE_ERROR, taskId, userId, null, cleaned); throw new IllegalArgumentException(模型输出格式非法, e); }6. 常见问题与排查清单受控智能体模式在落地过程中最容易踩的问题集中在模型输出、权限配置、审批流程和并发治理几个方面。下面按高频场景整理一份排查思路问题现象常见原因解决思路模型返回“工具不存在”模型幻觉编造了未注册工具强化系统提示词校验工具名时做相似度提示返回错误信息让模型重新规划参数解析失败模型返回的 JSON 不合法或字段缺失在提示词中给工具参数示例解析时打印原始输出对参数 schema 做强校验用户任务被拦截权限表未配置该用户的工具权限检查ToolAccessDecider中的权限配置确认用户 ID 是否拼写一致审批消息迟迟不回调审批服务未与引擎正确关联检查 taskId 是否贯穿整个链路确认审批回调地址配置正确增加审批超时机制并发任务一多就 OOM模型或工具调用阻塞积累任务队列无限增长使用有界队列对任务做限流给每个任务设置超时评估虚拟线程使用是否正确模型每次都重复调用同一工具系统提示词对任务拆解约束不够在计划生成阶段增加“最小调用次数”约束把工具描述写得更准确审计日志缺失校验或执行的某些分支没有埋点对照任务状态机检查每个节点的 record 调用确保所有分支都有日志下面是实操排查顺序遇到问题建议按这个顺序走打开审计日志定位任务卡在哪个阶段计划生成、校验、审批、执行。如果是计划阶段打印模型原始输出确认是模型问题还是解析问题。如果是审批阶段检查审批服务是否真正收到任务回调地址是否可达。如果是执行阶段单独用测试参数调用该工具排除工具本身的问题。检查是否所有异常分支都返回了明确的错误信息而不是悄悄吞掉异常。7. 最佳实践与工程建议7.1 权限设计最小化受控智能体模式下权限策略建议遵循最小够用原则。不要图省事给所有用户配全部工具权限。更合理的做法是查询类工具全员可配但写操作、删除操作、发送类操作单独授权。权限判断不仅看“谁能调这个工具”还要看“能操作哪些资源”。例如queryOrder工具必须校验订单归属防止水平越权。权限变更要有审批记录权限配置本身也要纳入审计。7.2 模型与平台职责分离模型应只负责“理解意图”和“生成参数”平台负责“决策与执行”。不要把权限判断逻辑写进提示词因为提示词可以被绕过不能作为安全边界。所有安全校验必须在代码中完成。7.3 提示词与工具 Schema 管理工具的描述和参数 schema 直接影响模型规划质量。建议工具描述写清楚这个工具做什么、什么时候用、什么时候不要用、参数含义是什么。必要时给一个调用示例。Schema 变更要建立评审流程因为工具描述变化会影响模型输出行为。我们一般把 Schema 作为配置项管理发布前可以 diff变更新旧版本做 A/B 对比。7.4 密钥与配置管理模型网关的 API Key 绝对不能写死在代码或配置文件里要通过环境变量或配置中心注入。我们团队使用 Spring Cloud Config 管理不同环境用不同 profile 隔离。同时要防止密钥通过模型输出或日志泄露。建议在审计日志中对敏感字段做脱敏处理。7.5 全链路质量评估没有评估体系Agent 就不敢上线。建议沉淀一个评估集包含三类样本正常任务样本验证基础能力是否稳定。越权任务样本验证权限拦截是否生效。对抗样本包含提示词注入、参数伪造等攻击场景验证平台是否仍然可控。每次调整模型版本、提示词模板、工具 Schema 后都跑一遍评估集再发布这是控制线上风险最直接的方式。7.6 灰度发布与监控线上 Agent 平台的变更模型版本、工具逻辑、提示词建议走灰度发布。可以先让 10% 流量切到新版本观察工具调用成功率、任务失败率、平均响应时间。核心监控指标至少包括任务提交量、完成量、失败量。计划阶段平均耗时、工具执行平均耗时。权限拦截次数、审批通过/拒绝比例。模型输出解析失败率。单工具调用成功率。这些指标异常时要能第一时间通过告警通知到值班人员。7.7 保持依赖克制Java 21 自带的虚拟线程、HttpClient、Record 等特性已经能解决很多问题不需要为了“AI 项目”强行引入一堆重量级框架。依赖越少出问题时的排查范围越小。我们当前这套平台的核心业务代码不超过 30 个类却能覆盖完整的受控调用链这种克制的工程风格在企业维护阶段非常受益。8. 总结这篇文章围绕“企业级 Aiagent 平台”展开完整拆解了受控智能体模式的设计与实现。核心思路可以用一句话概括模型负责想平台负责管。工具白名单、用户权限、敏感操作审批、全链路审计这四层机制共同保证了 Agent 在业务环境中的可靠、可控和安全。Java 21 在这套方案中的价值是实打实的。虚拟线程让大规模任务调度变得轻量Record 让核心模型定义简洁清晰内置 HttpClient 减少了第三方依赖。如果条件允许建议在真实业务中先把 1 到 2 个查询类工具接入受控链路试运行跑通之后再逐步扩展写操作和审批流。从 Java 开发者的视角来说AI Agent 并不是 Python 的专属领域用 Java 一样可以构建出工程化程度很高的企业级 Agent 平台。如果你正在用 Java 21 做 AI 项目或者对受控智能体模式有自己的落地经验欢迎在评论区交流。
