Cách xây dựng AI agent với Gemini 3 trong 10 phút

Sử dụng mô hình Gemini 3, chúng ta sẽ tạo một agent tự động phân tích các file CSV. Agent này load dữ liệu, tính toán số liệu thống kê, xác định xu hướng và đưa ra các khuyến nghị cho những hành động kinh doanh. Báo cáo kinh doanh thực tế, bảng điều khiển bán hàng và bất kỳ tác vụ nào khác yêu cầu thông tin chi tiết từ dữ liệu bảng tính đều có thể hưởng lợi từ phương pháp này.

Trước tiên, hãy cấu hình bộ công cụ Gemini.

Bước 1: Cài đặt bộ công cụ Gemini 3

Hãy làm theo các bước sau để cài đặt bộ công cụ Gemini 3 trên máy tính của bạn:

1. Trước tiên, hãy cài đặt Gemini SDK. Mở terminal và chạy lệnh:

pip install google-generativeai

2. Tiếp theo, chúng ta cần API key, vì vậy, hãy truy cập trang API key của Google và chọn “Create API key”. Đặt tên theo yêu cầu, tạo key và sao chép nó.

3. Đặt API key của bạn làm biến môi trường. Đối với Windows, hãy mở PowerShell và chạy lệnh sau:

$env:GEMINI_API_KEY='đặt-api-key-của-bạn-ở-đây'

Người dùng Mac/Linux có thể chạy lệnh sau:

export GEMINI_API_KEY='đặt-api-key-của-bạn-ở-đây'

4. Kiểm tra thiết lập của bạn với một đoạn code Python ngắn:

import google.generativeai as genai 
import os 

genai.configure(api_key=os.getenv('GEMINI_API_KEY')) 
model = genai.GenerativeModel('gemini-3-pro-preview') 
response = model.generate_content('Hello, Gemini!') 
print(response.text) 

Nếu thấy phản hồi, bạn đã sẵn sàng xây dựng agent của mình.

Bước 2: Thiết lập thư mục dự án

1. Tạo thư mục làm việc cho dự án agent của bạn bằng lệnh sau trên terminal:

mkdir gemini-data-agent
cd gemini-data-agent # sử dụng lệnh này để điều hướng vào bên trong thư mục đã tạo

2. Bây giờ, hãy tạo một tập dữ liệu mẫu. file CSV này chứa dữ liệu bán hàng trên các sản phẩm và khu vực khác nhau. Lưu file này dưới dạng sales.csv:

date,product,sales,region,quantity 
2024-01-15,Widget A,1200,North,45 
2024-01-16,Widget B,850,South,30 
2024-01-17,Widget A,1100,East,42 
2024-01-18,Widget C,2000,West,50 
2024-01-19,Widget B,750,North,25 
2024-01-20,Widget A,1300,South,48 
2024-01-21,Widget C,1900,East,47 
2024-01-22,Widget B,900,West,32 
2024-01-23,Widget A,1150,North,44 
2024-01-24,Widget C,2100,South,52 
2024-01-25,Widget B,820,East,28 
2024-01-26,Widget A,1250,West,46 
2024-01-27,Widget C,1950,North,49 
2024-01-28,Widget B,880,South,31 
2024-01-29,Widget A,1180,East,43 

Bộ dữ liệu này chứa 15 giao dịch với thông tin về ngày tháng, sản phẩm (Widget A, B và C), doanh thu, khu vực và số lượng hàng bán. Thông tin này sẽ được agent sử dụng để tính toán các chỉ số hiệu suất, phát hiện xu hướng và tạo ra những hiểu biết kinh doanh.

3. Tiếp theo, hãy tạo một file cấu hình xác định cách agent của bạn nên hoạt động. Lưu file này dưới dạng agent_config.json:

{  
  "role": "Data Analysis Agent",  
  "goal": "Load file CSV, phân tích dữ liệu và tạo ra những hiểu biết có thể hành động được",  
  "tasks": [  
    "Đọc nội dung file CSV và xác minh chất lượng dữ liệu",  
    "Tính toán số liệu thống kê tóm tắt cho tất cả các cột số",  
    "Xác định xu hướng, mô hình hoặc các giá trị ngoại lệ trong dữ liệu",  
    "Tạo ra những hiểu biết sâu sắc bằng ngôn ngữ tự nhiên thông qua các đề xuất"  
  ],  
  "allowed_tools": ["code_execution", "file_read"],  
  "restrictions": "Chỉ truy cập các file trong thư mục dự án. Chỉ thực thi code Python an toàn.", 
  "output_format": "Báo cáo có cấu trúc với số liệu thống kê, hình ảnh trực quan và phân tích chuyên sâu"  
}

