企业官网建设流程全解析

基于 hello-agents 框架的智能数据分析 Agent 实战：CPI 趋势分析报告全流程解读

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

导读

本文以 hello-agents 仓库共创项目 DataAnalysisAgent 生成的居民消费价格指数（CPI）数据分析报告为主体，完整拆解一份真实智能体产出的分析报告从数据读取、清洗统计、图表生成到 Markdown 报告落盘的完整链路。读完本文，你将掌握：如何用SimpleAgent+ 自定义工具完成一份可复用的数据分析报告，理解报告中统计结论与底层数据的对应关系，并学会用仓库源码复现这一流程。

本文的主体文档为 DataAnalysisAgent 的分析报告，其配套实现位于 main.ipynb 与 README.md。

一、报告从何而来：DataAnalysisAgent 项目背景

这份report.md并非人工撰写，而是由 DataAnalysisAgent —— 一个基于 hello-agents 框架（SimpleAgent）构建的智能数据分析助手自动生成的产物。根据 README.md，该项目能够自动分析数据、生成可视化图表并撰写分析报告，其技术栈为：

• hello-agents 框架：采用SimpleAgent智能体范式；
• Python AST 模块：用于解析 LLM 输出的 ECharts 代码与报告内容；
• OpenAI 兼容 API：通过环境变量接入大模型完成智能分析。

整个项目围绕main.ipynb展开，共分为 6 个部分：环境配置 → 定义数据分析工具 → 创建智能体 → 读取示例数据表格 → 执行数据分析 → 保存分析报告和图表。本文这份报告就是第 5 部分的真实输出，被保存到output/目录下。

二、分析背景与目标

报告开篇明确了本次分析的任务边界：

本报告旨在分析 2025 年 6 月至 10 月期间不同类别居民消费价格指数的变化趋势，以识别价格变动的规律、异常情况以及各分类之间的对比关系。通过可视化图表和统计分析，为政策制定者或相关机构提供决策支持。

对应的输入数据为 data/simple_data.xls，这是一份包含 13 个 CPI 分类指标、覆盖 2025 年 6 月至 10 月共 5 个月度的 Excel 表格（上年同月=100口径）。在 main.ipynb 第 4 部分中，pd.read_excel读取后保留原始 NaN，并整体序列化为 JSON 字符串sample_data传给智能体。

三、关键的发现：7 条核心结论

报告基于 13 个指标、5 个月度的对比，提炼出 7 条关键发现：

1. 整体趋势：CPI 总体呈上升趋势，由 100.1 升至 100.2；
2. 食品烟酒类价格波动：2025 年 6 月至 8 月间持续下降，9 月和 10 月有所回升，存在季节性波动；
3. 其他用品及服务类价格显著上涨：2025 年 10 月达到 112.8，为所有类别中涨幅最大，价格上涨压力较大；
4. 交通通信类价格稳步上升：从 96.3 上升至 98.5，持续增长；
5. 非食品 CPI 略有上升：从 100.1 上升至 100.9，温和上行；
6. 消费品 CPI 波动较小：6 月至 10 月基本保持稳定；
7. 服务类价格指数相对稳定：小幅上升，整体变化不大。

对照 main.ipynb 第 4 部分中的原始数据，这 7 条结论均与数据表一一对应——例如"其他用品及服务类"从 6 月的 108.1 一路升至 10 月的 112.8，是唯一突破 110 的类别；"交通通信类"逐月 96.3 → 96.9 → 97.6 → 98.0 → 98.5，呈现单调上升。可以看出，智能体并非凭空输出结论，而是严格按照数据取值进行归纳。

四、统计计算与趋势识别：逐指标关键统计量

报告对主要指标给出了平均值、最大值、最小值及增长率四类统计量，是整份报告中数据密度最高、最适合直接引用的部分。整理如下：

这些统计值可以由项目的DataStatisticsTool复现。该工具定义在 main.ipynb 第 2 部分，对数值型列计算count / mean / median / std / min / max / q25 / q75八项描述性统计量，对分类型列统计unique_count与 Top10 取值频次，并以 JSON 字符串返回给 LLM，作为趋势识别、异常检测的量化依据。

一个值得注意的细节：报告的"增长率"口径各不相同（如食品烟酒类 0.8% 为相对自身幅度的波动），使用时建议结合最大值、最小值与时间序列共同解读，避免对不同类别之间的增长率做直接横向比较。

五、异常检测：两类明显偏离

报告的异常检测聚焦于两个显著偏离：

• 其他用品及服务类：2025 年 10 月达 112.8，明显高于其他月份，报告推断可能由于特定商品价格上涨或供应紧张；
• 食品烟酒类：6 月至 8 月持续下降、9 月至 10 月回升，报告指出可能存在季节性因素影响。

