ai_agent.md 10 KB

以下是为您整理的 AI Agent 接口集成开发文档,专为前端联调与功能测试编写。


AI Agent 接口集成开发文档

1. 基础信息

  • Base URL:/api/agent(以实际环境网关/域名为准,例如 http://localhost:8888/api/agent)
  • 鉴权方式:Bearer Token(与业务接口完全一致)

    Authorization: Bearer <your_access_token>
    
  • 数据格式:

    • 请求: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)

适合无需打字机效果、直接展示最终结果与执行轨迹的页面。

请求示例

POST /api/agent/chat
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...

{
  "message": "帮我查询最近的订单,并告诉我有没有待支付的",
  "session_id": "sess_user_001",
  "stream": false
}

响应格式(HTTP 200)

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

适合聊天对话框、带有实时思考动效、调用工具卡片展开和打字机文字渲染的前端组件。

请求示例

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 自主调用的能力清单。
  • 响应示例:

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

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)。

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:“把刚才查出来的第一条订单取消掉”