📋 Documentation · v2.0

# AI Report Agent

Hướng dẫn chi tiết về luồng hoạt động, kiến trúc ReAct Reflect Loop, và các công cụ (tools) mà Agent sử dụng để tạo báo cáo phân tích từ dữ liệu thật.

← Quay lại 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.

Sẵn sàng tạo báo cáo?

📋 Mở AI Report Agent →