# Agent

**Repository Path**: bing910207/agent

## Basic Information

- **Project Name**: Agent
- **Description**: Agent 智能体平台，基于 Java 21、Spring Boot、Vue 3、Naive UI、PostgreSQL + pgvector 构建，支持模型接入、知识库 RAG、Agent 对话、工具调用、数据库查询、工作流编排、流式输出和调用日志追踪，适用于企业知识库问答与大模型应用开发。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent 智能体平台

Agent 智能体平台是一个面向企业内部 AI 应用建设的智能体管理与编排系统。项目围绕“模型接入、知识库构建、智能体问答、工具调用、数据库查询、工作流编排、调用追踪”这条主线展开，目标是把大模型能力从单次问答扩展为可配置、可追踪、可组合的业务智能体平台。

当前版本已经具备完整 MVP 能力：可以接入通义千问、OpenAI Compatible 或公司自部署模型；可以构建 pgvector 知识库；可以创建普通问答 Agent、知识库问答 Agent、工具型 Agent；可以通过工作流把知识库、模型和工具串联成确定性流程。

详细配置和使用步骤请参考：[docs/Instructions-for-Use.md](docs/Instructions-for-Use.md)。

目前处于项目初期阶段，后续会持续迭代版本

## 核心能力

- 模型供应商管理：支持 OpenAI / OpenAI Compatible 协议供应商配置，支持通义千问、公司自部署模型等兼容服务接入，API Key 加密存储。
- 模型管理：支持 Chat、Embedding、Rerank 等模型元数据配置，可维护上下文窗口、最大输出、向量维度、流式输出、工具调用等能力标识。
- 模型测试：支持 Chat 与 Embedding 连通性测试，Chat 支持 SSE 流式输出，展示耗时、Token Usage，并使用 Markdown 渲染模型回答。
- 知识库管理：支持知识库 CRUD、Embedding 模型绑定、chunk 参数、TopK 与相似度阈值配置。
- 文档处理：支持 txt、md、pdf 上传、解析、清洗、切片、向量化和异步处理。
- pgvector 检索：基于 PostgreSQL + pgvector 实现 TopK 相似片段检索，支持 RAG 命中日志追踪。
- Agent 管理：支持 Agent CRUD、模型绑定、系统提示词、上下文轮数、上下文记忆、启停配置。
- 普通 Agent 问答：未绑定知识库时，Agent 可直接基于模型能力进行通用问答。
- Agent + RAG 对话：对话时自动检索 Agent 绑定知识库，命中内容后注入上下文并展示引用来源。
- 上下文记忆：支持历史消息拼接和上下文长度控制，支持按 Agent 配置上下文轮数。
- SSE 流式输出：支持模型测试和 Agent 对话流式输出；绑定工具时通过 `tool_call`、`tool_result` 和最终回答事件展示工具调用过程。
- Markdown 回答渲染：模型测试、Agent 对话、工作流执行结果均使用 Markdown 渲染，支持标题、列表、代码块、表格、引用等常见格式。
- HTTP 工具调用：支持工具定义、测试执行、Agent 工具绑定、模型 tool calls 执行循环。
- 数据库查询工具：支持 MySQL、PostgreSQL、SQL Server，只读 SQL 查询和数据库结构查询，适合构建“自然语言问数据库”能力。
- 工作流编排：支持 START、KNOWLEDGE_SEARCH、LLM、TOOL、CONDITION、END 节点，支持条件表达式、连线校验、节点拖拽、Shift 多选/框选、多选移动、自动布局、复制粘贴、画布平移缩放和执行轨迹高亮。
- 日志追踪：支持模型调用日志、RAG 命中日志、requestId / agentId / conversationId 业务链路追踪。
- 基础治理：支持管理写接口权限拦截、基础限流、统一前端接口错误处理。

## 项目结构

