vitepress-template

Appearance

AI智能体系统 ​

**本文档引用的文件** - [[[[bi-chat 文档/聊天架构设计.md]]]](../ai/file/bi-chat/docs/chat-v1-design.md) - [[[[bi-chat 文档/记忆架构.md]]]](../ai/file/bi-chat/docs/memory-architecture.md) - [[[[bi-chat 核心模式/模式定义]]]](../ai/file/bi-chat/bi-chat/src/core/schemas.py) - [[[[bi-chat 核心/代理注册表]]]](../ai/file/bi-chat/bi-chat/src/core/agent-registry.py) - [[[[bi-chat 工作流/上下文]]]](../ai/file/bi-chat/bi-chat/src/workflow/context.py) - [[[[bi-chat 工作流/主流程]]]](../ai/file/bi-chat/bi-chat/src/workflow/main-flow.py) - [[[[bi-chat 代理/管理代理]]]](../ai/file/bi-chat/bi-chat/src/agents/manager-agent.py) - [[[[bi-chat 代理/数据代理]]]](../ai/file/bi-chat/bi-chat/src/agents/data-agent.py) - [[[[bi-chat 代理/通用代理]]]](../ai/file/bi-chat/bi-chat/src/agents/general-agent.py) - [[[[bi-chat 代理/报告代理]]]](../ai/file/bi-chat/bi-chat/src/agents/report-agent.py) - [[[[PRD/多智能体系统设计（AgentScope）]]]](../ai/file/docs/prd/prd-chatbi-agentscope-system.md) - [[[[PRD/BI聊天（AgentScope）]]]](../ai/file/docs/prd/prd-bi-chat-agentscope.md) - [[[[bi-chat 长期记忆服务]]]](../ai/file/bi-chat/bi-chat/src/services/long-term-memory.py)

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

引言 ​

本文件面向BI分析平台的AI智能体系统，围绕多智能体数据分析对话系统的设计理念与架构原理展开，重点覆盖以下方面：

  • 基于AgentScope框架的模块化与分布式运行时
  • 自定义Agent的开发与协作机制
  • 工具调用系统（数据查询、报表生成等）
  • 记忆管理系统（短期与长期）
  • 对话流程与状态管理
  • AI模型集成、API接口设计与性能优化
  • 开发者指南与调试技巧

项目结构 ​

本项目采用“模块化+工作流编排”的组织方式，核心位于bi-chat子系统，围绕AgentScope生态构建：

  • 核心模式与协议：定义意图、目标Agent、任务计划、数据产物等统一数据结构
  • 代理注册表：集中管理专家Agent的元信息与动态Prompt上下文
  • 工作流上下文：跨轮次共享状态、产物与依赖关系
  • 主流程编排：基于SequentialPipeline与DAG执行引擎的P-E-R-L循环
  • 代理实现：Manager、UnifiedDataAgent、GeneralAgent、CalculationAgent、SummaryAgent等
  • 记忆系统：短期会话记忆与长期用户记忆（向量检索）

图表来源

章节来源

核心组件 ​

  • 统一数据专家（UnifiedDataAgent）：基于ReAct循环，结合本体检索与工具调用，完成SQL生成与执行，输出标准化数据产物
  • 通用知识专家（GeneralAgent）：具备联网搜索与本地工具调用能力，处理外部实时信息
  • 管理代理（ManagerAgent）：意图识别、任务规划与路由，支持初始规划、增量重规划与并行/依赖图执行
  • 汇总代理（SummaryAgent）：整合多Agent结果，生成可读性强的报告
  • 工作流上下文（WorkflowContext）：承载原始查询、历史、计划、产物与完成状态
  • 代理注册表（AgentRegistry）：动态构建专家列表与Prompt上下文
  • 记忆服务：短期（会话级）与长期（用户级）记忆，支撑上下文压缩、检索与复用

章节来源

架构总览 ​

系统遵循AgentScope的模块化与分布式设计，强调“编排层-认知层-控制层”的分层与协作：

  • 编排层：MainPipeline负责P-E-R-L循环与任务执行
  • 认知层：Manager、UnifiedDataAgent、GeneralAgent、CalculationAgent、SummaryAgent等
  • 控制层：代理注册表与工作流上下文提供路由与状态管理
  • 工具层：数据库工具、公共API工具、向量检索与缓存
  • 存储层：短期记忆（内存+PostgreSQL）、长期记忆（Milvus向量库）

图表来源

章节来源

详细组件分析 ​

管理代理（ManagerAgent）：意图识别与任务规划 ​

  • 角色职责：识别用户意图（内部数据查询/通用查询/元数据查询/澄清），分配目标Agent，生成任务计划
  • 关键能力：
    • 基于专家注册表动态构建Prompt上下文
    • 初始规划、增量重规划与下一步任务提取
    • 输出标准化决策结构（IntentType、TargetAgent、reasoning）
  • 设计要点：
    • 内外部严格隔离：内部业务指标强制路由至UnifiedDataAgent
    • 任务提纯与依赖强制检查，避免跨域混杂
    • 支持并行加速与DAG执行模式

图表来源

章节来源

