纯Java Agent执行底座：BizBuddy企业级Agent Harness平台

1. 项目概述：为什么需要一个“纯 Java”的 Agent Harness 平台？

BizBuddy 这个名字听起来像一个轻量级的内部工具，但实际落地时你会发现，它根本不是给个人开发者写个 Demo 用的玩具。它是面向中大型企业后端技术栈的一次严肃重构——用纯 Java 实现一个可嵌入、可编排、可观测、可治理的 Agent 执行底座。这里说的“纯 Java”，不是指排斥 Spring Boot 或 MyBatis Plus，而是指不依赖 Python 运行时、不桥接 LLM 框架（如 LangChain、LlamaIndex）、不引入非 JVM 生态的调度中间件（如 Celery、Ray）。所有 Agent 的生命周期管理、上下文传递、工具调用、状态持久化、权限控制、日志追踪，全部跑在同一个 JVM 进程里，用 Java 原生线程模型、JUC 工具类、标准 SPI 扩展机制来完成。

你可能会问：现在主流 Agent 开发都用 Python，LangChain 写起来飞快，为什么偏要“自找麻烦”？答案很现实：某省属国企的风控中台要求所有生产服务必须通过等保三级审计，而 Python 环境的内存泄漏监控、GC 可视化、线程堆栈采样、JVM 参数调优、字节码增强（比如加审计日志）这些能力，在 Java 生态里是开箱即用的；但在 Python 里，你要自己搭 Pyroscope + Prometheus + OpenTelemetry + 自研 Profiler，成本高、稳定性差、运维团队不熟悉。BizBuddy 就是在这个背景下诞生的——它不是为了炫技，而是为了解决“AI 能力如何安全、可控、可审计地融入现有 Java 企业系统”这个真问题。

核心关键词“Agent Harness”在这里不是泛指“代理运行环境”，而是特指一种结构化封装 Agent 行为的契约容器。它定义了 Agent 必须实现的接口（如execute(Context ctx)）、必须声明的元数据（如@AgentMeta(name="credit-risk-assessor", version="1.2.0", scope="internal")）、必须遵守的执行约束（如最大超时 8s、最多重试 2 次、禁止访问外网 DNS）。这种契约不是靠文档约定，而是靠 Java 编译期检查 + 运行时 SPI 加载校验 + 启动阶段 Schema 验证三重保障。你提交一个 Agent Jar 包，BizBuddy 的AgentValidator会扫描其 classpath，确认它实现了BizBuddyAgent接口、包含合法agent.yaml描述文件、所依赖的工具类都在白名单内——通不过就拒绝加载，连启动都不让。

这直接决定了 BizBuddy 和 RuoYi-Vue-Plus 这类通用后台框架的本质区别：RuoYi 是“人操作系统的界面”，BizBuddy 是“AI 操作系统的内核”。前者管用户、菜单、权限、流程；后者管 Agent、工具、上下文、记忆、决策链路。它们可以共存——RuoYi 的某个审批节点背后，调用的就是 BizBuddy 提供的/v1/agents/contract-review/execute接口；但绝不能混用——你不能把 BizBuddy 的ToolRegistry当成 RuoYi 的SysMenuMapper来用，因为前者管理的是动态注册的 HTTP 客户端、数据库连接池、OCR SDK 实例，后者只管静态菜单树。

所以如果你是正在做 Java 后端的工程师，手头有 Spring Boot + MyBatis Plus 的多商户商城项目（比如热搜里提到的“跨境商城源码”），想把“智能选品推荐”“物流异常预测”“客服话术生成”这些能力模块化接入，又不想为每个 AI 功能单独起一个 Python 服务、配一套 Nginx 转发、搞一套独立鉴权，那么 BizBuddy 就是你需要的那块“粘合剂”。它不替代你的业务代码，而是让你的OrderService、ProductMapper、WmsClient这些已有资产，变成 Agent 可以直接调用的标准化工具——这才是“企业级”的真实含义：不是功能多，而是能无缝长进你已有的技术毛细血管里。

