Mẫu tác nhân ADK có bộ nhớ và MCP

1. Kiến thức bạn sẽ học được

Chào mừng bạn đến với Lớp học nâng cao về ADK – Hành trình khám phá hệ thống đa tác nhân

Bạn sắp bước vào thế giới thú vị của các tác nhân AI. Hãy quên đi những chatbot đơn giản chỉ trả lời câu hỏi. Chúng tôi đang nghiên cứu kỹ lưỡng Agent Development Kit (ADK) để xây dựng các hệ thống tự động, tinh vi có thể suy luận, lập kế hoạch và sử dụng các công cụ để hoàn thành những nhiệm vụ phức tạp.

Toàn bộ lớp học lập trình này sẽ là một hành trình thực tế, đây là 1 Kho lưu trữ GitHub chứa tất cả mã và ví dụ cho các phiên của chúng ta. kho lưu trữ github

Sau khi hoàn thành hướng dẫn này, bạn sẽ có thể:

• Xây dựng tác nhân AI đầu tiên: Từ con số 0 đến một tác nhân có đầy đủ chức năng, có thể hiểu nhu cầu của người dùng, sử dụng các công cụ như Google Tìm kiếm và tạo ra những câu trả lời chi tiết, hữu ích.
• Xây dựng hệ thống nhiều tác nhân: Tìm hiểu mẫu "Tác nhân dưới dạng công cụ", một khái niệm mang tính cách mạng trong đó các tác nhân uỷ quyền nhiệm vụ cho các tác nhân chuyên biệt khác, tạo ra một nhóm chuyên gia AI làm việc cùng nhau.
• Điều phối quy trình công việc phức tạp: Vượt xa việc uỷ quyền đơn giản và nắm vững các mẫu nâng cao như Bộ định tuyến, Chuỗi tuần tự, Vòng lặp và Thực thi song song để xây dựng các ứng dụng mạnh mẽ, hiệu quả và thông minh có thể xử lý hầu hết mọi yêu cầu.
• Cung cấp bộ nhớ cho các tác nhân: Hiểu rõ vai trò quan trọng của bộ nhớ đàm thoại, cho phép các tác nhân xử lý các câu hỏi nối tiếp, học hỏi từ ý kiến phản hồi và quản lý các nhiệm vụ nhiều bước một cách liền mạch.
• Kết nối với MCP: Kết nối với hộp công cụ MCP.

Hãy bắt đầu! 🚀

2. Thiết lập: Lấy khoá API

Thiết lập khoá API Google AI Studio

Lớp học lập trình này hoàn toàn chạy trên một khoá API miễn phí của Google AI Studio. Không cần dự án, tài khoản thanh toán hoặc tín dụng trên Google Cloud – mọi phiên, bao gồm cả Bộ nhớ (Phiên 6) và MCP (Phiên 7), đều chạy cục bộ dựa trên khoá của bạn. Mỗi người học sử dụng khoá riêng, vì vậy, hạn mức API là theo từng người chứ không dùng chung.

Những thứ bạn cần:

• Python 3.9 trở lên (python3 --version để kiểm tra)
• Tài khoản Google (để tạo khoá AI Studio)
• Một thiết bị đầu cuối – máy cục bộ hoặc Cloud Shell đều hoạt động
• Khoảng 10 phút

Để hỗ trợ các AI tác nhân, chúng tôi cần một khoá Gemini API từ Google AI Studio. Đây là cách nhanh nhất để bắt đầu.

Bước 1 – Lấy khoá Gemini API từ AI Studio (1 phút)

1. Mở https://aistudio.google.com/app/apikey trong một thẻ trình duyệt mới.
2. Đăng nhập bằng Tài khoản Google của bạn.
3. Nhấp vào "Tạo khoá API" (ở trên cùng bên phải).
4. Một hộp thoại sẽ mở ra với một trình đơn thả xuống dự án:

• Nếu bạn đã tạo một dự án trên Google trước đó: Chọn dự án đó rồi nhấp vào "Tạo khoá API trong dự án hiện có"
• Nếu dự án KHÔNG có trong danh sách: Nhấp vào "Tạo dự án".

5. Sao chép khoá API xuất hiện. Tham số này bắt đầu bằng AIza... và có khoảng 40 ký tự.

✏️ Dán mã này vào một nơi an toàn – bạn sẽ cần mã này trong Bước 4 bên dưới.

Hãy coi khoá API như mật khẩu. Đừng dán khoá này vào các cuộc trò chuyện công khai, ảnh chụp màn hình hoặc cam kết với một kho lưu trữ GitHub công khai.

Bước 2 — Sao chép kho lưu trữ (1 phút)

👉💻 Mở cửa sổ dòng lệnh (hoặc Cloud Shell) rồi sao chép kho lưu trữ hướng dẫn:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

Bước 3 – Tạo môi trường ảo và cài đặt các phần phụ thuộc

