DEMO-AGENT/docs/设计文档/1.智能体总体设计.md

智能体总体设计文档

1. 设计目标

Agent 设计的核心目标是支持未知复试题的快速适配。

系统不针对单一业务写死，而是通过场景配置、知识库、工具和输出模板组合出不同业务 Agent。

业务 Agent = 场景配置 + 知识库 + 工具集 + 输出模板 + 审计日志 + 模型适配器

2. Agent 类型

V1 预置 5 类 Agent 场景：

Agent ID	名称	适用场景
knowledge_qa	知识库问答助手	SOP、制度、客服知识库
document_review	文档审核助手	合同、制度、SOP、材料审核
ticket_assistant	工单处理助手	客服、售后、运维工单
quality_analysis	质量异常分析助手	生产、质检、缺陷分析
risk_audit	风险审核助手	财务、采购、报销、合同风险

3. Agent 执行链路

用户输入
  ↓
加载场景配置
  ↓
判断是否启用 RAG
  ↓
检索知识库片段
  ↓
加载可用工具
  ↓
构造 Prompt
  ↓
调用大模型
  ↓
解析工具调用和结构化输出
  ↓
生成 AgentResult
  ↓
写入审计日志
  ↓
页面展示

4. 场景配置结构

场景配置使用 YAML，V1 以配置文件作为场景唯一事实来源，后台管理不作为场景配置入口。

id: quality_analysis
name: 质量异常分析助手
description: 用于分析生产质量异常、检索 SOP、生成处理建议

agent:
  role: 质量管理专家
  goal: 根据用户问题、知识库和工具结果，输出可执行的质量分析报告
  system_prompt: ""
  instructions:
    - 回答必须基于知识库或工具结果
    - 不确定时必须说明缺失信息
    - 涉及质量风险时给出风险等级

rag:
  enabled: true
  collection: quality_docs
  top_k: 5

tools:
  - query_demo_records
  - calculate_rate

output:
  type: quality_report

audit:
  enabled: true
  log_retrieval: true
  log_tool_calls: true

5. Prompt 组成

Prompt 建议由以下部分组成：

系统角色
任务目标
行为约束
输出格式要求
知识库检索内容
工具调用结果
用户问题

V1 不追求复杂 Prompt 框架，优先保证可读、可改、可解释。

6. RAG 策略

RAG 在 V1 中负责给 Agent 提供题目材料和业务知识。

入库流程：

上传文件
  ↓
抽取文本
  ↓
文本切分
  ↓
生成 embedding
  ↓
写入 Chroma

检索流程：

用户问题
  ↓
按 scenario_id 和可选 document_ids 过滤
  ↓
向量检索 top_k
  ↓
返回片段内容、来源和分数

7. 工具调用策略

工具用于补足大模型不能直接可靠完成的业务动作。

V1 内置工具：

工具	用途
calculate_rate	计算比例、缺陷率、通过率
query_demo_records	查询模拟业务数据
check_required_fields	检查必填项
generate_action_items	生成行动项

工具返回格式：

{
  "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 统一返回：

{
  "answer": "",
  "structured_output": {},
  "references": [],
  "tool_calls": [],
  "raw_output": "",
  "model_name": "",
  "latency_ms": 0,
  "status": "success",
  "error": ""
}

10. Adapter 策略

V1 默认使用自研轻量 Orchestrator，通过 OpenAI 兼容接口接入 LLM 与 Embedding，可自主选择 OpenAI、硅基流动等兼容服务。

后续可以扩展：

• OpenAI Agents SDK Adapter。
• Dify API Adapter。
• LangGraph Adapter。

所有 Adapter 应保持统一接口：

run_agent(scenario_config, user_input, options=None) -> AgentResult

这样可以保证 Django 业务层不受底层 Agent 编排实现影响。