以下是为您整理的 AI Agent 接口集成开发文档,专为前端联调与功能测试编写。
/api/agent(以实际环境网关/域名为准,例如 http://localhost:8888/api/agent)鉴权方式:Bearer Token(与业务接口完全一致)
Authorization: Bearer <your_access_token>
数据格式:
Content-Type: application/jsonContent-Type: application/jsonContent-Type: text/event-stream| Method | Endpoint | 说明 | 适用场景 |
|---|---|---|---|
POST |
/api/agent/chat |
Agent 对话与指令执行(核心接口) | 同步获取结果或 SSE 实时流式交互 |
GET |
/api/agent/tools |
获取已开放的工具元数据 | 前端展示 Agent 拥有的系统能力 |
DELETE |
/api/agent/session/{session_id} |
清空指定会话记忆上下文 | 用户点击“新对话”时重置上下文 |
POST /api/agent/chat| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
message |
string |
是 | - | 用户输入的自然语言指令或问题 |
session_id |
string |
否 | null |
会话 ID。若开启多轮对话需保持一致;不传时后端自动生成 |
stream |
boolean |
否 | false |
false 返回普通 JSON;true 开启 SSE 流式输出 |
max_steps |
integer |
否 | 8 |
单次交互最大工具调用轮数(防止无限循环,范围 1~20) |
model |
string |
否 | null |
模型名称(不传使用后端配置的默认模型) |
stream: false)适合无需打字机效果、直接展示最终结果与执行轨迹的页面。
POST /api/agent/chat
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
{
"message": "帮我查询最近的订单,并告诉我有没有待支付的",
"session_id": "sess_user_001",
"stream": false
}
{
"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
}
]
}
}
stream: true)适合聊天对话框、带有实时思考动效、调用工具卡片展开和打字机文字渲染的前端组件。
POST /api/agent/chat
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
{
"message": "查一下法国相关的签证服务",
"session_id": "sess_user_001",
"stream": true
}
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}
GET /api/agent/tools响应示例:
{
"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
}
]
}
DELETE /api/agent/session/{session_id}session_id 的对话上下文与历史工具轨迹。fetch)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);
}
}
fetch + ReadableStream)提示:因为需要传递
Authorization: Bearer请求头,推荐使用fetch搭配流解析器(或前端流行库@microsoft/fetch-event-source)。
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);
}
}
}
}
前端开发在联调时,可用当前登录的用户身份测试以下典型场景:
session_id):