File cấu hình này cho agent biết vai trò của nó, các nhiệm vụ nó phải hoàn thành, những công cụ nó có thể sử dụng và các giới hạn nó nên tuân theo. Cấu trúc dự án của bạn giờ sẽ như sau:

gemini-data-agent/  
  ├── sales.csv  
  ├── agent_config.json  
  └── agent.py (chúng ta sẽ tạo ra nó ở bước tiếp theo) 

Chúng ta đã có dữ liệu và cấu hình sẵn sàng. Bước tiếp theo là xác định cách thức hoạt động và suy nghĩ của agent.

Bước 3: Xác định mục tiêu và hành vi của agent

Bây giờ, chúng ta cần cho agent biết chính xác phải làm gì và làm như thế nào. Điều này diễn ra trong hai phần:

• File cấu hình vừa tạo
• Các hướng dẫn hệ thống điều khiển hành vi của agent

File agent_config.json đã xác định các mục tiêu cấp cao. Tiếp theo, tạo một file mới có tên là agent.py và bắt đầu với trình load cấu hình:

import google.generativeai as genai  
import json  
import os 

 
class DataAnalysisAgent: 
  def __init__(self, config_path='agent_config.json', api_key=None):  
    """Khởi tạo agent với cấu hình và API key."""  
    self.config = self.load_config(config_path)  
    self.api_key = api_key or os.getenv('GEMINI_API_KEY') 

    if not self.api_key: 
      raise ValueError("Cần Gemini API key.") 
    self.setup_gemini() 
  
  def load_config(self, config_path):  
    """Load cấu hình agent từ file JSON"""  
    with open(config_path, 'r') as f:  
      return json.load(f) 

Bây giờ, hãy thêm phương thức xây dựng các lệnh hệ thống. Đây là nơi bạn xác định chính xác cách agent nên tiếp cận các nhiệm vụ phân tích:

  def build_system_instruction(self): 
    """Xây dựng hướng dẫn hệ thống cho Gemini agent.""" 
    instruction = f""" 

Bạn là một {self.config['role']}.  
Mục tiêu của bạn: {self.config['goal']} 

Các nhiệm vụ cần hoàn thành: 
{chr(10).join(f"- {task}" for task in self.config['tasks'])} 

Các công cụ có sẵn: {', '.join(self.config['allowed_tools'])}

Hạn chế: {self.config['restrictions']} 

Các quy tắc thực thi code:

- Thực thi code Python một cách im lặng mà không hiển thị code
- Sử dụng pandas để thao tác dữ liệu
- Tạo ra những thông tin chi tiết rõ ràng, có thể hành động được
- Trình bày kết quả trong các bảng được định dạng gọn gàng

Khi phân tích dữ liệu:

1. Load file CSV bằng pandas
2. Tính toán các số liệu thống kê tóm tắt toàn diện
3. Phân tích hiệu suất theo sản phẩm và khu vực
4. Xác định các giá trị ngoại lệ bằng các phương pháp thống kê (IQR)
5. Tạo ra 5-7 thông tin chi tiết quan trọng bằng ngôn ngữ tự nhiên
6. Đưa ra các khuyến nghị có thể hành động được

ĐỊNH DẠNG KẾT QUẢ QUAN TRỌNG:

- KHÔNG hiển thị các block code Python hoặc chi tiết thực thi code
- CHỈ hiển thị kết quả trong các phần được định dạng rõ ràng với tiêu đề
- Sau các bảng, cung cấp một phần phân tích toàn diện với những hiểu biết và khuyến nghị chính
- Sử dụng tiêu đề phần rõ ràng và định dạng chuyên nghiệp
    """ 

    return instruction.strip() 

Lưu ý: Tất cả các phương thức ở đây đều thuộc lớp DataAnalysisAgent, vì vậy chúng được thụt lề hai khoảng trắng bên dưới định nghĩa lớp.

