Hướng dẫn Gemini 3 API: Tự động hóa phân tích dữ liệu với Gemini 3 Pro và LangGraph

Gemini 3 Pro là mô hình AI tối tân mà tất cả chúng ta mong đợi, với cửa sổ ngữ cảnh đến một triệu token, có thể xử lý trơn tru tập dữ liệu, tài liệu, video và codebase trong một lần. Mô hình mang lại khả năng suy luận ở cấp độ Tiến sĩ, đồng thời vượt trội ở xử lý đa phương thức văn bản, hình ảnh, âm thanh và video cho quy trình sáng tạo liền mạch.

Trong hướng dẫn theo dự án này, tôi sẽ chỉ bạn cách dùng Gemini 3 API để xây dựng ứng dụng đa tác tử sử dụng tập dữ liệu CSV do người dùng cung cấp và thực hiện phân tích dữ liệu chuyên sâu. 

Tóm lại, ứng dụng đa tác tử sẽ thực hiện:

• Phân tích đơn giản: Khám phá nhanh cấu trúc và những điều cơ bản của tập dữ liệu.
• Sinh mã: Dùng Gemini 3 Pro để tạo mã phân tích nâng cao kèm trực quan hóa.
• Thực thi an toàn: Chạy mã trong môi trường sandbox và lưu kết quả.
• Lập luận thông minh: Phân tích và diễn giải phát hiện để rút ra insight chính.
• Biên soạn báo cáo PDF: Tạo PDF chỉn chu với hình ảnh và giải thích rõ ràng, nắm bắt insight trong vài giây.

Nếu bạn muốn tìm hiểu thêm về xây dựng quy trình làm việc AI tác tử, hãy xem hướng dẫn Google Antigravity, hướng dẫn Gemini 3 Flash, và lộ trình kỹ năng AI Agent Fundamentals.

1. Thiết lập môi trường Gemini 3 API

1. Chạy lệnh này để cài đặt mọi gói cần thiết cho ứng dụng đa tác tử của chúng ta:

!pip install -q google-genai langgraph langsmith grandalf pydantic pandas matplotlib markdown2 weasyprint markdown-it-py mdit-py-plugins

Phân tích gói:

• google-generativeai: Truy cập Gemini 3 Pro qua API chính thức.
• langgraph: Điều phối quy trình AI đa tác tử dễ dàng.
• langsmith: Theo dõi lượt chạy, giám sát hiệu năng và gỡ lỗi qua bảng điều khiển tương tác.
• grandalf: Trực quan hóa đồ thị tác tử dưới dạng sơ đồ ASCII gọn gàng.
• pydantic: Quản lý state chia sẻ của đồ thị với xác thực dữ liệu vững chắc.
• pandas: Khám phá và phân tích tập dữ liệu nhanh.
• matplotlib: Tạo trực quan hóa dữ liệu ấn tượng.
• markdown2: Chuyển Markdown sang HTML để định dạng báo cáo phong phú.
• weasyprint: Chuyển HTML/CSS thành báo cáo PDF chuyên nghiệp.
• markdown-it-py: Trình phân tích Markdown nâng cao cho định dạng phức tạp.
• mdit-py-plugins: Mở rộng markdown-it-py với plugin cho bảng, chú thích cuối trang, v.v.

Lưu ý: Chúng tôi dùng Jupyter Notebook để xây dựng dự án này.

2. Truy cập Google AI Studio và tạo API key của bạn. Hãy đảm bảo bạn đã cấu hình thanh toán cho tài khoản, vì mô hình Gemini 3 Pro không có ở gói miễn phí. 

3. Tiếp theo, tạo tài khoản LangSmith miễn phí và tạo API key. 

4. Lưu cả hai API key dưới dạng biến môi trường trên hệ thống cục bộ của bạn. Thiết lập LANGSMITH_API_KEY và GEMINI_API_KEY.

5. Import tất cả gói Python cần thiết trong notebook của bạn:

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

6. Đặt biến môi trường để chỉ định tên dự án LangSmith và bật theo dõi LangSmith:

