vitepress-template

Appearance

Agent架构设计 ​

**本文档引用的文件** - [[bi_chat/src/agents/base_agent.py]](../ai/file/bi-chat/src/agents/base-agent.py) - [[bi_chat/src/agents/bi_agent.py]](../ai/file/bi-chat/src/agents/bi-agent.py) - [[bi_chat/src/agents/conversation_manager.py]](../ai/file/bi-chat/src/agents/conversation-manager.py) - [[bi_chat/src/agents/data_agent.py]](../ai/file/bi-chat/src/agents/data-agent.py) - [[bi_chat/src/agents/tools.py]](../ai/file/bi-chat/src/agents/tools.py) - [[bi_chat/src/agents/report_agent.py]](../ai/file/bi-chat/src/agents/report-agent.py) - [[bi_chat/src/agents/manager_agent.py]](../ai/file/bi-chat/src/agents/manager-agent.py) - [[bi_chat/src/agents/model_wrapper.py]](../ai/file/bi-chat/src/agents/model-wrapper.py) - [[bi_chat/src/routes/chat.py]](../ai/file/bi-chat/src/routes/chat.py) - [[bi_chat/docs/chat_v1_design.md]](../ai/file/bi-chat/docs/chat-v1-design.md) - [[bi_chat/docs/memory_architecture.md]](../ai/file/bi-chat/docs/memory-architecture.md) - [[bi_chat/src/routes/sessions.py]](../ai/file/bi-chat/src/routes/sessions.py)

目录 ​

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

简介 ​

本文件面向BI分析平台的Agent架构设计，系统阐述基于AgentScope框架的智能体体系，重点覆盖：

  • ReActAgent模式的实现原理与执行流程
  • BaseAgent基类的设计理念与核心接口
  • BiAgent智能体（BIReActAgent）的生命周期管理、状态转换与消息处理机制
  • ConversationManager会话管理器的缓存、并发控制与超时清理
  • 智能体注册、配置管理与动态加载
  • 智能体间通信协议与协作模式

项目结构 ​

围绕bi-chat服务，Agent相关代码主要集中在bi_chat/src/agents目录，配合路由层、工具集与文档说明，形成完整的端到端处理链路。

图表来源

章节来源

核心组件 ​

  • BaseAgentHelper：为所有Agent提供统一的LLM模型初始化、内容解析、JSON解析与历史对话上下文构建能力，屏蔽AgentScope细节差异。
  • BIReActAgent：在ReActAgent基础上扩展，实现推理完成后自动保存消息到数据库、支持长期记忆与记忆压缩配置。
  • ConversationManager：提供会话级Agent实例管理，包含LRU缓存、并发控制、超时清理、动态工具注册与工作流Agent构建。
  • UnifiedDataAgent：基于显式ReAct循环的数据专家，负责意图感知、工具调用与产物收集，支持Schema预感知与结构化输出。
  • ReportAgent：报告生成专家，消费上游产物生成Markdown报告。
  • ManagerAgent：任务调度与规划专家，负责意图识别、路由决策与任务计划生成/重规划。
  • tools.py：提供实体检索、指标检索、SQL执行、数据库信息查询、环境感知、并行分析触发、知识图谱检索、推广计划与策略等工具。

章节来源

架构总览 ​

整体处理流程从HTTP入口开始，经会话管理器获取或创建Agent实例，随后进入ReAct推理循环，期间通过工具集完成数据查询、指标检索与环境感知，最终将增量消息持久化并生成报告。

图表来源

章节来源

详细组件分析 ​

BaseAgentHelper基类设计 ​

  • 统一模型初始化：优先复用全局共享模型单例，失败时回退到独立创建；通过RobustModelWrapper增强网络稳健性。
  • 统一内容解析：支持字符串与消息列表输入，自动注入系统时间信息，合并连续消息，清洗消息结构，支持流式增量上报。
  • 历史上下文构建：从ConversationManager获取Agent实例并读取内存历史，必要时回退到数据库加载，支持格式化输出与追踪信息展示。
  • JSON解析与鲁棒性：提供统一的JSON解析器，避免LLM输出不稳定导致的解析失败。

图表来源

章节来源

BIReActAgent智能体（ReActAgent扩展） ​

  • 生命周期管理：在reply执行完成后自动保存新增消息到数据库，支持增量保存与计数器维护。
  • 记忆与压缩：支持开启/关闭记忆压缩，配置触发阈值与保留近期条目，减少Token占用。
  • 长期记忆：可选接入长期记忆服务，支持用户隔离与管理模式配置。
  • 共享资源：提供共享模型与工具集的获取方法，确保应用级资源复用与一致性。

图表来源

章节来源

