143 lines
6.6 KiB
Markdown
143 lines
6.6 KiB
Markdown
# Agent A1 集成手册 (Integration Manual)
|
||
|
||
**版本**: 2.0
|
||
**最后更新**: 2025-12-27
|
||
**适用对象**: 后端工程师、系统架构师
|
||
|
||
## 1. 智能体概览 (Agent Overview)
|
||
|
||
**Agent A1** 是整个销售洞察系统的“前哨站”。它负责处理非结构化的微信聊天记录，将其转化为结构化的客户画像数据和标准化的知识库条目。
|
||
|
||
* **输入**: 原始微信聊天记录 (Raw Text/CSV)。
|
||
* **输出**: 严格的 JSON 对象，包含客户画像 (`client_profile`)、知识挖掘 (`knowledge_mining`) 和面诊建议 (`reception_tip`)。
|
||
* **核心依赖**: LLM (推荐 GPT-4o 或同级推理能力模型)，内置 `Med-3C` 心理推理框架。
|
||
* **延迟敏感度**: 异步处理（建议任务耗时 30s - 60s）。
|
||
|
||
## 2. 接口定义 (Interface Definition)
|
||
|
||
建议将 Agent A1 封装为一个独立的服务或 API 接口。
|
||
|
||
### 2.1 请求格式 (Request)
|
||
|
||
```json
|
||
POST /api/v1/agents/a1/process
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"trace_id": "uuid-v4-string", // 用于全链路追踪
|
||
"input_data": {
|
||
"raw_chat_text": "string", // 必需。完整的聊天记录文本。建议包含时间戳和发送人ID。
|
||
"consultant_name": "string", // 可选。咨询师的微信昵称，辅助LLM区分角色。
|
||
"client_name": "string", // 可选。客户的微信昵称。
|
||
"current_date": "YYYY-MM-DD" // 可选。用于推断相对时间（如“上周”）。
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 响应格式 (Response)
|
||
|
||
成功响应 (HTTP 200) 将返回一个标准的 JSON 包体。详细 Schema 请见下文“3. 输出数据结构详情”。
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"client_profile": { ... },
|
||
"knowledge_mining": [ ... ],
|
||
"consultation_insights": { ... },
|
||
"sales_audit": { ... },
|
||
"reception_tip": "..."
|
||
},
|
||
"usage": {
|
||
"prompt_tokens": 1200,
|
||
"completion_tokens": 800
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 输出数据结构详情 (Output Schema)
|
||
|
||
后端系统需按照此 Schema 进行解析和入库。
|
||
|
||
### 3.1 `client_profile` (客户画像表)
|
||
* **用途**: 更新 CRM 客户档案，作为 Agent B (深度画像) 的输入源。
|
||
|
||
| 字段名 | 类型 | 说明 | 示例值 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `facts.medical_history` | String | 已确认的病史/过往项目 | "玻尿酸填充史；青霉素过敏" |
|
||
| `facts.pain_sensitivity` | String | 疼痛敏感度 | "高（曾抱怨打针疼）" |
|
||
| `facts.location_context` | String | 地理位置特征 | "异地-天津（需坐高铁）" |
|
||
| `facts.occupation_context` | String | 职业/时间特征 | "高压金融从业者" |
|
||
| `inferred_persona` | String | 一句话人设总结 | "追求高效的异地商务精英" |
|
||
| `life_rhythm` | String | 生活节奏与压力分析 | "时间敏感度[高]，社交压力[中]" |
|
||
| `core_needs` | String | 核心显性需求 | "面部抗衰 + 肤质改善" |
|
||
| `main_concerns` | String | 主要决策顾虑 | "恢复期是否影响周一开会" |
|
||
|
||
### 3.2 `knowledge_mining` (知识挖掘表) - *核心资产*
|
||
* **用途**: **直接存入知识库 (Vector DB / KB SQL)**，供 Agent C 检索。
|
||
* **ETL 逻辑**: 该数组中的每一项应作为一条独立的 Record 插入知识库。
|
||
|
||
| 字段名 | 类型 | 说明 | 关键处理逻辑 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `category` | String | 业务分类 | 如 "术后护理", "价格谈判" |
|
||
| `original_context` | String | 原始对话 | 用于人工审核追溯。 |
|
||
| `refined_text` | String | **金牌话术 (SOP)** | **知识库的 `content` 字段。** |
|
||
| `why_it_works` | String | 策略分析 | 知识库的 `reasoning` 字段。 |
|
||
| `applicability_tags` | List<String> | **3C 标签** | **知识库的 `tags` 索引字段。** 严格匹配 Agent B 的输出标签。 |
|
||
|
||
**入库示例 (Pseudo-Code):**
|
||
```python
|
||
for item in response.data.knowledge_mining:
|
||
KnowledgeBase.insert({
|
||
"content": item.refined_text,
|
||
"tags": item.applicability_tags, # e.g. ["Mem:社交败露恐惧"]
|
||
"metadata": {
|
||
"source": "A1_Chat_Mining",
|
||
"reasoning": item.why_it_works
|
||
}
|
||
})
|
||
```
|
||
|
||
### 3.3 其他字段
|
||
* `reception_tip` (String): 直接展示在医生/前台接待 iPad 端。
|
||
* `sales_audit` (Object): 包含 `strategy_mismatch_alert`。若非 null，应在 CRM 中对该销售主管发送“预警通知”。
|
||
|
||
## 4. 业务逻辑与处理流程 (Workflow)
|
||
|
||
1. **预处理 (Pre-processing)**:
|
||
* **清洗格式**: 将导出的微信记录（通常是混乱的文本）处理为 `[Time] [Speaker]: [Content]` 的标准格式，减少 Token 消耗。
|
||
* **截断策略**: 建议仅截取最近 3-6 个月的聊天记录，或限制 Token 数在 10k-20k 之间，避免上下文溢出。
|
||
|
||
2. **Prompt 组装**:
|
||
* 加载 `System Prompt` (即上文提供的 Agent A1 V2.0 提示词)。
|
||
* 将预处理后的聊天记录注入 Prompt 的 `User Message` 部分。
|
||
|
||
3. **LLM 调用**:
|
||
* Temperature 建议设置在 `0.2 - 0.4`，保证输出格式的稳定性。
|
||
* **强制 JSON 模式**: 务必开启 Model 的 `JSON Mode` (如 OpenAI 的 `response_format: { "type": "json_object" }`)。
|
||
|
||
4. **后处理与验证 (Post-processing)**:
|
||
* **JSON Parse**: 解析返回字符串。
|
||
* **标签白名单校验**: 检查 `applicability_tags` 是否都在允许的 3C 标签列表中。如果出现未知标签，建议在入库前清洗掉或标记为“待人工审核”。
|
||
|
||
## 5. 异常处理机制 (Exception Handling)
|
||
|
||
| 异常情况 | 现象 | 建议处理方案 |
|
||
| :--- | :--- | :--- |
|
||
| **聊天记录为空/过短** | 输入文本 < 50 字符 | 直接返回默认空对象，不调用 LLM，节省成本。 |
|
||
| **JSON 解析失败** | LLM 输出非标准 JSON | 记录 Error Log，触发一次 Retry (Temperature 设为 0)。 |
|
||
| **无挖掘价值** | `knowledge_mining` 为空数组 | 正常入库 `client_profile`，忽略知识库插入步骤。 |
|
||
| **敏感信息残留** | 输出包含人名/手机号 | 在后端增加一层 Regex 过滤器，再次清洗 PII 信息。 |
|
||
|
||
## 6. 开发与测试 Checklists
|
||
|
||
### 开发阶段
|
||
- [ ] 确认后端可以接收并存储大文本（聊天记录可能很长）。
|
||
- [ ] 实现了 3C 标签的 Enum 定义，确保数据库能正确存储 Tag。
|
||
- [ ] 实现了将 `knowledge_mining` 数组拆解并批量写入知识库的逻辑。
|
||
|
||
### 测试阶段 (验收标准)
|
||
- [ ] **格式测试**: 输入一段混乱的聊天记录，必须返回合法的 JSON。
|
||
- [ ] **标签一致性**: `applicability_tags` 必须包含如 `[Mem: 社交败露恐惧]` 格式的标签。
|
||
- [ ] **润色效果**: 对比 `original_context` 和 `refined_text`，后者必须去除口语化词汇（如“亲”、“哈”）。
|
||
- [ ] **隐私合规**: 输出结果中不应包含具体的真实姓名。 |