Agentic BI — 03-10 启动与核心实现¶
项目启动背景¶
2026年3月10日，Dad 明确项目目标：开发一个不过度复杂的 Agentic BI POC，核心验证"多代理协作 + BI 查询/分析闭环"。技术栈限定为 Python + React，优先级是快速验证而非企业级完备性。
技术架构选型¶
后端技术选择¶
- FastAPI: 高性能 Python Web 框架，支持自动文档生成
- DuckDB: 选择理由
- 适合本地/嵌入式分析场景
- SQL 能力强，天然适合 Text-to-SQL
- POC 阶段无需引入重型数仓
- Azure OpenAI: Dad 指定使用现有
AZURE_OPENAI_API_KEY
多智能体架构设计¶
采用轻量自研框架，而非 LangGraph/AutoGen，原因： - Dad 要求"先不要做太繁杂" - 目标是验证 agent team work，不是框架能力
三层智能体分工： 1. Router Agent: 理解问题、选择技能、组织参数 2. Executor Agent: 执行 SQL 查询和具体技能 3. Reviewer Agent: 审核结果合理性，必要时触发修正
关键技术问题解决¶
1. Azure OpenAI 接入适配¶
问题: 初始使用标准 OpenAI client，与 Azure 格式不兼容
解决: 切换到 AzureOpenAI client，确保 API 调用格式正确
2. 技能注册失败¶
现象: Router 返回不存在的技能名
根因: 测试脚本未导入技能模块，skill registry 未初始化
解决: 修复测试启动流程，确保技能模块正确注册
结果: 端到端全流程验证通过
3. DuckDB 数据类型兼容性¶
现象: 字符串类型报错
根因: 样例数据使用了 numpy.str_，DuckDB 1.5 兼容性差
解决: 修复数据生成逻辑，显式转换为 DuckDB 可接受类型
4. SQL 生成逻辑错误¶
问题: JOIN 条件拼接错误，缺少前置 AND
影响: 存在 dimensions 时生成非法 SQL
解决: 修复条件拼接逻辑，确保语法正确
5. 技能参数不一致¶
问题: Router 传 "year"，但枚举只支持 month/quarter
解决:
- 扩展 trend/year_over_year 技能的 period 枚举
- 支持 "year" 参数
- trend 技能增加可选 year filter
6. datetime 序列化问题¶
现象: SSE 流无法完整输出结果
根因: DuckDB 返回的 datetime 对象无法 JSON 序列化
解决: executor 层统一转换为可序列化格式
部署策略¶
端口与服务配置¶
初始方案: 前后端分离（8000/8899端口测试）
最终方案: FastAPI 统一服务
- 同时提供 API 和静态前端文件
- 单服务监听 18816 端口
- 避免代理配置复杂性
外网访问¶
Dad 要求确认功能后开放到 18816 端口供外网访问，便于直接验收。
前端流式交互实现¶
SSE 流式输出¶
后端采用 Server-Sent Events 实现推理链实时展示：
- Router 分析过程
- Executor 执行步骤
- Reviewer 审核结果
- 最终数据和可视化
UI 设计原则¶
Dad 要求参考 Claude Web 聊天界面： - 推理链默认不显眼、小字显示 - 内联展示，支持折叠 - 避免右侧滑入面板 - 形成对话式 BI 体验
交互问题修复¶
SSE 解析问题: 前端 \r\n 换行处理错误，导致回调未触发
解决: 重写 SSE parser，增加兜底逻辑
UI 细节优化: - 合并重复的推理步骤显示 - 去除 emoji 重复 - 图表日期格式化 - 收紧布局边距 - 自定义滚动条样式
业务数据升级¶
从通用到专业¶
将样例数据从通用销售数据切换为 AIA 保险场景：
- 保单数据（policies）
- 理赔数据（claims）
- 续保数据（renewals）
技术改进¶
- 数据引擎支持多表查询
- Skills 从单表逻辑改为 schema-aware
- Router system prompt 更新为保险业务语义
业务价值¶
更符合真实 BI 分析场景，为保险专属技能奠定基础。
系统可解释性¶
配置页面需求¶
Dad 要求新增配置页，"一眼看出整个系统运行逻辑"： - 三个代理的 prompt 内容 - 测试数据结构 - 系统架构图
实现方案¶
- 后端新增
/api/system-config接口 - 前端新增
ConfigPage组件 - 展示系统架构、代理提示词、数据表、技能清单
价值体现¶
提升 POC 的可解释性与演示价值，便于技术汇报和决策评估。
里程碑成果¶
2026-03-10 当日完成： - ✅ Agentic BI POC 全部功能实现 - ✅ 多智能体协作验证通过 - ✅ 端到端测试 6/6 全部通过 - ✅ 服务在 18816 端口正常运行 - ✅ SSE 流式推理链正常展示 - ✅ Claude 风格 UI 交互体验
该里程碑标志着从概念设计到可用 POC 的完整实现，为后续功能深化提供了坚实基础。