admin/aiagent

Fork 0

Files

rjb 717cd2a1ac android app

2026-03-07 09:01:00 +08:00

6.0 KiB

Raw Blame History

知你客服 Agent 智能聊天 App 接入方案

一、结论

可以接入。「知你客服」是平台上的已发布聊天智能体，支持记忆管理、意图识别与多轮对话，通过平台提供的 执行 API 即可在智能聊天 App 中调用，由 App 后端或前端携带平台用户 Token 调用即可。

二、接入方式概览

方式	适用场景	说明
方式一：App 后端代理	推荐，移动端/多端 App	App 后端用平台账号拿 Token，代用户调执行 API，再把结果返回给 App
方式二：前端直连	Web 版聊天、用户已在平台登录	前端拿到平台 Token 后直接调执行 API（同域名或配置 CORS）
方式三：内嵌平台对话页	快速上线	用 iframe 或 H5 打开平台「使用」页的对话界面，无需对接 API

三、方式一：App 后端代理（推荐）

3.1 流程

在平台为「对接用」创建一个账号（如 app-service@yourcompany.com），并登录拿到 access_token。
在平台 Agent 管理 中打开「知你客服」，复制其 Agent ID（或通过「获取 Agent 列表」接口查到）。
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

POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

username=app-service&password=xxx

响应示例：

{ "access_token": "eyJ...", "token_type": "bearer" }

2）创建执行（发用户消息给知你客服）

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}，传了才能按用户隔离多轮记忆。

响应示例：

{
  "id": "execution_uuid",
  "agent_id": "...",
  "status": "pending",
  "task_id": "celery_task_id",
  "created_at": "2026-01-22T..."
}

3）轮询执行结果

GET /api/v1/executions/{execution_id}/status
Authorization: Bearer <access_token>

返回中有 status：pending / running / completed / failed。为 completed 后再取详情。

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 聊天场景：

前端从平台登录接口拿到 access_token。
用户发消息时，前端直接：
- POST /api/v1/executions，body 同上（agent_id + input_data）。
- 轮询 GET /api/v1/executions/{id}/status 和 GET /api/v1/executions/{id}。
将 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：调用平台接口（需登录）：

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 方式即可完成接入。

6.0 KiB Raw Blame History Unescape Escape