os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = os.environ.get("LANGSMITH_API_KEY", "YOUR_LANGSMITH_KEY")
os.environ["LANGSMITH_PROJECT"] = os.environ.get("LANGSMITH_PROJECT", "autolab-gemini3pro")

7. Tạo thư mục để lưu tất cả hình ảnh và PDF:

ARTIFACTS_DIR = Path("artifacts")
ARTIFACTS_DIR.mkdir(exist_ok=True)

2. Cách khởi tạo khách hàng Gemini 3 API

Trong phần này, chúng ta sẽ thiết lập client Gemini API và bọc các lời gọi mô hình để có thể được truy vết và ghi log trong LangSmith. Ngoài ra, chúng ta sẽ trích xuất siêu dữ liệu sử dụng token và trả về theo định dạng thân thiện với LangSmith.

Đầu tiên, khởi tạo client Gemini GenAI bằng cách cung cấp API key:

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
MODEL = "gemini-3-pro-preview"

Tiếp theo, viết một wrapper nhỏ quanh lời gọi mô hình Gemini để bật tự động truy vết bằng LangSmith. Sử dụng decorator @traceable, chúng ta đăng ký hàm như một lần chạy LLM. 

Trong hàm này, mã sẽ gửi prompt tới Gemini và trích xuất chi tiết sử dụng token, điều thiết yếu để theo dõi chính xác trong LangSmith, theo đúng hướng dẫn truy vết. 

Cuối cùng, hàm sẽ trả về đầu ra văn bản của mô hình cùng thống kê token và phản hồi thô theo định dạng LangSmith mong đợi, đảm bảo lần chạy hiển thị chính xác trên giao diện.

from langsmith import traceable
@traceable(name="gemini_generate_content", run_type="llm")
def gemini_call(prompt: str, thinking_level: str = "high"):
    """
    Gemini wrapper that:
    - uses correct ThinkingConfig schema
    - returns LangSmith LLM-run format so token usage shows in UI
    """
    resp = client.models.generate_content(
        model=MODEL,
        contents=prompt,
        config=types.GenerateContentConfig(
            thinking_config=types.ThinkingConfig(thinking_level=thinking_level)
        ),
    )

    usage = getattr(resp, "usage_metadata", None)
    token_usage = None
    if usage:
        token_usage = {
            "prompt_tokens": usage.prompt_token_count,
            "completion_tokens": usage.candidates_token_count,
            "total_tokens": usage.total_token_count,
            "thoughts_tokens": getattr(usage, "thoughts_token_count", None),
        }

    return {
        "generations": [{"text": resp.text}],
        "llm_output": {
            "model_name": MODEL,
            "token_usage": token_usage,
        },
        "raw_response": resp,
    }

3. Xây dựng công cụ cho quy trình đa tác tử Gemini 3

Giờ chúng ta sẽ tạo các công cụ cung cấp khả năng kiểm tra tập dữ liệu, thực thi Python an toàn và tạo báo cáo Markdown‑sang‑PDF để dùng trong quy trình tác tử AI.

Công cụ 1: Tải tập dữ liệu

Công cụ này nhận đường dẫn tệp, đọc CSV vào pandas DataFrame, rồi xây dựng bản tóm tắt gồm kích thước tập dữ liệu, tên cột, kiểu dữ liệu từng cột, phần trăm giá trị thiếu, 5 hàng đầu và thống kê mô tả đầy đủ. Nó trả về tóm tắt này để tác tử nhanh chóng hiểu tập dữ liệu.

def load_dataset(path: str):
    df = pd.read_csv(path)

    summary = {
        "shape": df.shape,
        "columns": list(df.columns),
        "dtypes": {c: str(t) for c, t in df.dtypes.items()},
        "missing_pct": df.isna().mean().to_dict(),
        "head": df.head(5).to_dict(orient="records"),
        "describe": df.describe(include="all").fillna("").to_dict()
    }
    return summary

Công cụ 2: Chạy mã Python an toàn (sandbox đơn giản)