2. 整体架构设计与关键取舍：为什么不用 Spring Cloud，也不用 Kafka？

BizBuddy 的架构图如果画出来，看起来甚至有点“简陋”：一个单体 JAR（可选打包为 Docker 镜像），里面包含 Web 层（Spring MVC）、Agent 核心引擎（AgentExecutor）、工具注册中心（ToolRegistry）、上下文管理器（ContextManager）、持久化模块（MyBatis Plus + MySQL）、可观测性组件（Micrometer + Prometheus）。没有 Eureka，没有 Nacos，没有 Kafka，没有 Redis（缓存用 Caffeine，分布式锁用数据库乐观锁）。这不是技术保守，而是基于三个硬约束做的主动放弃：

2.1 约束一：部署粒度必须与业务系统对齐

很多团队设想的 Agent 平台是独立部署的 SaaS 服务，Agent 通过 HTTP 调用远程 API。但企业真实场景是：风控系统要调用“反洗钱识别 Agent”，这个 Agent 必须能直接访问风控库的risk_transaction表；供应链系统要调用“库存预测 Agent”，它必须能拿到wms_inventory表的实时快照。如果 Agent 运行在独立进程里，跨进程访问数据库意味着要暴露 JDBC 连接串、绕过数据库行级权限、无法利用 MyBatis 的二级缓存、丢失事务一致性。BizBuddy 的解法是：Agent 作为 Spring Bean 被加载到同一 JVM 中。它和你的RiskService共享同一个DataSource、同一个TransactionManager、同一个SqlSessionFactory。@Transactional注解在 Agent 方法上依然生效，@Select("SELECT * FROM risk_transaction WHERE id = #{id}")这样的 Mapper 调用完全透明。这就要求整个平台必须是嵌入式设计——你可以把它打成一个 starter，<dependency>进你的商城项目，而不是部署一个新服务。

2.2 约束二：消息传递必须零序列化损耗

Agent 执行链路中，上游 Agent 的输出往往是下游 Agent 的输入。比如“合同解析 Agent”输出一个ContractDTO对象，直接传给“条款合规审查 Agent”作为参数。如果走 Kafka，这个 DTO 就得序列化成 JSON 或 Protobuf，再反序列化，不仅耗 CPU，还可能因字段类型不一致（如 Java 的LocalDateTimevs JSON 的字符串时间戳）导致运行时异常。BizBuddy 的选择是：所有 Agent 间通信走内存引用传递。AgentExecutor维护一个ConcurrentHashMap<String, Object>作为临时上下文存储，execute()方法签名是Result execute(Context ctx)，而Context本身就是一个Map<String, Object>的包装类，支持链式put("parsedContract", contractDto).get("parsedContract")。这样既避免了序列化，又保留了类型安全——你在写 Agent 时，IDE 能直接跳转到ContractDTO类定义，编译器能检查字段是否存在，而不是等到运行时报NoSuchFieldException。

2.3 约束三：可观测性必须原生支持 JVM 生态

企业运维最怕什么？不是功能出错，而是“出错了但不知道哪一行代码、哪个线程、哪个 SQL 导致的”。Python 的traceback.print_exc()在复杂异步链路里经常丢上下文，而 Java 的Thread.currentThread().getStackTrace()结合java.lang.instrument，可以精确到方法入口、SQL 执行耗时、HTTP 调用链路。BizBuddy 的AgentTracer模块就是基于此构建：它用 ByteBuddy 在类加载时注入字节码，在每个Agent.execute()方法前后插入Tracer.startSpan()和Tracer.endSpan()，自动采集spanId、parentId、durationMs、inputSizeBytes、outputSizeBytes、sqlCount、httpCallCount。这些数据通过 Micrometer 输出到 Prometheus，再用 Grafana 做看板。你不需要改一行 Agent 代码，就能看到“信用评估 Agent 平均耗时 320ms，其中 78% 耗在risk_score_mapper.selectByUserId()这条 SQL 上”。这种深度可观测性，是任何跨语言 RPC 框架都难以企及的。

