160 lines
4.0 KiB
Markdown
160 lines
4.0 KiB
Markdown
# Agent 页面后端接口清单
|
||
|
||
本文对应前端页面：[AgentManagePage.vue](frontend/src/pages/agent/AgentManagePage.vue) 和 [AgentDebugPage.vue](frontend/src/pages/agent/AgentDebugPage.vue)。
|
||
|
||
## 1. 页面目标
|
||
|
||
Agent 页面分为两块：
|
||
|
||
- Agent 管理：维护 `agent_definition` 基础配置（编码、名称、知识库绑定、状态、系统提示词）。
|
||
- Agent 调试：选择 Agent 发起对话，支持普通对话与 RAG 对话切换，并回显引用切片。
|
||
|
||
## 2. Agent 管理接口
|
||
|
||
### 2.1 查询全部 Agent
|
||
|
||
- `POST /api/agents/list`
|
||
|
||
返回类型：
|
||
|
||
- `RequestResult<List<AgentDefinitionResponse>>`
|
||
|
||
### 2.2 条件查询 Agent
|
||
|
||
- `POST /api/agents/query`
|
||
|
||
请求体示例：
|
||
|
||
```json
|
||
{
|
||
"agentCode": "AGENT_RAG_HELPER",
|
||
"agentName": "知识助手",
|
||
"status": "ENABLED",
|
||
"storeId": 1001
|
||
}
|
||
```
|
||
|
||
### 2.3 查询 Agent 详情
|
||
|
||
- `GET /api/agents/detail?id={id}`
|
||
|
||
### 2.4 新增或更新 Agent
|
||
|
||
- `POST /api/agents/save`
|
||
|
||
请求体示例：
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"agentCode": "AGENT_RAG_HELPER",
|
||
"agentName": "知识问答助手",
|
||
"systemPrompt": "你是企业知识助手，请优先基于知识库回答。",
|
||
"storeId": 1001,
|
||
"status": "ENABLED",
|
||
"remark": "客服场景"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `id` 为空时新增，非空时更新。
|
||
- `agentCode` 全局唯一。
|
||
- `storeId` 必须指向已存在的 `rag_store`。
|
||
- `status` 默认 `ENABLED`，可选 `ENABLED` / `DISABLED`。
|
||
|
||
### 2.5 删除 Agent
|
||
|
||
- `POST /api/agents/delete?id={id}`
|
||
|
||
## 3. Agent 调试接口
|
||
|
||
### 3.1 发起对话
|
||
|
||
- `POST /api/agents/{agentId}/chat`
|
||
|
||
请求体示例：
|
||
|
||
```json
|
||
{
|
||
"messages": [
|
||
{ "role": "user", "content": "请说明请假流程" }
|
||
],
|
||
"ragEnabled": true
|
||
}
|
||
```
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"resultcode": "0",
|
||
"message": null,
|
||
"data": {
|
||
"agentId": 1,
|
||
"agentCode": "AGENT_RAG_HELPER",
|
||
"agentName": "知识问答助手",
|
||
"storeId": 1001,
|
||
"storeName": "企业知识库",
|
||
"answer": "根据知识库，先提交 OA 审批单。",
|
||
"modelRequestId": "f4215d13d0b3493e963297f15428e2f2",
|
||
"references": [
|
||
{
|
||
"chunkId": 9001,
|
||
"documentId": 8001,
|
||
"chunkContent": "请假流程：员工先在OA提交审批单...",
|
||
"score": 0.9123
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. 对话模式说明
|
||
|
||
### 4.1 `ragEnabled=true`（默认）
|
||
|
||
执行路径：
|
||
|
||
1. 从消息列表中提取最后一条 `role=user` 的问题。
|
||
2. 读取该 Agent 绑定知识库的生效 Embedding 配置。
|
||
3. 生成查询向量并在 `rag_chunk_embedding` 按知识库 TopK 召回切片。
|
||
4. 将系统提示词、召回片段和会话消息组装后调用 Chat 模型。
|
||
5. 返回回答 + 引用切片 + `modelRequestId`。
|
||
|
||
### 4.2 `ragEnabled=false`
|
||
|
||
执行路径：
|
||
|
||
- 跳过向量化与召回，直接使用会话消息调用 Chat 模型，返回普通对话结果。
|
||
|
||
## 5. 调试联调前置条件
|
||
|
||
### 5.1 普通对话前置条件
|
||
|
||
- Agent 状态为 `ENABLED`。
|
||
- Agent 已绑定存在的知识库。
|
||
- 已配置可用的 Chat 路由（`taskType=CHAT_SIMPLE` 或 `RAG_ANSWER`）。
|
||
|
||
### 5.2 RAG 对话前置条件
|
||
|
||
- 满足普通对话前置条件。
|
||
- 知识库存在生效 `rag_store_model_config` 且已绑定 Embedding 模型。
|
||
- 目标知识库至少有可用向量数据（`rag_chunk_embedding`）。
|
||
|
||
## 6. 常见失败提示
|
||
|
||
- `Agent已停用，暂不支持对话`：需启用 Agent。
|
||
- `当前知识库未配置Embedding模型，无法执行检索对话`：需先配置知识库 Embedding 模型。
|
||
- `未召回到可用知识切片，请先完成知识库切片与向量化`：需补齐切片向量化流程。
|
||
|
||
## 7. 相关代码入口
|
||
|
||
- `src/main/java/com/bruce/agent/controller/AgentDefinitionController.java`
|
||
- `src/main/java/com/bruce/agent/service/impl/AgentDefinitionServiceImpl.java`
|
||
- `src/main/java/com/bruce/agent/entity/AgentDefinition.java`
|
||
- `src/main/java/com/bruce/modelprovider/gateway/ChatModelGatewayImpl.java`
|
||
- `frontend/src/api/agent.ts`
|
||
- `frontend/src/pages/agent/AgentManagePage.vue`
|
||
- `frontend/src/pages/agent/AgentDebugPage.vue`
|