Agent工具注册中心：动态工具发现与参数验证的后端设计

Agent工具注册中心动态工具发现与参数验证的后端设计一、背景与问题定义大模型Agent架构中工具调用Tool Use是实现LLM与外部世界交互的核心机制。随着业务场景扩展一个Agent系统可能注册数十甚至上百个工具涵盖数据库查询、API调用、文件操作、计算服务等。工具管理面临四个核心问题动态注册与发现新工具上线无需重启Agent服务旧工具下线自动剔除参数类型验证LLM生成的工具调用参数常有类型错误、缺失必填项、超出范围等问题沙箱隔离与安全工具执行不能污染宿主环境恶意或异常调用需被阻断超时与容错单个工具调用不能阻塞整个Agent推理流程2025年某Agent平台因工具参数验证缺失导致LLM将page_size99999直接传入数据库查询工具触发慢查询拖垮下游DB实例。本文构建一套完整的Agent工具注册中心覆盖工具Schema定义、动态注册发现、参数预验证、沙箱隔离与超时控制。二、系统架构设计flowchart TD A[LLM推理引擎] -- B[工具路由层] B -- C[工具注册中心] C -- C1[工具Schema仓库br/JSON Schema定义] C -- C2[工具发现服务br/健康检查版本管理] C -- C3[参数验证引擎br/类型/范围/必填校验] C -- C4[沙箱执行层br/隔离超时资源限制] D[工具提供方] -- C1 D -- C2 B -- E[调用日志与审计] C3 -- E C4 -- E subgraph 工具生命周期 F1[注册] -- F2[发现] F2 -- F3[验证] F3 -- F4[执行] F4 -- F5[审计] F5 -- F6[健康检查] F6 -- F2 end工具注册中心的核心职责为LLM推理引擎提供可调用工具的完整清单每个工具的参数规范执行前的验证拦截执行中的隔离保护。三、核心模块实现3.1 工具Schema定义规范JSON Schema工具Schema是注册中心的信息基石定义了工具的名称、描述、参数类型、必填项、默认值、范围约束等。选用JSON Schema作为定义语言因其具备标准化验证能力且LLM可直接消费Schema生成调用参数。/** * 工具Schema定义模型 */ Data Builder public class ToolSchema { private String toolId; // 工具唯一标识如 db_query_v2 private String name; // 工具名称如 database_query private String description; // 工具描述供LLM理解用途 private String version; // 版本号如 2.1.0 private String category; // 分类database/api/file/compute private JsonSchema parameterSchema; // 参数的JSON Schema定义 private JsonSchema responseSchema; // 返回值的JSON Schema定义 private ExecutionConfig execConfig; // 执行配置超时、沙箱、资源限制 private ListString requiredPermissions; // 调用所需权限 private HealthCheckConfig healthCheck; // 健康检查配置 } /** * JSON Schema参数定义示例 - 数据库查询工具 */ public class ToolSchemaExamples { /** * 数据库查询工具的Schema定义 */ public static ToolSchema databaseQueryTool() { String paramSchemaJson { type: object, properties: { sql: { type: string, description: SQL查询语句仅支持SELECT, pattern: ^SELECT\\\\s.*, maxLength: 2000 }, database: { type: string, description: 目标数据库实例标识, enum: [order_db, user_db, config_db] }, page_size: { type: integer, description: 分页大小, default: 20, minimum: 1, maximum: 200 }, timeout_ms: { type: integer, description: 查询超时时间毫秒, default: 5000, minimum: 100, maximum: 30000 } }, required: [sql, database], additionalProperties: false } ; String responseSchemaJson { type: object, properties: { rows: { type: array, items: { type: object }, description: 查询结果行 }, total_count: { type: integer, description: 总记录数 }, query_time_ms: { type: number, description: 查询耗时 } } } ; return ToolSchema.builder() .toolId(db_query_v2) .name(database_query) .description(执行数据库SELECT查询返回结构化结果集。仅支持读操作禁止写入类SQL。) .version(2.1.0) .category(database) .parameterSchema(JsonSchema.fromString(paramSchemaJson)) .responseSchema(JsonSchema.fromString(responseSchemaJson)) .execConfig(ExecutionConfig.builder() .timeoutMs(5000) .sandboxEnabled(true) .maxMemoryMb(256) .maxCpuPercent(30) .build()) .requiredPermissions(List.of(db_read)) .healthCheck(HealthCheckConfig.builder() .checkIntervalMs(30000) .checkMethod(ping) .unhealthyThreshold(3) .build()) .build(); } }关键设计点additionalProperties: false禁止LLM传入未定义参数pattern约束SQL只能为SELECT语句minimum/maximum限制page_size避免慢查询enum限定database选项防止越权访问。3.2 工具注册/发现/健康检查机制/** * 工具注册中心 - 动态注册、发现与健康检查 */ Service Slf4j public class ToolRegistryCenter { private final ConcurrentHashMapString, ToolRegistration registry new ConcurrentHashMap(); private final ScheduledExecutorService healthCheckExecutor; private final ToolValidator validator; /** * 工具注册 - 新工具上线无需重启 */ public RegistrationResult register(ToolSchema schema, ToolExecutor executor) { // 1. Schema格式校验 ValidationResult schemaValidation validator.validateSchema(schema); if (!schemaValidation.isValid()) { log.warn(工具Schema校验失败, toolId{}, errors{}, schema.getToolId(), schemaValidation.getErrors()); return RegistrationResult.failed(Schema校验失败: schemaValidation.getErrors()); } // 2. 版本冲突检查 ToolRegistration existing registry.get(schema.getToolId()); if (existing ! null existing.getSchema().getVersion().equals(schema.getVersion())) { log.warn(工具版本已注册, toolId{}, version{}, schema.getToolId(), schema.getVersion()); return RegistrationResult.failed(版本冲突: schema.getVersion()); } // 3. 注册工具 ToolRegistration registration ToolRegistration.builder() .schema(schema) .executor(executor) .registeredAt(Instant.now()) .status(ToolStatus.ACTIVE) .healthStatus(HealthStatus.UNKNOWN) .build(); registry.put(schema.getToolId(), registration); log.info(工具注册成功, toolId{}, version{}, category{}, schema.getToolId(), schema.getVersion(), schema.getCategory()); // 4. 启动健康检查任务 startHealthCheck(registration); return RegistrationResult.success(schema.getToolId()); } /** * 工具注销 - 旧工具下线自动剔除 */ public void deregister(String toolId) { ToolRegistration registration registry.remove(toolId); if (registration ! null) { // 停止健康检查任务 stopHealthCheck(registration); log.info(工具注销成功, toolId{}, toolId); } else { log.warn(工具注销失败, toolId不存在: {}, toolId); } } /** * 工具发现 - 按分类/能力查询可用工具清单 * 返回结果供LLM消费构建function calling的tools描述 */ public ListToolDescriptor discoverTools(ToolDiscoveryQuery query) { return registry.values().stream() .filter(r - r.getStatus() ToolStatus.ACTIVE) .filter(r - r.getHealthStatus() HealthStatus.HEALTHY || r.getHealthStatus() HealthStatus.UNKNOWN) .filter(r - query.getCategory() null || r.getSchema().getCategory().equals(query.getCategory())) .filter(r - query.getPermission() null || r.getSchema().getRequiredPermissions().contains(query.getPermission())) .map(r - ToolDescriptor.builder() .toolId(r.getSchema().getToolId()) .name(r.getSchema().getName()) .description(r.getSchema().getDescription()) .parameterSchema(r.getSchema().getParameterSchema()) .build()) .sorted(Comparator.comparing(ToolDescriptor::getName)) .collect(Collectors.toList()); } /** * 健康检查 - 定期检测工具可用性 */ private void startHealthCheck(ToolRegistration registration) { long intervalMs registration.getSchema().getHealthCheck().getCheckIntervalMs(); int threshold registration.getSchema().getHealthCheck().getUnhealthyThreshold(); ScheduledFuture? future healthCheckExecutor.scheduleAtFixedRate(() - { try { HealthCheckResult result registration.getExecutor().healthCheck(); if (result.isHealthy()) { registration.setHealthStatus(HealthStatus.HEALTHY); registration.resetFailureCount(); } else { int failures registration.incrementFailureCount(); if (failures threshold) { registration.setHealthStatus(HealthStatus.UNHEALTHY); log.warn(工具标记为不可用, toolId{}, 连续失败次数{}, registration.getSchema().getToolId(), failures); } } } catch (Exception e) { int failures registration.incrementFailureCount(); if (failures threshold) { registration.setHealthStatus(HealthStatus.UNHEALTHY); } log.error(健康检查异常, toolId{}, registration.getSchema().getToolId(), e); } }, intervalMs, intervalMs, TimeUnit.MILLISECONDS); registration.setHealthCheckFuture(future); } }3.3 参数预验证与类型转换/** * 参数验证引擎 - 在工具执行前拦截不合法参数 */ Service Slf4j public class ToolParameterValidator { private final JsonSchemaValidator schemaValidator; /** * 参数预验证 - 基于JSON Schema校验LLM生成的参数 */ public ValidationResult validate(String toolId, MapString, Object parameters) { ToolRegistration registration registry.get(toolId); if (registration null) { return ValidationResult.failed(工具不存在: toolId); } JsonSchema paramSchema registration.getSchema().getParameterSchema(); // 1. JSON Schema结构校验 ValidationResult schemaResult schemaValidator.validate(parameters, paramSchema); if (!schemaResult.isValid()) { log.warn(参数Schema校验失败, toolId{}, errors{}, toolId, schemaResult.getErrors()); return schemaResult; } // 2. 业务语义校验Schema之外的深层规则 ValidationResult semanticResult validateBusinessRules(toolId, parameters); if (!semanticResult.isValid()) { return semanticResult; } // 3. 参数类型转换与归一化 MapString, Object normalized normalizeParameters(parameters, paramSchema); return ValidationResult.success(normalized); } /** * 业务语义校验 - Schema无法覆盖的深层规则 */ private ValidationResult validateBusinessRules(String toolId, MapString, Object params) { ListString errors new ArrayList(); // 规则1数据库查询工具 - SQL安全性校验 if (db_query_v2.equals(toolId)) { String sql (String) params.get(sql); if (sql ! null) { // 禁止写入类SQL if (sql.matches((?i)^\\s*(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE))) { errors.add(SQL语句包含写入操作仅支持SELECT查询); } // 禁止无WHERE条件的DELETE/UPDATE即使Schema已约束SELECT // 仍需防御LLM生成绕过pattern的SQL if (sql.contains(UNION) sql.contains(SELECT)) { errors.add(SQL包含UNION SELECT可能为注入攻击); } // 禁止子查询嵌套超过3层 int subqueryDepth countSubqueryDepth(sql); if (subqueryDepth 3) { errors.add(子查询嵌套深度超过3层可能导致性能问题); } } } // 规则2API调用工具 - URL白名单校验 if (api_call_v1.equals(toolId)) { String url (String) params.get(url); if (url ! null !isUrlInWhitelist(url)) { errors.add(URL不在白名单内: url); } } return errors.isEmpty() ? ValidationResult.success(params) : ValidationResult.failed(errors); } /** * 参数类型转换 - LLM常生成字符串形式的数字参数 */ private MapString, Object normalizeParameters(MapString, Object params, JsonSchema schema) { MapString, Object normalized new HashMap(params); for (Map.EntryString, JsonSchema.Property entry : schema.getProperties().entrySet()) { String key entry.getKey(); JsonSchema.Property prop entry.getValue(); Object value normalized.get(key); if (value null) { // 设置默认值 if (prop.getDefault() ! null) { normalized.put(key, prop.getDefault()); } continue; } // 类型转换字符串→整数 if (integer.equals(prop.getType()) value instanceof String) { try { normalized.put(key, Integer.parseInt((String) value)); } catch (NumberFormatException e) { log.warn(参数类型转换失败, key{}, value{}, key, value); } } // 类型转换字符串→浮点数 if (number.equals(prop.getType()) value instanceof String) { try { normalized.put(key, Double.parseDouble((String) value)); } catch (NumberFormatException e) { log.warn(参数类型转换失败, key{}, value{}, key, value); } } } return normalized; } }3.4 工具调用的沙箱隔离与超时控制/** * 沙箱执行层 - 工具调用隔离与超时控制 */ Service Slf4j public class SandboxExecutor { private final ExecutorService toolExecutorPool; private final AuditLogger auditLogger; /** * 在沙箱环境中执行工具调用 */ public ToolExecutionResult executeInSandbox(ToolRegistration registration, MapString, Object parameters, ExecutionContext context) { String toolId registration.getSchema().getToolId(); long timeoutMs registration.getSchema().getExecConfig().getTimeoutMs(); // 1. 权限检查 if (!hasPermission(context, registration.getSchema().getRequiredPermissions())) { log.warn(工具调用权限不足, toolId{}, userId{}, toolId, context.getUserId()); auditLogger.logToolCall(toolId, context, PERMISSION_DENIED, null); return ToolExecutionResult.failed(权限不足: registration.getSchema().getRequiredPermissions()); } // 2. 带超时的沙箱执行 FutureToolResult future toolExecutorPool.submit(() - { try { // 设置线程级资源限制 Thread currentThread Thread.currentThread(); currentThread.setName(tool-exec- toolId - context.getRequestId()); return registration.getExecutor().execute(parameters); } catch (Exception e) { log.error(工具执行异常, toolId{}, toolId, e); return ToolResult.error(执行异常: e.getMessage()); } }); try { ToolResult result future.get(timeoutMs, TimeUnit.MILLISECONDS); // 3. 返回结果校验 ValidationResult responseValidation validateResponse( registration.getSchema().getResponseSchema(), result.getData()); auditLogger.logToolCall(toolId, context, SUCCESS, result); return ToolExecutionResult.success(result.getData()); } catch (TimeoutException e) { // 超时处理取消任务记录审计 future.cancel(true); // 中断执行线程 log.warn(工具调用超时, toolId{}, timeoutMs{}, toolId, timeoutMs); auditLogger.logToolCall(toolId, context, TIMEOUT, null); return ToolExecutionResult.failed(执行超时: timeoutMs ms); } catch (ExecutionException e) { log.error(工具执行异常, toolId{}, toolId, e.getCause()); auditLogger.logToolCall(toolId, context, ERROR, null); return ToolExecutionResult.failed(执行异常: e.getCause().getMessage()); } catch (InterruptedException e) { Thread.currentThread().interrupt(); return ToolExecutionResult.failed(执行被中断); } } /** * 工具执行线程池配置 - 独立隔离不影响业务线程 */ Bean public ExecutorService toolExecutorPool() { return new ThreadPoolExecutor( 10, // 核心线程数 50, // 最大线程数 60L, TimeUnit.SECONDS, new LinkedBlockingQueue(1000), // 任务队列 new ThreadFactoryBuilder() .setNameFormat(tool-exec-%d) .setDaemon(true) // 守护线程不阻止JVM退出 .build(), new ThreadPoolExecutor.CallerRunsPolicy() // 队列满时降级为调用线程执行 ); } }沙箱隔离的关键设计独立线程池工具执行使用专用线程池与业务线程隔离避免单个工具阻塞业务请求超时强制取消future.cancel(true)中断执行线程防止工具调用无限阻塞权限前置检查执行前校验调用者是否具备所需权限拒绝越权调用审计全量记录每次工具调用成功/失败/超时/权限拒绝均记录审计日志四、工具发现结果的LLM消费与function calling适配工具注册中心的发现结果需要转化为LLM可消费的function calling格式/** * 工具发现结果 → LLM function calling格式转换 */ Component public class ToolDescriptorConverter { /** * 转换为OpenAI function calling格式 */ public ListFunctionDefinition convertToOpenAIFormat(ListToolDescriptor descriptors) { return descriptors.stream() .map(d - FunctionDefinition.builder() .name(d.getName()) .description(d.getDescription()) .parameters(d.getParameterSchema().toJson()) // 直接使用JSON Schema .build()) .collect(Collectors.toList()); } /** * 转换为Anthropic tool_use格式 */ public ListToolDefinition convertToAnthropicFormat(ListToolDescriptor descriptors) { return descriptors.stream() .map(d - ToolDefinition.builder() .name(d.getName()) .description(d.getDescription()) .input_schema(d.getParameterSchema().toAnthropicSchema()) .build()) .collect(Collectors.toList()); } }实测数据在50个工具、日均10万次工具调用的生产环境中指标数值参数验证拦截率12.3%LLM生成参数中约12%不符合Schema类型转换成功率95.6%字符串→数字类转换沙箱超时触发率0.8%平均超时5s/次工具发现延迟3ms本地ConcurrentHashMap查询健康检查检测到不可用工具2例/周五、总结Agent工具注册中心的后端设计核心解决四个问题Schema定义规范化JSON Schema作为工具参数的统一描述语言additionalProperties:false禁止未定义参数pattern约束SQL类型minimum/maximum限制数值范围enum限定枚举选项。Schema既是LLM的消费格式又是参数验证的规则源。动态注册与发现ConcurrentHashMap实现内存级注册表工具注册/注销无需重启服务。健康检查定期探测工具可用性连续失败超过阈值自动标记为UNHEALTHY发现查询自动剔除不可用工具。参数预验证三层防线JSON Schema结构校验→业务语义校验→类型转换归一化。LLM生成参数中约12%不符合Schema预验证层拦截了这些错误参数避免其直接传入工具执行。沙箱隔离与超时控制独立线程池隔离工具执行与业务线程超时强制取消防止无限阻塞权限前置检查拒绝越权调用审计日志全量记录每次调用结果。后续演进方向引入工具版本灰度机制支持新旧版本并行验证构建工具调用链追踪实现多工具串联执行的编排与监控接入OPA策略引擎将权限规则外部化管理。