这三个取舍直接决定了 BizBuddy 的技术选型边界。它不排斥 Spring Boot，因为 Spring 的 IoC 容器天然适合管理 Agent Bean 的生命周期；它拥抱 MyBatis Plus，因为LambdaQueryWrapper可以让 Agent 直接写类型安全的查询，比如userMapper.selectList(new LambdaQueryWrapper<User>().eq(User::getStatus, "active"))；但它坚决不用 Spring Cloud Stream，因为 Kafka Binder 强制序列化；不用 Feign，因为 HTTP 调用无法共享事务；不用 ShardingSphere，因为分库分表逻辑应该由业务层处理，Agent 只需拿到一个干净的UserMapper实例即可。这种“有所为，有所不为”的设计哲学，才是企业级平台真正的成熟标志——不是堆砌技术名词，而是清楚知道每行代码在解决什么问题、放弃什么代价。

3. 核心模块详解：从 Agent 定义到工具注册的完整闭环

BizBuddy 的核心价值不在“能跑 Agent”，而在“如何让 Agent 安全、稳定、可维护地跑”。这体现在四个紧密耦合的模块上：Agent 定义规范、工具注册中心、上下文管理器、执行引擎。它们共同构成一个闭环：Agent 声明它需要什么工具 → 工具中心按需注入 → 上下文管理器提供隔离的执行环境 → 执行引擎驱动整个流程并捕获结果。下面逐层拆解，带你看清每一行关键代码背后的意图。

3.1 Agent 定义：用注解驱动的契约编程

BizBuddy 不要求你继承某个抽象类，而是用一组标准注解定义 Agent 的行为契约。最核心的是@BizBuddyAgent：

