# 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 编排实现影响。