OoderAI Agent V0.6 快速上手指南

OneCodeCN
98 阅读8分钟

1. 项目概述

​

ooderAI Agent V0.6 是 ooderAI superAgent 协议的示例程序，核心用途是演示协议的实际用法、验证协议逻辑可行性，同时提供可运行的基础代码、场景演示案例及全链路测试用例。本程序并非独立的分布式系统，而是对superAgent协议的具象化实现，供开发者参考协议适配方式、调试技能联动流程，为基于该协议的二次开发和业务落地提供示例支撑。

本示例程序包含三个核心技能的协议示例实现，仅用于演示superAgent协议定义的数据获取、协调、提交流程，聚焦协议功能验证，不具备生产环境部署条件：

本版本包含三个核心技能的测试实现，仅用于验证数据获取、协调、提交的基础流转闭环，不具备生产环境部署条件：

  • Skill A（协议示例实现）: 对应superAgent协议定义的信息检索技能，模拟从数据源获取信息，演示协议检索接口的适配方式。
  • Skill B（协议示例实现）: 对应superAgent协议定义的数据提交技能，模拟数据提交至目标地址，演示协议提交流程的合规实现。
  • Skill C（协议示例实现）: 对应superAgent协议定义的协调技能，作为示例调度中枢，演示协议约定的场景管理、多技能联动逻辑。

2. 环境准备

2.1 开发环境要求

需提前安装以下环境，确保版本兼容：

  • JDK 1.8+（推荐1.8或11版本，避免更高版本兼容性问题）
  • Maven 3.6+（用于项目构建与依赖管理）
  • Git（用于克隆代码仓库）

2.2 依赖组件

项目核心依赖已集成于pom.xml，无需手动下载，核心组件包括：

  • Spring Boot 2.7.0（分布式系统基础框架）
  • FastJSON 1.2.83（JSON数据序列化/反序列化）
  • Spring WebFlux（用于异步通信，提升高并发场景下的响应效率）
  • SLF4J（日志框架，统一日志输出格式）

3. 安装步骤

3.1 克隆代码库

从官方仓库克隆代码，进入指定目录：

git clone <repository-url>  # 替换为实际开源仓库地址
cd ooder-public/super-agent

3.2 构建项目

分别构建三个核心Skill模块，跳过测试环节加速构建：

# 构建Skill A（信息检索模块）
cd skill-a
mvn clean package -DskipTests

# 构建Skill B（数据提交模块）
cd ../skill-b
mvn clean package -DskipTests

# 构建Skill C（协调模块）
cd ../skill-c
mvn clean package -DskipTests

构建成功后，各模块target目录下会生成对应的jar包，可用于示例程序的演示运行。

4. 配置说明

各Skill模块独立配置，核心配置文件均为src/main/resources/application.yml，需根据实际部署环境调整参数。

4.1 Skill A 配置

文件路径：skill-a/src/main/resources/application.yml

server:
  port: 9000  # Skill A 服务端口，避免与其他服务冲突

spring:
  application:
    name: skill-a  # 服务名称，用于服务识别

skill-a:
  agent:
    id: skill-a-agent-001  # 唯一Agent ID，用于场景内身份标识
    type: skill-a  # 技能类型，固定值
  network:
    address: 127.0.0.1  # 数据源网络地址，部署时替换为实际地址
    port: 8080  # 数据源端口
  security:
    enabled: true  # 是否启用安全验证（开发环境可设为false）
    token: secret-token-001  # 安全令牌，需与Skill C保持一致

4.2 Skill B 配置

文件路径：skill-b/src/main/resources/application.yml

server:
  port: 9001  # Skill B 服务端口，与其他模块端口区分

spring:
  application:
    name: skill-b  # 服务名称

skill-b:
  agent:
    id: skill-b-agent-001  # 唯一Agent ID
    type: skill-b  # 技能类型，固定值
  network:
    address: 127.0.0.1  # 目标系统地址，部署时替换为实际地址
    port: 8081  # 目标系统端口
  security:
    enabled: true  # 安全验证开关
    token: secret-token-001  # 与Skill A、C共用同一令牌

4.3 Skill C 配置

文件路径：skill-c/src/main/resources/application.yml（协调模块核心配置）

server:
  port: 9010  # Skill C 服务端口，作为协调中枢端口

spring:
  application:
    name: skill-c  # 服务名称

skill-c:
  scene:
    id: RBC_SCENE_001  # 默认场景ID，用于数据流转场景标识
    name: Data Reporting Scene  # 场景名称
    type: data-reporting  # 场景类型，固定为数据上报类型
  agent:
    id: skill-c-agent-001  # 协调Agent唯一ID
  network:
    broadcast:
      port: 9876  # 广播端口，用于发现并联动Skill A、B

5. 运行指南

需按「协调模块→执行模块」的顺序启动服务，确保Skill C先完成初始化，为其他技能提供联动支撑。

5.1 启动Skill C（协调服务）

cd skill-c
mvn spring-boot:run

启动成功标识：控制台打印日志 Skill C coordination service started successfully。

5.2 启动Skill A（信息检索服务）