Những hướng dẫn này cho agent biết:

• Vai trò của nó là gì (Data Analysis Agent)
• Mục tiêu chính của nó là gì (phân tích dữ liệu và tạo ra những hiểu biết)
• Những nhiệm vụ cụ thể cần hoàn thành (load dữ liệu, tính toán số liệu thống kê, tìm kiếm các mẫu)
• Những công cụ nó có thể sử dụng (thực thi code và đọc file)
• Những hạn chế cần tuân theo (chỉ truy cập các file dự án, sử dụng code an toàn)
• Cách định dạng đầu ra (bảng sạch, không hiển thị code, cấu trúc chuyên nghiệp)

Agent sẽ sử dụng những hướng dẫn này mỗi khi nó phân tích dữ liệu. Điều này giống như việc cung cấp cho agent một cuốn cẩm nang chi tiết mà nó sẽ tự động tuân theo.

Bước 4: Cấu hình công cụ (truy cập file và thực thi code)

Các Gemini agent hoạt động bằng cách gọi những công cụ để hoàn thành nhiệm vụ. Đối với phân tích dữ liệu, chúng ta cần hai công cụ chính:

1. Thực thi code
2. Truy cập file.

Thêm phương thức này vào lớp DataAnalysisAgent của bạn:

  def setup_gemini(self): 
    """Thiết lập mô hình Gemini 3 bằng các công cụ và hướng dẫn hệ thống."""
     
    # Configure the API 
    genai.configure(api_key=self.api_key) 

    # Tạo mô hình bằng công cụ thực thi code
    self.model = genai.GenerativeModel( 
      'gemini-3-pro-preview', 
      tools='code_execution', 
      system_instruction=self.build_system_instruction() 
    ) 

    print("Initializing Gemini 3 Agent...") 
    print(f"Role: {self.config['role']}") 
    print(f"Goal: {self.config['goal']}") 
    print(f"Tools: {', '.join(self.config['allowed_tools'])}") 

Lưu ý: Phương thức này là một phần của lớp DataAnalysisAgent được thụt vào hai dấu cách bên dưới định nghĩa lớp.

Đây là những gì xảy ra trong thiết lập này:

1. Cấu hình API: Lệnh genai.configure() xác thực kết nối của bạn với Gemini bằng API key.

2. Tạo mô hình: Chúng ta khởi tạo mô hình Gemini với 3 thành phần chính:

• Tên mô hình: gemini-3-pro-preview (mô hình Gemini agent mới nhất)
• Công cụ: code_execution (cho phép agent viết và chạy code Python)
• Hướng dẫn hệ thống: Hướng dẫn hành vi chi tiết mà chúng ta đã tạo ở bước trước

3. An toàn công cụ: Gemini thực thi code trong môi trường sandbox. Điều này có nghĩa là:

• Agent chỉ có thể đọc các file bạn cung cấp rõ ràng
• Code chạy độc lập mà không cần truy cập vào hệ thống của bạn
• Bạn kiểm soát các thư mục và file mà agent có thể truy cập
• Tất cả các thao tác đều được ghi nhật ký và minh bạch

Công cụ code_execution làm cho agent này thực sự tự chủ. Thay vì chỉ mô tả phân tích cần thực hiện, agent thực sự viết code Python, thực thi nó, diễn giải kết quả và tạo ra thông tin chi tiết.

Bước 5: Viết định nghĩa agent

