212 lines
3.8 KiB
Markdown
212 lines
3.8 KiB
Markdown
# Agent 设计文档
|
|
|
|
## 1. 设计目标
|
|
|
|
Agent 设计的核心目标是支持未知复试题的快速适配。
|
|
|
|
系统不针对单一业务写死，而是通过场景配置、知识库、工具和输出模板组合出不同业务 Agent。
|
|
|
|
```text
|
|
业务 Agent = 场景配置 + 知识库 + 工具集 + 输出模板 + 审计日志 + 模型适配器
|
|
```
|
|
|
|
## 2. Agent 类型
|
|
|
|
V1 预置 5 类 Agent 场景：
|
|
|
|
| Agent ID | 名称 | 适用场景 |
|
|
|---|---|---|
|
|
| `knowledge_qa` | 知识库问答助手 | SOP、制度、客服知识库 |
|
|
| `document_review` | 文档审核助手 | 合同、制度、SOP、材料审核 |
|
|
| `ticket_assistant` | 工单处理助手 | 客服、售后、运维工单 |
|
|
| `quality_analysis` | 质量异常分析助手 | 生产、质检、缺陷分析 |
|
|
| `risk_audit` | 风险审核助手 | 财务、采购、报销、合同风险 |
|
|
|
|
## 3. Agent 执行链路
|
|
|
|
```text
|
|
用户输入
|
|
↓
|
|
加载场景配置
|
|
↓
|
|
判断是否启用 RAG
|
|
↓
|
|
检索知识库片段
|
|
↓
|
|
加载可用工具
|
|
↓
|
|
构造 Prompt
|
|
↓
|
|
调用大模型
|
|
↓
|
|
解析工具调用和结构化输出
|
|
↓
|
|
生成 AgentResult
|
|
↓
|
|
写入审计日志
|
|
↓
|
|
页面展示
|
|
```
|
|
|
|
## 4. 场景配置结构
|
|
|
|
场景配置建议使用 YAML。
|
|
|
|
```yaml
|
|
id: quality_analysis
|
|
name: 质量异常分析助手
|
|
description: 用于分析生产质量异常、检索 SOP、生成处理建议
|
|
|
|
agent:
|
|
role: 质量管理专家
|
|
goal: 根据用户问题、知识库和工具结果，输出可执行的质量分析报告
|
|
instructions:
|
|
- 回答必须基于知识库或工具结果
|
|
- 不确定时必须说明缺失信息
|
|
- 涉及质量风险时给出风险等级
|
|
|
|
rag:
|
|
enabled: true
|
|
collection: quality_docs
|
|
top_k: 5
|
|
|
|
tools:
|
|
- get_recent_defect_records
|
|
- calculate_defect_rate
|
|
|
|
output:
|
|
type: quality_report
|
|
|
|
audit:
|
|
enabled: true
|
|
log_retrieval: true
|
|
log_tool_calls: true
|
|
```
|
|
|
|
## 5. Prompt 组成
|
|
|
|
Prompt 建议由以下部分组成：
|
|
|
|
```text
|
|
系统角色
|
|
任务目标
|
|
行为约束
|
|
输出格式要求
|
|
知识库检索内容
|
|
工具调用结果
|
|
用户问题
|
|
```
|
|
|
|
V1 不追求复杂 Prompt 框架，优先保证可读、可改、可解释。
|
|
|
|
## 6. RAG 策略
|
|
|
|
RAG 在 V1 中负责给 Agent 提供题目材料和业务知识。
|
|
|
|
入库流程：
|
|
|
|
```text
|
|
上传文件
|
|
↓
|
|
抽取文本
|
|
↓
|
|
文本切分
|
|
↓
|
|
生成 embedding
|
|
↓
|
|
写入 Chroma
|
|
```
|
|
|
|
检索流程：
|
|
|
|
```text
|
|
用户问题
|
|
↓
|
|
按 scenario_id 过滤
|
|
↓
|
|
向量检索 top_k
|
|
↓
|
|
返回片段内容、来源和分数
|
|
```
|
|
|
|
## 7. 工具调用策略
|
|
|
|
工具用于补足大模型不能直接可靠完成的业务动作。
|
|
|
|
V1 内置工具：
|
|
|
|
| 工具 | 用途 |
|
|
|---|---|
|
|
| `calculate_rate` | 计算比例、缺陷率、通过率 |
|
|
| `query_demo_records` | 查询模拟业务数据 |
|
|
| `check_required_fields` | 检查必填项 |
|
|
| `generate_action_items` | 生成行动项 |
|
|
|
|
工具返回格式：
|
|
|
|
```json
|
|
{
|
|
"tool_name": "calculate_rate",
|
|
"success": true,
|
|
"arguments": {},
|
|
"result": {},
|
|
"error": ""
|
|
}
|
|
```
|
|
|
|
## 8. 结构化输出
|
|
|
|
V1 支持以下输出类型：
|
|
|
|
- `general_answer`
|
|
- `document_review_report`
|
|
- `ticket_response`
|
|
- `quality_report`
|
|
- `risk_audit_report`
|
|
|
|
结构化输出优先使用 JSON。
|
|
|
|
解析失败时：
|
|
|
|
- 保留模型原始输出。
|
|
- 返回解析错误。
|
|
- 页面展示原始回答。
|
|
- 审计日志记录失败原因。
|
|
|
|
## 9. AgentResult
|
|
|
|
Agent Core 统一返回：
|
|
|
|
```json
|
|
{
|
|
"answer": "",
|
|
"structured_output": {},
|
|
"references": [],
|
|
"tool_calls": [],
|
|
"raw_output": "",
|
|
"model_name": "",
|
|
"latency_ms": 0,
|
|
"status": "success",
|
|
"error": ""
|
|
}
|
|
```
|
|
|
|
## 10. Adapter 策略
|
|
|
|
V1 默认使用自研轻量 Orchestrator。
|
|
|
|
后续可以扩展：
|
|
|
|
- OpenAI Agents SDK Adapter。
|
|
- Dify API Adapter。
|
|
- LangGraph Adapter。
|
|
|
|
所有 Adapter 应保持统一接口：
|
|
|
|
```text
|
|
run(scenario_config, user_input, options=None) -> AgentResult
|
|
```
|
|
|
|
这样可以保证 Django 业务层不受底层 Agent 编排实现影响。
|
|
|