```text
Agent/
├── AgentServer/                         # 后端服务，Spring Boot
│   ├── src/main/java/com/zb/agentplatform
│   │   ├── agent/                       # Agent 管理与 Agent 对话
│   │   ├── agentknowledgebase/          # Agent 与知识库绑定
│   │   ├── agenttool/                   # Agent 与工具绑定
│   │   ├── conversation/                # 会话管理
│   │   ├── dashboard/                   # 控制台统计
│   │   ├── documentparse/               # 文档解析
│   │   ├── documentprocess/             # 文档清洗、切片、向量化
│   │   ├── knowledgebase/               # 知识库管理
│   │   ├── knowledgechunk/              # 知识片段与向量检索
│   │   ├── knowledgedocument/           # 知识库文档管理
│   │   ├── knowledgeretrieval/          # RAG 检索服务
│   │   ├── llm/                         # LLM Gateway 与 OpenAI Compatible Client
│   │   ├── model/                       # 模型管理
│   │   ├── modellog/                    # 模型调用日志
│   │   ├── modelprovider/               # 模型供应商管理
│   │   ├── modeltest/                   # 模型连通性测试
│   │   ├── raghitlog/                   # RAG 命中日志
│   │   ├── security/                    # API Key 加密、权限、限流
│   │   ├── tool/                        # 工具管理与工具执行
│   │   └── workflow/                    # 工作流编排与执行
│   └── src/main/resources/db/migration  # Flyway 数据库迁移脚本
├── AgentWeb/                            # 前端管理端，Vue 3 + Naive UI
│   ├── src/api/                         # API 封装
│   ├── src/components/                  # 通用组件
│   ├── src/router/                      # 路由
│   ├── src/stores/                      # Pinia 状态
│   └── src/views/                       # 页面模块
├── docs/                                # 使用手册与过程文档
├── UI风格参考图/                         # UI 风格参考素材，本地按需维护
├── ai-agent-platform-pgvector-workflow.md
└── README.md
```

## 技术架构

### 后端

- Java 21
- Spring Boot 3.3.x
- Spring MVC / WebFlux
- MyBatis Plus
- Flyway
- PostgreSQL + pgvector
- Apache PDFBox
- OpenAI Compatible API Client
- JUnit 5

### 前端

- Vue 3
- TypeScript
- Vite
- Naive UI
- Pinia
- Axios
- markdown-it + DOMPurify

### 数据与模型

- PostgreSQL 15+
- pgvector extension
- OpenAI / OpenAI Compatible 协议模型
- Chat 模型、Embedding 模型
- 支持 MySQL、PostgreSQL、SQL Server 数据库查询工具

## 环境要求

- JDK 21+
- Maven 3.9+
- Node.js 20+
- npm 10+
- PostgreSQL 15+
- pgvector

数据库需要提前启用 pgvector：