Bây giờ, chúng ta sẽ tạo phương thức phân tích chính liên kết mọi thứ lại với nhau. Phương thức này nhận một file CSV, gửi nó đến Gemini cùng với các hướng dẫn và trả về kết quả phân tích. Thêm đoạn code này vào lớp DataAnalysisAgent của bạn:

  def analyze_data(self, file_path):  
    """Phương pháp chính để phân tích file CSV bằng Gemini 3.""" 
    print(f"Analyzing: {file_path}\n") 

    # Đọc nội dung file CSV 
    with open(file_path, 'r') as f: 
      csv_content = f.read() 
 
    # Tạo prompt để phân tích 
    prompt = f""" 
  
Tôi có một file CSV với nội dung như sau:

```csv 
{csv_content} 
```  

Phân tích dữ liệu này một cách toàn diện và trình bày kết quả theo định dạng sau:

1. Hiển thị bảng thống kê tóm tắt với tiêu đề "--- Summary Statistics for Sales and Quantity ---"
2. Hiển thị bảng hiệu suất sản phẩm với tiêu đề "--- Performance by Product ---"
3. Hiển thị bảng hiệu suất khu vực với tiêu đề "--- Performance by Region ---"
4. Hiển thị kết quả phát hiện giá trị ngoại lệ với tiêu đề "--- Outlier Detection (IQR Method) ---"
5. Cung cấp phân tích toàn diện với:
  - Load dữ liệu và kiểm tra chất lượng
  - Thông tin chi tiết quan trọng (danh sách đánh số)
  - Các khuyến nghị có thể thực hiện (danh sách đánh số)

Thực thi code Python để phân tích nhưng KHÔNG hiển thị mã nguồn - chỉ hiển thị kết quả và thông tin chi tiết đã được định dạng.

Sử dụng pandas để phân tích và trình bày tất cả các bảng dưới dạng DataFrame gọn gàng. 
""" 

    # Gửi yêu cầu tới Gemini
    response = self.model.generate_content(prompt) 
 
    # In kết quả
    print(response.text) 
 
    return response.text 

Lưu ý: Phương thức này là một phần của lớp DataAnalysisAgent, vì vậy nó được thụt lề hai khoảng trắng bên dưới định nghĩa lớp.

Định nghĩa agent hoàn chỉnh của bạn hiện đã sẵn sàng. Phương thức `analyze_data()` thực hiện như sau:

• Đọc nội dung file CSV từ thư mục cục bộ của bạn
• Tạo một prompt chi tiết cho Gemini biết chính xác phân tích nào cần thực hiện và cách định dạng kết quả
• Gửi yêu cầu đến Gemini cùng với dữ liệu
• Trả về kết quả phân tích đã được định dạng

Giờ đây, agent đã có mọi thứ cần thiết: Cấu hình, hướng dẫn hệ thống, quyền truy cập công cụ và phương pháp phân tích.

Bước 6: Tạo hàm thực thi chính

Bây giờ, chúng ta hãy tạo hàm chính sẽ chạy agent. Thêm đoạn code này vào cuối file agent.py của bạn (bên ngoài lớp, không thụt lề):

def main():  
  """Chức năng thực thi chính."""  
  print("\nGEMINI 3 DATA ANALYSIS AGENT (Production)\n") 

  # Khởi tạo agent  
  agent = DataAnalysisAgent('agent_config.json') 

  # Chạy phân tích
  agent.analyze_data('sales.csv') 

if __name__ == "__main__":  
  main() 

Hàm này thực hiện 3 việc:

• In tiêu đề để hiển thị agent đang khởi động.
• Tạo một thể hiện agent bằng cách load file cấu hình mà chúng ta đã tạo trước đó.
• Gọi hàm analyze_data() với đường dẫn đến file CSV của chúng ta.

Bước 7: Cải thiện và gỡ lỗi agent

Điều gì xảy ra khi thiếu API key, file CSV không tồn tại hoặc dữ liệu gặp sự cố bất ngờ? Nếu không có cơ chế xử lý lỗi, agent của bạn sẽ bị sập với các thông báo khó hiểu. Hãy làm cho nó mạnh mẽ hơn.

Hãy wrap hàm main() của bạn bằng phần xử lý lỗi thích hợp:

def main():  
  """Chức năng thực thi chính."""  
  print("\nGEMINI 3 DATA ANALYSIS AGENT (Production)\n") 

  # Kiểm tra API key 
  api_key = os.getenv('GEMINI_API_KEY')  
  if not api_key:  
    print("ERROR: GEMINI_API_KEY environment variable not set.")  
    print("\nTo use this agent:")  
    print("1. Get your API key from: https://ai.google.dev/")  
    print("2. Set it as environment variable:")  
    print(" export GEMINI_API_KEY='your-api-key-here'")  
    return 

  try:  
    # Khởi tạo agent  
    agent = DataAnalysisAgent('agent_config.json') 

    # Chạy phân tích 
    agent.analyze_data('sales.csv') 
  
  except FileNotFoundError as e:  
    print(f"Error: File not found - {str(e)}")  
    print("Make sure sales.csv and agent_config.json exist in the current directory") 

  except Exception as e:  
    print(f"Error: {str(e)}")  
    print("\nMake sure:")  
    print("1. You have installed: pip install google-generativeai")  
    print("2. Your API key is valid")  
    print("3. All required files exist in the current directory") 