Công cụ này chạy an toàn mã Python sinh động trong môi trường hạn chế. Nó chuẩn bị môi trường cục bộ nhỏ, sau đó thực thi mã được cung cấp với exec. 

Mã được thực thi được kỳ vọng trả về đường dẫn artifact (như các biểu đồ đã lưu) và siêu dữ liệu. 

def run_python(code: str):
    """
    Generated code MUST:
      - save plots to ARTIFACTS_DIR
      - collect paths in _artifacts (list[str])
      - collect meta in _charts_meta (list[dict])
      - optionally set _stdout (string)
    """
    local_env = {"ARTIFACTS_DIR": ARTIFACTS_DIR}
    try:
        exec(textwrap.dedent(code), {}, local_env)
        return {
            "ok": True,
            "stdout": local_env.get("_stdout", ""),
            "artifacts": local_env.get("_artifacts", []),
            "charts_meta": local_env.get("_charts_meta", []),
        }
    except Exception:
        return {"ok": False, "traceback": traceback.format_exc()}

Công cụ 3: Kết xuất PDF từ Markdown

Công cụ này chuyển Markdown thành PDF được định dạng đẹp. Đầu tiên, nó xây dựng trình phân tích markdown hỗ trợ bảng, danh sách, danh sách nhiệm vụ và chú thích cuối trang. 

Sau đó render_pdf chuyển đổi văn bản markdown thành HTML, bọc trong mẫu có CSS tùy chỉnh (điều khiển phông chữ, hiển thị bảng, kích thước ảnh, v.v.), và dùng WeasyPrint để tạo tệp PDF. 

Cuối cùng, nó lưu PDF vào thư mục artifacts và trả về đường dẫn.

from markdown_it import MarkdownIt
from mdit_py_plugins.tasklists import tasklists_plugin
from mdit_py_plugins.footnote import footnote_plugin

# Create a strong markdown parser once (supports tables, lists, etc.)
md = (
    MarkdownIt("commonmark", {"breaks": True, "html": True})
    .enable(["table", "strikethrough"])
    .use(tasklists_plugin)
    .use(footnote_plugin)
)

def render_pdf(markdown_text: str):
    """
    Better Markdown -> HTML -> PDF:
    - proper tables
    - stable lists
    - centered/small images
    - clean page breaks
    """
    html_body = md.render(markdown_text)

    html_template = f"""
    <html>
    <head>
      <meta charset="utf-8">
      <style>
        body {{
          font-family: Arial, sans-serif;
          font-size: 12px;
          line-height: 1.5;
          color: #111;
        }}

        h1 {{ font-size: 20px; margin-bottom: 6px; }}
        h2 {{ font-size: 16px; margin-top: 18px; margin-bottom: 6px; }}
        h3 {{ font-size: 13px; margin-top: 12px; margin-bottom: 4px; }}

        p {{ margin: 6px 0; }}

        ul, ol {{
          margin: 6px 0 6px 18px;
        }}
        li {{ margin: 2px 0; }}

        table {{
          width: 100%;
          border-collapse: collapse;
          margin: 8px 0 12px 0;
          font-size: 11px;
        }}
        th, td {{
          border: 1px solid #ccc;
          padding: 6px;
          text-align: left;
        }}
        th {{ background: #f2f2f2; }}

        img {{
          display: block;
          margin: 8px auto 8px auto;
          max-width: 70%;
          height: auto;
          page-break-inside: avoid;
        }}

        .chart-block {{
          page-break-inside: avoid;
          margin-bottom: 12px;
        }}

        code {{
          background: #f6f6f6;
          padding: 2px 4px;
          border-radius: 4px;
          font-size: 11px;
        }}
        pre code {{
          display: block;
          padding: 8px;
          overflow-x: auto;
        }}
      </style>
    </head>
    <body>
      {html_body}
    </body>
    </html>
    """

    pdf_path = ARTIFACTS_DIR / "report.pdf"
    weasyprint.HTML(
        string=html_template,
        base_url=str(ARTIFACTS_DIR.parent.resolve())
    ).write_pdf(str(pdf_path))

    return str(pdf_path)

