以下是为您整理的 **AI Agent 接口集成开发文档**,专为前端联调与功能测试编写。 --- # AI Agent 接口集成开发文档 ## 1. 基础信息 - **Base URL**:`/api/agent`(以实际环境网关/域名为准,例如 `http://localhost:8888/api/agent`) - **鉴权方式**:`Bearer Token`(与业务接口完全一致) ```http Authorization: Bearer ``` - **数据格式**: - 请求:`Content-Type: application/json` - 同步响应:`Content-Type: application/json` - 流式响应:`Content-Type: text/event-stream` --- ## 2. 接口列表概览 | Method | Endpoint | 说明 | 适用场景 | | :--- | :--- | :--- | :--- | | `POST` | `/api/agent/chat` | Agent 对话与指令执行(核心接口) | 同步获取结果或 SSE 实时流式交互 | | `GET` | `/api/agent/tools` | 获取已开放的工具元数据 | 前端展示 Agent 拥有的系统能力 | | `DELETE` | `/api/agent/session/{session_id}` | 清空指定会话记忆上下文 | 用户点击“新对话”时重置上下文 | --- ## 3. 核心接口详情:`POST /api/agent/chat` ### 3.1 请求参数(Body JSON) | 字段 | 类型 | 必填 | 默认值 | 描述 | | :--- | :--- | :---: | :--- | :--- | | `message` | `string` | **是** | - | 用户输入的自然语言指令或问题 | | `session_id` | `string` | 否 | `null` | 会话 ID。若开启多轮对话需保持一致;不传时后端自动生成 | | `stream` | `boolean` | 否 | `false` | **`false` 返回普通 JSON;`true` 开启 SSE 流式输出** | | `max_steps` | `integer` | 否 | `8` | 单次交互最大工具调用轮数(防止无限循环,范围 1~20) | | `model` | `string` | 否 | `null` | 模型名称(不传使用后端配置的默认模型) | --- ### 3.2 模式一:同步模式(`stream: false`) 适合无需打字机效果、直接展示最终结果与执行轨迹的页面。 #### 请求示例 ```json POST /api/agent/chat Content-Type: application/json Authorization: Bearer eyJhbGciOi... { "message": "帮我查询最近的订单,并告诉我有没有待支付的", "session_id": "sess_user_001", "stream": false } ``` #### 响应格式(HTTP 200) ```json { "code": 0, "message": "success", "data": { "session_id": "sess_user_001", "answer": "您好,为您查询到您当前有 1 笔待支付订单:订单号 ORD-20260908-9876,商品为【欧洲申根签证服务】,金额 1500 CNY。请问需要为您取消该订单吗?", "steps_count": 1, "steps": [ { "tool": "query_user_orders", "arguments": { "limit": 5 }, "result": { "count": 1, "orders": [ { "order_id": "ORD-20260908-9876", "product_name": "欧洲申根签证服务", "final_amount": 1500, "currency": "CNY", "status": "pending", "created_at": "2026-09-08 22:30:00" } ] }, "is_error": false } ] } } ``` --- ### 3.3 模式二:SSE 流式模式(`stream: true`) 适合聊天对话框、带有**实时思考动效**、**调用工具卡片展开**和**打字机文字渲染**的前端组件。 #### 请求示例 ```json POST /api/agent/chat Content-Type: application/json Authorization: Bearer eyJhbGciOi... { "message": "查一下法国相关的签证服务", "session_id": "sess_user_001", "stream": true } ``` #### SSE 事件流规范(`text/event-stream`) 后端会依次向下推送不同类型的 SSE 事件: | 事件名 (`event`) | 数据载荷 (`data`) 结构 | 前端处理建议 | | :--- | :--- | :--- | | `think` | `{"status": "started" \| "planning", "step": 1}` | 显示“正在规划 / 思考中...”状态动画 | | `tool_start` | `{"tool": "search_products", "arguments": {"country": "法国"}, "call_id": "call_xxx"}` | 渲染“正在调用工具: search_products”卡片 | | `tool_end` | `{"tool": "search_products", "result": {...}, "is_error": false, "call_id": "call_xxx"}` | 更新工具卡片为“执行完成”并展示折叠结果 | | `message` | `{"delta": "为您查到以下...", "full": "为您查到以下..."}` | 增量打字机渲染文本内容 | | `finish` | `{"session_id": "...", "answer": "...", "steps_count": 1}` | 标记回答完毕,解除输入框禁用 | | `error` | `{"error": "错误原因"}` | 提示执行异常 | #### 实际返回流示例: ``` event: think data: {"status": "started", "session_id": "sess_user_001"} event: think data: {"status": "planning", "step": 1} event: tool_start data: {"tool": "search_products", "arguments": {"country": "法国"}, "call_id": "call_001"} event: tool_end data: {"tool": "search_products", "result": {"count": 1, "products": [{"product_id": 101, "title": "法国旅游签证"}]}, "is_error": false, "call_id": "call_001"} event: message data: {"delta": "为您查询到以下法国相关服务:\n1. 法国旅游签证(ID: 101)", "full": "为您查询到以下法国相关服务:\n1. 法国旅游签证(ID: 101)"} event: finish data: {"session_id": "sess_user_001", "answer": "为您查询到以下法国相关服务:\n1. 法国旅游签证(ID: 101)", "steps_count": 1} ``` --- ## 4. 辅助接口 ### 4.1 获取可用工具列表:`GET /api/agent/tools` - **说明**:获取当前系统允许 Agent 自主调用的能力清单。 - **响应示例**: ```json { "code": 0, "message": "success", "data": [ { "name": "query_user_orders", "description": "查询当前登录用户的订单列表,可按订单状态筛选", "is_dangerous": false, "schema": { "type": "function", "function": { "name": "query_user_orders", "description": "查询当前登录用户的订单列表...", "parameters": { ... } } } }, { "name": "cancel_user_order", "description": "取消指定的订单(仅未完成/未关闭的订单可取消)", "is_dangerous": true }, { "name": "search_products", "description": "检索可用的增值服务/签证/产品列表", "is_dangerous": false } ] } ``` ### 4.2 清除会话记忆:`DELETE /api/agent/session/{session_id}` - **说明**:清空 Redis 中对应 `session_id` 的对话上下文与历史工具轨迹。 --- ## 5. 前端集成参考代码 ### 5.1 同步模式调用(原生 `fetch`) ```typescript async function askAgentSync(message: string, sessionId?: string) { const token = localStorage.getItem("access_token"); const res = await fetch("/api/agent/chat", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ message, session_id: sessionId, stream: false }) }); const json = await res.json(); if (json.code === 0) { console.log("Agent 回答:", json.data.answer); console.log("执行的工具轨迹:", json.data.steps); return json.data; } else { throw new Error(json.message); } } ``` --- ### 5.2 SSE 流式模式解析(标准 `fetch` + `ReadableStream`) > **提示**:因为需要传递 `Authorization: Bearer` 请求头,推荐使用 `fetch` 搭配流解析器(或前端流行库 `@microsoft/fetch-event-source`)。 ```typescript async function askAgentStream( message: string, sessionId: string, handlers: { onThink?: (step: number) => void; onToolStart?: (tool: string, args: any) => void; onToolEnd?: (tool: string, result: any, isError: boolean) => void; onMessage?: (delta: string, full: string) => void; onFinish?: (finalAnswer: string, stepsCount: number) => void; onError?: (err: any) => void; } ) { const token = localStorage.getItem("access_token"); const response = await fetch("/api/agent/chat", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` }, body: JSON.stringify({ message, session_id: sessionId, stream: true }) }); if (!response.ok || !response.body) { handlers.onError?.(new Error(`HTTP error ${response.status}`)); return; } const reader = response.body.getReader(); const decoder = new TextDecoder("utf-8"); let buffer = ""; while (true) { const { value, done } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const chunks = buffer.split("\n\n"); buffer = chunks.pop() || ""; // 保留末尾未完整的数据包 for (const chunk of chunks) { if (!chunk.trim()) continue; let eventType = "message"; let dataStr = ""; chunk.split("\n").forEach(line => { if (line.startsWith("event:")) { eventType = line.replace("event:", "").trim(); } else if (line.startsWith("data:")) { dataStr = line.replace("data:", "").trim(); } }); if (!dataStr) continue; try { const payload = JSON.parse(dataStr); switch (eventType) { case "think": handlers.onThink?.(payload.step); break; case "tool_start": handlers.onToolStart?.(payload.tool, payload.arguments); break; case "tool_end": handlers.onToolEnd?.(payload.tool, payload.result, payload.is_error); break; case "message": handlers.onMessage?.(payload.delta, payload.full); break; case "finish": handlers.onFinish?.(payload.answer, payload.steps_count); break; case "error": handlers.onError?.(payload.error); break; } } catch (err) { console.error("解析 SSE 数据包失败:", err, dataStr); } } } } ``` --- ## 6. 当前可测试的指令示例 前端开发在联调时,可用当前登录的用户身份测试以下典型场景: 1. **商品检索**: - *“帮我查一下法国相关的签证服务”* - *“看看系统里推荐指数最高的商品有哪些”* 2. **订单查询**: - *“查一下我最近的订单”* - *“看看我有没有待支付的订单”* 3. **订单处理**: - *“帮我把订单号为 ORD-xxx 的订单取消掉”* 4. **多轮问答(保持同一 `session_id`)**: - 轮次 1:*“帮我查下我的待支付订单”* - 轮次 2:*“把刚才查出来的第一条订单取消掉”*