统一数据专家（UnifiedDataAgent）：ReAct数据查询与分析 ​

  • 角色职责：将自然语言翻译为SQL，执行并分析，输出标准化数据产物
  • 关键能力：
    • ReAct循环：思考-动作-观察，支持精细化进度上报
    • Schema感知：通过本体检索获取物理表定义，避免幻觉
    • 工具调用：execute_sql、get_database_info、search_entities、search_indicators
    • 产物标准化：DataArtifact（含数据、描述、SQL、图表配置）
  • 设计要点：
    • 表选择金律：明细/日期优先、统计/趋势适用
    • 原子化查询：优先在SQL中完成聚合与计算
    • 输出严格遵循JSON Schema，便于后续计算与可视化

图表来源

章节来源

通用知识专家（GeneralAgent）：联网搜索与工具调用 ​

  • 角色职责：处理外部实时信息，具备联网搜索与本地工具调用能力
  • 关键能力：
    • 工具注册：calculate、search_wikipedia、get_exchange_rate、search_web
    • 工具调用循环：LLM输出工具调用JSON，执行后继续推理直至最终答案
    • 上下文融合：可复用前序步骤产生的内部数据进行综合分析
  • 设计要点：
    • 禁止幻觉：联网检索不到准确数据时诚实说明
    • 抗干扰：无法访问数据库时明确告知

图表来源

章节来源

汇总代理（SummaryAgent）：报告生成与洞察提炼 ​

  • 角色职责：整合多Agent结果，生成结构化报告（Markdown），必要时附带图表配置
  • 关键能力：
    • 基于Artifacts与历史上下文生成报告
    • 规范化输出（标题、摘要、详细分析、结论）
    • 引用数据资产，确保可追溯性

章节来源

工作流上下文（WorkflowContext）：状态与产物管理 ​

  • 角色职责：跨轮次共享状态、任务计划、产物仓库与完成标志
  • 关键能力：
    • 原始查询、历史、计划、当前步骤、完成步骤集合
    • 产物仓库（artifacts）按步骤ID或类型键控
    • 获取下一个未完成子任务

章节来源

记忆系统：短期与长期 ​

  • 短期记忆（会话级）：InMemoryMemory + PostgreSQL双写，支持压缩、消息过滤、LRU淘汰与会话超时
  • 长期记忆（用户级）：Mem0单例管理，基于Milvus向量检索，支持agent_control/static_control/both模式
  • 记忆工具：record_to_memory、retrieve_from_memory

图表来源

章节来源

依赖分析 ​

  • 组件耦合：
    • MainPipeline依赖Manager、UnifiedDataAgent、GeneralAgent、CalculationAgent、SummaryAgent与ClarificationGuard
    • ManagerAgent依赖AgentRegistry与工作流上下文
    • UnifiedDataAgent依赖数据库工具与本体检索
    • GeneralAgent依赖公共API工具与联网搜索
  • 外部依赖：
    • AgentScope运行时与消息总线
    • 数据库（StarRocks/PostgreSQL）
    • 向量数据库（Milvus）
    • 缓存（Redis）

图表来源

章节来源

性能考量 ​

  • 并行与依赖图执行：通过DAGExecutor与TaskPlan.execution_mode提升吞吐
  • 缓存与重用：ManagerAgent与LLM调用结果缓存，减少重复推理
  • 记忆压缩与淘汰：短期记忆支持Token阈值压缩与LRU淘汰
  • 工具调用异步化：数据库与公共API工具采用异步执行与线程池隔离
  • 安全与限流：SQL执行前过滤高危词、Join放大风险评估、执行时长与内存限制

章节来源

故障排查指南 ​

  • 意图识别偏差：检查ManagerAgent的决策Schema与历史注入，确认是否误判为clarification
  • ReAct循环卡滞：关注工具调用返回结构与JSON解析，确保输出严格符合Schema
  • 工具执行异常：查看工具返回摘要与异常栈，定位数据库连接或网络搜索失败
  • 记忆未命中：确认用户实例是否存在、向量检索top_k与关键词匹配度
  • 进度上报中断：检查ProgressReporter上下文注入与SSE通道

章节来源

结论 ​

本系统以AgentScope为核心，构建了“意图识别-任务规划-并行执行-反思重规划-结果汇总”的闭环，配合短期与长期记忆，实现了可解释、可观测、可扩展的多智能体数据分析对话系统。通过工具调用与标准化产物，系统能够稳定地完成从SQL生成到报告呈现的全链路任务。

附录 ​

开发者指南 ​

  • 自定义Agent开发
    • 继承基础助手类，实现reply方法，注入必要的工具与Schema
    • 在AgentRegistry中注册，提供描述与触发条件，以便ManagerAgent动态构建上下文
  • 任务规划与路由
    • 使用TaskPlan与SubTask定义执行策略与依赖关系
    • 在ManagerAgent中完善决策原则与Schema校验
  • 工具调用系统
    • 数据查询：封装execute_sql与get_database_info，确保返回结构化摘要与审计字段
    • 外部查询：注册公共API工具，遵循“先工具调用再回答”的约束
  • 记忆集成
    • 短期记忆：InMemoryMemory + PostgreSQL，注意压缩与淘汰策略
    • 长期记忆：BIMem0LongTermMemory + Milvus，按用户实例管理
  • API与接口
    • 对接AgentScope Runtime，遵循消息与元数据约定
    • 提供SSE/WS接口，支持进度上报与组件渲染

章节来源