Phần này chỉ đăng ký cả ba hàm như các công cụ sẵn có cho tác tử sử dụng.

TOOLS = [load_dataset, run_python, render_pdf]

4. State dùng chung của đồ thị

Lớp này định nghĩa đối tượng state dùng chung lưu mọi thứ mà quy trình tác tử tạo ra: như đường dẫn tập dữ liệu, thông tin hồ sơ, kế hoạch sinh ra, mã, kết quả thực thi, insight và báo cáo cuối, cùng giới hạn retry và thông báo lỗi để tránh vòng lặp vô hạn.

class State(BaseModel):
    dataset_path: str
    profile: dict | None = None
    plan: dict | None = None
    code: str | None = None
    exec_result: dict | None = None
    charts_meta: list | None = None
    insights: str | None = None
    report_md: str | None = None
    report_pdf: str | None = None

    retry_count: int = 0          # NEW: stop infinite loops
    last_error: str | None = None # NEW: pass traceback to coder

MAX_RETRIES = 2

5. Tạo tác tử Gemini 3 API cho phân tích dữ liệu

Giờ chúng ta sẽ tạo các tác tử AI phối hợp cùng nhau để lập hồ sơ tập dữ liệu, viết và chạy mã phân tích, tạo insight và xuất báo cáo PDF cuối cùng.

Tác tử 1: Lập hồ sơ dữ liệu và lập kế hoạch

Tác tử này chịu trách nhiệm hiểu tập dữ liệu và tạo kế hoạch phân tích có cấu trúc. Nó tải tập dữ liệu bằng công cụ load_dataset, cho ra tóm tắt gồm kích thước, giá trị thiếu, kiểu cột, thống kê mô tả và hàng ví dụ. 

Sau đó, nó gửi tóm tắt này tới LLM kèm hướng dẫn rất rõ: xác định loại tác vụ, chọn cột mục tiêu nếu có, quyết định các bước khám phá cần thực hiện, đề xuất các biểu đồ cần tạo và phác thảo bước mô hình hóa nếu tập dữ liệu gợi ý phân loại hoặc hồi quy. 

LLM trả về cấu trúc JSON đại diện cho kế hoạch này, và tác tử phân tích nó, rơi về lưu văn bản thô nếu việc phân tích JSON thất bại. 

Cuối cùng, nó lưu cả hồ sơ tập dữ liệu và kế hoạch vào state dùng chung để các tác tử tiếp theo có đủ thông tin cần thiết.

@traceable(name="profiler_agent")
def profiler_agent(state: State):
    profile = load_dataset(state.dataset_path)

    prompt = f"""
    You are the Data Profiler Agent.
    Produce a JSON analysis plan with:
      - task_type: "classification"|"regression"|"eda_only"
      - target_column (if any)
      - eda_steps (list)
      - charts_to_make (list)  # 5-10 max, most informative
      - baseline_model_steps (list if modeling)
      - risks_or_data_issues (list)

    Dataset profile:
    {json.dumps(profile, indent=2)}
    """

    resp = gemini_call(prompt, thinking_level="high")
    text = resp["generations"][0]["text"]

    try:
        plan = json.loads(text)
    except:
        plan = {"raw_plan": text}

    state.profile = profile
    state.plan = plan
    return state

Tác tử 2: Người viết mã

Tác tử này chuyển kế hoạch phân tích thành mã Python có thể thực thi. Nó nhận hồ sơ tập dữ liệu, kế hoạch và mọi lỗi thực thi trước đó. Dựa trên toàn bộ ngữ cảnh, nó yêu cầu LLM chỉ xuất mã Python. 

Prompt có yêu cầu nghiêm ngặt: tải tập dữ liệu, làm đúng kế hoạch, tạo từng biểu đồ đã định, lưu biểu đồ vào ARTIFACTS_DIR, theo dõi đường dẫn và siêu dữ liệu biểu đồ, ghi lại output console, đóng figure sau khi lưu, và tùy chọn tính toán chỉ số mô hình. 

