基于HelloAgents SimpleAgent构建智能数据分析助手：DataAnalysisAgent 实战指南

基于HelloAgents SimpleAgent构建智能数据分析助手：DataAnalysisAgent 实战指南

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents

本文基于《从零开始构建智能体》教程仓库中的共创项目 DataAnalysisAgent，完整讲解如何利用 HelloAgents 框架的 SimpleAgent、Tool/ToolParameter 工具抽象与 ModelScope 大模型 API，搭建一个能自动清洗数据、统计指标、生成 ECharts 图表并输出 Markdown 分析报告的数据分析智能体。读者读完本文后，将掌握自定义数据分析工具的开发方法、SimpleAgent 的组装与运行流程，以及分析结果落地为文件的完整实操方案。

项目概览：一个"读表 → 清洗 → 统计 → 出图 → 写报告"的端到端智能体

DataAnalysisAgent 是 HelloAgents 生态下的智能数据分析工具，核心定位是：让大模型作为"数据分析师"，自动完成表格数据的分析闭环。根据 README.md 的说明，它包含三大核心能力：

• 数据分析：统计表格数据的变化趋势，根据数据特征选用合适的图表类型；
• 智能建议：基于 LLM 生成可视化图表代码（ECharts）与结构化分析报告；
• 报告生成：输出 Markdown 格式的分析报告，并保存为独立的.md文件与可视化.html页面。

技术栈

• HelloAgents 框架的SimpleAgent（简单对话式智能体）作为智能体载体；
• PythonAST 模块（import ast）参与代码解析流程；
• OpenAI 兼容 API（项目实际使用 ModelScope 推理服务）提供智能分析能力；
• pandas / xlrd 负责 Excel 数据读取与处理。

实际项目结构

仓库中该项目的真实目录如下（与 README 中树状图略有出入，以实际为准）：

Co-creation-projects/1zrj-DataAnalysisAgent/ ├── README.md # 项目说明文档 ├── requirements.txt # 依赖列表 ├── main.ipynb # 主程序（含环境配置、工具定义、智能体创建、分析执行、结果保存） ├── data/ │ └── simple_data.xls # 示例数据表（居民消费价格指数月度数据） └── output/ ├── report.md # 生成的数据分析报告 └── echarts.html # 生成的 ECharts 可视化页面

环境准备：依赖安装与 LLM 参数配置

安装依赖

项目依赖集中在 requirements.txt，各依赖作用如下：

安装命令：

pip install -r requirements.txt

配置 LLM 参数（两种方式）

方式 1：使用.env文件（推荐）

# 复制示例文件 cp .env.example .env # 编辑 .env 文件，填入你的配置 # LLM_MODEL_ID=Qwen/Qwen2.5-72B-Instruct # LLM_API_KEY=your_api_key_here # LLM_BASE_URL=https://api-inference.modelscope.cn/v1/

方式 2：在 Notebook 中直接设置环境变量

main.ipynb 第 1 部分已经预配置了 ModelScope 的 API（采用Qwen/Qwen3-8B模型），如需更换模型，修改环境变量即可：

os.environ["LLM_MODEL_ID"] = "Qwen/Qwen3-8B" os.environ["LLM_API_KEY"] = "your_api_key_here" os.environ["LLM_BASE_URL"] = "https://api-inference.modelscope.cn/v1/" os.environ["LLM_TIMEOUT"] = "60"

四个关键环境变量的含义与说明：

说明：README 技术栈中标注"OpenAI API"，而 main.ipynb 实际通过 ModelScope 的 OpenAI 兼容接口接入 Qwen 模型，两者本质一致——凡是兼容 OpenAI Chat Completions 协议的端点均可通过LLM_BASE_URL接入，这也体现了 HelloAgents 对多服务商的适配能力。

工具系统设计：让 LLM 拥有"清洗"与"统计"两只手

数据分析智能体的关键不在于 LLM 本身，而在于为其装备的工具。本项目基于 HelloAgents 的Tool/ToolParameter抽象，定义了两个自定义工具。

DataCleaningTool：数据清洗工具

在 main.ipynb 第 2 部分定义，工具名为data_cleaner，描述为"对传入的表格数据执行清洗操作，包括去空值、列筛选等"。其get_parameters()声明的参数契约如下：

其run()的执行流程（源码可证）：

1. 从参数中取出data_json，缺失时返回"错误：缺少原始数据（data_json 不能为空）"；
2. json.loads解析数据，并读取顶层键"完整数据"对应的记录列表（这正是 main.ipynb 第 4 部分构造的输入格式）；
3. 列筛选：若指定columns_to_keep，先校验列是否都存在，缺失列会返回错误信息（f"错误：指定保留的列不存在：{missing_cols}"），避免静默丢列；
4. 空值处理：若drop_na=True则执行df.dropna()删除含空值的行，随后df.fillna(0)将剩余空值填充为 0，兼顾"删行"与"补零"两种策略；
5. 通过df.where(pd.notnull(df), None).to_dict(orient='records')将 DataFrame 转回可 JSON 序列化的记录列表，返回{"clean_data": [...]}。

