Java Semantic Kernel 插件式 Agent 实践

Semantic Kernel 可把 Java 方法或 OpenAPI 能力作为插件。

问题背景

生成式模型擅长处理模糊语言和提出候选方案，却不天然保证状态一致、权限正确或动作可恢复。讨论“Java Semantic Kernel 插件式 Agent 实践”时，重点不应只是跑通演示，而是系统失败后是否知道发生了什么、能否安全继续，以及结果能否重复验证。

设计方案

插件保持业务语义，过滤器统一授权追踪，应用层控制会话状态。

在“Kernel 插件边界”进入实现前，先标注输入来源、调用身份和数据等级；输出通过结构与领域校验后才允许进入下一步。涉及外部副作用时，执行记录必须包含稳定业务键和脱敏证据。

实施产物：Kernel 插件边界

插件方法使用窄 DTO；注册时声明副作用；过滤器统一做身份、审批和观测；会话不保存请求级凭据。先在测试环境保存一条完整运行证据，再接入真实写操作；每次变更都必须能定位到配置、代码和数据版本。

record JavaSemanticKernelPolicy(Duration timeout, int maxAttempts) {}

ToolResult java_semantic_kernel(ToolRequest request, JavaSemanticKernelPolicy policy) {
    validator.validate(request);
    return executor.execute(request, policy.timeout());
}

示例只表达边界，不是可直接复制的完整框架配置。落地时应使用当前依赖版本的官方 API，并把超时、身份和审计接到现有基础设施。

实施步骤

选一个可回放的小任务，写清输入、成功条件和禁止发生的副作用。
实现“Kernel 插件边界”，把模型建议与真正执行隔离。
人工走通成功、拒绝和恢复三条路径，保存 run_id 与关键事件。
加入自动化回归，再用小比例非关键流量观察指标。
达到门槛后逐步放量；任一安全约束失败立即停止新任务并回退版本。

失败演练与验收

首要反例是：把 Spring Bean 全量暴露成插件。不要只验证顺利完成；还要注入超时、重复请求、取消、无权限输入和依赖返回畸形数据。

本篇的硬性验收是：未授权插件调用在方法进入前被过滤器拒绝。同时记录 过滤器拒绝数、插件错误率、调用延迟。验收脚本应按结构化字段判定，不以“回答看起来合理”代替测试。

上线与回滚

“Kernel 插件边界”上线前要固定模型、提示、规则、工具 schema 与数据版本，并用影子或灰度流量比较旧版。若 过滤器拒绝数、插件错误率、调用延迟 越过门槛，先停止新 Run，再处理在途任务，恢复旧组合后逐项核对未决副作用。

适用边界

当场景是“无需工具的文本生成”时，这套设计的维护成本通常高于收益。权限、金额、删除和一致性约束始终交给确定性代码，不能交给模型自行判断。

插件发现与执行之间还有策略门

阶段	检查
register	名称唯一、schema、risk、owner
advertise	按身份/任务裁剪可见函数
bind	严格参数与领域类型转换
authorize	tenant、对象、policy、approval
invoke	deadline、并发、幂等、trace

插件方法保持薄：将 kernel arguments 转为领域 command，真正权限和事务由应用服务处理。不要把 Spring bean 中所有 public 方法自动暴露；使用明确允许列表和独立 DTO，返回值也做脱敏与大小限制。

Filter 拿到规范化 action hash 后执行策略、审批和遥测，审批后在 invoke 前重新核对参数与资源版本。多个插件同名或描述近似时在启动期失败，不能依赖注册顺序决定调用哪个。

测试未授权函数不可发现、直接构造函数名仍被拒绝、畸形参数不进入方法、filter 超时 fail closed，以及方法成功但响应丢失后的幂等恢复。插件升级固定 schema 版本，旧 Run 恢复时使用兼容实现或明确停止迁移。

第二轮实践复核

围绕“Kernel 插件边界”建立一个不接触生产数据的最小项目，固定运行时、框架、模型、提示、规则和工具 schema 版本。正文代码块若缺少完整依赖、导入或领域类型，应视为架构伪代码；只有放入示例仓库并通过下述命令的代码才标记为可运行。

项目验证：./mvnw test（或项目既有的 ./gradlew test）
回归夹具：把输入、结构化输出、工具轨迹和副作用记录为 JSON，用固定版本执行正常、拒绝、超时、取消与重复请求五组回归样本。
必留证据：run_id、版本组合、终止原因、动作幂等键，以及 过滤器拒绝数、插件错误率、调用延迟。
通过条件：未批准写操作为零副作用；相同幂等键重复执行只产生一个业务结果；超时或恢复后状态可解释。
失败处理：先停新任务，再核对在途动作；回滚模型、提示、规则、工具与状态迁移的完整组合，不能只换回模型。

复用顺序

为“Java Semantic Kernel 插件式 Agent 实践”建立确定性假工具，先跑契约与失败用例，不接触真实凭据。
围绕“Kernel 插件边界”接入只读能力，核对权限裁剪、脱敏字段和 Trace 完整性。
需要写能力时先输出 dry-run 差异，再绑定审批结果与一次性动作哈希。
以本文验收指标比较影子流量；达到门槛才放量，越线立即执行文中的组合回滚。

实践与资料复核日期：2026-08-22；框架 API 以锁定版本的官方文档为准。

参考资料

官方文档

框架 API 会持续演进，复制示例前应再次确认当前版本。可持续的 AI 工程不依赖某个模型偶尔表现出色，而依赖清晰契约、可靠 Harness 与可重复验证。