Điều này đảm bảo mã có thể tái lập và an toàn trong sandbox. Kết quả được lưu trong state.code, sẵn sàng cho bộ thực thi chạy.

@traceable(name="code_writer_agent")
def code_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

Tác tử 3: Bộ thực thi (kèm tự động retry)

Tác tử này chạy mã Python do Người viết mã tạo ra bằng sandbox run_python cách ly. Nó ghi nhận kết quả thực thi, siêu dữ liệu biểu đồ, standard output và mọi artifact được tạo. 

Nếu chạy thành công, kết quả được lưu và quy trình tiếp tục bình thường. Nếu thất bại, tác tử tăng bộ đếm retry và lưu traceback để tác tử Người viết mã sửa lỗi ở lần thử tiếp theo. 

Với MAX_RETRIES giới hạn vòng lặp, tác tử này ngăn vòng lặp vô hạn và cung cấp tín hiệu phản hồi cần thiết cho tự sửa lỗi.

@traceable(name="executor_agent")
def executor_agent(state: State):
    result = run_python(state.code)
    state.exec_result = result
    state.charts_meta = result.get("charts_meta", [])

    if not result["ok"]:
        state.retry_count += 1
        state.last_error = result.get("traceback", "Unknown error")

    return state

Tác tử 4: Người viết insight

Tác tử này diễn giải toàn bộ phân tích. Nó lấy hồ sơ tập dữ liệu, đầu ra thực thi và siêu dữ liệu biểu đồ, rồi tạo insight phân tích dễ đọc cho con người. 

Nó hướng dẫn LLM sinh insight có cấu trúc: với mỗi biểu đồ, đưa ra hai điểm rút ra và một rủi ro, rồi tạo một tập nhỏ insight tổng thể. 

Tác tử phải đảm bảo không có gạch đầu dòng trống, không lặp ý, và insight phải đặc thù cho tập dữ liệu này, không chung chung. 

Báo cáo insight thu được được lưu trong state.insights, trở thành đầu vào cho giai đoạn báo cáo cuối.

@traceable(name="insights_agent")
def insights_agent(state: State):
    prompt = f"""
    You are the Insights Agent.

    HARD REQUIREMENTS:
    - No empty bullets.
    - No repeated bullets.
    - Be specific to this dataset and these charts.
    - Output format:

      ### Chart Insights
      For each chart in charts_meta:
      - **<title>**
        - Takeaway 1 (one sentence)
        - Takeaway 2 (one sentence)
        - Caveat/Risk (one sentence)

      ### Overall Insights
      - 3-5 bullets max, each one sentence.

    Inputs:
    Profile:
    {json.dumps(state.profile, indent=2)}

    Execution result:
    {json.dumps(state.exec_result, indent=2)}

    Charts meta:
    {json.dumps(state.charts_meta, indent=2)}
    """

    resp = gemini_call(prompt, thinking_level="high")
    state.insights = resp["generations"][0]["text"]
    return state

Tác tử 5: Dựng báo cáo → PDF

Đây là tác tử tổng hợp cuối cùng. Nó sử dụng toàn bộ đầu ra của pipeline: hồ sơ, insight, siêu dữ liệu biểu đồ, log thực thi, và soạn một báo cáo Markdown đầy đủ, sạch sẽ. 

Prompt bắt buộc quy tắc định dạng nghiêm: không lặp tiêu đề, khoảng cách nhất quán, mỗi biểu đồ hiển thị đúng một lần trong khối HTML chuẩn hóa, và tích hợp mượt insight. 

Khi Markdown đã được tạo, tác tử gọi render_pdf để chuyển thành PDF chỉn chu bằng WeasyPrint. Cả Markdown và đường dẫn PDF được lưu trong state dùng chung, hoàn tất quy trình phân tích.

@traceable(name="report_agent")
def report_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. Xây dựng đồ thị đa tác tử

Bước cuối cùng này là dựng toàn bộ quy trình đa tác tử bằng cách lắp ghép các tác tử vào một đồ thị điều khiển theo state. 

