文章目录1. 架构概览2. 环境准备2.1 MySQL 安装2.2 创建数据库3. 项目配置3.1 Maven 依赖3.2 schema.sql — 建表3.3 相关配置3.3.1 应用配置application.yml3.3.2 JDBC 分布式存储配置3.4 构建 HarnessAgent4. 工作原理4.1 命名空间路由4.2 数据读写流程4.3 Overlay 模式5. 验证5.1 启动服务5.2 发送对话5.3 检查 .agentscope5.4 检查 MySQL 数据将AgentScope HarnessAgent的工作区从本地磁盘迁移到MySQL实现多实例共享记忆、技能、会话日志。1. 架构概览┌───────────────┐ ┌───────────────┐ │ 实例 A │ │ 实例 B │ │ HarnessAgent │ │ HarnessAgent │ └───────┬───────┘ └───────┬───────┘ │ │ └──────────┬──────────┘ │ ┌────────▼────────┐ │ MySQL Server │ │ │ │ agentscope_store │ ← 工作区 KVJdbcStore │ agent_state │ ← Agent 会话状态MysqlAgentStateStore └──────────────────┘核心组件组件作用存储位置JdbcStore工作区文件 KV 存储MEMORY.md、skills、sessions 等agentscope_store表MysqlAgentStateStoreAgent 会话状态持久化agent_state表框架自动创建RemoteFilesystemSpec将工作区路由到远程存储配置层不存数据2. 环境准备2.1 MySQL 安装# Docker 方式推荐dockerrun-d--namemysql-agentscope\-eMYSQL_ROOT_PASSWORDroot123\-eMYSQL_DATABASEagentscope\-p3306:3306\mysql:8.0\--character-set-serverutf8mb4 --collation-serverutf8mb4_unicode_ci2.2 创建数据库CREATEDATABASEIFNOTEXISTSagentscopeDEFAULTCHARACTERSETutf8mb4DEFAULTCOLLATEutf8mb4_unicode_ci;3. 项目配置3.1 Maven 依赖在pom.xml中添加!-- AgentScope Harness --dependencygroupIdio.agentscope/groupIdartifactIdagentscope-harness/artifactIdversion2.0.0-RC2/version/dependency!-- AgentScope MySQL 扩展提供 JdbcStore MysqlAgentStateStore --dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-mysql/artifactIdversion2.0.0-RC2/version/dependency!-- Spring Boot JDBC --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-jdbc/artifactId/dependency!-- MySQL 驱动 --dependencygroupIdcom.mysql/groupIdartifactIdmysql-connector-j/artifactIdscoperuntime/scope/dependency3.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_jsonLONGTEXTNOTNULLCOMMENTJSON 序列化的值,versionBIGINTNOTNULLDEFAULT0COMMENT乐观锁版本号,updated_atBIGINTNOTNULLDEFAULT0COMMENT更新时间epoch millis,PRIMARYKEY(namespace_path,item_key))ENGINEInnoDBDEFAULTCHARSETutf8mb4;3.3 相关配置3.3.1 应用配置application.ymlserver:port:8090spring:application:name:agentscope-demodatasource:url:jdbc:mysql://localhost:3306/agentscope?useSSLfalseallowPublicKeyRetrievaltrueserverTimezoneUTCdriver-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全套承载DistributedStorestoreRedisDistributedStore.fromJedis(jedis);示例2混合异构存储MySQL存业务数据Redis做沙箱控制DistributedStorestoreDistributedStore.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时配置本地文件工作区注入分布式存储启用远程文件系统BaseStore自动注入ConfigurationpublicclassAgentScopeConfig{// HarnessAgent BeanpublicHarnessAgentharnessAgent(Modelmodel,DistributedStorestore,Toolkittoolkit){PathworkspacePathPaths.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表的不同命名空间工作区路径MySQL namespace_path 前缀AGENTS.md、MEMORY.md、tools.jsonagents/harness-demo/users/uid/rootmemory/.../memoryskills/.../skillssubagents/.../subagentsknowledge/.../knowledgeagents/id/sessions/.../sessionsagents/id/tasks/.../tasks每个namespace_path段之间用ASCII0x1FUnit 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.mdcopy-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: tableagentscope_store, dialect... HarnessAgent built: nameharness-demo (JDBC RemoteFilesystem mode)5.2 发送对话curlhttp://localhost:8090/agent/harness/call?query今天天气怎么样userIddemosessionIdtest-0015.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 | {...}