# 知你客服 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 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 ``` 返回中有 `status`：`pending` / `running` / `completed` / `failed`。为 `completed` 后再取详情。 ```http GET /api/v1/executions/{execution_id} Authorization: Bearer ``` 响应中的 `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 ``` 在返回列表中找到名称为「知你客服」的项，取其 `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 方式即可完成接入。