Một StateGraph được tạo với State dùng chung, đảm bảo mọi tác tử tương tác với cùng đối tượng state đang tiến hóa khi quy trình diễn ra. Mỗi thành phần, như profiler, người viết mã, bộ thực thi, người viết insight và bộ dựng báo cáo, được thêm vào đồ thị như một node riêng biệt, đại diện cho một giai đoạn cụ thể trong pipeline. 

Quy trình luôn bắt đầu với tác tử profiler, được chỉ định làm điểm vào. Điều này đảm bảo quá trình khởi động bằng việc hiểu kỹ tập dữ liệu và tạo kế hoạch phân tích.

Các cạnh được thiết lập để xác định luồng. Sau khi lập hồ sơ, đầu ra được chuyển tới người viết mã, rồi tới bộ thực thi. Logic chính nằm ở điều hướng có điều kiện từ bộ thực thi. 

Hàm trợ giúp retry_or_continue kiểm tra kết quả thực thi. Nếu mã chạy thành công, quy trình chuyển sang tác tử insight. 

Nếu thất bại nhưng vẫn còn lượt retry, nó vòng lại người viết mã để tự động sửa.

 Nếu hết số lần retry, nó bỏ qua phân tích tiếp theo và chuyển thẳng tới bộ tạo báo cáo, đảm bảo hệ thống không rơi vào vòng lặp vô tận. Các cạnh có điều kiện được đưa vào node bộ thực thi để quy trình có thể thích ứng dựa trên thành bại của việc thực thi.

Cuối cùng, đồ thị nối giai đoạn insight tới giai đoạn báo cáo, và từ báo cáo tới kết thúc quy trình. Đồ thị sau đó được biên dịch thành cấu trúc có thể thực thi, và sơ đồ ASCII được tạo để trực quan hóa luồng. 

Đồ thị đa tác tử này điều phối toàn bộ pipeline phân tích thích ứng, cho phép phục hồi lỗi, phối hợp từng bước và chuyển tiếp mượt giữa các tác tử.

g = StateGraph(State)

g.add_node("profiler", profiler_agent)
g.add_node("code_writer", code_writer_agent)
g.add_node("executor", executor_agent)
g.add_node("insights", insights_agent)
g.add_node("report", report_agent)

g.set_entry_point("profiler")
g.add_edge("profiler", "code_writer")
g.add_edge("code_writer", "executor")

def retry_or_continue(state: State):
    # success path
    if state.exec_result and state.exec_result.get("ok"):
        return "insights"
    # stop retrying after MAX_RETRIES
    if state.retry_count >= MAX_RETRIES:
        return "report"
    return "code_writer"

g.add_conditional_edges(
    "executor",
    retry_or_continue,
    {"code_writer": "code_writer", "insights": "insights", "report": "report"}
)

g.add_edge("insights", "report")
g.add_edge("report", END)

graph = g.compile()

print(graph.get_graph().draw_ascii())

      +-----------+      
          | __start__ |      
          +-----------+      
                 *           
                 *           
                 *           
           +----------+      
           | profiler |      
           +----------+      
                 *           
                 *           
                 *           
          +-------------+    
          | code_writer |    
          +-------------+    
                 .           
                 .           
                 .           
           +----------+      
           | executor |      
           +----------+      
           ..         ..     
         ..             ..   
        .                 .. 
+----------+                .
| insights |              .. 
+----------+            ..   
           **         ..     
             **     ..       
               *   .         
            +--------+       
            | report |       
            +--------+       
                 *           
                 *           
                 *           
            +---------+      
            | __end__ |      
            +---------+  

7. Chạy toàn bộ pipeline phân tích dữ liệu Gemini 3 API

Để chạy toàn bộ pipeline, bạn chỉ cần cung cấp đường dẫn tập dữ liệu, tạo đối tượng State ban đầu và gọi đồ thị đã biên dịch. Ở đây, chúng tôi dùng tập dữ liệu Boston Housing.

DATASET_PATH = "/work/housing.csv"  # <-- change this

