10ee7ee625
The platform has evolved from a low-code workflow engine to an autonomous agent platform with ReAct runtime, multi-agent marketplace, persistent memory, multimodal tools, and multi-channel integration. "天工" (Tiangong) draws from 《天工开物》- the wonders of nature and human ingenuity, reflecting the platform's purpose: empowering users to create and orchestrate AI agents as masterfully as nature creates all things. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
157 lines
7.8 KiB
Markdown
157 lines
7.8 KiB
Markdown
# 知你客服能力的集成和扩展方案
|
||
|
||
本文面向**业务/App 对接**与**平台内二次开发**，说明如何将「知你客服」系列 Agent 接入自有系统，以及如何安全、可维护地扩展工具与版本。具体某版本能力见 `知你客服14号能力文档.md`，记忆机制见 `agent记忆实现方案.md`，App 侧 HTTP 细节可参考 `知你客服Agent智能聊天App接入方案.md`。
|
||
|
||
---
|
||
|
||
## 一、集成目标与边界
|
||
|
||
| 目标 | 说明 |
|
||
|------|------|
|
||
| **对话能力** | 通过平台 **执行 API** 创建异步任务，由 **Celery** 跑完工作流后返回 `output_data`。 |
|
||
| **多轮记忆** | 依赖工作流 **Cache** 键（常见 `user_memory_{user_id}`）；集成侧必须传**稳定 `user_id`**，否则记忆串号或落在 `default`。 |
|
||
| **能力边界** | 具体能调用的工具、提示词约束以**当前 Agent 工作流**为准（如 14 号含全量内置工具）；文件、DB、adb 等受**部署环境与配置**限制。 |
|
||
|
||
---
|
||
|
||
## 二、集成方式选型
|
||
|
||
| 方式 | 适用 | 要点 |
|
||
|------|------|------|
|
||
| **后端代理（推荐）** | 移动 App、多端、需隐藏平台账号 | 服务端用平台账号换 `access_token`，代用户调 `POST /api/v1/executions`，再轮询状态/详情。 |
|
||
| **前端直连** | Web、用户已在平台登录 | 浏览器携带 Bearer Token 调同一套 API；需处理 CORS 与 Token 刷新。 |
|
||
| **内嵌平台对话页** | 快速验证 | iframe/WebView 打开平台「使用」页，不直接对接执行 API。 |
|
||
|
||
仓库内 **SAARS** 等示例提供「平台登录 + 转发执行」的代理思路，可与上述方式一对照实现。
|
||
|
||
---
|
||
|
||
## 三、执行 API 集成要点
|
||
|
||
### 3.1 认证
|
||
|
||
- `POST /api/v1/auth/login`（`application/x-www-form-urlencoded`）获取 `access_token`。
|
||
- 后续请求头：`Authorization: Bearer <access_token>`。
|
||
|
||
### 3.2 创建执行
|
||
|
||
- `POST /api/v1/executions`
|
||
- 典型 body：
|
||
|
||
```json
|
||
{
|
||
"agent_id": "<知你客服某版本的 Agent UUID>",
|
||
"input_data": {
|
||
"query": "用户本轮输入",
|
||
"USER_INPUT": "用户本轮输入",
|
||
"user_id": "业务侧稳定用户标识"
|
||
}
|
||
}
|
||
```
|
||
|
||
- **`user_id`**：强烈建议传入且长期不变，与 Cache 键一致方可多轮隔离。
|
||
- 字段名可与工作流 Start 节点约定对齐（常见 `query` / `USER_INPUT`）。
|
||
|
||
### 3.3 获取结果
|
||
|
||
1. `GET /api/v1/executions/{id}/status` 直至 `completed` / `failed`。
|
||
2. `GET /api/v1/executions/{id}` 读取 **`output_data`**。
|
||
|
||
### 3.4 展示层处理（避免重复 JSON）
|
||
|
||
知你类工作流常约定：**自然语言 + 最后一行单行 JSON**（`intent` / `reply` / `user_profile`）。
|
||
前端若直接展示整段字符串，用户会看到「正文 + JSON」重复感。可参考平台 **`AgentChatPreview`** 中的做法：展示前去掉末行结构化 JSON，或仅展示 JSON 中的 `reply`（以产品为准）。
|
||
|
||
### 3.5 运维
|
||
|
||
- 工作流在 **Celery Worker** 中执行；升级**引擎或工具**后需 **重启 API + Celery**（可用 `backend/scripts/restart_api_worker.ps1`）。
|
||
- 轮询间隔建议约 **0.5～1 s**，并设总超时。
|
||
|
||
---
|
||
|
||
## 四、记忆与持久化（集成侧责任）
|
||
|
||
- **键隔离**：必须传 **`user_id`**；详见 `agent记忆实现方案.md`。
|
||
- **Redis + 可选 MySQL**：热数据与持久化关系、合并规则、条数截断（如默认 `max_history_length`）见该文档。
|
||
- **业务无关数据**：勿把敏感密钥写入可被 `file_write` 触及的公开路径；生产环境应配置 **`LOCAL_FILE_TOOLS_ROOT`** 等。
|
||
|
||
---
|
||
|
||
## 五、扩展路径总览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 扩展维度 │ 主要改动位置 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 新内置工具 │ builtin_tools 实现 + tools_bootstrap 注册 │
|
||
│ 新版本 Agent │ scripts/create_zhini_kefu_XX.py 复制/补丁 │
|
||
│ 工作流结构 │ 平台工作流编辑器 + 导出/入库 API │
|
||
│ 提示词与工具列表 │ llm-unified 节点 data.prompt / tools │
|
||
│ HTTP/外部工具 │ 平台「工具管理」中配置 + tool_registry │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 六、扩展内置工具（后端）
|
||
|
||
1. **实现**：在 `backend/app/services/builtin_tools.py` 中实现异步函数，并定义 **JSON Schema**（与 OpenAI function calling 兼容）。
|
||
2. **注册**：在 `backend/app/core/tools_bootstrap.py` 的 `ensure_builtin_tools_registered` 中 **`register_builtin_tool(name, func, schema)`**。
|
||
3. **生效**：确保 **API 进程与 Celery Worker** 均会 import 执行流（已含 bootstrap）；部署后**重启**两处进程。
|
||
4. **工作流**：在目标 Agent 的 **LLM 节点** `data.tools` / `selected_tools` 中加入新工具名，`enable_tools: true`。
|
||
|
||
**注意**：工具名、参数 schema 与模型实际调用必须一致；敏感能力（如 shell）不建议放入内置工具。
|
||
|
||
---
|
||
|
||
## 七、扩展「知你客服」版本（脚本化）
|
||
|
||
- 仓库已提供 **`create_zhini_kefu_12.py` … `create_zhini_kefu_14.py`** 等脚本：登录平台 → 复制 Agent → 调整边与布局 → 更新 `llm-unified` 提示词与工具列表 → `PUT` 写回。
|
||
- **推荐做法**：以**上一稳定版本**为源复制，只改差异（工具数组、追加提示段落、描述），便于回溯。
|
||
- **文档**：为新版本补充 **`知你客服XX号能力文档.md`**，避免运营与开发认知不一致。
|
||
|
||
---
|
||
|
||
## 八、扩展工作流结构（天工）
|
||
|
||
- 在平台 **工作流设计器** 中增删节点：Cache、LLM、条件分支、向量检索、HTTP 等。
|
||
- **记忆链路**勿随意断开：保证 **读 Cache → LLM → 写 Cache** 顺序仍可达，且 `user_memory_*` 键模板未破坏。
|
||
- **自动布局**仅影响坐标，不改变执行语义；复杂图建议配合引擎的占位符与合并逻辑测试多轮对话。
|
||
|
||
---
|
||
|
||
## 九、安全与合规
|
||
|
||
| 项 | 建议 |
|
||
|----|------|
|
||
| **database_query** | 引擎侧限制 **SELECT**；生产应限制可见表/行或仅用只读账号；勿在提示词中鼓励随意扫库。 |
|
||
| **adb_log** | 仅在内网或受控环境开启；需本机 adb 与设备授权。 |
|
||
| **file_read / file_write** | 严格 **`LOCAL_FILE_TOOLS_ROOT`**；控制写入大小上限。 |
|
||
| **http_request** | 注意 SSRF 与出站策略（若平台侧有网关/白名单应一并配置）。 |
|
||
| **Token** | App 代理勿把平台账号密码下发客户端；`access_token` 缓存于服务端并处理过期。 |
|
||
|
||
---
|
||
|
||
## 十、测试建议
|
||
|
||
- **单轮**：工具是否被调用、返回是否进入 `reply` 或末行 JSON。
|
||
- **多轮**：同一 `user_id` 连续两轮，验证画像与历史是否写入 Cache/DB。
|
||
- **回归**：升级引擎或工具后跑一遍「问名—再问名」与一次需要工具调用的用例。
|
||
|
||
---
|
||
|
||
## 十一、相关文档与代码索引
|
||
|
||
| 说明 | 路径 |
|
||
|------|------|
|
||
| 14 号能力与工具表 | `知你客服14号能力文档.md` |
|
||
| 记忆与 Redis/DB | `agent记忆实现方案.md` |
|
||
| App HTTP 接入示例 | `知你客服Agent智能聊天App接入方案.md` |
|
||
| 创建/更新 14 号脚本 | `backend/scripts/create_zhini_kefu_14.py` |
|
||
| 内置工具注册 | `backend/app/core/tools_bootstrap.py` |
|
||
| 引擎与 Cache | `backend/app/services/workflow_engine.py` |
|
||
|
||
---
|
||
|
||
*随平台版本与仓库迭代，以实际接口与工作流配置为准。*
|