if __name__ == "__main__":  
  main() 

Và thế là xong, mọi thứ đã được thiết lập đúng cách!

Bước 8: Kiểm tra agent

Bây giờ, hãy chạy agent và xem liệu nó có cung cấp cho chúng ta những thông tin chi tiết cần thiết hay không. Chạy agent từ cửa sổ dòng lệnh:

python agent.py 

Nếu mọi thứ được thiết lập đúng cách, bạn sẽ thấy kết quả như sau:

GEMINI 3 DATA ANALYSIS AGENT (Production) 
Khởi tạo Gemini 3 Agent...  
Role: Data Analysis Agent  
Goal: Load file CSV, phân tích dữ liệu và tạo ra những thông tin chi tiết hữu ích
Tools: code_execution, file_read 

Phân tích: sales.csv  

--- Summary Statistics for Sales and Quantity --- 
             sales   quantity 
count    15.000000  15.000000 
mean   1288.666667  40.800000 
std     468.414753   8.993649 
min     750.000000  25.000000 
25%     890.000000  31.500000 
50%    1180.000000  44.000000 
75%    1600.000000  47.500000 
max    2100.000000  52.000000 
 
--- Performance by Product --- 
          total_sales  average_sales  total_quantity  average_quantity  transaction_count 
product 
Widget C         7950    1987.500000             198         49.500000                  4 
Widget A         7180    1196.666667             268         44.666667                  6 
Widget B         4200     840.000000             146         29.200000                  5 
 
--- Performance by Region --- 
        total_sales  average_sales  total_quantity  average_quantity  transaction_count 
region 
South          5130    1282.500000             161         40.250000                  4 
North          5050    1262.500000             163         40.750000                  4 
East           5000    1250.000000             160         40.000000                  4 
West           4150    1383.333333             128         42.666667                  3 
 
--- Outlier Detection (IQR Method) --- 
Không phát hiện thấy giá trị ngoại lệ nào đối với 'doanh số' hoặc 'số lượng' bằng phương pháp IQR. 
  

### Load dữ liệu và kiểm tra chất lượng

Dữ liệu CSV đã được load thành công vào DataFrame của pandas. Tập dữ liệu chứa 15 mục và 5 cột: date, product, sales, region và quantity. Tất cả các cột đều có kiểu dữ liệu chính xác, với sales và quantity là số nguyên, còn date, product, region là kiểu dữ liệu chuỗi ký tự. Không có giá trị thiếu trong bất kỳ cột nào, cho thấy chất lượng dữ liệu tốt.

### Những hiểu biết chính

1. **Sản phẩm C dẫn đầu về doanh số và số lượng bán ra trên mỗi giao dịch:** Sản phẩm C có tổng doanh số cao nhất (7950) và doanh số trung bình trên mỗi giao dịch cao nhất (1987,50), cũng như số lượng bán ra trung bình trên mỗi giao dịch cao nhất (49,50). Điều này cho thấy đây là sản phẩm có giá trị nhất.

2. **Sản phẩm B là sản phẩm có hiệu suất thấp nhất:** Sản phẩm B luôn có tổng doanh số thấp nhất (4200), doanh số trung bình thấp nhất (840,00) và số lượng bán trung bình thấp nhất (29,20) trong số tất cả các sản phẩm, cho thấy đây là sản phẩm có hiệu suất kém nhất.

3. **Sản phẩm A có số lượng giao dịch nhiều nhất:** Sản phẩm A ghi nhận số lượng giao dịch cao nhất (6), đóng góp đáng kể vào hoạt động chung, mặc dù doanh số và số lượng trung bình của nó ở mức vừa phải.

4. **Phân bổ doanh số khu vực cân bằng:** Tổng doanh số được phân bổ khá đều giữa các khu vực, với các khu vực phía Nam, phía Bắc và phía Đông cho thấy tổng doanh số tương tự nhau (khoảng 5000-5130). Khu vực phía Tây có tổng doanh số thấp hơn một chút nhưng cũng có ít giao dịch hơn.

