从零搭建数据分析智能体：自然语言查数、自动分析并给出结论

上个月我被业务部门同一个问题问了三遍“为什么华南区退货率又涨了”每次我都得重新跑SQL、拉Excel、做透视表然后发一份差不多的报表出去。后来我实在受不了了花了两个晚上做了一个数据分析智能体基于Agent的思路从零搭建跑通之后把这个小项目的完整过程整理成了这篇内容。这个Agent能接收自然语言问题自己决定需要看哪些数据、跑什么代码最后直接给出带数字依据的结论。整个项目从空文件夹到跑通没用什么重型框架核心代码我也全部贴在下面你可以直接拿去改成自己的版本。这篇内容适合两类人一类是每天被取数需求淹没的数据分析师想做个能自动应答的助手另一类是刚接触Agent开发想找一个能落地、能演示、能扩展的练手项目。前者可以重点看核心实现和踩坑部分后者可以从技术选型那一段开始看。1. 为什么要为数据分析做一个Agent1.1 我每天在重复回答同样的问题业务方不会写SQL也不一定理解指标口径。这是所有数据分析师都懂却不太愿意承认的事实一天工作时间里有七成花在取数、清洗、做表上真正用来思考业务问题的可能不到三成。我统计过自己一周的工作光“退货率为什么涨”“哪些品类最近卖不动”“华东区的销售有没有掉”这三类问题就占了所有取数请求的一半以上。关键是他们每次问的角度都差不多只是时间范围换一换、区域换一换。这种问题本质上是同一套分析流程的重复执行。有BI工具也没完全解决。看板能回答“是什么”但业务方真正想追问的是“为什么、怎么办”这需要临时拆解数据、组合指标做一次性的探索分析。这类探索是BI工具最不擅长的却恰恰是数据分析Agent能发挥作用的地方。1.2 Agent和“调接口出报表”完全是两码事我最早想的是做一个自然语言转SQL的小工具把问题翻译成查询语句跑出来给个结果完事。做着做着发现这条路走不通业务方问“为什么华南区退货率涨了”这根本不是一条SQL能回答的需要先看整体退货率的变化再按省份拆开看趋势然后定位到具体品类甚至还要对比退款原因分布。这个拆解过程有先后顺序有依赖关系光靠“输入到输出”的单轮转换根本搞不定。Agent和这类固定流程工具最大的差别在于它能自己规划步骤根据上一步的结果决定下一步干什么并且在运行过程中根据工具的返回信息修正自己的判断。吴恩达在他的Agent教程里把Agent的能力拆成Reflection反思、Tool Use工具调用、Planning规划、Multi-Agent Collaboration多Agent协作几个模式。数据分析Agent至少要用到Tool Use和Planning这两项工具调用让模型可以真正操作数据规划能力让它可以拆解复杂问题。1.3 先明确Agent的边界在哪做之前我认为得先划清楚边界否则后面不知道该做到什么程度。我的定位很明确这个Agent不是来替代数据分析师的而是处理掉那些“例行公事”式的取数和描述性统计需求。它适合回答结构化、指标口径清晰的问题。比如“上季度各区域销售额排名”“哪些SKU的毛利率低于20%”“请筛选出金额超过阈值且被退货的订单”。这类问题有明确的答案通过代码就能算出来非常适合交给Agent去自动执行。不适合交给它的是那些需要业务直觉和因果推断的探索性问题比如“为什么这个活动没有达到预期效果”“用户流失的根本原因是什么”。这类分析需要结合行业经验、业务背景甚至访谈信息。Agent目前做不到硬做只会一本正经地胡说八道。所以我把这个Agent定位成“数据分析的前置过滤器”先挡掉80%的例行查询让分析师能把精力放到真正需要判断力的事情上。2. 从技术选型说起框架、模型和工具链的取舍2.1 Agent框架LangChain、LlamaIndex还是自建现在聊Agent开发绕不开框架选型。我先列一下我当时的对比情况方案优势劣势适用场景LangChain生态全Agent、Memory、Retriever都有现成组件版本迭代快抽象层多出了问题不好排查需要快速集成大量外部组件时LlamaIndex擅长知识索引和RAG数据问答有现成方案数据分析场景的对话管理还是要自己搭以文档检索和问答为核心的项目AutoGen多Agent编排能力强单Agent数据分析用它有点重调试成本高需要多个角色协作的复杂场景自建Function Calling代码量少逻辑透明可控性强需要自己处理对话状态和工具协议想搞清楚原理、追求可控性的项目我最后选了自建Function Calling的方案。原因很简单数据分析Agent的核心逻辑其实就是“模型决定调哪个工具→拿结果继续推理”的循环这个循环用LangChain写也是封装的不如自己维护一套几百行的代码出了任何问题都能直接看明白。而且自建方案换模型很方便今天用这个明天用那个只要支持OpenAI兼容的工具调用接口就能无缝切换。2.2 LLM选择能力、成本和数据合规的平衡模型的选择直接决定Agent能用不能用。两个主要维度一是模型是否具备稳定的工具调用能力二是成本和数据合规要求。在Demo阶段我直接用支持OpenAI兼容接口的国产模型部署简单价格也低。这类模型现在基本都支持Function Calling调用格式和OpenAI一致只需要改base_url和model名称。预算更充足的话换更强的商用模型效果会更好但要注意API调用成本会随对话轮数快速上升。另外一个容易被忽视的点工具调用能力的稳定性。有些模型写普通对话没问题但让它输出结构化工具调用参数的时候偶尔会漏参数、输出非法JSON。我会在提示词里强制要求并在代码层做参数解析容错解析失败就回传错误信息让模型重试。不要觉得这是小概率事件实际跑起来会经常遇到。2.3 工具集设计让Agent有手有脚数据分析Agent的核心能力其实就是工具集。我设计时只保留了三个工具不多加describe_data查看数据概览让模型先建立对数据的基本认知。run_python_code执行分析代码完成筛选、聚合、计算等实际操作。save_chart专门用于生成并保存图表文件。工具设计的核心原则是能用代码表达的事情尽量让模型通过run_python_code去做。不要为了省事拆出各种细粒度小工具那样工具描述反而会干扰模型的选择。每个工具的说明一定要写清楚“什么场景下使用”模型在工具选择上才不容易跑偏。3. 项目骨架搭建从空文件夹到可运行体系3.1 环境初始化这个项目不需要装重型框架Python 3.10以上就够用了。我在虚拟环境里跑通依赖如下pip install pandas openai python-dotenv matplotlibopenai是用来调用兼容接口的pandas和matplotlib负责数据处理与可视化python-dotenv管理环境变量。整个项目跑起来不到1000行代码。如果你不想用OpenAI的SDK直接用requests调用也行但需要自己处理工具调用的协议格式没必要重复造轮子。3.2 目录结构我习惯把项目结构拆得清楚一点方便后面扩展。最后长这样data_agent/ ├── config.py # 模型配置、数据路径、最大步数 ├── data/ │ └── sales_data.csv # 示例销售数据 ├── output/ # 图表输出目录 ├── tools/ │ ├── __init__.py │ ├── describe.py # 数据概览工具 │ └── python_executor.py # Python代码执行工具 ├── agent.py # Agent主循环 ├── main.py # 交互式入口 └── requirements.txt每个文件的职责比较单一排查问题的时候直接定位到文件就行。这里有个小提醒output目录最好提前建好否则后面模型调用save_chart时如果目录不存在会报错备选方案是让代码负责自动创建目录。3.3 示例数据准备没有真实数据的时候我建议用模拟数据先跑通流程。我的sales_data.csv包含这些字段字段类型说明order_idstring订单号order_datedatetime下单时间provincestring省份categorystring商品品类amountfloat订单金额costfloat成本is_refundboolean是否退货数据量不用大生成个5000行左右就够了。模拟数据阶段最重要的是覆盖足够的业务场景要有时间趋势、有区域差异、有品类差异还要有一些“异常值”比如退货率明显偏高的记录。这样测试Agent时才能看出它能不能发现真正有价值的洞察。4. 核心实现ReAct循环和两个关键工具4.1 数据概览工具先让模型认识数据模型第一次看到问题是不知道数据长什么样的所以我给了它一个“先摸数据”的工具。这个工具会把数据形状、列名、数据类型、数值字段统计量和前几行样例都返回给模型。import pandas as pd def describe_data(df: pd.DataFrame) - str: lines [] lines.append(f数据形状: {df.shape[0]} 行 x {df.shape[1]} 列) lines.append(列名与数据类型:) for col in df.columns: lines.append(f - {col}: {df[col].dtype}) lines.append(\n数值列统计信息:) lines.append(df.describe().to_string()) lines.append(\n前5行样例:) lines.append(df.head().to_string()) return \n.join(lines)这段代码没什么稀奇的关键是这个工具的存在改变了模型的行为。如果没有这一步模型很可能凭错误的猜测去写分析代码最后得到的结果完全不可信。先看数据再动手是数据分析Agent行为规范的第一条。4.2 Python执行工具让模型真正操作数据这是整个Agent的引擎也是风险最高的部分。模型的自然语言提问经过推理后会生成一段pandas代码这段代码需要被安全地执行并把结果返回给模型。import io import sys import pandas as pd SAFE_BUILTINS { len: len, print: print, range: range, list: list, dict: dict, tuple: tuple, set: set, str: str, int: int, float: float, bool: bool, min: min, max: max, sum: sum, abs: abs, round: round, sorted: sorted, zip: zip, enumerate: enumerate, isinstance: isinstance, type: type, Exception: Exception, } class PythonExecutor: def __init__(self, df: pd.DataFrame): self.df df def execute(self, code: str) - str: print(----- 执行代码 -----) print(code) print(-------------------) local_ns {pd: pd, df: self.df, plt: __import__(matplotlib.pyplot)} old_stdout sys.stdout buffer io.StringIO() sys.stdout buffer try: exec(code, {__builtins__: SAFE_BUILTINS}, local_ns) output buffer.getvalue().strip() if not output: return 代码执行成功无打印输出。 return output except Exception as e: return f执行出错: {type(e).__name__}: {e} finally: sys.stdout old_stdout这段代码里有几个设计点值得说一下。首先我重定向了sys.stdout这样模型代码里的print输出才能被捕获并回传给模型否则你在终端能看到结果模型却一无所知。其次我过滤了__builtins__只保留常用函数避免模型生成的代码干一些危险的事。必须坦白一点这个实现只适合本地Demo并不是真正的安全沙盒。生产环境要想办法把代码放到Docker容器或者独立进程里跑做网络隔离、文件系统限制和执行超时控制后面我会单独讲安全话题。4.3 ReAct主循环Agent的大脑Agent的主循环我采用的是ReAct思路具体实现用Function Calling协议来完成。流程不复杂把系统提示词和用户问题发给模型。模型决定直接回答或者调用某个工具。如果选择调用工具我把工具参数解析出来执行工具再把工具结果以tool角色消息发回去。模型看到工具结果后继续判断直到直接回答为止。import json from openai import OpenAI from config import API_KEY, BASE_URL, MODEL_NAME, DATA_PATH from tools.describe import describe_data from tools.python_executor import PythonExecutor client OpenAI(api_keyAPI_KEY, base_urlBASE_URL) executor PythonExecutor(df) TOOLS [ { type: function, function: { name: describe_data, description: 查看数据集的概览信息包括形状、列名、类型、统计信息和样例数据。任何问题都建议先调用它。, parameters: {type: object, properties: {}} } }, { type: function, function: { name: run_python_code, description: 执行Python代码用于数据分析代码中数据变量名为df。需要计算、筛选、聚合、排序时调用。, parameters: { type: object, properties: { code: {type: string, description: 要执行的Python代码} }, required: [code] } } } ] SYSTEM_PROMPT 你是一位资深数据分析师Agent。你手上有一份销售数据表格可以使用工具获取数据信息或执行Python代码来回答问题。 工作原则 1. 在回答问题前先使用 describe_data 工具了解数据结构。 2. 需要计算、筛选、聚合时使用 run_python_code 工具代码中数据变量名为 df。 3. 如果代码执行出错根据错误信息修复代码后重试不要重复同样的错误。 4. 最终回答必须给出结论和依据尽量引用具体数字。 5. 如果问题不明确请主动说明你的理解并基于常见业务口径给出分析结果。 def run_agent(question, max_steps6): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: question} ] for step in range(max_steps): resp client.chat.completions.create( modelMODEL_NAME, messagesmessages, toolsTOOLS, tool_choiceauto ) msg resp.choices[0].message if msg.tool_calls: messages.append({ role: assistant, content: msg.content or , tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments } } for tc in msg.tool_calls ] }) for tc in msg.tool_calls: name tc.function.name args json.loads(tc.function.arguments) if name describe_data: result describe_data(df) elif name run_python_code: result executor.execute(args[code]) else: result f未知工具: {name} messages.append({ role: tool, tool_call_id: tc.id, content: result[:8000] # 防止返回过大截断 }) continue return msg.content return 已达到最大推理步数未能得到结论。两个容易踩坑的细节第一tool_choice我用的是auto也就是让模型自己决定是否调用工具不要强制。强制调用工具在有些场景下会出问题比如问题跟数据无关时模型会为了完成任务随机调一个工具。第二工具结果我截断到8000字符不然模型输出一长串数据框内容很容易把上下文撑爆而且大部分内容模型根本用不上。4.4 主入口交互式命令行最后加一个简单的命令行入口方便本地测试。import pandas as pd from config import DATA_PATH, MAX_STEPS from agent import run_agent df pd.read_csv(DATA_PATH) if __name__ __main__: while True: question input(\n请输入问题输入exit退出: ) if question.strip().lower() exit: break if not question.strip(): continue answer run_agent(question, max_stepsMAX_STEPS) print(\n Agent回答 ) print(answer)到这一步一个最小可用的数据分析Agent就成型了。从输入问题到拿到分析结论整个链路是通的。5. 实测跑三个任务从普通问答到数据洞察5.1 任务一找出退货率最高的商品品类我先试了个相对简单的让Agent找出退货率最高的品类。它按照提示词要求第一步先调用了describe_data看到了is_refund字段和各个品类列名然后写了一段pandas代码refund_rate df.groupby(category)[is_refund].mean().sort_values(ascendingFalse) print(refund_rate)它根据输出结果给出了结论数码配件类的退货率最高达到17.3%明显高于全品类平均的9.6%。整个过程中模型判断准确没有多余的步骤输出也符合要求。这是我第一次感受到“它在分析数据”而不是“在执行我的命令”。5.2 任务二计算华东区月度销售额走势这个问题比第一个复杂因为它需要先明确“华东区”包括哪些省份然后按月汇总销售额最后判断趋势。模型的做法是east df[df[province].isin([上海, 江苏, 浙江, 安徽, 福建])] east[month] pd.to_datetime(east[order_date]).dt.to_period(M) monthly east.groupby(month)[amount].sum() print(monthly)它选的城市列表基本合理个月份汇总也对了。但这里也有一个值得注意的点模型对“华东区”的界定是它自己从常识推断出来的如果公司内部对“华东区”的范围有明确定义应该在提示词或工具里写清楚否则不同口径下结果会不一样。5.3 任务三自动画出销售额Top10省份的柱状图可视化本来是传统表格分析最麻烦的一步但对Agent来说反而简单。它只需要生成绘图代码并调用matplotlib即可top10 df.groupby(province)[amount].sum().sort_values(ascendingFalse).head(10) plt.figure(figsize(12, 6)) top10.plot(kindbar, titleTop10省份销售额) plt.savefig(output/top10_province.png, bbox_inchestight) print(图表已保存)执行完成后output目录下出现了top10_province.png。模型在回答里直接告诉用户图表保存的位置用户自己打开看就行。这里我建议在工具描述里要求模型输出图片的完整路径方便业务方直接找到文件。5.4 实测感受能用的底线在哪里三个任务跑下来我最大的感受是这类Agent处理“结构化、有明确口径”的问题已经达到可用水平单轮问题基本在30秒内出结果稳定性也不错。但问题描述一旦模糊就容易出偏差。比如我问“最近销售情况怎么样”它会按自己的理解做统计给出销售额均值、总量这些数字但业务方真正关心的是对比上期还是完成率还是结构变化这些上下文Agent并不知道。所以我的建议是给Agent一个默认的指标口径说明或者在问答前要求用户提供更具体的问题描述这比让模型猜要靠谱得多。6. 踩坑实录和工程化补充6.1 六个高频问题和排查思路从零到一跑通靠的不止是代码还有不断调试。我遇到的问题和解决思路整理成了表格问题现象可能原因排查与解决模型不调用工具直接瞎答系统提示词要求不够明确或模型工具能力弱在系统提示词里明确要求“必须先调用describe_data”工具参数解析失败或JSON不合法工具参数Schema描述不清楚检查properties描述是否详细增加JSON解析容错Python执行报错模型写出不兼容的pandas代码把Traceback原样返回让模型自己修复重试模型重复调用同一错误代码模型没有从错误中学习就继续在工具结果里增加“请修复代码不要重复相同错误”的提示中文输出乱码终端编码或打印问题检查控制台编码必要时在代码里设置UTF-8环境变量上下文被工具结果撑爆数据框输出内容过长工具结果截断只保留关键统计信息其中最常遇到的是第二个。模型在生成工具参数时偶尔会给出非法JSON比如多一个逗号、字段名写错。我在解析工具参数时加了容错处理解析失败就把异常信息以工具结果形式返回给模型让它重新生成参数。6.2 代码执行安全不设防等于裸奔这个必须单独强调。数据分析Agent让你能在自然语言和代码之间架了一座桥但这座桥如果控制不好等于把服务器的代码执行权限交到了一个黑盒手里。我的Demo代码里对__builtins__做了白名单过滤但严格意义上这只是减少风险不能完全防御。生产环境最低限度要做到代码在独立进程或容器中执行限制网络访问和文件系统范围设置执行超时对接数据库时使用只读账号所有查询走参数绑定防止SQL注入对敏感数据列进行脱敏或者访问日志记录。另外还有一个容易忽略的点Agent生成的代码可能合法但不安全比如恶意遍历文件、尝试连接外网。在容器里加一层网络策略比在代码层去过滤危险函数靠谱得多。6.3 对接企业内网和本地数据源很多企业不会把业务数据传到外部API服务这时候的改造思路是把LLM换成内网部署的推理服务。现在有不少本地推理框架支持OpenAI兼容接口部署好之后只需要改config.py里的BASE_URL和MODEL_NAME代码完全不用动。数据源从CSV换成数据库也很自然。我在工具集里增加一个query_database工具内部使用只读账号执行SQL查询并把查询结果转成DataFrame快照。要注意的是数据库表往往比较大全表交给Agent去做pandas处理不现实工具描述里就应该限制它先做初步筛选和聚合而不是SELECT *。还要考虑权限和审计。不是所有人都应该能访问全量数据也不是所有Agent执行的操作都应该无痕。最简单的做法是增加用户身份参数在执行日志里记录谁、在什么时间、问了什么问题、执行了哪些操作。这不仅是安全要求也是后面优化Agent的重要依据。6.4 后续扩展方向我说几个我个人觉得值得继续做的方向。第一个是把Agent的结论接入数据看板。Agent的分析结果不应该是孤立的文字而是可以推送到内部看板或IM机器人让业务方在常用渠道里直接看到结论。第二个是往多Agent方向演进。目前是单个Agent完成所有步骤下一步可以拆成“取数Agent”和“解读Agent”前者专注数据获取后者专注从结果中提炼洞察这样每个Agent的职责单一效果会更稳。吴恩达那套多Agent协作模式放到数据分析场景里是比较自然的落地场景。第三个是给Agent补充更多数据源比如把订单数据、用户行为数据都接进来让它能回答跨源问题。数据源变多之后才真正具备商业数据分析的雏形。数据量达到一定级别后还需要考虑用Spark这类大数据方案取代本地pandas执行。最后想说我从这个项目里最大的收获不是写了一个Agent而是想明白了一件事Agent项目里真正的成本不在Agent框架本身而在工具定义和工作流的约束。第一次跑通的时候很兴奋但真正稳定好用是后面两天反复打磨提示词、调整工具描述之后的事。你把这个项目拿去改成自己的场景时多花时间在工具边界和提示词上会比换更厉害的模型收益大得多。