值得注意的错误处理设计：工具对json.JSONDecodeError与其他异常分别返回中文错误提示（"错误：data_json 不是有效的 JSON 格式"/"清洗过程中出错：..."），而不是抛异常中断对话，这样 LLM 可以在下一轮根据错误信息自行修正参数，这是面向 Agent 的工具接口设计要点。

DataStatisticsTool：描述性统计工具

同名 Notebook 第 2 部分定义，工具名为data_statistics，接收经清洗后的数据（读取顶层键"clean_data"），按列类型分别统计：

• 数值型列（select_dtypes(include=[np.number])）：输出count、mean（均值）、median（中位数）、std（标准差）、min、max、q25（25 分位数）、q75（75 分位数）；
• 分类型列（select_dtypes(include=['object'])）：输出unique_count（唯一值数量）与top_values（Top10 取值频次，来自value_counts().head(10)）；
• 同时给出整体shape（"X 行, Y 列"）。

返回结构示例：

{ "shape": "13 行, 6 列", "numeric_stats": { "2025年10月": {"count": 13, "mean": 101.0, "median": 100.8, "std": 2.4, "min": 98.4, "max": 112.8, "q25": 100.1, "q75": 101.4} }, "categorical_stats": { "指标": {"unique_count": 13, "top_values": {"居民消费价格指数(上年同月=100)": 1}} } }

这套统计输出覆盖了均值、中位数、标准差、四分位数等描述性统计核心指标，为后续 LLM 撰写报告提供了量化依据。

智能体组装：ToolRegistry 注册与 SimpleAgent 创建

注册工具并创建 Agent

main.ipynb 第 3 部分展示了 HelloAgents 标准的组装流程：

from hello_agents import ToolRegistry # 创建工具注册表 tool_registry = ToolRegistry() tool_registry.register_tool(DataCleaningTool()) # 创建智能体 agent = SimpleAgent( name="数据分析助手", llm=HelloAgentsLLM(), system_prompt=system_prompt, tool_registry=tool_registry )

运行后输出✅ 工具 'data_cleaner' 已注册。与✅ 可用工具: ['data_cleaner']，验证注册生效。

注意：Notebook 中创建 Agent 时注册的是DataCleaningTool，而 system_prompt 同时要求使用data_cleaner和data_statistics两个工具。若希望统计能力真正被 Agent 调度，可同样执行tool_registry.register_tool(DataStatisticsTool())后重建 Agent（从源码结构看，两个工具类均已完整定义，具备直接注册的条件）。

SimpleAgent 的底层工作流

要理解上述组装为什么能工作，可以结合 HelloAgents 教程仓库 code/chapter7/my_simple_agent.py 中对SimpleAgent的重写实现来看其内部机制：

• 增强系统提示词：_get_enhanced_system_prompt()会把tool_registry.get_tools_description()得到的工具描述追加到用户 system_prompt 之后，并声明工具调用格式[TOOL_CALL:{tool_name}:{parameters}]，让模型"知道"有哪些工具可用；
• 多轮工具调用循环：_run_with_tools()在一个while current_iteration < max_tool_iterations（默认 3 轮）循环中反复调用llm.invoke()，通过正则解析[TOOL_CALL:...]标记 → 执行工具 → 把"工具执行结果：\n{tool_results_text}"回填进对话 → 再次请求 LLM，直到模型给出不含工具调用的最终回答；
• 历史记忆：每轮对话通过add_message()保存 user/assistant 消息，保证多轮交互的上下文连续性。

也就是说，即使不依赖原生 function calling，SimpleAgent 也能通过提示词约定 + 文本解析完成"思考 → 调用工具 → 基于结果作答"的循环，这正是本项目数据流能够跑通的底层支撑。

system_prompt 设计：把"分析范式"写进提示词

本项目为数据分析师角色设计了结构化 system_prompt（源码可证），核心要求：

1. 使用data_cleaner工具清洗数据；
2. 使用data_statistics工具统计数据；
3. 选择合适图表，用ECharts 代码绘制图表，并给出option = {...}的 bar/line 图示例模板；
4. 不输出 html，只输出 echarts 代码（约束输出格式，便于后续正则提取）；
5. 最后基于数据提供详细分析报告，报告须包含：
   • 分析背景与目标；
   • 关键的发现；
   • 统计计算、趋势识别、异常检测或对比分析；
   • 结论需基于数据、避免主观臆断；
   • 以 Markdown 格式输出。

这个提示词把"数据分析方法论"（背景-发现-统计-异常-对比-结论）直接编码进系统消息，让通用 LLM 表现得像一名合格的数据分析师，是该项目最具复用价值的工程经验之一。

数据读取与分析执行：完整调用链

读取 Excel 并构造输入格式

main.ipynb 第 4 部分读取./data/simple_data.xls（即 simple_data.xls，内含 13 项 CPI 分类指数在 2025 年 6 月至 10 月的月度数据）：