从数据上看，其他用品及服务类是唯一在单个月份出现"台阶式"跳升的指标（9 月 109.9 → 10 月 112.8，单月上涨 2.9 个百分点），确实符合异常检测中"离群高值"的典型特征。这类分析正是DataStatisticsTool提供的std、max、min等统计量所支撑的"数据驱动识别"，报告在此处也保持了谨慎表述（"可能由于……"），未做超出数据范围的臆断。

六、对比分析：类别间的横向关系

报告从横向对比角度给出三组结论：

1. 其他用品及服务类增长幅度最大，对整体 CPI 的影响最为显著；
2. 食品烟酒类与交通通信类趋势不同：前者波动较大，后者平稳（交通通信类五个月单调上升且斜率均匀）；
3. 非食品 CPI 与服务 CPI 增长趋势相似，显示非食品与服务类价格在整体 CPI 中的占比逐渐增加。

第 3 点值得结合原始数据验证：非食品 CPI 从 100.1 逐月升至 100.9，服务 CPI 从 100.5 升至 100.8，两条曲线斜率接近，因此报告将其归为"相似趋势"是有据可依的。

七、结论与决策价值

报告的结论部分对全文进行收束：

2025 年 6 月至 10 月期间，居民消费价格指数整体呈温和上升趋势，其中其他用品及服务类价格指数的涨幅最大，而食品烟酒类价格指数则表现出明显的季节性波动。这些变化提示我们关注特定类别价格变动的原因，并采取相应措施以应对潜在的通胀压力。

整份报告遵循了"背景目标 → 关键发现 → 统计计算 → 异常检测 → 对比分析 → 结论"的完整分析闭环，且每一处判断都能在原始数据中找到依据，体现了SimpleAgent在结构化报告生成上的实用价值。

八、从报告到代码：如何用仓库源码复现该流程

如果你希望自行复现这份报告，可以按照 main.ipynb 的 6 个部分依次执行：

1. 环境配置：安装依赖（hello-agents[all]>=0.1.0、jupyter、xlrd、python-dotenv，见 requirements.txt），并通过环境变量设置LLM_MODEL_ID、LLM_API_KEY、LLM_BASE_URL、LLM_TIMEOUT；
2. 定义工具：继承Tool基类实现DataCleaningTool（去空值、列筛选、空值补 0）与DataStatisticsTool（描述性统计）；
3. 创建智能体：实例化ToolRegistry注册工具，再以SimpleAgent(name=..., llm=HelloAgentsLLM(), system_prompt=..., tool_registry=...)创建"数据分析助手"；
4. 读取数据：用pd.read_excel读取 data/simple_data.xls 并转为 JSON；
5. 执行分析：agent.run("对以下数据绘制图表和数据分析\n\n{data}\n")，让 LLM 依次调用清洗、统计工具并输出 ECharts 配置与 Markdown 报告；
6. 保存产物：用正则分别从结果中提取option = {...}与# 数据分析报告...部分，保存为 echarts.html 与 report.md。

8.1 关键源码佐证：SimpleAgent 如何驱动工具调用

hello-agents 框架中SimpleAgent的实现可参考 Co-creation-projects/YYHDBL-HelloCodeAgentCli/agents/simple_agent.py。其run方法会在系统提示词中自动注入工具描述与调用格式（[TOOL_CALL:工具名:参数]），随后进入"调用 LLM → 解析工具调用 → 执行工具 → 回填结果"的迭代循环，max_tool_iterations控制最大工具调用轮数——这正是 DataAnalysisAgent 中"先清洗、再统计、最后写报告"这一串行流程能够被自动执行的底层机制。

8.2 关键源码佐证：Tool 基类的契约

自定义工具必须实现run(parameters) -> str与get_parameters() -> List[ToolParameter]两个抽象方法（见 tools/base.py），其中ToolParameter声明参数名、类型、描述与是否必填，用于指导 LLM 正确生成参数。DataAnalysisAgent 中DataCleaningTool的三个参数（data_json必填、drop_na与columns_to_keep可选）即遵循该契约，这也是智能体能够按 JSON 格式正确传参的原因。

8.3 运行前提与限制

• 本项目依赖真实 LLM API（README 与 notebook 中预配置了 ModelScope 兼容接口），无 API Key 时无法复现完整推理；
• simple_data.xls使用xlrd读取，需保证.xls格式（旧版 Excel）；
• 报告中统计值由 LLM 基于工具返回值生成，不同模型/温度下的具体措辞与增长率口径可能略有差异，但数据事实以原始表为准。

附：仓库中的关联产物

• 报告正文：output/report.md
• 可视化图表：output/echarts.html（13 条折线序列的 ECharts 单页图）
• 完整实现：main.ipynb
• 项目说明：README.md
• 依赖清单：requirements.txt
• 示例数据：data/simple_data.xls

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