MyAgent

一个基于 Spring AI 实现的 AI Agent 示例程序，提供多模型、多工具、多知识库 RAG 增强的对话式 AI 服务。

特性

• 多模型支持：集成 OpenAI、DeepSeek、GLM、Qwen，支持动态切换
• 工具调用：Agent 可使用文件读写、Shell 执行、文本搜索、网页抓取、天气查询等工具
• Skill 系统：支持从目录加载自定义 Skill，扩展 Agent 能力
• 会话管理：创建/更新/删除/分页查询会话，支持会话级别工具配置
• 流式响应：基于 SSE（Server-Sent Events）的流式对话
• 知识库 & RAG：基于文档向量化的知识库管理，提供检索增强生成能力
• 配置热加载：config.yaml 文件变更自动生效，无需重启
• Web 界面：内置 Vue 3 + TypeScript 前端，提供对话、知识库管理、设置页面

界面预览

新建对话	对话
设置	知识库

内置工具

工具	能力
File	读取、写入、编辑文件
Shell	执行 Bash 命令
Grep	文本内容搜索
Glob	文件名模式匹配
WebFetch	抓取网页内容
Weather	查询城市天气（调用 wttr.in）
Skill	加载自定义技能

快速开始

1. 配置 API 密钥

通过环境变量设置 AI 提供商 API 密钥：

export OPENAI_API_KEY=sk-xxx
export DEEPSEEK_API_KEY=sk-xxx
export GLM_API_KEY=xxx
export QWEN_API_KEY=sk-xxx

API 密钥也可以在 config.yaml 中直接配置，但推荐使用环境变量。

2. 启动服务

依赖 JDK 17+

# 启动服务
./gradlew bootRun

服务启动后，访问：

• Web 界面: http://localhost:8989（需先构建前端，见下文）
• Swagger REST API 文档: http://localhost:8989/swagger-ui/index.html
• API 根路径: http://localhost:8989/api

3. 构建前端（可选，仅使用 Web 界面时需要）

前端工程位于 frontend/，构建产物输出到 src/main/resources/static，由后端直接托管。 需要先自行安装依赖并构建（需要 Node.js 20+ 与 pnpm，Gradle 不会自动构建前端）：

cd frontend
pnpm install
pnpm build           # vue-tsc 类型检查 + vite build

构建完成后执行 ./gradlew bootRun，访问 http://localhost:8989 即可打开 Web 界面。 若只用 REST API，可跳过本步骤。

前端开发时可用 Vite dev server（已配置 /api 代理到 8989，绕过 CORS）：

cd frontend
pnpm dev             # http://localhost:5173

4. 快速体验

# 创建新会话
curl -X POST http://localhost:8989/api/session/new \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "deepseek:agent", "modelId": "deepseek-v4-flash" }'

# 发送消息（同步）
curl -X POST http://localhost:8989/api/session/chat \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "deepseek:agent", "content": "查询杭州天气"}'

# 流式对话（SSE）
curl -X POST http://localhost:8989/api/session/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "deepseek:agent", "content": "查询杭州天气"}'

# 将文件 `README.md` 上传到知识库
curl -X POST http://localhost:8989/api/knowledge/kb/upload/file \
  -H "Content-Type: multipart/form-data" --form "file=@README.md"

# 使用知识库，增强大模型的对话生成（RAG）
curl -X POST http://localhost:8989/api/session/chat \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "deepseek:agent", "content": "MyAgent 项目有哪些内置工具？", "knowledgeId": "kb" }'

其他接口调用示例，参见 api-test.http 文件。

配置说明

1. 应用配置 (application.yaml)

主要配置项：

myagent:
  data-dir: ~/myagent              # 默认数据目录，目录下包含 SQLite 文件、config.yaml、skills目录、知识库文件上传目录等
  db-file: data.sqlite             # SQLite 数据库文件名
  config-file: config.yaml         # Agent 配置文件名
  skills-dir: ~/myagent/skills, ~/.agents/skills   # skills目录，多个用逗号分隔
  knowledge:
    vector-db-file: vectordb.json  # 向量数据库文件名
    upload-file-dir: files         # 知识库文件上传目录
  env:
    # API_KEY 环境变量名
    openai-api-key: OPENAI_API_KEY
    deepseek-api-key: DEEPSEEK_API_KEY
    glm-api-key: GLM_API_KEY
    qwen-api-key: QWEN_API_KEY

另有 dev profile 配置（application-dev.yaml），将数据目录指向项目内的 data/ 并开启 debug 日志，可用 --spring.profiles.active=dev 启用。

完整的 application.yaml 配置文件参见 application.yaml。

2. Agent 配置 (config.yaml)

默认位置在 ~/myagent/config.yaml，主要配置项：

default:
  # 默认会话配置
  session:
    model-id: deepseek-v4-flash
    tools: [ File, Shell, Glob, Grep, WebFetch, Skill ]
  # 默认嵌入模型配置
  embedding:
    provider-id: GLM
    model-id: embedding-3
    dimensions: 256
  max-tool-rounds: 20   # 单轮对话中工具调用的最大轮数

