common_agent/agent-page-apis.md

Agent 页面后端接口清单

本文对应前端页面：AgentManagePage.vue 和 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

请求体示例：

{
  "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

请求体示例：

{
  "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

请求体示例：

{
  "messages": [
    { "role": "user", "content": "请说明请假流程" }
  ],
  "ragEnabled": true
}

返回示例：

{
  "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