Xây Dựng Agentic Sử Dụng Google ADK

Giới thiệu

Trong bài viết này, chúng ta sẽ tìm hiểu cách xây dựng một agent sử dụng Google Agent Development Kit (ADK) để truy vấn thông tin chứng khoán thông qua YFinance. Agent này sẽ cung cấp các thông tin như giá hiện tại, mức cao/thấp trong ngày và khuyến nghị đầu tư, sử dụng mô hình Gemini. Bài viết sẽ đi qua kiến trúc, cách thức cài đặt, cấu hình và cả những gợi ý để phát triển thêm cho dự án này.

Tại sao lại chọn dự án này?

• Giao diện người dùng thân thiện: Truy cập thông tin chứng khoán một cách tự nhiên và dễ hiểu.
• Tính ứng dụng cao: Kết hợp các mô hình Gemini với nguồn dữ liệu thực tế (Yahoo Finance qua YFinance).
• Học hỏi và phát triển: Cung cấp hướng dẫn về cách triển khai công cụ Python trong một agent với Google ADK.

Kiến trúc dự án

Dưới đây là kiến trúc tổng quan của agent mà chúng ta sẽ xây dựng:

• Agent: query_yfinance_agent với mô hình gemini-2.0-flash, được định nghĩa trong query-yfinance/agent.py.
• Công cụ: fetch_stock_info(ticker_symbol: str), sử dụng yfinance để lấy thông tin:
  • displayName (hoặc shortName)
  • currentPrice
  • dayLow
  • dayHigh
  • recommendationKey
• Orchestration: Google ADK kích hoạt mô hình và quyết định khi nào gọi công cụ dựa trên yêu cầu của người dùng.
• Cấu hình: Các biến được định nghĩa trong query-yfinance/.env (tự động tải bởi ADK).

Mã nguồn chính

Tệp query-yfinance/agent.py

• Công cụ truy vấn:
  • Nhận ticker_symbol (ví dụ: PETR4.SA, AAPL).
  • Sử dụng yfinance.Ticker(...).info để trả về một từ điển với các trường thông tin hữu ích.
• Agent ADK:
  • Định nghĩa name, model, description, và instruction.
  • Đăng ký công cụ với tools=[fetch_stock_info].

Yêu cầu hệ thống

• Python: Phiên bản >= 3.12.
• API Key Google Generative AI (đối với API công cộng): Biến GOOGLE_API_KEY.
• Tùy chọn: Vertex AI (với GOOGLE_GENAI_USE_VERTEXAI=TRUE + thông tin xác thực GCP).

Hướng dẫn cài đặt

Cài đặt với uv (khuyến nghị)

1. Cài đặt uv: Hướng dẫn cài đặt uv
2. Trong thư mục dự án, chạy uv sync.
3. Kích hoạt môi trường: source .venv/bin/activate.

Cài đặt với pip

1. Tạo và kích hoạt môi trường ảo: python3.12 -m venv .venv && source .venv/bin/activate
2. Cập nhật pip: pip install -U pip
3. Cài đặt dự án: pip install -e .

Các phụ thuộc chính được liệt kê trong pyproject.toml: google-adk và yfinance.

Cấu hình dự án

1. Sao chép mẫu biến: cp query-yfinance/.env-sample query-yfinance/.env
2. Chỉnh sửa query-yfinance/.env:
   • GOOGLE_API_KEY=... (khi không sử dụng Vertex)
   • GOOGLE_GENAI_USE_VERTEXAI=FALSE (hoặc TRUE + gcloud auth application-default login + xuất các biến GOOGLE_CLOUD_PROJECT và GOOGLE_CLOUD_REGION)

Lưu ý: ADK sẽ đọc tệp .env từ thư mục của agent; giữ tệp trong query-yfinance/.

Chạy chương trình (CLI)

1. Kích hoạt môi trường ảo.
2. Chạy lệnh adk run query-yfinance.
3. Một số ví dụ câu hỏi:
   • “Giá hiện tại của PETR4.SA là bao nhiêu?”
   • “Cho biết mức thấp và cao trong ngày của AAPL.”

Ví dụ về ticker:

• Brazil (B3): PETR4.SA, VALE3.SA (lưu ý đuôi .SA).
• USA: AAPL, GOOGL, MSFT.

Quy trình thực thi

1. Người dùng tương tác với agent qua terminal.
2. Mô hình Gemini phân tích câu hỏi và quyết định khi nào gọi fetch_stock_info với ticker.
3. Công cụ sử dụng YFinance và trả về các trường dữ liệu.
4. Agent tổng hợp câu trả lời tự nhiên với dữ liệu nhận được.

Xử lý lỗi và giới hạn

• Ticker không hợp lệ: YFinance có thể trả về dữ liệu không đầy đủ; agent vẫn sẽ phản hồi với tên/ticker đã cho.
• Thiếu trường dữ liệu: Không phải tất cả các tài sản đều có currentPrice/recommendationKey; mã đã xử lý trường hợp dict rỗng.
• Mạng/giới hạn: YFinance phụ thuộc vào Yahoo Finance và có thể tạm thời không phản hồi; hãy thử lại sau.
• Độ chính xác và độ trễ: Dữ liệu đến từ bên thứ ba và có thể có độ trễ; hãy xác minh trước khi đưa ra quyết định tài chính.

Cấu trúc thư mục dự án

• query-yfinance/agent.py: chứa agent và công cụ fetch_stock_info.
• query-yfinance/.env-sample: mẫu biến.
• README.md: hướng dẫn nhanh cho người dùng.
• pyproject.toml: chứa thông tin metadata và phụ thuộc.

Kết luận

Chỉ với một vài dòng mã và Google ADK, chúng ta đã tích hợp mô hình Gemini với một nguồn dữ liệu tài chính thực tế (YFinance), tạo ra một agent trò chuyện có khả năng trả lời các câu hỏi về thị trường. Phương pháp này có thể mở rộng: có thể thêm nhiều công cụ mới để phong phú hóa các phân tích, lịch sử và định dạng báo cáo.

Câu hỏi thường gặp (FAQ)

1. Làm thế nào để cài đặt Google ADK?
Bạn có thể cài đặt Google ADK qua pip bằng lệnh pip install google-adk.

2. Có cần thiết phải sử dụng Vertex AI không?
Vertex AI là tùy chọn, nhưng sẽ cung cấp thêm tính năng cho agent của bạn nếu bạn sử dụng nó.

3. Tại sao dữ liệu từ YFinance có thể không chính xác?
Dữ liệu từ YFinance phụ thuộc vào Yahoo Finance, vì vậy có thể có độ trễ hoặc không đầy đủ.

4. Làm thế nào để chạy agent sau khi cài đặt?
Sau khi cài đặt và cấu hình, bạn chỉ cần chạy lệnh adk run query-yfinance để khởi động agent.

Tài nguyên tham khảo

• Tài liệu Google ADK
• YFinance Documentation
• Hướng dẫn cài đặt Python Virtualenv