```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

当前开发环境默认数据库配置：

```text
Host: <数据库主机>
Port: 5432
Database: agent
Username: agent
Password: <数据库密码>
```

配置文件位置：

```text
AgentServer/src/main/resources/application-dev.yml
```

可通过环境变量覆盖：

```bash
DB_HOST=<数据库主机>
DB_PORT=5432
DB_NAME=agent
DB_USERNAME=agent
DB_PASSWORD=<数据库密码>
```

## 功能模块

### 控制台

展示模型供应商、模型、智能体、知识库等核心资源数量，用于快速确认系统配置完整度。

### 模型中心

- 模型供应商：配置 OpenAI / OpenAI Compatible 供应商，保存 Base URL、API Key、协议类型、超时时间等信息。
- 模型管理：维护 Chat、Embedding、Rerank 等模型元数据，配置上下文窗口、最大输出、向量维度、流式输出、工具调用能力等。
- 模型测试：支持 Chat 和 Embedding 连通性测试，Chat 支持 SSE 流式输出，回答内容使用 Markdown 渲染。
- 调用日志：记录模型调用链路、耗时、Token、成功状态、错误信息、会话和 Agent 关联信息。

### 知识库

- 知识库管理：创建知识库，绑定 Embedding 模型，配置切片长度、重叠长度、TopK、相似度阈值。
- 知识库文档：上传 txt、md、pdf 文档，完成解析、清洗、切片、向量化和 pgvector 入库。
- 检索测试：对知识库进行向量检索测试，查看命中片段、相似度、元数据。

### Agent

- Agent 管理：创建智能体，绑定 Chat 模型，配置系统提示词、上下文记忆、温度、TopP、最大输出等。
- Agent 知识库：将知识库绑定给指定 Agent，形成 RAG 问答能力。
- Agent 工具：将工具绑定给指定 Agent，使模型可以在对话中自主触发工具调用。
- Agent 对话：支持普通问答、RAG 问答、工具调用问答和 SSE 流式输出。没有绑定知识库时，Agent 会直接走通用模型问答；命中知识库时才进入 RAG 提示。

### 工具管理

- HTTP 工具：封装 HTTP API，支持请求方法、URL、Header、参数 Schema、超时等配置。
- 数据库查询工具：支持 MySQL、PostgreSQL、SQL Server。Agent 可根据用户问题生成只读 SQL 查询并格式化回答。
- 工具测试：工具创建后可独立测试，确认接口、数据库连接和参数 Schema 可用。

### 工作流编排

通过可视化流程把模型、知识库、工具组合成固定执行链路。当前支持节点：

- `START`
- `KNOWLEDGE_SEARCH`
- `LLM`
- `TOOL`
- `CONDITION`
- `END`

适合流程明确、需要可追踪、可复用的业务场景，例如“先查数据库结构，再生成 SQL，再执行查询，再格式化答案”。

### 日志追踪

- 模型调用日志：追踪模型调用耗时、Token 和错误信息。
- RAG 命中日志：追踪知识库检索命中片段、相似度、requestId、agentId、conversationId。
- 工作流执行轨迹：记录每个节点输入输出、连线命中和最终结果。

## 本地启动

### 后端启动

```bash
cd AgentServer
mvn spring-boot:run
```

默认地址：

```text
http://127.0.0.1:8080
```

健康检查：

```text
GET http://127.0.0.1:8080/actuator/health
```

### 前端启动

```bash
cd AgentWeb
npm install
npm run dev -- --host 127.0.0.1
```

默认地址：

```text
http://127.0.0.1:5173
```

前端开发代理：

```text
/api -> http://127.0.0.1:8080
```

## 打包部署

### 后端打包

```bash
cd AgentServer
mvn clean package -DskipTests
```

启动 Jar：

```bash
java -jar target/agent-platform-server-0.0.1-SNAPSHOT.jar
```

生产环境建议通过环境变量注入：

```bash
SPRING_PROFILES_ACTIVE=prod
SERVER_PORT=8080
DB_HOST=数据库地址
DB_PORT=5432
DB_NAME=agent
DB_USERNAME=agent
DB_PASSWORD=******
KNOWLEDGE_UPLOAD_DIR=/data/agent/uploads/knowledge
```

### 前端打包

```bash
cd AgentWeb
npm install
npm run build
```

构建产物：

```text
AgentWeb/dist/
```

部署建议：

- 使用 Nginx 托管 `dist/`
- 将 `/api` 反向代理到后端服务
- 示例：

```nginx
server {
    listen 80;
    server_name agent.example.com;

    root /opt/agent/AgentWeb/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8080/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

### 数据库迁移

后端使用 Flyway 管理数据库结构，迁移脚本位于：

```text
AgentServer/src/main/resources/db/migration
```

服务启动时会自动执行未应用的迁移脚本。

## 使用手册

配置模型供应商、模型、知识库、Agent、工具、数据库查询工具和工作流，请参考：

[docs/Instructions-for-Use.md](docs/Instructions-for-Use.md)

该手册包含完整配置步骤、示例参数和页面截图索引。

## 常用验证命令

```bash
cd AgentServer
mvn test
```

```bash
cd AgentWeb
npm run build
```

```powershell
Invoke-WebRequest http://127.0.0.1:8080/actuator/health -UseBasicParsing
```

## 当前状态

当前项目已经完成智能体平台核心闭环，具备继续扩展为企业内部 AI 应用底座的基础。后续可继续加强：

- 更完整的端到端测试
- 更细粒度的权限、审计和多用户体系
- 工作流节点模板和版本管理
- 工具市场与工具权限隔离
- 更完善的模型供应商参数适配