161 lines
6.0 KiB
Markdown
161 lines
6.0 KiB
Markdown
# 知你客服 Agent 智能聊天 App 接入方案
|
||
|
||
## 一、结论
|
||
|
||
**可以接入。**「知你客服」是平台上的已发布聊天智能体，支持记忆管理、意图识别与多轮对话，通过平台提供的 **执行 API** 即可在智能聊天 App 中调用，由 App 后端或前端携带平台用户 Token 调用即可。
|
||
|
||
---
|
||
|
||
## 二、接入方式概览
|
||
|
||
| 方式 | 适用场景 | 说明 |
|
||
|------|----------|------|
|
||
| **方式一：App 后端代理** | 推荐，移动端/多端 App | App 后端用平台账号拿 Token，代用户调执行 API，再把结果返回给 App |
|
||
| **方式二：前端直连** | Web 版聊天、用户已在平台登录 | 前端拿到平台 Token 后直接调执行 API（同域名或配置 CORS） |
|
||
| **方式三：内嵌平台对话页** | 快速上线 | 用 iframe 或 H5 打开平台「使用」页的对话界面，无需对接 API |
|
||
|
||
---
|
||
|
||
## 三、方式一：App 后端代理（推荐）
|
||
|
||
### 3.1 流程
|
||
|
||
1. 在平台为「对接用」创建一个账号（如 `app-service@yourcompany.com`），并登录拿到 **access_token**。
|
||
2. 在平台 **Agent 管理** 中打开「知你客服」，复制其 **Agent ID**（或通过「获取 Agent 列表」接口查到）。
|
||
3. App 用户发消息时，App 后端：
|
||
- 用上述 token 调「创建执行」接口，传入 `agent_id` 和 `input_data`（见下）。
|
||
- 轮询「执行状态」或「执行详情」，直到 `status` 为 `completed`。
|
||
- 从 `output_data` 中取出回复内容返回给 App 用户。
|
||
|
||
### 3.2 接口说明（与知你客服约定）
|
||
|
||
- **Base URL**：`http(s)://你的平台域名:8037`（如 `http://101.43.95.130:8037`）
|
||
|
||
**1）登录拿 Token**
|
||
|
||
```http
|
||
POST /api/v1/auth/login
|
||
Content-Type: application/x-www-form-urlencoded
|
||
|
||
username=app-service&password=xxx
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{ "access_token": "eyJ...", "token_type": "bearer" }
|
||
```
|
||
|
||
**2）创建执行（发用户消息给知你客服）**
|
||
|
||
```http
|
||
POST /api/v1/executions
|
||
Authorization: Bearer <access_token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"agent_id": "知你客服的Agent ID",
|
||
"input_data": {
|
||
"query": "用户当前这句话",
|
||
"user_id": "app侧用户唯一ID"
|
||
}
|
||
}
|
||
```
|
||
|
||
- `query`：必填，用户本轮输入。
|
||
- `user_id`：建议传。知你客服工作流里用「缓存」做记忆时，key 一般为 `user_memory_{user_id}`，传了才能按用户隔离多轮记忆。
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"id": "execution_uuid",
|
||
"agent_id": "...",
|
||
"status": "pending",
|
||
"task_id": "celery_task_id",
|
||
"created_at": "2026-01-22T..."
|
||
}
|
||
```
|
||
|
||
**3）轮询执行结果**
|
||
|
||
```http
|
||
GET /api/v1/executions/{execution_id}/status
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
返回中有 `status`：`pending` / `running` / `completed` / `failed`。为 `completed` 后再取详情。
|
||
|
||
```http
|
||
GET /api/v1/executions/{execution_id}
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
响应中的 `output_data` 即为工作流输出，其中会包含客服回复内容（具体字段以知你客服工作流 End 节点输出为准，常见为 `reply`、`content`、`output` 等）。
|
||
|
||
### 3.3 App 后端实现要点
|
||
|
||
- Token 管理：登录一次，将 `access_token` 缓存在服务端（注意过期时间，过期前重新登录或使用 refresh 若平台支持）。
|
||
- 每个 App 用户建议固定一个 `user_id`（如 open_id、user_uuid），保证多轮对话记忆正确。
|
||
- 轮询间隔建议 0.5～1 秒，最多轮询约 30～60 秒，超时可按「请求超时」处理。
|
||
|
||
---
|
||
|
||
## 四、方式二：前端直连
|
||
|
||
适用于「用户已在低代码平台登录」的 Web 聊天场景：
|
||
|
||
1. 前端从平台登录接口拿到 `access_token`。
|
||
2. 用户发消息时，前端直接：
|
||
- `POST /api/v1/executions`，body 同上（`agent_id` + `input_data`）。
|
||
- 轮询 `GET /api/v1/executions/{id}/status` 和 `GET /api/v1/executions/{id}`。
|
||
3. 将 `output_data` 中的回复展示在聊天界面。
|
||
|
||
注意：需保证前端请求能带 Cookie/Header 到 8037 端口，且平台 CORS 已放行该前端域名（当前配置见 `docker-compose.dev.yml` 中 `CORS_ORIGINS`）。
|
||
|
||
---
|
||
|
||
## 五、方式三：内嵌平台对话页
|
||
|
||
- 在 Agent 管理中对「知你客服」点击 **「使用」**，会打开平台自带的对话页。
|
||
- 在智能聊天 App 内用 **WebView / iframe** 打开该对话页 URL，即可在 App 内使用知你客服，无需对接执行 API。
|
||
- 优点：零开发量；缺点：界面与账号体系受平台限制，且无法深度定制 UI 与用户标识（多端统一记忆需平台支持「使用」页传 user_id 等参数，若当前不支持可向平台侧确认是否可扩展）。
|
||
|
||
---
|
||
|
||
## 六、知你客服输入输出约定（建议在平台上确认）
|
||
|
||
- **输入**（`input_data`）：
|
||
- `query`（必填）：用户当前轮次文本。
|
||
- `user_id`（建议）：App 侧用户唯一 ID，用于记忆 key。
|
||
- **输出**（`output_data`）：
|
||
- 以实际工作流 End 节点输出为准，可在平台「执行历史」中跑一轮对话，查看该执行详情中的 `output_data` 结构，再在 App 中解析展示。
|
||
|
||
---
|
||
|
||
## 七、获取 Agent ID
|
||
|
||
- 方式 A：在 Agent 管理列表中，用浏览器开发者工具查看「知你客服」对应行的接口或 DOM，可看到 `id`。
|
||
- 方式 B：调用平台接口（需登录）：
|
||
|
||
```http
|
||
GET /api/v1/agents?search=知你客服
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
在返回列表中找到名称为「知你客服」的项，取其 `id` 作为上述 `agent_id`。
|
||
|
||
---
|
||
|
||
## 八、小结
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 是否可接入 | 可以，通过执行 API 或内嵌「使用」页 |
|
||
| 推荐方式 | 智能聊天 App 用 **App 后端代理**（方式一） |
|
||
| 认证 | 使用平台账号登录得到的 Bearer Token |
|
||
| 多轮记忆 | 在 `input_data` 中传稳定 `user_id` |
|
||
| 文档与调试 | 可访问 `http(s)://域名:8037/docs` 查看并调试执行、状态、详情等接口 |
|
||
|
||
若后续需要「无登录、仅用 API Key 调用知你客服」，需在平台侧为 Agent 增加 API Key 鉴权接口，再在 App 后端用 Key 替代 Token 调用即可；当前版本按上述 Token 方式即可完成接入。
|