ConversationManager会话管理器 ​

  • LRU缓存与并发控制：使用有序字典维护会话热序，会话级锁保证串行访问，全局锁保证列表操作原子性。
  • 会话创建与加载：达到上限时LRU淘汰最旧会话；从数据库加载历史记忆，避免触发压缩；动态注册环境感知工具。
  • 超时清理：定时扫描last_access，超过阈值的会话异步归档并从内存移除。
  • 工作流构建：按需构建Manager、Data、General、Knowledge、Calculation、Summary、ClarificationGuard等Agent实例。

图表来源

章节来源

UnifiedDataAgent数据专家（ReAct循环） ​

  • 显式ReAct循环：支持最大迭代次数、思考/行动/观察阶段的结构化输出，结合Schema预感知与工具调用结果。
  • Schema感知：通过本体检索器获取物理表结构，指导SQL生成与表选择策略，避免幻觉。
  • 产物收集：将工具执行结果（如SQL数据）封装为Artifacts，供后续报告生成使用。
  • 结构化输出：使用JSON Schema约束输出，确保FINISH动作与DataArtifact结构一致。

图表来源

章节来源

ReportAgent报告专家 ​

  • 输入：接收上游产物Artifacts与原始查询，构造上下文描述。
  • 输出：基于Artifacts生成Markdown结构化报告，遵循数据驱动与图文并茂的要求。

章节来源

ManagerAgent任务调度与规划 ​

  • 意图识别：基于历史上下文与专家清单，识别用户意图并路由到合适专家。
  • 决策输出：使用JSON Schema约束输出，包含目标专家与推理原因。
  • 任务规划：生成初始计划（并行/DAG），支持增量重规划与依赖声明。
  • 缓存优化：对LLM决策结果进行缓存，提升重复查询的响应速度。

章节来源

工具集（tools.py） ​

  • 实体与指标检索：基于向量数据库检索业务实体与指标定义，辅助SQL生成。
  • SQL执行：沙箱执行SELECT查询，限制危险关键字，返回JSON结果并截断大数据量。
  • 数据库信息：返回StarRocks配置与SQL编写规范。
  • 环境感知：返回当前页面上下文信息，帮助理解用户业务场景。
  • 并行分析：触发多专家并行分析，汇总结果生成综合报告。
  • 知识图谱检索：Neo4j图谱查询，返回结构化关联信息。
  • 推广计划与策略：根据分析结果智能推荐投放策略，生成执行链接。

章节来源

依赖关系分析 ​

  • 会话管理依赖：ConversationManager依赖AgentScope的ReActAgent与InMemoryMemory，以及长期记忆服务与会话服务。
  • Agent依赖：BaseAgentHelper依赖RobustModelWrapper与统一内容解析器；BIReActAgent依赖消息存储服务实现增量保存。
  • 工具依赖：tools.py依赖OntologyRetriever、SQLSandbox与Redis缓存；并行分析依赖并行执行器。
  • 路由依赖：chat.py路由依赖ConversationManager与消息流式打印工具。

图表来源

章节来源

性能考量 ​

  • 模型与工具调用稳健性：通过RobustModelWrapper实现指数回退与异常分类处理，降低网络抖动对用户体验的影响。
  • 记忆压缩与加载策略：ConversationManager在加载历史时采用字符计数与阈值控制，避免触发压缩；同时剥离不完整工具调用链，修复历史消息格式。
  • 并发与缓存：会话级锁保证串行访问，LRU淘汰与超时清理控制内存占用；ManagerAgent对决策结果进行缓存，减少重复推理开销。
  • 数据截断与流式输出：SQL执行结果限制返回行数，消息流式增量上报，兼顾吞吐与实时性。

[本节为通用性能讨论，不直接分析具体文件]

故障排查指南 ​

  • LLM调用失败：检查RobustModelWrapper的重试日志与异常类型，确认网络连接、超时与SSL握手错误。
  • 历史消息格式异常：ConversationManager在加载时会进行历史净化，剥离不完整工具调用链；若仍出现400错误，检查消息序列完整性。
  • 会话超时与内存泄漏：确认cleanup_idle_sessions定时任务是否运行，检查会话锁释放与清理流程。
  • 工具执行异常：tools.py中的工具均提供错误兜底与结构化返回，定位异常工具与输入参数，关注SQL沙箱的安全检查与错误信息。

章节来源

结论 ​

本架构以AgentScope为核心，结合会话管理、统一基类与工具集，实现了从意图识别、任务规划、数据查询到报告生成的完整闭环。ReActAgent模式确保推理过程可解释、可追踪；ConversationManager提供高可用的会话生命周期管理；BaseAgentHelper与RobustModelWrapper保障了跨Agent的一致性与稳健性。通过结构化输出与Artifacts收集，系统能够稳定地产出高质量的分析报告与可视化建议。

[本节为总结性内容，不直接分析具体文件]

附录 ​

  • ReAct推理循环与最大迭代次数参考：见chat_v1_design文档中的推理循环图与max_iters配置。
  • 会话统计与清理策略：见memory_architecture文档中的统计方法与清理流程。
  • 会话API：见sessions路由，支持创建与删除会话。

章节来源