👉💻 Tạo và kích hoạt một môi trường ảo có tên là .adk_env, sau đó cài đặt các phần phụ thuộc:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Bạn sẽ thấy (.adk_env) ở đầu dấu nhắc của thiết bị đầu cuối.

Bước 4 – 🔥 QUAN TRỌNG: Thêm khoá API

⚠️ Đừng bỏ qua bước này! Tạo tệp .env trong thư mục gốc của thư mục adk_tutorial. Tệp này hỗ trợ mọi phiên trong lớp học lập trình này – các phiên ADK Web (1–5) và các phiên Bộ nhớ và MCP trên dòng lệnh (6–7) đều tự động đọc tệp này.

👉💻 Tạo tệp .env bằng khoá của bạn (thay thế your_actual_api_key_here bằng khoá ở Bước 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

~/adk_tutorial/.env của bạn hiện phải chứa:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 CRITICAL: Thay thế your_actual_api_key_here bằng khoá API thực tế của bạn trong Bước 1 (khoá này bắt đầu bằng AIza...).

⚠️ Đảm bảo bạn đã đặt GOOGLE_GENAI_USE_VERTEXAI thành FALSE. Thao tác này hướng dẫn ADK xác thực bằng khoá API Google AI Studio thay vì Vertex AI.

✅ Điểm kiểm tra: Bạn có một tệp .env tại ~/adk_tutorial/.env chứa khoá AIza... và lời nhắc trên thiết bị đầu cuối của bạn cho thấy (.adk_env). Bạn đã sẵn sàng tạo tác nhân!

3. Phiên 1: Tác nhân đầu tiên của bạn trong ADK Web

Mở ADK Web bằng cách chạy:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

Sau khi chạy các lệnh, bạn sẽ thấy đầu ra trong thiết bị đầu cuối cho biết Máy chủ web ADK đã khởi động, tương tự như sau:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 Tiếp theo, hãy mở trình duyệt để truy cập vào http://localhost:8000 nhằm truy cập vào Giao diện người dùng dành cho nhà phát triển ADK.

Bạn đang chạy trong Cloud Shell thay vì chạy cục bộ? Nhấp vào biểu tượng Xem trước trên web trong thanh công cụ Cloud Shell (thường ở trên cùng bên phải), chọn Thay đổi cổng, đặt cổng thành 8000 rồi nhấp vào "Thay đổi và xem trước". Cloud Shell sẽ mở giao diện người dùng ADK Dev trong một thẻ trình duyệt mới.

👉 Nghi thức triệu hồi của bạn đã hoàn tất và tác nhân hiện đang chạy. Giao diện người dùng dành cho nhà phát triển ADK trong trình duyệt là kết nối trực tiếp của bạn với Familiar.

chọn tác nhân đầu tiên Trong trình đơn thả xuống ở đầu giao diện người dùng, hãy chọn a_single_agent.

Bạn có thể chọn a_single_agent tại đây:

Bạn có thể xem thông tin theo dõi tại đây:

👉 Câu lệnh thử nghiệm:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. Phiên 2: Tác nhân quy trình công việc: Tác nhân tuần tự, Tác nhân song song, Tác nhân vòng lặp

Mở giao diện người dùng web ADK theo các bước trong phiên 1.

Tác nhân song song

chọn tác nhân quy trình song song Trong trình đơn thả xuống ở đầu giao diện người dùng, hãy chọn b2_parallel_agent.

👉 Câu lệnh thử nghiệm:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

Bạn có thể chọn b2_parallel_agent tại đây:

Bạn có thể xem thông tin theo dõi tại đây:

Tác nhân tuần tự

chọn tác nhân quy trình làm việc tuần tự Trong trình đơn thả xuống ở đầu giao diện người dùng, hãy chọn b1_sequential_agent.

👉 Câu lệnh thử nghiệm:

Find a good sushi near Standford and tell me how to get there.

Bạn có thể chọn b1_sequential_agent tại đây:

Bạn có thể xem thông tin theo dõi tại đây:

Tác nhân Loop

chọn tác nhân quy trình làm việc lặp lại Trong trình đơn thả xuống ở đầu giao diện người dùng, hãy chọn b3_loop_agent.

👉 Câu lệnh thử nghiệm:

Plan a trip from Sunnyvale to San Francisco today.

Bạn có thể chọn b3_loop_agent tại đây:

Bạn có thể xem thông tin theo dõi tại đây:

5. Phiên 3: Nhân viên hỗ trợ tuỳ chỉnh

Mở giao diện người dùng web ADK theo các bước trong phiên 1.

Sau khi giao diện người dùng web ADK mở ra, hãy chọn c_custom_agent trong trình đơn thả xuống.

👉 Câu lệnh thử nghiệm:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

Bạn có thể chọn c_custom_agent tại đây:

Bạn có thể xem thông tin theo dõi tại đây:

6. Phiên 4: Mẫu điều phối – Tác nhân định tuyến

Mở giao diện người dùng web ADK theo các bước trong phiên 1.

Sau khi giao diện người dùng web ADK mở ra, hãy chọn d_routing_agent trong trình đơn thả xuống.

👉 Câu lệnh thử nghiệm:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Bạn có thể chọn d_routing_agent tại đây:

Bạn có thể xem thông tin theo dõi tại đây:

7. Phiên 5: Tác nhân dưới dạng công cụ

Mở giao diện người dùng web ADK theo các bước trong phiên 1.

Sau khi giao diện người dùng web ADK mở ra, hãy chọn e_agent_as_tool trong trình đơn thả xuống.

👉 Câu lệnh thử nghiệm:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Bạn có thể chọn e_agent_as_tool tại đây:

Bạn có thể xem thông tin theo dõi tại đây:

8. Phiên 6: Tác nhân có bộ nhớ dài hạn

Chạy hoàn toàn trên thiết bị. Phiên này lưu trữ bộ nhớ cuộc trò chuyện trong cơ sở dữ liệu SQLite cục bộ (trong ~/.adk/), vì vậy, các lựa chọn ưu tiên của bạn sẽ được duy trì khi khởi động lại mà không cần Google Cloud, thông tin thanh toán hoặc tín dụng. Tác nhân sẽ đọc khoá AI Studio của bạn từ ~/adk_tutorial/.env mà bạn đã tạo trong phần Thiết lập.

👉💻 Kiểm tra trí nhớ dài hạn bằng cách chuyển đến thư mục và sử dụng trình chạy để tăng sức mạnh cho tác nhân:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Câu lệnh thử nghiệm:

I like Art and Italian food.

Sau đó, kết thúc phiên bằng cách nhấn tổ hợp phím Ctrl+C. Khởi động lại phiên:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Câu lệnh thử nghiệm:

Plan a trip to San Francisco based on my preference.

✅ Trợ lý ảo phải nhớ được "Nghệ thuật và ẩm thực Ý" từ lần trò chuyện trước đó – đó là bộ nhớ dài hạn hoạt động trên các phiên.

9. Phiên 7: Trang bị cho nhân viên hỗ trợ của bạn bằng MCP

Chạy hoàn toàn trên thiết bị. Phiên này sẽ khởi động một máy chủ Bộ công cụ MCP cục bộ để đọc cơ sở dữ liệu SQLite cục bộ (destinations.db) – không cần Google Cloud, thông tin thanh toán hoặc tín dụng. Tệp nhị phân duy nhất có thể tải xuống bên ngoài là tệp nhị phân nguồn mở của Hộp công cụ MCP.

Bước 1: Chuẩn bị cơ sở dữ liệu cục bộ

👉💻 Từ thư mục gốc của kho lưu trữ, hãy tạo cơ sở dữ liệu mẫu:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

Thao tác này sẽ tạo destinations.db trong ~/adk_tutorial/.

⚠️ Cơ sở dữ liệu mẫu chỉ chứa 4 thành phố: Paris, Rome, New York và Tokyo (các loại địa điểm tham quan: Địa danh, Bảo tàng, Công viên). Những câu lệnh tham chiếu đến các thành phố khác (ví dụ: San Francisco hoặc Sunnyvale) sẽ trả về chính xác không có kết quả, vì những hàng đó không tồn tại. Hãy sử dụng 4 thành phố ở trên khi kiểm thử phiên này.

Bước 2: Cài đặt và chạy MCP Toolbox Server

👉💻 Tải tệp nhị phân MCP Toolbox xuống cho hệ điều hành của bạn:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

sau khi tải xuống xong, rồi chạy

chmod +x toolbox

Bạn không biết chắc mình đang dùng máy Mac nào? Chạy uname -m – arm64 = Apple Silicon, x86_64 = Intel. Trên Windows, hãy tải .../windows/amd64/toolbox.exe xuống rồi chạy từ PowerShell.

Bước 3

Trong một dòng lệnh Chạy lệnh sau (để lệnh này chạy – tác nhân sẽ kết nối với lệnh này tại http://127.0.0.1:7001):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

Trong một cửa sổ dòng lệnh khác Chạy lệnh sau

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Câu lệnh kiểm thử (sử dụng các thành phố có trong cơ sở dữ liệu mẫu – Paris, Rome, New York hoặc Tokyo):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

Khắc phục sự cố trong phiên 7

• "Connection refused" (Kết nối bị từ chối) / nhân viên hỗ trợ không tìm thấy công cụ nào: máy chủ Toolbox trong thiết bị đầu cuối đầu tiên không chạy – hãy khởi động lại và xác nhận rằng máy chủ đang nghe trên cổng 7001.
• Mọi truy vấn đều trả về kết quả trống: xác nhận rằng bạn đã chạy Bước 1 để ~/adk_tutorial/destinations.db tồn tại và câu lệnh của bạn sử dụng một trong bốn thành phố (Paris, Rome, New York, Tokyo).
• toolbox: cannot execute binary file trên macOS: bạn đã tải bản dựng Linux xuống – chạy lại Bước 2 bằng OS=darwin/arm64 (Apple Silicon) hoặc OS=darwin/amd64 (Intel).