Hướng dẫn — AI Report Agent

Tổng quan

Agent hoạt động như thế nào?

AI Report Agent sử dụng kiến trúc ReAct (Reasoning + Acting) với cơ chế Reflect Loop. Thay vì chạy cứng một pipeline, Agent tự suy nghĩ, query dữ liệu, đánh giá xem đã đủ chưa, và tự quyết định khi nào dừng lại để viết báo cáo.

💡

Tại sao dùng Reflect Loop?
Pipeline truyền thống (Planner → Tools → Writer) sẽ quyết định tất cả tools từ đầu. Nếu 1 tool lỗi hoặc trả data thiếu, không có cơ chế bổ sung. Reflect Loop cho phép Agent tự đánh giá và query thêm khi cần.

Luồng hoạt động

ReAct Reflect Loop — Chi tiết

  📝  User nhập yêu cầu báo cáo
         ↓
  🧠  THINK — Agent phân tích, chọn tools + viết SQL
         ↓
  🔧  ACT — Execute tools song song (asyncio.gather)
         ↓
  👁️  OBSERVE — Thu thập kết quả từ các tools
         ↓
  🔍  REFLECT — LLM tự đánh giá:
      │   • Dữ liệu đã đủ chưa?
      │   • Chất lượng data có ổn không?
      │   • Còn thiếu góc nhìn nào?
      │
      ├── ❌ Chưa đủ → Quay lại THINK (thêm queries)
      │   (tối đa 3 vòng reflect)
      │
      └── ✅ Đủ rồi → Tiếp tục xuống
         ↓
  ✍️  WRITE — LLM viết báo cáo hoàn chỉnh từ data thật
         ↓
  📄  Stream sections lên frontend (progressive rendering)
         ↓
  🏁  DONE — Báo cáo hoàn thành!

🧠

Phase 1: THINK — Phân tích & Lên kế hoạch

Agent nhận yêu cầu từ user, phân tích cần data gì, tạo SQL queries phù hợp. Chọn 2-4 tools đa dạng cho batch đầu.

LLM Call #1

🔧

Phase 2: ACT — Execute Tools Song Song

Tất cả tools trong batch được execute đồng thời bằng asyncio.gather(). Không chờ tuần tự → nhanh gấp 3-4x. Mỗi kết quả được stream lên sidebar realtime.

Parallel I/O

🔍

Phase 3: REFLECT — Tự đánh giá dữ liệu

LLM xem lại toàn bộ data đã thu thập. Đánh giá: Đủ chưa? Chất lượng ổn không? Thiếu góc nhìn nào? Nếu thiếu → tạo thêm queries. Nếu đủ → chuyển sang viết.

LLM Call #2 · Reflect Max 3 vòng

✍️

Phase 4: WRITE — Viết báo cáo hoàn chỉnh

LLM nhận toàn bộ data thật → viết báo cáo JSON gồm: executive summary, highlights, 4-6 sections (mỗi section có paragraphs + chart/table), conclusion, recommendations. Sections được stream lần lượt lên frontend.

LLM Call #3 · Writer

Công cụ dữ liệu

4 Tools Agent sử dụng

Agent có quyền truy cập 4 tools để thu thập dữ liệu. Mỗi tool chỉ được phép SELECT (read-only).

📊

sql_langfuse

Query bảng analytic.chatbot_rsa_trace_event_detail trên StarRocks. Chứa dữ liệu Langfuse: traces, latency, costs, models, errors.

👉 Dùng cho: Hiệu suất chatbot, chi phí LLM, user analytics

🏷️

sql_starrocks

Query bảng sản phẩm shared_source.magento_product_dimension_*. Chứa: tên SP, giá, số lượng bán, màu, chất liệu, mùa.

👉 Dùng cho: Phân tích sản phẩm, doanh thu, thống kê catalog

💬

sql_postgres

Query bảng public.langgraph_chat_histories. Chứa: tin nhắn user, bot, timestamp, identity.

👉 Dùng cho: Phân tích hội thoại, volume chat, engagement

🧮

calculator

Tính toán math thuần túy: phép cộng, trừ, nhân, chia, phần trăm. Chỉ nhận digits + operators.

👉 Dùng cho: Tỉ lệ tăng trưởng, % thay đổi, trung bình

Schema

Bảng Langfuse trên StarRocks

Bảng analytic.chatbot_rsa_trace_event_detail — chứa toàn bộ traces từ Langfuse, sync tự động.

Cột	Kiểu	Mô tả
`trace_id`	VARCHAR	ID unique của trace
`session_id`	VARCHAR	ID phiên hội thoại
`customer_id`	VARCHAR	Mã khách hàng (từ Canifa)
`device_id`	VARCHAR	ID thiết bị user
`model_name`	VARCHAR	Model LLM (gpt-5.2-codex, gemini-3.1-flash-lite...)
`trace_latency`	DECIMAL	Tổng latency trace (giây)
`user_latency`	DECIMAL	Latency user cảm nhận (giây)
`input_cost`	DECIMAL	Chi phí input tokens (USD)
`output_cost`	DECIMAL	Chi phí output tokens (USD)
`total_cost`	DECIMAL	Tổng chi phí (USD)
`total_obs`	BIGINT	Tổng observations trong trace
`total_obs_error`	BIGINT	Observations bị lỗi
`nb_generation_error`	BIGINT	Số lỗi generation
`is_guest`	TINYINT	1 = khách vãng lai, 0 = đã login
`is_user`	TINYINT	1 = user đã xác thực
`traced_at`	DATETIME	Thời điểm trace xảy ra

Output

Cấu trúc báo cáo

Agent viết báo cáo dưới dạng JSON, frontend render realtime. Mỗi report có:

📝

Executive Summary

Tóm tắt 3-5 câu từ data thật

📊

4-6 Sections

Mỗi section: text + chart hoặc table

💡

Recommendations

4-6 khuyến nghị dựa trên findings

📈

Chart types hỗ trợ: Bar, Line, Area, Horizontal Bar, Donut.
Tất cả data trên biểu đồ đều đến từ query thật — không có số giả.

Tech Stack

Kiến trúc kỹ thuật

🖥️ Frontend

React 18 (UMD) + Babel standalone + Chart.js 4. SSE streaming qua fetch() + ReadableStream. Progressive section rendering.

⚡ Backend

FastAPI + StreamingResponse (SSE). Async tools via asyncio.gather(). Endpoint: POST /api/report-agent

🤖 LLM

Codex GPT-5.3 (default). 2-3 LLM calls per report: Think + Reflect + Write. Custom system prompts cho mỗi phase.

🗄️ Databases

StarRocks (product catalog + Langfuse) + PostgreSQL (chat histories). Read-only access, SQL injection protected.