5. **Khu vực phía Tây cho thấy doanh số trung bình trên mỗi giao dịch cao nhất:** Mặc dù có ít giao dịch nhất (3), khu vực phía Tây lại tự hào có doanh số trung bình trên mỗi giao dịch cao nhất (1383,33) và số lượng trung bình trên mỗi giao dịch cao nhất (42,67), cho thấy các giao dịch có giá trị cao.

6. **Không phát hiện thấy giá trị ngoại lệ:** Phân tích bằng phương pháp IQR không tìm thấy bất kỳ giá trị ngoại lệ đáng kể nào trong 'doanh số' hoặc 'số lượng', cho thấy mô hình bán hàng tương đối nhất quán trong giai đoạn quan sát.

### Các đề xuất khả thi

1. **Tận dụng thành công của Sản phẩm C:** Đầu tư nhiều hơn vào tiếp thị và sản xuất cho Sản phẩm C, tìm kiếm cơ hội mở rộng phạm vi thị trường hoặc giới thiệu các biến thể, dựa trên giá trị bán hàng cao và số lượng mỗi giao dịch lớn.

2. **Cải thiện hiệu suất của Sản phẩm B:** Điều tra các lý do đằng sau hiệu suất thấp hơn của Sản phẩm B. Điều này có thể bao gồm điều chỉnh giá, các chiến dịch tiếp thị, cải tiến sản phẩm hoặc kết hợp nó với các sản phẩm có hiệu suất cao hơn.

3. **Nhắm mục tiêu vào các khu vực có giá trị cao:** Phân tích các yếu tố góp phần vào giá trị giao dịch trung bình cao hơn ở khu vực phía Tây. Nhân rộng các chiến lược thành công từ khu vực phía Tây, nếu có, ở các khu vực khác để tăng doanh số bán hàng trung bình.

4. **Tối ưu hóa chiến lược khu vực dựa trên số lượng giao dịch:** Mặc dù tổng doanh số bán hàng tương tự nhau, nhưng số lượng giao dịch lại khác nhau. Đối với các khu vực có số lượng giao dịch cao (như Bắc, Nam, Đông), hãy tập trung vào việc tăng giá trị giao dịch trung bình. Đối với các khu vực có ít giao dịch hơn nhưng giá trị cao hơn (như Tây), hãy tập trung vào việc tăng tần suất giao dịch mà không làm giảm giá trị.

5. **Theo dõi hiệu suất ổn định của Sản phẩm A:** Sản phẩm A có số lượng giao dịch cao nhất. Đảm bảo nguồn cung ổn định và sự hài lòng của khách hàng để duy trì đóng góp ổn định của sản phẩm này vào doanh thu tổng thể. Cân nhắc bán chéo Sản phẩm C cho khách hàng của Sản phẩm A.

6. **Phân tích khu vực chuyên sâu hơn:** Mặc dù tổng doanh thu tương tự nhau, nhưng vẫn tồn tại những khác biệt nhỏ. Phân tích sâu hơn về nhân khẩu học khách hàng cụ thể, xu hướng thị trường địa phương hoặc bối cảnh cạnh tranh ở mỗi khu vực có thể giúp phát hiện ra các cơ hội hoặc thách thức tăng trưởng cục bộ.

Agent đã phân tích dữ liệu của bạn thành công. Dưới đây là những gì đã xảy ra:

• Công cụ đã load cấu hình của bạn và hiểu vai trò của nó như một nhà phân tích dữ liệu.
• Gemini đã đọc nội dung CSV và tự động lập kế hoạch các bước phân tích.
• Công cụ đã viết code Python để tính toán số liệu thống kê, nhóm dữ liệu theo sản phẩm và khu vực, và phát hiện các giá trị ngoại lệ.
• Gemini đã thực thi code trong môi trường sandbox an toàn và diễn giải kết quả.
• Công cụ đã tổng hợp các phát hiện thành những hiểu biết rõ ràng và các khuyến nghị kinh doanh.

Hãy thử với dữ liệu của riêng bạn. Thay thế sales.csv bằng bất kỳ file CSV nào chứa dữ liệu số, và công cụ sẽ điều chỉnh phân tích của nó cho phù hợp với cấu trúc dữ liệu của bạn. Bạn cũng có thể sửa đổi agent_config.json để thay đổi mục tiêu của công cụ và nhận được các loại thông tin chi tiết khác nhau.