@BizBuddyAgent( name = "credit-risk-assessor", version = "1.2.0", description = "基于用户征信报告和交易流水评估信贷风险等级", author = "risk-team@company.com", scope = AgentScope.INTERNAL // INTERNAL / EXTERNAL / SANDBOX ) public class CreditRiskAssessor implements BizBuddyAgent { @Override public Result execute(Context ctx) { // 1. 从上下文中提取输入 String userId = ctx.get("userId", String.class); // 2. 调用已注册的工具 CreditReport report = creditReportTool.fetch(userId); List<Transaction> txns = transactionTool.listByUser(userId, 90); // 最近90天 // 3. 业务逻辑 double score = calculateRiskScore(report, txns); String level = score > 80 ? "HIGH" : score > 50 ? "MEDIUM" : "LOW"; // 4. 返回结构化结果 return Result.success() .put("riskScore", score) .put("riskLevel", level) .put("recommendation", getRecommendation(level)); } }

这个看似简单的类，背后有三层设计：

• 编译期校验：@BizBuddyAgent注解被AgentProcessor（一个javax.annotation.processing.Processor）扫描。它检查：类是否 public、是否实现了BizBuddyAgent接口、execute()方法签名是否正确（必须返回Result，参数必须是Context）。如果不符合，编译直接失败，而不是运行时报ClassCastException。

• 运行时元数据注入：AgentLoader在 Spring Boot 启动时，通过ClassPathScanningCandidateComponentProvider扫描所有@BizBuddyAgent类，反射读取注解值，生成AgentMeta对象，并存入AgentRegistry的ConcurrentMap<String, AgentMeta>。name字段成为 Agent 的唯一标识符，用于 API 路由（POST /v1/agents/{name}/execute）和权限控制（RBAC 规则里可以写allow: credit-risk-assessor:read）。

• 安全沙箱基础：scope = AgentScope.INTERNAL这个字段至关重要。它告诉AgentExecutor：这个 Agent 只能调用ToolRegistry中标记为@Tool(scope = INTERNAL)的工具。比如creditReportTool的定义是：

  @Tool(name = "credit-report-fetcher", scope = AgentScope.INTERNAL) @Component public class CreditReportTool { @Autowired private CreditReportMapper mapper; public CreditReport fetch(String userId) { ... } }

  如果某个EXTERNALAgent（比如开放给第三方的“营销文案生成”）试图调用creditReportTool，AgentExecutor会在执行前拦截并抛出SecurityException。这种基于注解的权限模型，比配置文件或数据库规则更直观、更易维护。

3.2 工具注册中心：让数据库 Mapper 和 HTTP Client 成为“即插即用”的工具

BizBuddy 的ToolRegistry是整个平台的“能力中枢”。它不是简单地把工具类塞进 Map，而是提供了一套标准化的注册、发现、调用、熔断机制。注册过程分三步：

1. 声明工具：用@Tool注解标记 Spring Bean。
2. 自动注册：ToolRegistrar实现ApplicationContextAware，在 Spring 上下文刷新后，遍历所有@ToolBean，提取name、scope、description，存入ConcurrentMap<String, ToolInstance>。
3. 动态代理增强：对每个ToolInstance，ToolProxyFactory创建 JDK 动态代理。代理逻辑包括：
   • 记录调用耗时（用于熔断统计）
   • 捕获异常并分类（SQLException归为 DB_ERROR，HttpClientErrorException归为 HTTP_ERROR）
   • 检查调用方 Agent 的 scope 是否匹配

关键点在于：工具可以是任何 Spring Bean，包括 MyBatis Mapper。这是 BizBuddy 与 LangChain 的本质差异——LangChain 的 Tool 是 Python 函数，调用数据库要写db.query("SELECT ...")；而 BizBuddy 的 Tool 是UserMapper，你可以直接写userMapper.selectById(123)，享受 IDE 补全、编译检查、事务传播、二级缓存所有好处。

实操中，我们常把“根据 Java 实体类生成建表 SQL”这个需求做成一个 Tool：

@Tool(name = "ddl-generator", scope = AgentScope.INTERNAL) @Component public class DdlGeneratorTool { // MyBatis Plus 的内置功能，无需额外依赖 private final DatabaseTableInfo databaseTableInfo; public DdlGeneratorTool(DatabaseTableInfo databaseTableInfo) { this.databaseTableInfo = databaseTableInfo; } public String generateCreateSql(Class<?> entityClass) { // MyBatis Plus 的 TableInfo 机制，自动解析 @TableName、@TableField TableInfo tableInfo = TableInfoHelper.getTableInfo(entityClass); return new MySqlBuilder().buildCreateTableSql(tableInfo); } }

Agent 调用时只需ddlGeneratorTool.generateCreateSql(Order.class)，就能得到标准的CREATE TABLE t_order (...) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;。这个过程完全在 JVM 内完成，不涉及任何外部 SQL 解析器，性能极佳，且与你的实体类定义强一致——改了@TableField注解，生成的 SQL 自动更新。

3.3 上下文管理器：为每个 Agent 执行创建独立的“思维空间”

Context是 BizBuddy 的核心数据载体，但它不是简单的HashMap。ContextManager提供了三种上下文模式：

• Request Context：每次 HTTP 请求对应一个Context实例，生命周期从 Controller 进入到 Response 返回。它支持父子关系，比如 A Agent 调用 B Agent，B 的 Context 会继承 A 的Context，形成链路。
• Session Context：针对需要多轮交互的 Agent（如客服对话机器人），Context可以绑定到用户会话 ID，跨请求保持状态，但默认不持久化（避免内存泄漏），需显式调用context.persist()存入 Redis 或 DB。
• Isolated Context：最严格模式，Context完全隔离，不继承父上下文，所有put()操作只影响当前 Agent。适用于金融计算类 Agent，防止上游污染下游。

Context的设计亮点在于懒加载与类型安全：

public class Context { private final Map<String, Object> data = new ConcurrentHashMap<>(); // 类型安全的 get 方法，避免强制转换 public <T> T get(String key, Class<T> type) { Object value = data.get(key); if (value == null) return null; if (type.isInstance(value)) { return type.cast(value); } throw new ClassCastException("Key '" + key + "' expected " + type.getName() + ", but got " + value.getClass().getName()); } // 懒加载：只有第一次 get 时才真正执行 supplier public <T> T computeIfAbsent(String key, Class<T> type, Supplier<T> supplier) { return (T) data.computeIfAbsent(key, k -> supplier.get()); } }

这意味着 Agent 可以这样写：

// 只有当需要时才查询数据库，且结果自动缓存在当前 Context 中 CreditReport report = ctx.computeIfAbsent("creditReport", CreditReport.class, () -> creditReportTool.fetch(userId));

既保证了性能（避免重复查询），又保证了线程安全（ConcurrentHashMap.computeIfAbsent是原子操作），还保证了类型安全（编译器知道report是CreditReport类型）。

3.4 执行引擎：同步、异步、流式响应的统一抽象

AgentExecutor是 BizBuddy 的“大脑”，它不关心 Agent 具体做什么，只负责标准化执行流程：

1. 准入检查：验证 Agent 是否存在、是否启用、调用方是否有权限。
2. 上下文准备：根据请求参数创建Context，注入预设变量（如requestId,timestamp,callerIp）。
3. 工具注入：从ToolRegistry获取 Agent 声明依赖的工具列表，通过@Autowired方式注入（实际是代理对象）。
4. 执行与监控：调用agent.execute(ctx)，记录耗时、异常、SQL 数量等指标。
5. 结果处理：将Result对象序列化为 JSON，设置 HTTP 状态码（Result.success()→ 200，Result.error("xxx")→ 400）。

关键创新在于对流式响应的支持。很多 Agent（如“实时语音转文字”）需要边处理边返回数据。BizBuddy 为此扩展了Result类型：

public class Result { // 普通结果 public static Result success() { ... } public static Result error(String msg) { ... } // 流式结果：返回一个 Flux，每个事件是一个 Chunk public static Result stream(Flux<Chunk> chunks) { return new Result().setStream(true).setData(chunks); } } // Controller 层 @PostMapping("/v1/agents/{name}/stream") public ResponseEntity<Flux<Chunk>> streamExecute(@PathVariable String name, @RequestBody ContextRequest request) { Context ctx = contextManager.createRequestContext(request.getParams()); Result result = agentExecutor.execute(name, ctx); if (result.isStream()) { return ResponseEntity.ok() .contentType(MediaType.APPLICATION_NDJSON) // Server-Sent Events .body((Flux<Chunk>) result.getData()); } throw new IllegalArgumentException("Agent does not support streaming"); }

这样，前端可以用EventSource接收data: {"text": "hello"}\n\n这样的流式数据，而 Agent 内部只需ctx.stream().next("hello").next("world")，完全屏蔽了底层 Netty 或 WebFlux 的复杂性。这种设计让 BizBuddy 既能处理传统 REST API，也能支撑实时 AI 应用，而代码复杂度几乎为零。

4. 实操落地：从零搭建 BizBuddy 平台的完整步骤

现在我们把前面讲的理论，变成可执行的命令和代码。假设你手头有一个基于 Spring Boot 2.7 + MyBatis Plus 3.5 的跨境商城项目（类似热搜里的“多商户源码”），你想把 BizBuddy 集成进去。整个过程分为五步，每一步都有明确的命令、配置和验证方式，确保你能亲手跑起来。

4.1 步骤一：添加 BizBuddy Starter 依赖

不要下载 ZIP 包或 clone 整个仓库——BizBuddy 设计为 Maven Starter，最小化侵入。在你的商城项目pom.xml中，添加：

<dependency> <groupId>com.bizbuddy</groupId> <artifactId>bizbuddy-spring-boot-starter</artifactId> <version>1.3.0</version> </dependency>

注意版本号：1.3.0是当前稳定版，它强制要求 Spring Boot ≥2.6.0、MyBatis Plus ≥3.4.3，因为要用到@MapperScan的新特性。如果你的项目还在用 Spring Boot 2.3，必须先升级，否则AgentLoader无法正确扫描@BizBuddyAgent类。

验证方式：mvn clean compile。如果看到类似[INFO] --- maven-compiler-plugin:3.8.1:compile (default-compile) @ your-shop ---且无错误，说明依赖已成功解析。此时项目结构里会多出bizbuddy-core、bizbuddy-spring两个 jar，它们不包含任何业务代码，只提供接口和注解。

4.2 步骤二：初始化数据库表结构

BizBuddy 需要 3 张核心表来存储 Agent 元数据、执行日志、工具配置。它不强制要求你手动建表，而是提供 MyBatis Plus 的AutoGenerator脚本，根据 Java 实体类自动生成建表 SQL——这正是热搜词“mybatisplus根据java实体类生成创建表的sql语句”的真实应用场景。

在你的项目中新建一个SqlGenerator类：

public class SqlGenerator { public static void main(String[] args) { // 1. 配置数据源（指向你的开发库） DataSourceConfig dsc = new DataSourceConfig(); dsc.setUrl("jdbc:mysql://localhost:3306/your_shop?useSSL=false&serverTimezone=GMT%2B8"); dsc.setUsername("root"); dsc.setPassword("123456"); // 2. 配置全局策略 GlobalConfig gc = new GlobalConfig(); gc.setOutputDir("src/main/resources/sql"); // SQL 文件输出目录 // 3. 配置包信息 PackageConfig pc = new PackageConfig(); pc.setModuleName("bizbuddy"); pc.setParent("com.yourshop"); // 4. 配置策略（重点：指定实体类路径） StrategyConfig strategy = new StrategyConfig(); strategy.setEntityLombokModel(true); strategy.setRestControllerStyle(true); strategy.setInclude("AgentMeta", "AgentExecutionLog", "ToolConfig"); // 三个实体类名 // 5. 执行生成 new AutoGenerator() .setDataSource(dsc) .setGlobalConfig(gc) .setPackageInfo(pc) .setStrategy(strategy) .execute(); } }

运行这个main方法，它会扫描com.yourshop.bizbuddy.entity包下的AgentMeta.java等实体类，根据@TableName("bizbuddy_agent_meta")、@TableId(type = IdType.ASSIGN_ID)等注解，生成标准的 MySQL 建表语句，保存到src/main/resources/sql/目录下。生成的 SQL 示例：

CREATE TABLE `bizbuddy_agent_meta` ( `id` bigint NOT NULL COMMENT '主键ID', `name` varchar(64) NOT NULL COMMENT 'Agent名称', `version` varchar(16) NOT NULL COMMENT '版本号', `description` varchar(255) DEFAULT NULL COMMENT '描述', `author` varchar(128) DEFAULT NULL COMMENT '作者', `scope` tinyint NOT NULL DEFAULT '0' COMMENT '作用域：0-INTERNAL,1-EXTERNAL', `status` tinyint NOT NULL DEFAULT '1' COMMENT '状态：0-禁用,1-启用', `created_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_name_version` (`name`,`version`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Agent元数据表';

然后，你只需把生成的 SQL 复制到 MySQL 客户端执行即可。这一步的关键价值在于：表结构与 Java 实体类完全一致，改了@TableField注解，下次生成 SQL 就自动更新，杜绝了“数据库字段和代码字段不一致”的经典坑。

4.3 步骤三：编写第一个 Agent —— “订单智能分单”

现在我们写一个真实业务场景的 Agent：跨境商城的订单分单。传统做法是硬编码在OrderService里，现在把它抽成可配置、可灰度、可监控的 Agent。

创建com.yourshop.bizbuddy.agent.OrderDispatchAgent.java：

@BizBuddyAgent( name = "order-dispatch", version = "1.0.0", description = "根据商品类目、买家国家、仓库库存情况，智能分配订单到最优仓库", author = "logistics-team@company.com", scope = AgentScope.INTERNAL ) @Component public class OrderDispatchAgent implements BizBuddyAgent { @Autowired private WarehouseMapper warehouseMapper; @Autowired private ProductMapper productMapper; @Autowired private CountryRuleTool countryRuleTool; // 自定义工具 @Override public Result execute(Context ctx) { // 1. 获取输入（来自前端 POST 的 JSON） Long orderId = ctx.get("orderId", Long.class); if (orderId == null) { return Result.error("orderId is required"); } // 2. 查询订单详情（复用现有 Mapper） Order order = orderMapper.selectById(orderId); if (order == null) { return Result.error("Order not found: " + orderId); } // 3. 查询商品类目（复用现有 Mapper） Product product = productMapper.selectById(order.getProductId()); // 4. 查询可用仓库（复用现有 Mapper） List<Warehouse> candidates = warehouseMapper.selectList( new LambdaQueryWrapper<Warehouse>() .eq(Warehouse::getStatus, "ACTIVE") .ge(Warehouse::getStock, order.getQuantity()) ); // 5. 应用分单规则（调用自定义工具） Warehouse selected = countryRuleTool.selectWarehouse( order.getBuyerCountry(), product.getCategory(), candidates ); // 6. 更新订单（复用现有 Service） order.setWarehouseId(selected.getId()); order.setStatus("DISPATCHED"); orderMapper.updateById(order); // 7. 返回结构化结果 return Result.success() .put("warehouseId", selected.getId()) .put("warehouseName", selected.getName()) .put("dispatchTime", System.currentTimeMillis()); } }

注意几个细节：

• 它直接@Autowired了OrderMapper、ProductMapper，说明 BizBuddy 和你的业务代码共享同一个 MyBatisSqlSessionFactory。
• countryRuleTool是一个自定义 Tool，你需要另外写一个@Tool类，实现复杂的分单逻辑（比如根据时区、关税政策、物流时效计算权重）。
• orderMapper.updateById(order)这行代码，会自动参与当前事务——如果后续步骤失败，整个分单操作会回滚，保证数据一致性。

4.4 步骤四：配置与启动

BizBuddy 的配置极其精简，全部通过application.yml控制：

bizbuddy: # Agent 扫描包路径（必须指定，否则找不到 @BizBuddyAgent） agent-package: com.yourshop.bizbuddy.agent # 工具扫描包路径 tool-package: com.yourshop.bizbuddy.tool # 执行超时（毫秒） timeout-ms: 10000 # 最大重试次数 max-retry: 2 # 是否启用流式响应 enable-streaming: true # MyBatis Plus 配置（复用原有配置） mybatis-plus: mapper-locations: classpath*:mapper/**/*Mapper.xml configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

启动你的 Spring Boot 应用（Application.java），观察控制台日志：

[INFO] Started AgentLoader: found 1 @BizBuddyAgent classes [INFO] Registered Agent: order-dispatch (1.0.0) [INFO] Registered Tool: country-rule-tool (scope=INTERNAL) [INFO] BizBuddy started successfully. Ready to serve.

这表示 BizBuddy 已加载成功。此时，你的应用除了原有的/api/order/**接口，还自动暴露了：

• POST /v1/agents/order-dispatch/execute（同步执行）
• POST /v1/agents/order-dispatch/stream（流式执行）

4.5 步骤五：测试与验证

用 curl 测试第一个 Agent：

# 同步执行 curl -X POST http://localhost:8080/v1/agents/order-dispatch/execute \ -H "Content-Type: application/json" \ -d '{"orderId": 12345}' # 返回示例 { "code": 200, "message": "success", "data": { "warehouseId": 101, "warehouseName": "Shenzhen Warehouse", "dispatchTime": 1712345678901 } }

同时，打开你的 MySQL，查bizbuddy_agent_execution_log表，会看到一条新记录，包含agent_name、input_json、output_json、duration_ms、status（SUCCESS/ERROR）等字段。这就是 BizBuddy 的“可审计”能力——每一次 Agent 调用，都有完整的数字证据链。

提示：如果测试失败，最常见的原因是orderId不存在，或者warehouseMapper.selectList(...)返回空列表。这时日志里会有清晰的AgentExecutionException堆栈，指向OrderDispatchAgent.java的第 42 行，而不是模糊的“Internal Server Error”。

5. 常见问题与避坑指南：那些文档里不会写的实战经验

在给 12 家企业客户落地 BizBuddy 的过程中，我们踩过不少坑。有些是 Java 本身的陷阱，有些是 Agent 场景特有的挑战。下面分享 5 个最典型的问题，以及我们验证过的解决方案。这些不是理论，而是你明天就会遇到的真实场景。

5.1 问题一：Agent 执行时出现java.lang.OutOfMemoryError: Metaspace

现象：平台运行几天后，突然所有 Agent 调用都超时，JVM 日志显示Metaspace OOM，重启后暂时恢复，但一周后复发。

原因分析：BizBuddy 支持动态加载 Agent Jar（比如从 FTP 下载新版本），每次加载都会创建新的ClassLoader。而 Java 的 Metaspace 存储类的元数据（方法签名、字段信息），如果ClassLoader不被回收，这些元数据就永远留在 Metaspace 里。我们的客户曾在一个 Agent 里写了new GroovyShell().parse(script)，Groovy 动态编译会生成大量匿名类，每个类占用几 KB Metaspace，一天下来就吃光 256MB 默认值。

解决方案：

• 禁止动态类加载：在application.yml中设置bizbuddy.allow-dynamic-classloader: false，强制所有 Agent 必须在启动时加载。
• 监控 Metaspace：在 Prometheus 配置中加入jvm_memory_pool_used_bytes{pool="Metaspace"}指标，设置告警阈值 80%。
• JVM 参数调优：启动时加-XX:MaxMetaspaceSize=512m -XX:MetaspaceSize=256m，避免频繁 GC。

实操心得：我们给某银行客户做压测时，发现他们用了javassist在运行时修改 Agent 字节码。我当场建议他们改用编译期 AOP（@Around），因为javassist生成的类名是随机的（如SampleAgent$$_javassist_123），根本无法被ClassLoader回收。改完后，Metaspace 占用从每天增长 50MB 降到稳定在 120MB。

5.2 问题二：Agent 调用数据库时，事务不生效，出现脏读

现象：一个 Agent 先查订单状态，再根据状态决定是否发货，但并发请求下，两个 Agent 同时读到status=PENDING，都执行了发货逻辑，导致重复发货。

原因分析：@Transactional默认作用于public方法。而 BizBuddy 的AgentExecutor.execute()是public，但 Agent 的execute(Context ctx)方法是public，却没有@Transactional注解。事务传播是由调用方（AgentExecutor）控制的，不是由被调用方（Agent）控制的。如果AgentExecutor没开启事务，Agent 里的orderMapper.updateById()就是自动提交的。

解决方案：

• 统一事务管理：在AgentExecutor的execute()方法上加@Transactional(rollbackFor = Exception.class)。这样，整个 Agent 执行链路都在一个事务里。
• 明确事务边界：在 Agent 文档里强调：“所有数据库操作必须在execute()方法内完成，不要在 Tool 里开启新事务”。

注意：如果 Agent 需要调用多个微服务（如先调库存服务，再调支付服务），就不能依赖本地事务。这时要用 Saga 模式，BizBuddy 提供@Compensable注解，标记补偿方法，但这属于高级用