Agent Scope Java 2.x 系列【18】Harness：从零搭建 MySQL 工作区

将AgentScope HarnessAgent的工作区从本地磁盘迁移到MySQL，实现多实例共享记忆、技能、会话日志。

1. 架构概览

┌───────────────┐ ┌───────────────┐ │ 实例 A │ │ 实例 B │ │ HarnessAgent │ │ HarnessAgent │ └───────┬───────┘ └───────┬───────┘ │ │ └──────────┬──────────┘ │ ┌────────▼────────┐ │ MySQL Server │ │ │ │ agentscope_store │ ← 工作区 KV（JdbcStore） │ agent_state │ ← Agent 会话状态（MysqlAgentStateStore） └──────────────────┘

核心组件：

2. 环境准备

2.1 MySQL 安装

# Docker 方式（推荐）dockerrun-d--namemysql-agentscope\-eMYSQL_ROOT_PASSWORD=root123\-eMYSQL_DATABASE=agentscope\-p3306:3306\mysql:8.0\--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

2.2 创建数据库

CREATEDATABASEIFNOTEXISTSagentscopeDEFAULTCHARACTERSETutf8mb4DEFAULTCOLLATEutf8mb4_unicode_ci;

3. 项目配置

3.1 Maven 依赖

在pom.xml中添加：

<!-- AgentScope Harness --><dependency><groupId>io.agentscope</groupId><artifactId>agentscope-harness</artifactId><version>2.0.0-RC2</version></dependency><!-- AgentScope MySQL 扩展（提供 JdbcStore + MysqlAgentStateStore） --><dependency><groupId>io.agentscope</groupId><artifactId>agentscope-extensions-mysql</artifactId><version>2.0.0-RC2</version></dependency><!-- Spring Boot JDBC --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-jdbc</artifactId></dependency><!-- MySQL 驱动 --><dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><scope>runtime</scope></dependency>

3.2 schema.sql — 建表

文件路径：src/main/resources/schema.sql

-- JdbcStore KV 表-- 关键：MySQL utf8mb4 下联合主键最大 3072 字节-- VARCHAR(300) + VARCHAR(200) = 500 字符 × 4 字节 = 2000 字节，安全落在限制内CREATETABLEIFNOTEXISTSagentscope_store(namespace_pathVARCHAR(300)NOTNULLCOMMENT'命名空间路径，用 0x1F 分隔',item_keyVARCHAR(200)NOTNULLCOMMENT'条目 Key',value_jsonLONGTEXTNOTNULLCOMMENT'JSON 序列化的值',versionBIGINTNOTNULLDEFAULT0COMMENT'乐观锁版本号',updated_atBIGINTNOTNULLDEFAULT0COMMENT'更新时间（epoch millis）',PRIMARYKEY(namespace_path,item_key))ENGINE=InnoDBDEFAULTCHARSET=utf8mb4;

3.3 相关配置

3.3.1 应用配置：application.yml

server:port:8090spring:application:name:agentscope-demodatasource:url:jdbc:mysql://localhost:3306/agentscope?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTCdriver-class-name:com.mysql.cj.jdbc.Driverusername:rootpassword:${MYSQL_PASSWORD:root123}sql:init:mode:alwaysschema-locations:classpath:schema.sqlagentscope:api-key:${DASHSCOPE_API_KEY:your-api-key}

3.3.2 JDBC 分布式存储配置

DistributedStore：分布式持久化存储组件一站式统一配置入口

解决痛点：不用分别单独注入AgentStateStore、BaseStore、沙箱快照、沙箱锁四类组件，统一封装后传给HarnessAgent.Builder一键挂载存储体系。

示例1：同介质统一存储（Redis全套承载）：

DistributedStorestore=RedisDistributedStore.fromJedis(jedis);

示例2：混合异构存储（MySQL存业务数据，Redis做沙箱控制）：

DistributedStorestore=DistributedStore.builder().agentStateStore(mysqlStore.agentStateStore()).baseStore(mysqlStore.baseStore()).sandboxSnapshotSpec(redisStore.sandboxSnapshotSpec()).sandboxExecutionGuard(redisStore.sandboxExecutionGuard()).build();

这里，使用配置Agent会话状态、工作区使用JDBC存储：

