Hello Agents

Hello Agents

Hello Agents 是一个从0到1原生构建、基于 Java 和 Spring Boot 的现代化 AI 智能体（Agent）开发框架。它旨在简化构建具有高级记忆能力、工具使用能力和 RAG（检索增强生成）功能的智能体应用。

✨ 特性

• 多智能体架构：内置 ReAct Agent 和 MCAgent（Memory Classification Agent），支持复杂的推理和任务执行。
• 高级记忆系统：

- 多层级记忆：支持工作记忆（Working）、情景记忆（Episodic）、语义记忆（Semantic）和感知记忆（Perceptual）。 - 持久化存储：集成 Redis Stack（向量存储）和 Neo4j（图存储）以实现高效的记忆检索和关联。

• RAG (检索增强生成)：

- 内置文档处理流程（基于 Apache Tika）。 - 支持文档切片、向量化和语义检索。

• MCP 协议支持：集成 Model Context Protocol (MCP)，可轻松扩展外部工具（如高德地图）。
• 工具生态：

- 内置 Google Search (SerpApi)。 - 支持自定义工具注册和调用。

• 模型兼容性：

- 支持 OpenAI 兼容接口（如 DeepSeek）。 - 支持 Alibaba DashScope。

🛠️ 技术栈

• 语言: Java 21
• 框架: Spring Boot 3.5.8
• 数据存储:

- Redis (Vector Store) - Neo4j (Graph Database)

• AI SDK:

- OpenAI Java SDK - DashScope SDK - MCP SDK

🚀 快速开始

1. 环境准备 (Docker 快速部署)

如果您本地没有安装 Redis Stack 或 Neo4j，可以使用以下 Docker 命令快速启动：

启动 Redis Stack (支持向量检索):

docker run -d \
  --name redis-stack-server \
  -p 6379:6379 \
  -e REDIS_ARGS="--bind 0.0.0.0 --protected-mode no" \
  redis/redis-stack-server

启动 Neo4j (图数据库):

docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  -e NEO4J_dbms_default__listen__address=0.0.0.0 \
  -e NEO4J_dbms_connector_bolt_listen__address=0.0.0.0:7687 \
  -e NEO4J_dbms_connector_http_listen__address=0.0.0.0:7474 \
  neo4j:latest

2. 获取 API Key

• LLM API Key: 准备好您的 OpenAI 或 DashScope (阿里云) API Key。
• SerpApi Key: 访问 SerpApi 注册账号并获取 API Key（新用户每月有免费额度），用于支持联网搜索功能。

3. 项目配置

修改 src/main/resources/application.yml 文件，配置您的 API Key 和服务地址：

agent:
  llm:
    api-key: your-deepseek-api-key # 或其他 OpenAI 兼容的 Key
    base-url: https://api.deepseek.com/v1
  dashscope:
    api-key: your-dashscope-api-key
  serpapi:
    api-key: your-serpapi-key # 填入申请的 SerpApi Key

spring:
  data:
    redis:
      host: localhost
      port: 6379
  neo4j:
    uri: bolt://localhost:7687
    authentication:
      username: neo4j
      password: password # 与 Docker 启动命令中的密码保持一致

4. ⚡️ 快速体验

无需编写代码，直接运行测试用例即可体验智能体功能：

1. 打开项目中的测试类：src/test/java/com/kylin/helloagents/app/RunAgentTest.java
2. 找到 runReActAgent 方法。
3. 点击运行（Run），观察控制台输出。智能体将自动进行思考、搜索并回答问题。

@Test
void runReActAgent() {
    String context = "2025年小米的最新款手机是哪款?";
    runAgent.runReActAgent(context);
}

5. 运行完整应用

1. 克隆仓库

git clone https://github.com/your-username/hello-agents.git
cd hello-agents

1. 构建项目

./mvnw clean install

1. 启动应用

运行 HelloAgentsApplication 主类即可启动 Spring Boot 应用。

📖 核心功能示例

项目中的 com.kylin.helloagents.app.RunAgent 类提供了核心功能的使用示例：

运行 ReAct 智能体

@Resource
private ReActAgent reActAgent;

public void runAgent() {
    reActAgent.setName("my-agent");
    reActAgent.registerTool(searchTool); // 注册搜索工具
    
    String result = reActAgent.run(sessionId, "查询一下今天北京的天气，并推荐适合的户外活动");
    System.out.println(result);
}

导入 RAG 文档

@Resource
private RagService ragService;

public void importDocs() {
    File doc = new File("path/to/document.txt");
    ragService.ingest(doc, sessionId);
}

📂 项目结构

hello-agents/
├── src/main/java/com/kylin/helloagents/
│   ├── agent/       # 智能体核心实现 (ReAct, MCAgent)
│   ├── core/        # 核心组件 (LLMClient)
│   ├── memory/      # 记忆系统 (Vector, Graph, Memory Types)
│   ├── rag/         # RAG 实现 (Ingestion, Retrieval)
│   ├── mcp/         # MCP 协议集成
│   ├── tool/        # 工具定义 (Search, RAG Tool)
│   └── app/         # 示例应用代码
└── src/main/resources/
    ├── application.yml # 配置文件
    ├── prompts/        # Prompt 模板
    └── document/       # RAG 知识库示例文档

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进本项目！

🙏 致谢

本项目的内容与设计灵感借鉴了 Datawhale 的开源项目 Hello-Agents，感谢社区提供的优秀教程与资源。

� 许可证

MIT License