cd ../skill-a  # 从Skill C目录切换至Skill A
mvn spring-boot:run

启动成功后，Skill A会自动注册至Skill C的默认场景。

5.3 启动Skill B（数据提交服务）

cd ../skill-b  # 从Skill A目录切换至Skill B
mvn spring-boot:run

三个服务全部启动后，系统进入就绪状态，可执行数据流转操作。

6. 交互示例

通过curl命令调用各模块API，验证服务可用性与数据流转效果，支持Postman等工具替代调用。

6.1 健康检查

验证各服务是否正常运行：

# 检查Skill A健康状态
curl http://localhost:9000/api/v1/skill-a/health

# 检查Skill B健康状态
curl http://localhost:9001/api/v1/skill-b/health

# 检查Skill C健康状态
curl http://localhost:9010/api/v1/skill-c/health

返回 {"status":"UP"} 即表示服务正常。

6.2 数据检索（Skill A）

调用Skill A接口从数据源获取数据：

curl http://localhost:9000/api/v1/skill-a/retrieve

返回结果为数据源原始数据JSON格式。

6.3 数据提交（Skill B）

POST方式调用Skill B接口，提交数据至目标系统：

curl -X POST -H "Content-Type: application/json" \
  http://localhost:9001/api/v1/skill-b/submit \
  -d '{"data":{"key":"value"},"agentId":"test-agent"}'

6.4 数据流转协调（Skill C）

调用Skill C接口，触发全流程数据流转（自动调用Skill A检索、Skill B提交）：

curl -X POST -H "Content-Type: application/json" \
  http://localhost:9010/api/v1/skill-c/data/coordinate \
  -d '{"sceneId":"RBC_SCENE_001"}'

返回 {"status":"success","message":"Data flow coordinated successfully"} 即流转成功。

7. 场景管理

Skill C支持场景的动态创建与技能加入，适配多业务场景需求。

7.1 创建场景

创建新的测试场景，指定场景名称与分组ID：

curl -X POST -H "Content-Type: application/json" \
  http://localhost:9010/api/v1/skill-c/scenes/RBC_SCENE_002/groups \
  -d '{"name":"New Scene","description":"A new scene for testing","groupId":"GROUP_002"}'

7.2 加入场景

将Skill A加入已创建的场景（默认场景无需手动加入）：

curl -X POST -H "Content-Type: application/json" \
  http://localhost:9010/api/v1/skill-c/scenes/RBC_SCENE_001/join \
  -d '{"agentId":"skill-a-agent-001","type":"skill-a","endpoint":"http://localhost:9000"}'

8. 常见问题和解决方案

问题现象原因分析解决方案
服务启动失败，提示端口被占用配置文件中端口与本地其他服务冲突修改对应Skill的application.yml文件，调整server.port为未占用端口
数据流转失败，Skill C提示无法找到AgentSkill A/B未正确加入场景，或Agent ID配置错误检查场景ID是否匹配，重新启动Skill A/B，或手动调用加入场景接口
调用接口提示安全认证错误各模块安全令牌不一致，或未携带令牌确保Skill A/B/C的security.token一致；开发环境可将security.enabled设为false

9. 代码结构说明

9.1 Skill A 核心组件

  • InformationRetrievalSkill: 核心技能实现类，封装信息检索业务逻辑。
  • RpcController: REST API控制器，提供外部调用接口。
  • InformationRetrievalService: 信息检索服务层，对接数据源获取数据。
  • NetworkService: 网络通信服务，负责与Skill C的联动通信。

9.2 Skill C 核心组件

  • CoordinationService: 数据流转协调服务，核心调度逻辑实现类。
  • SceneService: 场景管理服务，负责场景创建、技能加入、场景删除等操作。
  • RpcController: REST API控制器，提供协调与场景管理接口。

10. 扩展开发

10.1 开发新技能

  1. 创建新的Spring Boot项目，命名规范为skill-{技能名称}。
  2. 实现核心技能接口，继承系统基础Skill抽象类。
  3. 配置application.yml，指定服务端口、Agent ID、网络地址及安全参数。
  4. 通过Skill C的场景加入接口，将新技能注册至目标场景，完成联动。

10.2 自定义数据处理

修改Skill C的CoordinationService类，添加自定义数据处理逻辑：

public Mono<Map<String, Object>> coordinateDataFlow(String sceneId) {
    return retrieveDataFromSkillA(sceneId)
            .flatMap(data -> {
                // 自定义数据处理逻辑（示例：数据过滤、格式转换、校验等）
                processData(data);
                return submitDataToSkillB(sceneId, data);
            })
            .doOnSuccess(result -> logger.info("Successfully coordinated data flow for scene {}", sceneId));
}

11. 监控和日志

各技能模块统一使用SLF4J日志框架，默认日志输出至控制台，支持自定义配置：

  • 日志配置文件：各模块src/main/resources/logback-spring.xml。
  • 可通过配置文件调整日志级别（DEBUG/INFO/WARN/ERROR）、输出路径、日志格式。
  • 生产环境建议将日志输出至文件，便于问题排查与追溯。

编写日期：2026-01-18

版本：V0.6

​

avatar
文章
阅读
粉丝