@ConfigurationpublicclassAgentScopeConfig{// ==================== JDBC 分布式存储 ====================@BeanpublicDistributedStoredistributedStore(DataSourcedataSource){returnDistributedStore.builder()// Agent 会话状态走 MySQL（自动建表）.agentStateStore(newMysqlAgentStateStore(dataSource,true))// 工作区文件 KV 走 MySQL（表由 schema.sql 创建，不自动建表）.baseStore(JdbcStore.builder(dataSource).initializeSchema(false).build()).build();}}

3.4 构建 HarnessAgent

构建HarnessAgent时配置：

1. 本地文件工作区
2. 注入分布式存储
3. 启用远程文件系统（BaseStore自动注入）

@ConfigurationpublicclassAgentScopeConfig{// ==================== HarnessAgent ====================@BeanpublicHarnessAgentharnessAgent(Modelmodel,DistributedStorestore,Toolkittoolkit){PathworkspacePath=Paths.get(System.getProperty("user.home"),".agentscope","workspace","demo-agent");try{java.nio.file.Files.createDirectories(workspacePath);}catch(Exceptionignored){}returnHarnessAgent.builder().name("harness-demo").model(model).workspace(workspacePath).toolkit(toolkit).sysPrompt("你是一个有用的 AI 助手。")// 注入分布式存储.distributedStore(store)// 启用远程文件系统（BaseStore 自动注入）.filesystem(newRemoteFilesystemSpec().isolationScope(IsolationScope.USER)).maxIters(5).build();}}

在CompositeFilesystem实例中，可以看到优先使用【远程文件系统】：

4. 工作原理

4.1 命名空间路由

RemoteFilesystemSpec将工作区目录按路径前缀分片路由到agentscope_store表的不同命名空间：

每个namespace_path段之间用ASCII0x1F（Unit Separator）分隔，支持前缀搜索。

4.2 数据读写流程

Agent 读取 AGENTS.md │ ├─ RemoteFilesystem.read("AGENTS.md") │ └─ JdbcStore.get(["agents","harness-demo","users","uid","root"], "AGENTS.md") │ └─ SELECT value_json FROM agentscope_store │ WHERE namespace_path = 'agentsharness-demousersuidroot' │ AND item_key = 'AGENTS.md' │ ├─ 如果远程没有 → 回退到本地工作区模板文件（Overlay 下层） │ Agent 写入 MEMORY.md（copy-on-write） │ └─ RemoteFilesystem.write("MEMORY.md", content) └─ JdbcStore.put(["agents","harness-demo","users","uid","root"], "MEMORY.md", value) └─ UPDATE ... SET value_json = ?, version = version + 1 WHERE namespace_path = ? AND item_key = ?

4.3 Overlay 模式

每条路由采用双层结构：

• 上层（RemoteFilesystem）：可读写，数据存入MySQL，用户修改的版本在这里
• 下层（LocalFilesystem，只读）：本地工作区模板文件作为基线

Agent读取时优先取上层（MySQL），上层没有则回退到下层（本地模板）。写入始终去上层。

5. 验证

5.1 启动服务

mvn spring-boot:run-plagentscope-demo

观察日志确认没有报错：

JdbcStore built: table=agentscope_store, dialect=... HarnessAgent built: name=harness-demo (JDBC RemoteFilesystem mode)

5.2 发送对话

curl"http://localhost:8090/agent/harness/call?query=今天天气怎么样&userId=demo&sessionId=test-001"

5.3 检查 .agentscope

本地磁盘并不是没有任何数据，有些数据会永远同步写入本地磁盘：

5.4 检查 MySQL 数据

-- 查看命名空间分布SELECTnamespace_path,COUNT(*)ASitemsFROMagentscope_storeGROUPBYnamespace_pathORDERBYnamespace_path;-- 查看具体条目SELECTnamespace_path,item_key,LEFT(value_json,100)ASpreview,versionFROMagentscope_storeORDERBYnamespace_path,item_key;

预期会看到类似数据：

namespace_path | item_key | preview agents/harness-demo/users/demo/root/ | MEMORY.md | {"content":"...","encoding":"utf-8"} agents/harness-demo/users/demo/sessions/ | test-001.log | {...}