df = pd.read_excel(file_path) # ⚠️ 不做清洗！保留原始 NaN（pandas 会自动将 Excel 空单元格转为 NaN） data_records = df.to_dict(orient='records') # 构造符合 DataCleaningTool 要求的输入格式 clean_input = {"完整数据": data_records} sample_data = json.dumps(clean_input, ensure_ascii=False, indent=2)

这里的关键设计是：读取阶段刻意不清洗数据，保留 pandas 转换出的NaN，把清洗责任完全交给data_cleaner工具——让 LLM 在真实"脏数据"上完整走一遍工具调用流程，而不是把数据预处理藏在代码里。

执行分析

第 5 部分通过一行代码触发全流程：

result = agent.run(f"对以下数据绘制图表和数据分析\n\n{sample_data}\n")

agent.run()内部依次完成：增强提示词组装 → LLM 规划 → （需要时）调用data_cleaner清洗 → 基于清洗结果统计 → 生成 EChartsoption代码 → 生成 Markdown 报告。运行日志输出=== 开始数据分析 ===后即为模型产出的完整结果。

结果落地：正则提取、报告与图表保存

Agent 返回的result是"ECharts 代码 + Markdown 报告"的混合文本，第 6 部分通过正则将其拆分为两个产物：

1. 提取 ECharts 代码并封装 HTML

echarts_match = re.search(r"option\s*=\s*(\{[\s\S]*?\});", result) echarts_code = echarts_match.group(1)

随后用 f-string 拼接一个完整的 HTML 页面：页面引入 ECharts 的 JavaScript 库，创建#main容器（600px × 400px），把提取到的option注入myChart.setOption(option)，最终保存为 output/echarts.html，浏览器打开即可看到交互式图表。

2. 提取 Markdown 报告并落盘

report_match = re.search(r"(# 数据分析报告[\s\S]*)", result) markdown_report = report_match.group(1).strip() output_dir = "./output" os.makedirs(output_dir, exist_ok=True) md_path = os.path.join(output_dir, "report.md") with open(md_path, "w", encoding="utf-8") as f: f.write(markdown_report)

该正则要求模型报告以# 数据分析报告标题开头，与 system_prompt 的 Markdown 约束形成前后呼应——提示词约定格式 + 代码按约定解析，是 Agent 产物结构化落地的通用套路。

运行产物示例

仓库中已保留一次真实运行结果 output/report.md，可看到 LLM 对 CPI 数据的分析能力：

• 关键发现：整体 CPI 由 100.1 升至 100.2 呈温和上升；食品烟酒类在 6—8 月持续下降后于 9、10 月回升，呈季节性波动；"其他用品及服务类"10 月达 112.8，为涨幅最大类别；
• 统计计算：对 CPI（均值 100.15）、食品烟酒类（均值 99.2）、交通通信类（均值 97.4）等逐项给出均值、最大/最小值与增长率；
• 异常检测：识别出"其他用品及服务类"112.8 的显著异常高点；
• 结论：在数据支撑下给出"关注特定类别价格变动原因、应对潜在通胀压力"的落点。

运行方式与使用流程

按 README 的快速开始指引，完整使用流程为：

jupyter lab # 打开 main.ipynb 并运行所有单元格

1. 运行「第 1 部分：环境配置」，完成库导入与 LLM 配置；
2. 运行「第 2—3 部分」，定义工具并创建智能体；
3. 将待分析的数据表格放入 data/ 目录（如需分析自己的数据，替换main.ipynb第 4 部分中的file_path）；
4. 依次运行后续单元格，执行数据分析；
5. 查看生成的可视化图表 output/echarts.html 与数据分析报告 output/report.md。

扩展思路：从 SimpleAgent 走向更强范式

本项目选用SimpleAgent完成"单轮工具调用闭环"，若需要更复杂的推理-行动交替（ReAct）或反思能力，HelloAgents 教程仓库提供了可直接替换的范式：

• code/chapter7/my_react_agent.py 展示了ReActAgent的重写方式：以MY_REACT_PROMPT模板约束模型输出Thought: ...与Action: 工具名[参数]，通过max_steps（默认 5 步）控制推理深度，每步把Action与Observation追加到历史中供模型回顾，直至输出Finish[最终答案]。数据分析场景中，可让 ReAct Agent 按"清洗 → 统计 → 出图 → 报告"分步推理，提高复杂任务的容错率；
• 也可以进一步注册DataStatisticsTool、接入文件读写与搜索工具，构建更完整的分析工作流。

总结

DataAnalysisAgent 是一个麻雀虽小、五脏俱全的智能体实践项目：它用Tool/ToolParameter把数据清洗与统计抽象为可被 LLM 调用的能力，用ToolRegistry+SimpleAgent完成组装，用精心设计的 system_prompt 约束输出格式，最终通过正则解析把模型产物落地为可交付的 Markdown 报告与 ECharts 页面。对于希望快速上手"LLM + 工具"模式、或搭建自有数据分析助手的开发者而言，本文的组装流程、参数契约与提示词模板均可直接迁移复用——这也是 HelloAgents 框架"从零构建智能体"理念的最佳注脚。

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents