一、为什么做这个项目？

在做完 PromptCraft 提示词管理平台后，我开始思考：如何让 AI 不只是“回答问题”，而是能“动手执行任务”？

正好看到小红书的 Agent 工程实习生招聘，要求具备工具调用、任务编排、可观测性等能力。于是决定用 Java + Spring Boot + LangChain4j 从零搭建一个轻量级 Agent 引擎，命名为 Hermes（希腊神话中的众神使者，象征信息传递与任务执行）。

二、项目目标

• 实现自然语言驱动的数据库查询（用户说“查标签”，AI 自动查库并返回）

• 支持多工具注册与智能路由（标签/用户/提示词三张表）

• 对比手动解析与框架自动调用两种实现方式

• 为后续的 L2（多步推理）、L3（可靠性）、L4（可观测）打基础

三、技术栈

• Java 21 + Spring Boot 3.x

• LangChain4j 0.36.2（Java 生态的 AI 框架）

• DeepSeek API（通过硅基流动调用）

• MySQL 8.0 + JDBC Template

• Maven + IDEA

四、核心设计

4.1 整体架构

用户请求 → Controller → AI 决策（DeepSeek）→ 工具执行（DatabaseTool）→ 结果返回

 

4.2 工具抽象层

将数据库查询封装为统一工具接口，支持动态注册：
 

@Component
public class DatabaseTool {
    public List<Map<String, Object>> queryAllTags() { ... }
    public List<Map<String, Object>> queryAllUsers() { ... }
    public List<Map<String, Object>> queryAllPrompts() { ... }
}

4.3 两种实现方式

方式	实现	特点
路径 A	手动构建 Prompt，解析 AI 返回的 JSON	透明可控，适合理解原理
路径 B	使用 @SystemMessage + AiServices	代码简洁，适合生产环境

4.4 L1 工作流程

1. 用户输入：“帮我查一下标签”
2. 构建 Prompt 发送给 DeepSeek
3. AI 返回：{"tool": "queryAllTags", "params": {}}
4. 解析 JSON，提取工具名
5. 执行 DatabaseTool.queryAllTags()，查询 MySQL
6. 将结果再次发送给 AI，组织成自然语言
7. 返回给用户

4.5 L2 多步推理（ReAct 循环）

通过 while 循环支持 AI 连续调用多个工具：

while (step < maxSteps) {
    // 1. 调用 AI 决策
    // 2. 判断是否结束（final）
    // 3. 解析工具名并执行
    // 4. 结果拼回 Prompt，继续循环
}

五、踩坑记录

坑 1：LangChain4j 版本与注解不兼容

0.30.0 和 0.36.2 版本的 API 差异较大，@AiService 在部分环境中报红。

解决方案：手动用 AiServices.builder() 创建 Bean，绕过注解扫描。

坑 2：IDEA 索引与 Maven 不一致

依赖已下载，但 IDEA 持续报红。

解决方案：删除 .idea 文件夹，用 Maven 面板执行 clean → compile，确认编译通过后再重启 IDEA。

坑 3：数据库字段不匹配

user 表中没有 email 字段，SQL 执行报错。

解决方案：使用 DESC user; 查看真实表结构，修改 SQL 为 id, username, nickname, status。

六、成果与总结

已实现功能：

• ✅ L1 工具调用（标签/用户/提示词三种查询）

• ✅ L2 ReAct 多步推理（循环执行，支持多轮工具调用）

• ✅ 两种实现方案（手动 + 框架）

• ✅ 统一接口规范（Result 封装 + 全局异常处理）

未完成功能（后续规划）：

• ⬜ L3 可靠性机制（重试/降级/回退）

• ⬜ L4 可观测性（全链路追踪 + 会话回放）

个人收获：

• 深入理解了 Agent 的核心机制：AI 做决策，后端做执行

• 掌握了 Tool Calling 的两种实现方式及各自的适用场景

• 学会了从“传统 CRUD 思维”向“AI 编排思维”转变

• 为后续投递 Agent 工程岗位积累了扎实的项目经验

项目已开源：https://gitee.com/luo-ziqi_luoziqi/hermes.git