基于 HelloAgents SimpleAgent 构建智能数据分析助手DataAnalysisAgent 实战指南【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agentsDataAnalysisAgent 是 Datawhale《从零开始构建智能体》hello-agents仓库中一个基于 HelloAgents 框架SimpleAgent打造的智能数据分析共创项目它接收 Excel 表格数据自动完成数据清洗、描述性统计再由 LLM 生成 ECharts 图表代码与 Markdown 分析报告。阅读本文后你将掌握用 HelloAgents 的Tool/ToolParameter/ToolRegistry自定义分析工具、用SimpleAgent编排清洗→统计→可视化→报告完整链路并把 LLM 输出解析落地为echarts.html与report.md两个可直接交付的产物。一、项目定位与核心功能DataAnalysisAgent 的定位是一句话可概括的基于 HelloAgents 框架的智能数据分析工具让用户把待分析的数据表格交给智能体剩下的怎么分析、画什么图、报告写什么全部由 LLM 自主决策。根据项目 README.md 与 main.ipynb其核心功能有三项功能说明落地产物数据分析统计数据变化趋势、识别规律与异常并自主选用合适的图表类型数据统计 JSON 结果智能建议基于 LLM 生成 ECharts 可视化图表代码与结构化分析报告echarts.html报告生成生成包含背景目标、关键发现、统计计算、异常检测与结论的 Markdown 报告report.md该项目的技术栈横跨三个层次HelloAgents 框架使用SimpleAgent作为智能体主体配合Tool、ToolParameter、ToolRegistry构建可插拔工具系统Python AST 模块在数据分析链路中承担代码解析能力项目中用于安全解析与提取 LLM 输出的 ECharts 代码段LLM API通过 OpenAI 兼容协议接入模型推理服务main.ipynb 中实际配置的是 ModelScope 的推理端点https://api-inference.modelscope.cn/v1/与Qwen/Qwen3-8B模型README 中所述OpenAI API指的即是这一 OpenAI 兼容接口。二、项目结构与运行入口先厘清项目的真实文件组织注意README 中项目结构一节存在复制粘贴错误实际结构以仓库为准Co-creation-projects/1zrj-DataAnalysisAgent/ ├── README.md # 项目说明文档 ├── requirements.txt # 依赖列表 ├── main.ipynb # 主程序环境配置、工具定义、智能体创建、数据分析、结果保存 ├── data/ │ └── simple_data.xls # 示例数据表格居民消费价格指数 CPI 月度数据 └── output/ ├── report.md # 生成的数据分析报告Markdown └── echarts.html # 生成的图表页面HTML整个项目围绕单一 Notebook 入口 main.ipynb 运行其中按顺序组织为 6 个部分环境配置 → 定义数据分析工具 → 创建智能体 → 读取示例数据 → 执行数据分析 → 保存分析报告与图表。README 中提到的第 0 部分快速演示即用于快速体验全流程的演示单元。三、环境准备与依赖安装在开始前需要准备一个可运行 Jupyter Notebook 的 Python 环境。依赖清单见 requirements.txt共四组# HelloAgents框架 hello-agents[all]0.1.0 # Jupyter环境 jupyter1.0.0 notebook7.0.0 # 读取excel文件 xlrd2.0.1 # 环境变量管理 python-dotenv1.0.0各组依赖的职责如下hello-agents[all]0.1.0HelloAgents 框架本体提供SimpleAgent、HelloAgentsLLM、Tool、ToolParameter、ToolRegistry等核心类jupyter1.0.0、notebook7.0.0Jupyter 运行环境用于执行 main.ipynbxlrd2.0.1读取旧版.xls格式 Excel 文件的解析库示例数据 simple_data.xls 即为此格式python-dotenv1.0.0加载.env环境变量文件配合HelloAgentsLLM的自动探测机制使用。安装命令pip install -r requirements.txt安装完成后启动 Notebook 并打开主程序jupyter lab # 打开 main.ipynb 并依次运行所有单元格四、LLM 参数配置两种方式与底层自动探测原理智能体的一切智能行为都依赖 LLM 推理。项目提供了两种配置方式方式 1使用.env文件推荐# 复制示例文件 cp .env.example .env # 编辑 .env 文件填入你的配置 # LLM_MODEL_IDQwen/Qwen2.5-72B-Instruct # LLM_API_KEYyour_api_key_here # LLM_BASE_URLhttps://api-inference.modelscope.cn/v1/方式 2在 Notebook 中直接设置项目已预配置main.ipynb 第 1 部分已预置了 ModelScope 的 API 配置可直接使用如需更换模型或服务商编辑该部分的环境变量即可os.environ[LLM_MODEL_ID] Qwen/Qwen3-8B os.environ[LLM_API_KEY] ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx os.environ[LLM_BASE_URL] https://api-inference.modelscope.cn/v1/ os.environ[LLM_TIMEOUT] 60其中LLM_TIMEOUT用于控制单次请求的超时时间单位为秒本项目设为 60避免长文本生成场景下请求被过早中断。这一零参数实例化之所以成立源于框架文档 第七章 构建你的Agent框架 中介绍的HelloAgentsLLM自动探测机制。其内部通过_auto_detect_provider与_resolve_credentials两个方法协作完成服务商识别与凭据补全最高优先级——服务商专属环境变量依次检查MODELSCOPE_API_KEY、OPENAI_API_KEY、ZHIPU_API_KEY等命中即确定 provider次高优先级——解析base_url按域名特征如api-inference.modelscope.cn→ modelscope、api.openai.com→ openai或本地端口特征:11434→ ollama、:8000→ vllm推断服务商辅助判断——分析LLM_API_KEY格式例如以ms-前缀开头的 Key 判定为 ModelScope本项目LLM_API_KEY正是ms-开头兜底返回auto使用通用配置。确定 provider 后_resolve_credentials会为 modelscope 自动补全默认base_url为https://api-inference.modelscope.cn/v1/为 openai 自动补全为https://api.openai.com/v1。因此本项目的代码只需HelloAgentsLLM()裸实例化即可正确连上 ModelScope 服务。若在 Notebook 中同时使用python-dotenv的load_dotenv()还可以实现改.env不动代码的服务商无缝切换。五、自定义数据分析工具Tool 与 ToolParameter 实战HelloAgents 的工具系统为自定义工具定义了统一契约。框架文档 第七章 展示了Tool抽象基类的设计——每个工具必须实现两个方法run(parameters: Dict[str, Any]) - str执行工具逻辑入参为字典、返回字符串保证框架调用一致性get_parameters() - List[ToolParameter]返回参数定义清单实现工具的自描述introspection为自动化文档生成与参数校验提供基础。ToolParameter则是一个参数描述模型包含name、type、description、required、default等字段。DataAnalysisAgent 严格遵循这一契约定义了两个数据分析工具。5.1 DataCleaningTool数据清洗工具class DataCleaningTool(Tool): 数据清洗工具 - 基于用户指定规则清洗表格数据 def __init__(self): super().__init__( namedata_cleaner, description对传入的表格数据执行清洗操作包括去空值、列筛选等 ) def run(self, parameters: Dict[str, Any]) - str: data_json parameters.get(data_json) if not data_json: return 错误缺少原始数据data_json 不能为空 try: raw_data json.loads(data_json) records raw_data.get(完整数据, []) if not records: return 警告原始数据为空无法清洗 df pd.DataFrame(records) # 1. 列筛选 columns_to_keep parameters.get(columns_to_keep) if columns_to_keep: missing_cols [col for col in columns_to_keep if col not in df.columns] if missing_cols: return f错误指定保留的列不存在{missing_cols} df df[columns_to_keep] # 2. 删除空值行 if parameters.get(drop_na, False): original_len len(df) df df.dropna() dropped original_len - len(df) if dropped 0: pass df df.fillna(0) cleaned_records df.where(pd.notnull(df), None).to_dict(orientrecords) result {clean_data: cleaned_records} return json.dumps(result, ensure_asciiFalse, indent2) except json.JSONDecodeError: return 错误data_json 不是有效的 JSON 格式 except Exception as e: return f清洗过程中出错{str(e)} def get_parameters(self) - List[ToolParameter]: return [ ToolParameter( namedata_json, typestring, description原始数据的 JSON 字符串, requiredTrue ), ToolParameter( namedrop_na, typeboolean, description是否删除包含空值的行, requiredFalse ), ToolParameter( namecolumns_to_keep, typearray, description要保留的列名列表, requiredFalse ), ]这个工具的设计有三个值得注意的工程细节输入输出均为 JSON 字符串data_json是必填参数输出{clean_data: [...]}结构保证工具与 LLM 之间传递的数据可被稳定序列化、解析参数可选性与默认值drop_na默认False不删除空值行columns_to_keep为空则跳过列筛选且对不存在的列名做了显式校验与中文错误提示把LLM 传错参数的容错前置到工具层数据口径约定工具约定输入的顶层键为完整数据与后文第 4 部分读表逻辑严格对齐清洗后输出键为clean_data与统计工具的数据入口严格对齐两个工具通过这一约定形成流水线衔接。5.2 DataStatisticsTool数据统计工具class DataStatisticsTool(Tool): 数据统计工具 - 提供描述性统计分析 def __init__(self): super().__init__( namedata_statistics, description对数据进行描述性统计分析包括均值、中位数、标准差等 ) def run(self, parameters: Dict[str, Any]) - str: data_json parameters.get(data_json) if not data_json: return 错误缺少数据 try: raw_data json.loads(data_json) records raw_data.get(clean_data, []) # 读取清洗后的数据 df pd.DataFrame(records) # 数值型列的统计 numeric_stats {} for col in df.select_dtypes(include[np.number]).columns: numeric_stats[col] { count: int(df[col].count()), mean: float(df[col].mean()), median: float(df[col].median()), std: float(df[col].std()), min: float(df[col].min()), max: float(df[col].max()), q25: float(df[col].quantile(0.25)), q75: float(df[col].quantile(0.75)) } # 分类型列的统计 categorical_stats {} for col in df.select_dtypes(include[object]).columns: value_counts df[col].value_counts().head(10).to_dict() categorical_stats[col] { unique_count: int(df[col].nunique()), top_values: value_counts } result { shape: f{len(df)} 行, {len(df.columns)} 列, numeric_stats: numeric_stats, categorical_stats: categorical_stats, } return json.dumps(result, ensure_asciiFalse, indent2) except Exception as e: return f统计分析出错{str(e)} def get_parameters(self) - List[ToolParameter]: return [ ToolParameter( namedata_json, typestring, description数据的 JSON 字符串, requiredTrue ) ]统计工具按列类型分流处理并输出一套可直接供 LLM 引用的结构化指标指标维度覆盖内容数值型列count计数、mean均值、median中位数、std标准差、min/max极值、q25/q75四分位数分类型列unique_count唯一值数量、top_values频数 Top 10 分布整体形状shapeN 行, M 列从源码结构看该工具使用np.number筛选数值列实际运行时依赖 numpy 环境可用pandas 本身依赖 numpy多数环境中可直接引用若遇 NameError可在文件头部显式import numpy as np。这套统计输出正是第 5 部分 LLM 撰写统计计算与趋势识别章节时的事实依据——所有数字都由工具真实计算得出而非模型臆造。六、智能体编排ToolRegistry SimpleAgent 系统提示词工具就绪后进入智能体组装阶段main.ipynb 第 3 部分from hello_agents import ToolRegistry # 创建工具注册表并注册数据清洗工具 tool_registry ToolRegistry() tool_registry.register_tool(DataCleaningTool()) system_prompt 你是一名数据分析师,你的任务是: 1. 使用data_cleaner工具清洗数据 2. 使用data_statistics工具统计数据 3. 选择合适的图表用echarts代码绘制图表例如 option { xAxis: { type: category, data: [Mon, Tue, Wed, Thu, Fri, Sat, Sun] }, yAxis: { type: value }, series: [ { data: [120, 200, 150, 80, 70, 110, 130], type: bar } ] }; 3、不要对代码分析不要输出html只输出echarts代码 4、最后基于数据提供详细的数据分析报告 数据分析报告应包括 - 分析背景与目标 - 关键的发现 - 进行统计计算、趋势识别、异常检测或对比分析 避免主观臆断结论需基于数据 请以Markdown格式输出报告。 # 创建智能体 agent SimpleAgent( name数据分析助手, llmHelloAgentsLLM(), system_promptsystem_prompt, tool_registrytool_registry )6.1 ToolRegistry 的注册机制ToolRegistry是工具系统的管理中枢。框架文档 第七章 给出了其核心设计内部以self._tools: dict[str, Tool]保存Tool对象支持两种注册方式——register_tool(tool)注册完整工具对象本项目采用的方式适合带参数校验的复杂工具以及register_function(...)直接注册普通函数适合简单工具同时提供get_tools_description()生成格式化工具清单框架会将该清单注入 Agent 提示词让 LLM 知道自己有哪些工具可用。本项目中运行日志输出的✅ 可用工具: [data_cleaner]正是读取tool_registry._tools键的结果。6.2 SimpleAgent 的多轮工具调用循环SimpleAgent是框架中最基础的对话智能体。以仓库教学实现 my_simple_agent.py 为例其run方法在启用工具时会进入_run_with_tools多轮循环调用 LLM → 解析文本中的[TOOL_CALL:工具名:参数]标记 → 执行工具 → 把执行结果回填消息 → 再次调用 LLM直至模型给出不含工具调用的最终回答受max_tool_iterations轮数上限约束。这说明 DataAnalysisAgent 的清洗 → 统计 → 绘图 → 报告并非预先写死的流水线而是模型在工具可用清单的引导下自主决策、逐步完成的 ReAct 式循环。6.3 系统提示词的三重约束设计system_prompt是本项目的灵魂它通过三重约束保证输出质量流程约束明确要求先清洗、再统计的两步走顺序格式约束给出 EChartsoption的标准模板并强约束只输出 echarts 代码不输出 html、不做代码分析——这为第 7 部分的正则提取提供了前提报告约束规定报告必须包含分析背景与目标、关键发现、统计计算/趋势识别/异常检测/对比分析且结论需基于数据、避免主观臆断以 Markdown 格式输出。七、数据读取与执行分析7.1 读取 Excel 示例数据main.ipynb 第 4 部分负责把 data/simple_data.xls 读入内存并序列化为工具要求的输入格式file_path ./data/simple_data.xls try: df pd.read_excel(file_path) # ⚠️ 不做清洗保留原始 NaNpandas 会自动将 Excel 空单元格转为 NaN data_records df.to_dict(orientrecords) # 构造符合 DataCleaningTool 要求的输入格式 clean_input { 完整数据: data_records } sample_data json.dumps(clean_input, ensure_asciiFalse, indent2) except FileNotFoundError: sample_data json.dumps({error: fExcel 文件不存在: {file_path}}, ensure_asciiFalse) except Exception as e: sample_data json.dumps({error: f读取 Excel 文件失败: {str(e)}}, ensure_asciiFalse)这里有一个精心设计的要点读表阶段刻意不做清洗保留 pandas 自动将空单元格转换出的 NaN把是否删除空值的决策权交给 LLM 在调用data_cleaner时用drop_na参数决定。同时完整数据这一键名与DataCleaningTool.run中raw_data.get(完整数据, [])严格对齐构成工具链的数据契约。示例数据为 13 个 CPI居民消费价格指数上年同月100分类指标在 2025 年 6 月至 10 月的月度数值包括居民消费价格指数、食品烟酒类、衣着类、居住类、交通通信类等——这是一个典型的宽表 多分类时序场景非常适合演示多系列折线图与分类对比分析。7.2 执行数据分析第 5 部分将序列化后的数据作为用户消息提交给智能体result agent.run(f对以下数据绘制图表和数据分析\n\n{sample_data}\n)智能体收到数据后按系统提示词的引导自主完成全流程调用清洗工具 → 调用统计工具 → 基于统计结果输出 EChartsoption代码 → 输出 Markdown 分析报告。实际运行产物显示LLM 最终选择了折线图type: line横轴为[2025年6月 ... 2025年10月]13 个 CPI 分类各占一条 series数据值与 Excel 原始值一一对应——证明统计、绘图均建立在真实计算之上。八、结果解析与产物保存LLM 的原始返回是一个混合了 ECharts 代码与 Markdown 报告的复合文本main.ipynb 第 6 部分用两个正则完成结构化拆解1. 提取 ECharts 代码匹配option {...};形式的 JS 对象字面量import re import os echarts_match re.search(roption\s*\s*(\{[\s\S]*?\});, result) if echarts_match: echarts_code echarts_match.group(1) else: print(未找到 ECharts 代码)2. 提取 Markdown 报告从# 数据分析报告标题处截取到结尾report_match re.search(r(# 数据分析报告[\s\S]*), result) markdown_report report_match.group(1).strip()3. 保存报告到文件output_dir ./output os.makedirs(output_dir, exist_okTrue) md_path os.path.join(output_dir, report.md) with open(md_path, w, encodingutf-8) as f: f.write(markdown_report) print(f\nMarkdown 报告已保存至: {md_path})4. 将 ECharts 代码嵌入 HTML 模板通过IPython.display.HTML构建页面并用IFrame/文件写入保存为 echarts.htmlhtml_code f !DOCTYPE html html head meta charsetutf-8 title第一个 ECharts 实例/title !-- 引入 echarts.js -- script srchttps://cdn.staticfile.org/echarts/4.3.0/echarts.min.js/script /head body !-- 为ECharts准备一个具备大小宽高的Dom -- div idmain stylewidth: 600px;height:400px;/div script typetext/javascript // 基于准备好的dom初始化echarts实例 var myChart echarts.init(document.getElementById(main)); // 指定图表的配置项和数据 var option {echarts_code} // 使用刚指定的配置项和数据显示图表。 myChart.setOption(option); /script /body /html with open(./output/echarts.html, w, encodingutf-8) as f: f.write(html_code)这套正则提取 HTML 模板注入的落地方式非常轻量不需要额外的前端工程ECharts 通过 CDN 引入版本 4.3.0LLM 生成的option对象被直接setOption渲染即可在浏览器中看到交互式图表。九、实际运行效果报告与图表质量验证运行完成后output/目录下的两份产物即为最终交付物。以 report.md 为例其报告结构完整覆盖了系统提示词要求的全部章节分析背景与目标明确报告对象为 2025 年 6–10 月各分类 CPI 变化趋势服务于趋势识别、异常定位与对比分析关键的发现提炼出 7 条结论例如CPI 总体温和上升100.1 → 100.2其他用品及服务类价格指数 10 月达 112.8涨幅最大食品烟酒类存在季节性波动统计计算与趋势识别逐类列出平均值、最大值、最小值与增长率如其他用品及服务类平均值 108.3、增长率 4.4%交通通信类平均值 97.4、增长率 2.3%——这些数字与 DataStatisticsTool 输出口径一致异常检测识别出其他用品及服务类 10 月 112.8 显著偏高食品烟酒类 6–8 月持续下行、9–10 月回升两处异常并给出特定商品价格上涨或供应紧张季节性因素等数据驱动的推测对比分析横向比较各分类涨跌幅度差异指出非食品与服务类占比上升的趋势结论对全篇分析给出凝练收束。对应的 echarts.html 则承载了 13 个分类的折线对比图。将报告的文字结论与图表的视觉走向相互印证即可验证整个工具计算 → LLM 解读链路的可靠性——这也正是本项目作为智能数据分析助手区别于传统 BI 模板的关键分析视角与结论表述完全由 LLM 依据真实统计结果动态生成。十、总结与扩展方向DataAnalysisAgent 以约 200 行 Notebook 代码完整演示了 HelloAgents 框架下数据密集型 Agent的最小可行范式工具系统通过Tool/ToolParameter/ToolRegistry把 Pandas 清洗与统计能力封装为 LLM 可感知、可调用的原子能力智能体编排用SimpleAgent 精心设计的系统提示词实现清洗→统计→绘图→报告的自主决策链路结论必须基于工具的真实计算结果产物落地用正则从模型复合输出中拆解 EChartsoption与 Markdown 报告一键产出可分享的 HTML 图表与结构化报告。若在此基础上继续扩展可以从以下几个方向增强更多分析工具注册异常检测如 Z-score/3σ 规则、相关性分析、趋势回归等Tool让统计深度随工具数量线性增长多数据源支持扩展excel_reader思路增加 CSV、数据库等读取工具并保持原始数据键名 → 清洗工具 → 统计工具的数据契约一致性结果质量把关在保存报告前加入格式校验或在报告中嵌入统计工具输出的关键指标作为证据链进一步抑制模型幻觉框架能力升级参考仓库 第四章 智能体经典范式构建 与 第七章 构建你的Agent框架 中的 ReActAgent、ReflectionAgent 等范式为数据分析流程引入先规划再执行或自我反思能力。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 HelloAgents SimpleAgent 构建智能数据分析助手：DataAnalysisAgent 实战指南
基于 HelloAgents SimpleAgent 构建智能数据分析助手DataAnalysisAgent 实战指南【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agentsDataAnalysisAgent 是 Datawhale《从零开始构建智能体》hello-agents仓库中一个基于 HelloAgents 框架SimpleAgent打造的智能数据分析共创项目它接收 Excel 表格数据自动完成数据清洗、描述性统计再由 LLM 生成 ECharts 图表代码与 Markdown 分析报告。阅读本文后你将掌握用 HelloAgents 的Tool/ToolParameter/ToolRegistry自定义分析工具、用SimpleAgent编排清洗→统计→可视化→报告完整链路并把 LLM 输出解析落地为echarts.html与report.md两个可直接交付的产物。一、项目定位与核心功能DataAnalysisAgent 的定位是一句话可概括的基于 HelloAgents 框架的智能数据分析工具让用户把待分析的数据表格交给智能体剩下的怎么分析、画什么图、报告写什么全部由 LLM 自主决策。根据项目 README.md 与 main.ipynb其核心功能有三项功能说明落地产物数据分析统计数据变化趋势、识别规律与异常并自主选用合适的图表类型数据统计 JSON 结果智能建议基于 LLM 生成 ECharts 可视化图表代码与结构化分析报告echarts.html报告生成生成包含背景目标、关键发现、统计计算、异常检测与结论的 Markdown 报告report.md该项目的技术栈横跨三个层次HelloAgents 框架使用SimpleAgent作为智能体主体配合Tool、ToolParameter、ToolRegistry构建可插拔工具系统Python AST 模块在数据分析链路中承担代码解析能力项目中用于安全解析与提取 LLM 输出的 ECharts 代码段LLM API通过 OpenAI 兼容协议接入模型推理服务main.ipynb 中实际配置的是 ModelScope 的推理端点https://api-inference.modelscope.cn/v1/与Qwen/Qwen3-8B模型README 中所述OpenAI API指的即是这一 OpenAI 兼容接口。二、项目结构与运行入口先厘清项目的真实文件组织注意README 中项目结构一节存在复制粘贴错误实际结构以仓库为准Co-creation-projects/1zrj-DataAnalysisAgent/ ├── README.md # 项目说明文档 ├── requirements.txt # 依赖列表 ├── main.ipynb # 主程序环境配置、工具定义、智能体创建、数据分析、结果保存 ├── data/ │ └── simple_data.xls # 示例数据表格居民消费价格指数 CPI 月度数据 └── output/ ├── report.md # 生成的数据分析报告Markdown └── echarts.html # 生成的图表页面HTML整个项目围绕单一 Notebook 入口 main.ipynb 运行其中按顺序组织为 6 个部分环境配置 → 定义数据分析工具 → 创建智能体 → 读取示例数据 → 执行数据分析 → 保存分析报告与图表。README 中提到的第 0 部分快速演示即用于快速体验全流程的演示单元。三、环境准备与依赖安装在开始前需要准备一个可运行 Jupyter Notebook 的 Python 环境。依赖清单见 requirements.txt共四组# HelloAgents框架 hello-agents[all]0.1.0 # Jupyter环境 jupyter1.0.0 notebook7.0.0 # 读取excel文件 xlrd2.0.1 # 环境变量管理 python-dotenv1.0.0各组依赖的职责如下hello-agents[all]0.1.0HelloAgents 框架本体提供SimpleAgent、HelloAgentsLLM、Tool、ToolParameter、ToolRegistry等核心类jupyter1.0.0、notebook7.0.0Jupyter 运行环境用于执行 main.ipynbxlrd2.0.1读取旧版.xls格式 Excel 文件的解析库示例数据 simple_data.xls 即为此格式python-dotenv1.0.0加载.env环境变量文件配合HelloAgentsLLM的自动探测机制使用。安装命令pip install -r requirements.txt安装完成后启动 Notebook 并打开主程序jupyter lab # 打开 main.ipynb 并依次运行所有单元格四、LLM 参数配置两种方式与底层自动探测原理智能体的一切智能行为都依赖 LLM 推理。项目提供了两种配置方式方式 1使用.env文件推荐# 复制示例文件 cp .env.example .env # 编辑 .env 文件填入你的配置 # LLM_MODEL_IDQwen/Qwen2.5-72B-Instruct # LLM_API_KEYyour_api_key_here # LLM_BASE_URLhttps://api-inference.modelscope.cn/v1/方式 2在 Notebook 中直接设置项目已预配置main.ipynb 第 1 部分已预置了 ModelScope 的 API 配置可直接使用如需更换模型或服务商编辑该部分的环境变量即可os.environ[LLM_MODEL_ID] Qwen/Qwen3-8B os.environ[LLM_API_KEY] ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx os.environ[LLM_BASE_URL] https://api-inference.modelscope.cn/v1/ os.environ[LLM_TIMEOUT] 60其中LLM_TIMEOUT用于控制单次请求的超时时间单位为秒本项目设为 60避免长文本生成场景下请求被过早中断。这一零参数实例化之所以成立源于框架文档 第七章 构建你的Agent框架 中介绍的HelloAgentsLLM自动探测机制。其内部通过_auto_detect_provider与_resolve_credentials两个方法协作完成服务商识别与凭据补全最高优先级——服务商专属环境变量依次检查MODELSCOPE_API_KEY、OPENAI_API_KEY、ZHIPU_API_KEY等命中即确定 provider次高优先级——解析base_url按域名特征如api-inference.modelscope.cn→ modelscope、api.openai.com→ openai或本地端口特征:11434→ ollama、:8000→ vllm推断服务商辅助判断——分析LLM_API_KEY格式例如以ms-前缀开头的 Key 判定为 ModelScope本项目LLM_API_KEY正是ms-开头兜底返回auto使用通用配置。确定 provider 后_resolve_credentials会为 modelscope 自动补全默认base_url为https://api-inference.modelscope.cn/v1/为 openai 自动补全为https://api.openai.com/v1。因此本项目的代码只需HelloAgentsLLM()裸实例化即可正确连上 ModelScope 服务。若在 Notebook 中同时使用python-dotenv的load_dotenv()还可以实现改.env不动代码的服务商无缝切换。五、自定义数据分析工具Tool 与 ToolParameter 实战HelloAgents 的工具系统为自定义工具定义了统一契约。框架文档 第七章 展示了Tool抽象基类的设计——每个工具必须实现两个方法run(parameters: Dict[str, Any]) - str执行工具逻辑入参为字典、返回字符串保证框架调用一致性get_parameters() - List[ToolParameter]返回参数定义清单实现工具的自描述introspection为自动化文档生成与参数校验提供基础。ToolParameter则是一个参数描述模型包含name、type、description、required、default等字段。DataAnalysisAgent 严格遵循这一契约定义了两个数据分析工具。5.1 DataCleaningTool数据清洗工具class DataCleaningTool(Tool): 数据清洗工具 - 基于用户指定规则清洗表格数据 def __init__(self): super().__init__( namedata_cleaner, description对传入的表格数据执行清洗操作包括去空值、列筛选等 ) def run(self, parameters: Dict[str, Any]) - str: data_json parameters.get(data_json) if not data_json: return 错误缺少原始数据data_json 不能为空 try: raw_data json.loads(data_json) records raw_data.get(完整数据, []) if not records: return 警告原始数据为空无法清洗 df pd.DataFrame(records) # 1. 列筛选 columns_to_keep parameters.get(columns_to_keep) if columns_to_keep: missing_cols [col for col in columns_to_keep if col not in df.columns] if missing_cols: return f错误指定保留的列不存在{missing_cols} df df[columns_to_keep] # 2. 删除空值行 if parameters.get(drop_na, False): original_len len(df) df df.dropna() dropped original_len - len(df) if dropped 0: pass df df.fillna(0) cleaned_records df.where(pd.notnull(df), None).to_dict(orientrecords) result {clean_data: cleaned_records} return json.dumps(result, ensure_asciiFalse, indent2) except json.JSONDecodeError: return 错误data_json 不是有效的 JSON 格式 except Exception as e: return f清洗过程中出错{str(e)} def get_parameters(self) - List[ToolParameter]: return [ ToolParameter( namedata_json, typestring, description原始数据的 JSON 字符串, requiredTrue ), ToolParameter( namedrop_na, typeboolean, description是否删除包含空值的行, requiredFalse ), ToolParameter( namecolumns_to_keep, typearray, description要保留的列名列表, requiredFalse ), ]这个工具的设计有三个值得注意的工程细节输入输出均为 JSON 字符串data_json是必填参数输出{clean_data: [...]}结构保证工具与 LLM 之间传递的数据可被稳定序列化、解析参数可选性与默认值drop_na默认False不删除空值行columns_to_keep为空则跳过列筛选且对不存在的列名做了显式校验与中文错误提示把LLM 传错参数的容错前置到工具层数据口径约定工具约定输入的顶层键为完整数据与后文第 4 部分读表逻辑严格对齐清洗后输出键为clean_data与统计工具的数据入口严格对齐两个工具通过这一约定形成流水线衔接。5.2 DataStatisticsTool数据统计工具class DataStatisticsTool(Tool): 数据统计工具 - 提供描述性统计分析 def __init__(self): super().__init__( namedata_statistics, description对数据进行描述性统计分析包括均值、中位数、标准差等 ) def run(self, parameters: Dict[str, Any]) - str: data_json parameters.get(data_json) if not data_json: return 错误缺少数据 try: raw_data json.loads(data_json) records raw_data.get(clean_data, []) # 读取清洗后的数据 df pd.DataFrame(records) # 数值型列的统计 numeric_stats {} for col in df.select_dtypes(include[np.number]).columns: numeric_stats[col] { count: int(df[col].count()), mean: float(df[col].mean()), median: float(df[col].median()), std: float(df[col].std()), min: float(df[col].min()), max: float(df[col].max()), q25: float(df[col].quantile(0.25)), q75: float(df[col].quantile(0.75)) } # 分类型列的统计 categorical_stats {} for col in df.select_dtypes(include[object]).columns: value_counts df[col].value_counts().head(10).to_dict() categorical_stats[col] { unique_count: int(df[col].nunique()), top_values: value_counts } result { shape: f{len(df)} 行, {len(df.columns)} 列, numeric_stats: numeric_stats, categorical_stats: categorical_stats, } return json.dumps(result, ensure_asciiFalse, indent2) except Exception as e: return f统计分析出错{str(e)} def get_parameters(self) - List[ToolParameter]: return [ ToolParameter( namedata_json, typestring, description数据的 JSON 字符串, requiredTrue ) ]统计工具按列类型分流处理并输出一套可直接供 LLM 引用的结构化指标指标维度覆盖内容数值型列count计数、mean均值、median中位数、std标准差、min/max极值、q25/q75四分位数分类型列unique_count唯一值数量、top_values频数 Top 10 分布整体形状shapeN 行, M 列从源码结构看该工具使用np.number筛选数值列实际运行时依赖 numpy 环境可用pandas 本身依赖 numpy多数环境中可直接引用若遇 NameError可在文件头部显式import numpy as np。这套统计输出正是第 5 部分 LLM 撰写统计计算与趋势识别章节时的事实依据——所有数字都由工具真实计算得出而非模型臆造。六、智能体编排ToolRegistry SimpleAgent 系统提示词工具就绪后进入智能体组装阶段main.ipynb 第 3 部分from hello_agents import ToolRegistry # 创建工具注册表并注册数据清洗工具 tool_registry ToolRegistry() tool_registry.register_tool(DataCleaningTool()) system_prompt 你是一名数据分析师,你的任务是: 1. 使用data_cleaner工具清洗数据 2. 使用data_statistics工具统计数据 3. 选择合适的图表用echarts代码绘制图表例如 option { xAxis: { type: category, data: [Mon, Tue, Wed, Thu, Fri, Sat, Sun] }, yAxis: { type: value }, series: [ { data: [120, 200, 150, 80, 70, 110, 130], type: bar } ] }; 3、不要对代码分析不要输出html只输出echarts代码 4、最后基于数据提供详细的数据分析报告 数据分析报告应包括 - 分析背景与目标 - 关键的发现 - 进行统计计算、趋势识别、异常检测或对比分析 避免主观臆断结论需基于数据 请以Markdown格式输出报告。 # 创建智能体 agent SimpleAgent( name数据分析助手, llmHelloAgentsLLM(), system_promptsystem_prompt, tool_registrytool_registry )6.1 ToolRegistry 的注册机制ToolRegistry是工具系统的管理中枢。框架文档 第七章 给出了其核心设计内部以self._tools: dict[str, Tool]保存Tool对象支持两种注册方式——register_tool(tool)注册完整工具对象本项目采用的方式适合带参数校验的复杂工具以及register_function(...)直接注册普通函数适合简单工具同时提供get_tools_description()生成格式化工具清单框架会将该清单注入 Agent 提示词让 LLM 知道自己有哪些工具可用。本项目中运行日志输出的✅ 可用工具: [data_cleaner]正是读取tool_registry._tools键的结果。6.2 SimpleAgent 的多轮工具调用循环SimpleAgent是框架中最基础的对话智能体。以仓库教学实现 my_simple_agent.py 为例其run方法在启用工具时会进入_run_with_tools多轮循环调用 LLM → 解析文本中的[TOOL_CALL:工具名:参数]标记 → 执行工具 → 把执行结果回填消息 → 再次调用 LLM直至模型给出不含工具调用的最终回答受max_tool_iterations轮数上限约束。这说明 DataAnalysisAgent 的清洗 → 统计 → 绘图 → 报告并非预先写死的流水线而是模型在工具可用清单的引导下自主决策、逐步完成的 ReAct 式循环。6.3 系统提示词的三重约束设计system_prompt是本项目的灵魂它通过三重约束保证输出质量流程约束明确要求先清洗、再统计的两步走顺序格式约束给出 EChartsoption的标准模板并强约束只输出 echarts 代码不输出 html、不做代码分析——这为第 7 部分的正则提取提供了前提报告约束规定报告必须包含分析背景与目标、关键发现、统计计算/趋势识别/异常检测/对比分析且结论需基于数据、避免主观臆断以 Markdown 格式输出。七、数据读取与执行分析7.1 读取 Excel 示例数据main.ipynb 第 4 部分负责把 data/simple_data.xls 读入内存并序列化为工具要求的输入格式file_path ./data/simple_data.xls try: df pd.read_excel(file_path) # ⚠️ 不做清洗保留原始 NaNpandas 会自动将 Excel 空单元格转为 NaN data_records df.to_dict(orientrecords) # 构造符合 DataCleaningTool 要求的输入格式 clean_input { 完整数据: data_records } sample_data json.dumps(clean_input, ensure_asciiFalse, indent2) except FileNotFoundError: sample_data json.dumps({error: fExcel 文件不存在: {file_path}}, ensure_asciiFalse) except Exception as e: sample_data json.dumps({error: f读取 Excel 文件失败: {str(e)}}, ensure_asciiFalse)这里有一个精心设计的要点读表阶段刻意不做清洗保留 pandas 自动将空单元格转换出的 NaN把是否删除空值的决策权交给 LLM 在调用data_cleaner时用drop_na参数决定。同时完整数据这一键名与DataCleaningTool.run中raw_data.get(完整数据, [])严格对齐构成工具链的数据契约。示例数据为 13 个 CPI居民消费价格指数上年同月100分类指标在 2025 年 6 月至 10 月的月度数值包括居民消费价格指数、食品烟酒类、衣着类、居住类、交通通信类等——这是一个典型的宽表 多分类时序场景非常适合演示多系列折线图与分类对比分析。7.2 执行数据分析第 5 部分将序列化后的数据作为用户消息提交给智能体result agent.run(f对以下数据绘制图表和数据分析\n\n{sample_data}\n)智能体收到数据后按系统提示词的引导自主完成全流程调用清洗工具 → 调用统计工具 → 基于统计结果输出 EChartsoption代码 → 输出 Markdown 分析报告。实际运行产物显示LLM 最终选择了折线图type: line横轴为[2025年6月 ... 2025年10月]13 个 CPI 分类各占一条 series数据值与 Excel 原始值一一对应——证明统计、绘图均建立在真实计算之上。八、结果解析与产物保存LLM 的原始返回是一个混合了 ECharts 代码与 Markdown 报告的复合文本main.ipynb 第 6 部分用两个正则完成结构化拆解1. 提取 ECharts 代码匹配option {...};形式的 JS 对象字面量import re import os echarts_match re.search(roption\s*\s*(\{[\s\S]*?\});, result) if echarts_match: echarts_code echarts_match.group(1) else: print(未找到 ECharts 代码)2. 提取 Markdown 报告从# 数据分析报告标题处截取到结尾report_match re.search(r(# 数据分析报告[\s\S]*), result) markdown_report report_match.group(1).strip()3. 保存报告到文件output_dir ./output os.makedirs(output_dir, exist_okTrue) md_path os.path.join(output_dir, report.md) with open(md_path, w, encodingutf-8) as f: f.write(markdown_report) print(f\nMarkdown 报告已保存至: {md_path})4. 将 ECharts 代码嵌入 HTML 模板通过IPython.display.HTML构建页面并用IFrame/文件写入保存为 echarts.htmlhtml_code f !DOCTYPE html html head meta charsetutf-8 title第一个 ECharts 实例/title !-- 引入 echarts.js -- script srchttps://cdn.staticfile.org/echarts/4.3.0/echarts.min.js/script /head body !-- 为ECharts准备一个具备大小宽高的Dom -- div idmain stylewidth: 600px;height:400px;/div script typetext/javascript // 基于准备好的dom初始化echarts实例 var myChart echarts.init(document.getElementById(main)); // 指定图表的配置项和数据 var option {echarts_code} // 使用刚指定的配置项和数据显示图表。 myChart.setOption(option); /script /body /html with open(./output/echarts.html, w, encodingutf-8) as f: f.write(html_code)这套正则提取 HTML 模板注入的落地方式非常轻量不需要额外的前端工程ECharts 通过 CDN 引入版本 4.3.0LLM 生成的option对象被直接setOption渲染即可在浏览器中看到交互式图表。九、实际运行效果报告与图表质量验证运行完成后output/目录下的两份产物即为最终交付物。以 report.md 为例其报告结构完整覆盖了系统提示词要求的全部章节分析背景与目标明确报告对象为 2025 年 6–10 月各分类 CPI 变化趋势服务于趋势识别、异常定位与对比分析关键的发现提炼出 7 条结论例如CPI 总体温和上升100.1 → 100.2其他用品及服务类价格指数 10 月达 112.8涨幅最大食品烟酒类存在季节性波动统计计算与趋势识别逐类列出平均值、最大值、最小值与增长率如其他用品及服务类平均值 108.3、增长率 4.4%交通通信类平均值 97.4、增长率 2.3%——这些数字与 DataStatisticsTool 输出口径一致异常检测识别出其他用品及服务类 10 月 112.8 显著偏高食品烟酒类 6–8 月持续下行、9–10 月回升两处异常并给出特定商品价格上涨或供应紧张季节性因素等数据驱动的推测对比分析横向比较各分类涨跌幅度差异指出非食品与服务类占比上升的趋势结论对全篇分析给出凝练收束。对应的 echarts.html 则承载了 13 个分类的折线对比图。将报告的文字结论与图表的视觉走向相互印证即可验证整个工具计算 → LLM 解读链路的可靠性——这也正是本项目作为智能数据分析助手区别于传统 BI 模板的关键分析视角与结论表述完全由 LLM 依据真实统计结果动态生成。十、总结与扩展方向DataAnalysisAgent 以约 200 行 Notebook 代码完整演示了 HelloAgents 框架下数据密集型 Agent的最小可行范式工具系统通过Tool/ToolParameter/ToolRegistry把 Pandas 清洗与统计能力封装为 LLM 可感知、可调用的原子能力智能体编排用SimpleAgent 精心设计的系统提示词实现清洗→统计→绘图→报告的自主决策链路结论必须基于工具的真实计算结果产物落地用正则从模型复合输出中拆解 EChartsoption与 Markdown 报告一键产出可分享的 HTML 图表与结构化报告。若在此基础上继续扩展可以从以下几个方向增强更多分析工具注册异常检测如 Z-score/3σ 规则、相关性分析、趋势回归等Tool让统计深度随工具数量线性增长多数据源支持扩展excel_reader思路增加 CSV、数据库等读取工具并保持原始数据键名 → 清洗工具 → 统计工具的数据契约一致性结果质量把关在保存报告前加入格式校验或在报告中嵌入统计工具输出的关键指标作为证据链进一步抑制模型幻觉框架能力升级参考仓库 第四章 智能体经典范式构建 与 第七章 构建你的Agent框架 中的 ReActAgent、ReflectionAgent 等范式为数据分析流程引入先规划再执行或自我反思能力。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考