# 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`