# 模型提供商配置
providers:
  - id: DeepSeek
    name: DeepSeek
    base-url: https://api.deepseek.com
    api-key: ${DEEPSEEK_API_KEY}
    models:
      # 模型列表
      - id: deepseek-v4-flash
        name: DeepSeek V4 Flash
      - id: deepseek-v4-pro
        name: DeepSeek V4 Pro
  - id: GLM
    name: 智谱GLM
    base-url: https://open.bigmodel.cn/api/paas/v4
    api-key: ${GLM_API_KEY}
    models:
      - id: glm-5
      - id: glm-5.1
      - id: embedding-3
        type: embedding

• 完整的默认配置文件参见 config.yaml。服务首次启动时，该文件会自动拷贝到 ~/myagent/config.yaml 。
• 模型提供商 provider 的 id 必须是 DeepSeek、OpenAI、GLM、Qwen 中的一个，否则无法识别。 若某模型提供商提供兼容 OpenAI 的接口，可以将 id 配置为 OpenAI，其他配置项根据实际情况填写。
• 若要服务正常运行，config.yaml 设置的默认模型的 API_KEY，必须先配置对应的环境变量或直接在 config.yaml 中设置，若同时配置，环境变量优先。
• 修改 config.yaml 后配置会自动热加载，无需重启服务。

API 概览

服务启动后，可以访问完整的 Swagger REST API 文档：http://localhost:8989/swagger-ui/index.html

配置相关

方法	路径	说明
GET	/api/config/models	获取可用模型列表
POST	/api/config/switch-model	切换默认模型
GET	/api/config/tools	获取内置工具列表
GET	/api/config/skills	获取可加载的技能列表
POST	/api/config/reload	重新加载 config.yaml 配置

会话相关

方法	路径	说明
POST	/api/session/page	分页查询会话列表
GET	/api/session/{sessionId}	获取会话详情
POST	/api/session/new	创建新会话
POST	/api/session/update	更新会话，包括标题和模型
DELETE	/api/session/{sessionId}	删除会话
GET	/api/session/{sessionId}/message/all	获取会话所有消息
GET	/api/session/{sessionId}/req-resp/{messageId}	获取消息对（用户请求+AI响应）

• 新建/更新会话时可通过 tools 指定工具列表：不传则使用默认工具；包含 NONE 或为空数组表示不使用工具；包含 FULL 表示启用全部内置工具。
• 会话 sessionId、modelId 长度不超过 32 字符，title 不超过 30 字符。

对话相关

方法	路径	说明
POST	/api/session/chat	同步对话
POST	/api/session/chat/stream	流式对话（SSE）

• 请求体 { sessionId, content, knowledgeId? }，其中 knowledgeId 非必传，指定后本轮对话使用该知识库进行 RAG 增强。

流式事件类型：

事件	说明
MSG	消息内容片段
DONE	单条消息完成
SESSION	会话信息更新（自动生成标题时触发）
ERROR	流已建立后发生异常，内容为 {code,msg}
END	所有消息完成，流结束

知识库相关

方法	路径	说明
GET	/api/knowledge/list	查询知识库列表
GET	/api/knowledge/{knowledgeId}	查询知识库详情
POST	/api/knowledge/new	创建知识库
POST	/api/knowledge/update	更新知识库
DELETE	/api/knowledge/{knowledgeId}	删除知识库
GET	/api/knowledge/{knowledgeId}/doc/list	查询知识库文档列表
GET	/api/knowledge/{knowledgeId}/{docId}	查询知识库文档详情
POST	/api/knowledge/{knowledgeId}/upload/file	添加文档文件到知识库
POST	/api/knowledge/{knowledgeId}/upload/text	添加纯文本到知识库
POST	/api/knowledge/{knowledgeId}/{docId}/embed	（重新）向量化知识库文档
DELETE	/api/knowledge/{knowledgeId}/{docId}	删除知识库文档
GET	/api/knowledge/file/{fileKey}	下载知识库文件

• 上传的文档文件，基于 Apache Tika 库实现文本提取，格式支持包括 pdf、doc/docx、ppt/pptx、html、txt 等，完整支持格式列表参见 Apache Tika。

数据库表设计

表名	说明
t_session	会话表
t_session_message	会话消息表
t_knowledge	知识库表
t_knowledge_doc	知识库文档表

• 完整表定义参见 schema.sql。
• 服务运行时使用 SQLite 数据库，内嵌数据库，无需额外配置。
• 向量检索依赖 sqlite-vec 扩展，首次启动时会通过 vec0-install.sh 自动安装。

技术栈

后端

组件	版本	用途
Java	17+	运行环境
Spring Boot	4.1.0	应用框架
Spring AI	2.0.1	AI 集成框架
Spring AI Agent Utils	0.10.0	Agent 工具（File、Shell、Grep 等）
MyBatis-Plus	3.5.15	ORM 持久层
SQLite	3.53	关系型数据库
sqlite-vec	—	基于 SQLite 扩展的向量检索
SpringDoc OpenAPI	3.0.3	API 文档 / Swagger UI

前端

组件	版本	用途
Vue	3.5	前端框架
TypeScript	6.0	类型系统
Vite	8.3	构建工具
Pinia	4.0	状态管理
Vue Router	5.3	路由
markdown-it	15.0	Markdown 渲染
highlight.js	11.12	代码高亮

许可证

MIT