state = State(dataset_path=DATASET_PATH)
out = graph.invoke(state)

Khi được gọi, hệ thống đa tác tử sẽ tự động thực hiện toàn bộ phân tích: lập hồ sơ tập dữ liệu, tạo kế hoạch, viết và chạy mã Python, rút insight, và tạo cả báo cáo Markdown lẫn 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).

Sau khi chạy xong, bạn có thể mở bảng điều khiển LangSmith và đi tới dự án “autolab-gemini3pro”. Mỗi lượt chạy tác tử đều xuất hiện ở đó. 

Nhấp vào lượt chạy gần đây và chuyển sang chế độ xem Waterfall sẽ hiển thị dòng thời gian của từng bước: thời lượng tác tử thực hiện và công cụ đã dùng.

Bạn có thể nhấp vào bất kỳ tác tử nào để kiểm tra:

• Prompt mà nó nhận
• Phần sinh của mô hình chính xác
• Chi tiết thực thi công cụ
• Artifact, biểu đồ và vết truy theo trả về

LangSmith đóng vai trò then chốt trong việc cải thiện toàn bộ quy trình. Những gì bạn thấy là phiên bản cuối cùng, nhưng đã mất nhiều lần thử để làm đúng dự án này, và LangSmith giúp tôi gỡ lỗi các vấn đề trong các tác tử.

8. Hiển thị Markdown và PDF của báo cáo

Khi quy trình đa tác tử hoàn tất, bạn có thể trực tiếp kiểm tra báo cáo Markdown được tạo ngay trong notebook của mình. 

Phiên bản Markdown hữu ích để xem nhanh phân tích, đọc insight và kiểm tra cấu trúc báo cáo mà không rời không gian làm việc.

print(out["report_md"][:2000])

# 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.............

Ngoài Markdown, quy trình cũng tạo báo cáo PDF chỉn chu. PDF được tự động lưu trong thư mục artifacts, và bạn có thể xem đường dẫn như sau:

print("PDF saved at:", out["report_pdf"])

PDF saved at: artifacts/report.pdf

PDF tạo ra hoàn chỉnh và chứa mọi thành phần chính của phân tích: thuyết minh, biểu đồ được kết xuất, diễn giải biểu đồ, tóm tắt mô hình và khuyến nghị cuối. 

Điều này lý tưởng để chia sẻ với đồng đội, quản lý hoặc khách hàng, đặc biệt khi bạn cần phiên bản kết quả sạch, sẵn sàng trình bày.

Suy ngẫm cuối

Làm việc trên dự án này cho thấy các mô hình AI hiện đại và quy trình tác tử dựa trên đồ thị đã tiến xa đến mức nào. Không lâu trước đây, xây dựng ngay cả một tác tử với nhiều công cụ cũng mất nhiều ngày tinh chỉnh, gỡ lỗi và xử lý hành vi khó lường. 

Ngày nay, với các mô hình như Gemini 3 Pro, hệ thống có thể hiểu tập dữ liệu, sinh mã chính xác, chạy phân tích, diễn giải trực quan hóa và lắp ghép một báo cáo chỉn chu với độ tin cậy đáng kể. 

Trong dự án này, chúng ta đã xây dựng ứng dụng phân tích dữ liệu đa tác tử hoàn chỉnh, có khả năng nhận bất kỳ tập dữ liệu CSV nào, thực hiện phân tích khám phá end‑to‑end, chạy mô hình nền tảng, tạo insight và xuất báo cáo PDF định dạng đầy đủ. 

Dự án sử dụng năm tác tử phối hợp: lập hồ sơ & lập kế hoạch, sinh mã, thực thi có retry, tạo insight và báo cáo, cùng ba công cụ cốt lõi cho tải tập dữ liệu, thực thi mã an toàn và kết xuất Markdown‑sang‑PDF. 

Kết quả là một luồng phân tích tự động, gọn gàng, tạo báo cáo mang tính tường thuật chuyên nghiệp được hậu thuẫn bởi trực quan hóa.