4. 将这两个 API 密钥保存为本地系统的环境变量。设置 LANGSMITH_API_KEY 与 GEMINI_API_KEY。
5. 在 Notebook 中导入所有必要的 Python 包:
from google import genai
from google.genai import types
from pydantic import BaseModel
from langgraph.graph import StateGraph, END
import os, json, textwrap, traceback
from pathlib import Path
import pandas as pd
import markdown2
import weasyprint技术支持
@traceable(name="code_writer_agent")defcode_writer_agent(state: State):
prompt =f"""
You are the Code Writer Agent.
Write Python code ONLY (no markdown).
Previous error to fix (if any):
{state.last_error}
HARD REQUIREMENTS:
1. Load dataset from: {state.dataset_path}
2. Follow the plan exactly.
3. Create ALL charts in charts_to_make.
4. Save every chart in ARTIFACTS_DIR with filenames like:
ARTIFACTS_DIR / "chart_01_<short_name>.png"
5. Track saved plot paths in _artifacts (list[str]).
6. Track chart metadata in _charts_meta (list[dict]) with:
{{
"title": "<human readable chart title>",
"filename": "artifacts/chart_01_x.png",
"description": "<what this plot shows (1-2 sentences)>",
"one_liner": "<ONE line insight from the chart>"
}}
The one_liner MUST be a single sentence, max ~20 words.
7. Store useful console output in _stdout.
IMPORTANT:
- import matplotlib.pyplot as plt
- plt.close() after saving each plot
- ensure _artifacts and _charts_meta exist even if empty
- if modeling, add baseline metrics to _stdout
Dataset profile:
{json.dumps(state.profile, indent=2)}
Analysis plan:
{json.dumps(state.plan, indent=2)}
Return ONLY executable python code.
"""
resp = gemini_call(prompt, thinking_level="high")
state.code = resp["generations"][0]["text"]return state技术支持
提示要求严格的格式规范:不重复章节标题与图表标题、保持统一空行间距、每张图表仅展示一次,且用标准化的 HTML 区块呈现,并将洞察恰当地整合。
生成 Markdown 后,智能体调用 render_pdf 将其转为排版精良的 PDF(使用 WeasyPrint)。Markdown 与 PDF 路径会存入共享状态,至此分析工作流完成。
@traceable(name="report_agent")defreport_agent(state: State):
prompt =f"""
You are the Report Agent.
Create a neat Markdown report (HTML allowed).
HARD REQUIREMENTS:
- Do NOT repeat section titles or chart titles.
- Do NOT output empty bullet points. If a bullet would be empty, skip it.
- Keep spacing consistent: one blank line between sections.
- Use charts_meta as the ONLY source of charts.
- Include EVERY chart, exactly once, in the same order as charts_meta.
- For each chart output EXACTLY this block:
<div class="chart-block">
<h3>Chart {{i}}: {{title}}</h3>
<img src="{{filename}}" alt="{{title}}">
<p><b>What it shows:</b> {{one_liner}}</p>
</div>
Where:
- title, filename, one_liner come from charts_meta
- one_liner must be ONE sentence, max ~20 words.
Sections:
1. Dataset Overview (short)
2. Data Quality Notes (bullets)
3. Exploratory Analysis (chart-by-chart blocks only, no extra chart titles)
4. Modeling Results (if any; use a markdown table)
5. Key Insights (use insights text)
6. Recommendations / Next Steps (bullets)
Inputs:
Profile: {json.dumps(state.profile, indent=2)}
Exec stdout: {state.exec_result.get("stdout","")}
Exec ok: {state.exec_result.get("ok")}
Traceback (if any): {state.exec_result.get("traceback","")}
Charts meta:
{json.dumps(state.charts_meta, indent=2)}
Insights:
{state.insights}
Return ONLY the Markdown report.
"""
resp = gemini_call(prompt, thinking_level="low")
state.report_md = resp["generations"][0]["text"]
state.report_pdf = render_pdf(state.report_md)return state技术支持
6. 构建多智能体图
最后一步是将所有智能体组装为一个由状态驱动的完整多智能体工作流。
通过共享的 State 模型构建 StateGraph,确保随着流程推进,每个智能体都与同一个不断演化的状态对象交互。画像器、代码编写器、执行器、洞察撰写器与报告构建器分别作为节点加入图中,对应流水线中的不同阶段。
DATASET_PATH ="/work/housing.csv"# <-- change this
state = State(dataset_path=DATASET_PATH)
out = graph.invoke(state)技术支持
执行后,多智能体系统会自动完成整个分析:数据集画像、生成计划、编写与执行 Python 代码、提取洞察,并产出 Markdown 与 PDF 报告。
--- Modeling Baseline Results ---
Dataset Shape:(489,4)
Linear Regression -> RMSE:82,395.54, R2:0.6911
Random Forest -> RMSE:56,931.38, R2:0.8525
Observations: Random Forest typically outperforms Linear Regression due to capturing non-linear relationships (e.g., LSTAT).技术支持
# Housing Price Analysis Report## 1. Dataset Overview
The dataset consists of **489 records**and**4 features** focusing on housing metrics. The target variable is `MEDV` (Median Value of owner-occupied homes). The features include `RM` (average number of rooms), `LSTAT.............技术支持
除 Markdown 外,工作流还会生成排版精良的 PDF 报告。PDF 会自动保存到 artifacts 文件夹,您可通过如下方式查看其路径:
Gemini 3 Pro 是我们一直期待的前沿 AI 模型,配备高达一百万标记的上下文窗口,能在一次调用中从容处理数据集、文档、视频与代码库。它具备博士级推理能力,并在文本、图像、音频与视频的多模态处理上表现出色,可无缝支持创意工作流。
在这个项目式教程中,我将向您展示如何使用 Gemini 3 API 构建多智能体应用,基于用户提供的 CSV 数据集开展深度数据分析。
简单来说,这个多智能体应用将执行:
如果您希望进一步学习如何构建智能体工作流,建议查看我们的Google Antigravity 指南、Gemini 3 Flash 教程,以及AI Agent Fundamentals 技能路径。
1. 配置 Gemini 3 API 环境
1. 运行以下命令安装多智能体应用所需的全部依赖:
依赖说明:
注意:本项目使用 Jupyter Notebook 构建。
2. 前往Google AI Studio 生成您的 API 密钥。请确保已在账户中启用计费,因为 Gemini 3 Pro 不提供免费层访问。
3. 接着,创建一个免费的 LangSmith 账户并生成 API 密钥。
4. 将这两个 API 密钥保存为本地系统的环境变量。设置
LANGSMITH_API_KEY与GEMINI_API_KEY。5. 在 Notebook 中导入所有必要的 Python 包:
6. 设置环境变量,指定 LangSmith 项目名并启用 LangSmith 跟踪:
7. 创建保存所有图像与 PDF 的文件夹:
2. 初始化 Gemini 3 API 客户端
本节将设置 Gemini API 客户端,并封装模型调用以便在 LangSmith 中进行追踪与记录。同时,我们会提取令牌使用的元数据,并以 LangSmith 友好的格式返回。
首先,通过提供 API 密钥来初始化 Gemini GenAI 客户端:
接着,我们在 Gemini 模型调用外包一层轻量封装,以启用 LangSmith 的自动追踪。借助
@traceable装饰器,我们将函数注册为一次 LLM 运行。在该函数中,代码会将提示发送给 Gemini,并提取令牌使用详情。根据追踪指南,这些信息对于准确的 LangSmith 跟踪至关重要。
最后,函数会返回模型的文本输出、令牌统计信息以及原始响应,且格式符合 LangSmith 的要求,确保在 UI 中准确显示本次运行。
3. 为 Gemini 3 多智能体工作流构建工具
我们将创建用于数据集检查、安全执行 Python 代码,以及将 Markdown 渲染为 PDF 报告的工具,并在 AI 智能体工作流中使用。
工具 1:加载数据集
该工具接收文件路径,读取 CSV 到 pandas DataFrame,然后生成总结信息,其中包含数据集的形状、列名、各列数据类型、缺失值比例、前五行示例及完整描述性统计。它返回此摘要,便于智能体快速理解数据集。
工具 2:安全运行 Python 代码(简易沙盒)
该工具在受限环境中安全地运行动态生成的 Python 代码。它会准备一个小型本地环境,然后用 exec 执行所提供的代码。
被执行的代码应返回制品(如已保存的图表)路径和元数据。
工具 3:将 Markdown 渲染为 PDF
该工具将 Markdown 转换为格式美观的 PDF。它首先构建一个支持表格、列表、任务清单与脚注的 Markdown 解析器。
随后,
render_pdf将 Markdown 文本转为 HTML,包裹在自定义 CSS 样式的模板中(控制字体、表格外观、图像尺寸等),并使用 WeasyPrint 生成 PDF 文件。最后,它会将 PDF 保存到 artifacts 文件夹并返回路径。
此处只是将三项函数注册为智能体可用的工具。
4. 共享图状态
该类定义了共享的
state对象,保存智能体工作流产出的所有内容:如数据集路径、画像信息、生成的计划、代码、执行结果、洞察以及最终报告,并包含重试上限与错误信息,避免无限循环。5. 创建用于数据分析的 Gemini 3 API 智能体
我们将创建协同工作的 AI 智能体:对数据集进行画像、编写并执行分析代码、生成洞察,并最终产出 PDF 报告。
智能体 1:数据画像与规划
该智能体负责理解数据集并创建结构化的分析计划。它首先使用
load_dataset工具加载数据集,获取包含形状、缺失值、列类型、描述性统计与示例行的摘要。随后它将该摘要发送给 LLM,并给出明确指令:识别任务类型,如适用则选择目标列;确定应执行哪些探索步骤;提出应生成的图表;若数据集支持分类或回归,还需概述建模步骤。
LLM 返回表示该计划的 JSON 结构;若解析失败,智能体会回退为存储原始文本。
最后,它将数据集画像与生成的计划保存到共享状态,以供后续智能体使用。
智能体 2:代码编写
该智能体将分析计划转化为可执行的 Python 代码。它接收数据集画像、计划以及先前的执行错误,并基于这些上下文请求 LLM 仅输出 Python 代码。
提示中包含严格要求:加载数据集、严格遵循计划、生成指定的每个图表、将图表保存至
ARTIFACTS_DIR、记录路径与图表元数据、捕获控制台输出、保存后关闭图像、并可选计算建模指标。这确保代码在沙盒中可复现且安全。结果存入
state.code,供执行器运行。智能体 3:执行器(带自动重试)
该智能体在隔离的
run_python沙盒中运行代码编写智能体生成的 Python 代码。它会捕获执行结果、图表元数据、标准输出及所有制品。如果代码成功运行,则保存结果并按正常流程推进;若失败,智能体会增加重试计数并保存回溯信息,便于代码编写智能体在下一轮修复错误。
通过
MAX_RETRIES限制循环,该智能体可避免无限重试,并为自我纠错提供反馈信号。智能体 4:洞察撰写
该智能体负责解读整个分析过程。它接收数据集画像、执行输出及图表元数据,生成可读性强的分析洞察。
它会要求 LLM 生成结构化洞察:针对每个图表给出两条结论与一条风险提示,并生成少量总体洞察。
智能体必须确保不出现空项目符号、不重复表述,且洞察要与该数据集和这些图表具体相关,而非泛泛而谈。
生成的洞察报告会存入
state.insights,并作为最终报告阶段的输入。智能体 5:报告构建 → PDF
这是最终的综合智能体。它利用完整的流水线输出:画像、洞察、图表元数据与执行日志,编写一份完整、干净的 Markdown 报告。
提示要求严格的格式规范:不重复章节标题与图表标题、保持统一空行间距、每张图表仅展示一次,且用标准化的 HTML 区块呈现,并将洞察恰当地整合。
生成 Markdown 后,智能体调用
render_pdf将其转为排版精良的 PDF(使用 WeasyPrint)。Markdown 与 PDF 路径会存入共享状态,至此分析工作流完成。6. 构建多智能体图
最后一步是将所有智能体组装为一个由状态驱动的完整多智能体工作流。
通过共享的 State 模型构建 StateGraph,确保随着流程推进,每个智能体都与同一个不断演化的状态对象交互。画像器、代码编写器、执行器、洞察撰写器与报告构建器分别作为节点加入图中,对应流水线中的不同阶段。
工作流始终从画像智能体开始,并将其设为入口点,确保起步于对数据集的全面理解与分析计划的生成。
随后通过边来定义流程:画像后进入代码编写,再进入执行器。关键逻辑在于执行器的条件路由。
辅助函数
retry_or_continue会检查执行结果。若代码成功执行,工作流流转至洞察智能体。若失败但仍可重试,则回到代码编写器进行自动修复。
若无重试机会,则跳过后续分析,直接进入报告生成器,确保系统不会陷入无尽循环。条件边被纳入执行器节点,使工作流可根据执行成败自适应分流。
最后,图将洞察阶段连接至报告阶段,再由报告阶段结束整个工作流。图被编译为可执行结构,并生成 ASCII 图以可视化流程。
该多智能体图统筹整个自适应分析流水线,实现错误恢复、分步协作与平滑的智能体间切换。
7. 运行完整的 Gemini 3 API 数据分析流水线
要运行完整的流水线,您只需提供数据集路径,创建初始 State 对象,并调用已编译的图。这里我们使用波士顿房价(Boston Housing)数据集。
执行后,多智能体系统会自动完成整个分析:数据集画像、生成计划、编写与执行 Python 代码、提取洞察,并产出 Markdown 与 PDF 报告。
运行结束后,您可以打开 LangSmith 控制台,进入“autolab-gemini3pro”项目。每次智能体运行都会出现在那里。
点击最近一次运行并切换到瀑布图视图,即可查看各步骤的时间线:每个智能体耗时与所用工具。
您可以点击任一智能体查看:
LangSmith 对完善整个工作流发挥了关键作用。您看到的是最终版本,但在此之前为使项目达标我们尝试了许多次,Langsmith 帮助我调试了智能体中的问题。
8. 展示报告的 Markdown 与 PDF
当多智能体工作流完成后,您可以直接在 Notebook 中查看生成的 Markdown 报告。
Markdown 版本便于快速审阅分析、阅读洞察并检查报告结构,无需离开工作空间。
除 Markdown 外,工作流还会生成排版精良的 PDF 报告。PDF 会自动保存到 artifacts 文件夹,您可通过如下方式查看其路径:
生成的 PDF 完整呈现了分析关键组成部分:叙述性说明、可视化图表、图表解读、建模摘要与最终建议。
非常适合在需要展示清晰、可直接演示的结果时,与团队成员、主管或客户分享。
结语
完成这个项目让我切实感受到现代 AI 模型与基于图的智能体工作流的长足进步。不久之前,哪怕只构建一个带多工具的智能体,也往往需要数天的调优、调试与应对不确定行为。
如今,借助Gemini 3 Pro 等模型,系统能够理解数据集、生成准确代码、运行分析、解读可视化,并高度可靠地组装出精美的报告。
在本项目中,我们构建了一个完整的多智能体数据分析应用,能接收任意 CSV 数据集,完成端到端探索性分析、运行基线模型、生成洞察,并产出完整格式化的 PDF 报告。
该项目由五个协同智能体组成:画像与规划、代码生成、带重试的执行、洞察生成与报告输出;并包含三项核心工具用于数据集加载、安全执行代码与Markdown 转 PDF 渲染。
结果是一个干净、自动化的分析流程,输出由可视化支撑的专业叙事型报告。