# 知你客服 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 方式即可完成接入。