aiagent/知你客服Agent智能聊天App接入方案.md

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