Xây dựng các tác nhân AI bằng ADK: Nền tảng

1. Tổng quan

Tác nhân AI kết hợp mô hình ngôn ngữ lớn (LLM) với các chỉ dẫn, trạng thái và công cụ để có thể suy luận về yêu cầu của người dùng và tự động thực hiện các nhiệm vụ gồm nhiều bước. Nếu không có khung tác nhân có cấu trúc, nhà phát triển phải tự kết nối ứng dụng khách của mô hình, cấu hình môi trường, phiên trò chuyện và giao diện gỡ lỗi cục bộ trước khi thử nghiệm một câu lệnh.

Trong phần đầu tiên của loạt bài Xây dựng tác nhân AI bằng ADK, bạn sẽ thiết lập một môi trường phát triển Python trên Google Cloud và tạo một tác nhân personal_assistant trên Nền tảng tác nhân bằng Bộ công cụ phát triển tác nhân (ADK 2) và gemini-3.8-flash. Bạn khám phá gói tác nhân được tạo và kiểm thử tác nhân thông qua cả CLI dòng lệnh tương tác (adk run) và Giao diện người dùng web ADK dựa trên trình duyệt (adk web). Bạn cũng có thể mở trực tiếp lớp học lập trình này tại goo.gle/adk-foundation.

Chuỗi bài học về cách xây dựng tác nhân AI bằng ADK: Sau khi hoàn thành bài thực hành cơ bản này, hãy tiếp tục với bài Cung cấp các công cụ, Điều phối quy trình công việc của tác nhân và Điều phối quy trình công việc dạng biểu đồ.

Điều kiện tiên quyết

• Hiểu rõ các khái niệm về AI tạo sinh
• Thành thạo cơ bản về lập trình Python
• Quen thuộc với dòng lệnh/thiết bị đầu cuối và gcloud CLI

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

• Cách định cấu hình Google Cloud Shell và môi trường Python 3.12 tách biệt bằng uv
• Cách tạo một gói tác nhân ADK 2 khởi đầu dựa trên gemini-3.8-flash trên Nền tảng tác nhân
• Cách ADK 2 sắp xếp mã tác nhân trên agent.py, __init__.py và .env
• Cách chạy, kiểm thử và kiểm tra các sự kiện, dấu vết và phiên dựa trên SQLite trong adk run và adk web

Bạn cần có

• Tài khoản Google (sử dụng tài khoản @gmail.com cá nhân nếu bạn muốn nhận tín dụng cho hội thảo)
• Đường liên kết nhận tín dụng cho hội thảo do người hướng dẫn cung cấp (cùng với camera điện thoại để quét mã QR) hoặc một tài khoản thanh toán trên Cloud đang hoạt động
• Google Chrome (bạn nên dùng cửa sổ ẩn danh để tránh nhầm lẫn giữa tài khoản cá nhân và tài khoản công việc)

Mẹo về chế độ ẩn danh: Hãy mở lớp học lập trình này trong cửa sổ ẩn danh để mọi đường liên kết đến Cloud Console và Cloud Shell đều mở trong cùng một phiên.

2. Nhận khoản tín dụng Google Cloud (Không bắt buộc)

Nếu bạn đang tham dự một hội thảo có đường liên kết nhận tín dụng cho sự kiện, hãy nhận tín dụng Google Developer Program để cấp tài khoản thanh toán mà không cần thẻ tín dụng.

Bạn đang sử dụng tài khoản thanh toán của riêng mình? Chuyển đến phần Tạo dự án trên Google Cloud (Không bắt buộc) (hoặc Thiết lập môi trường nếu bạn đã có dự án). Nếu bạn cần một tài khoản thanh toán mới không có khoản tín dụng cho sự kiện, hãy xem bài viết Tạo tài khoản thanh toán trên Cloud hoặc Dùng thử Google Cloud miễn phí.

Nhận khoản tín dụng cho sự kiện

⚠️ Sử dụng Tài khoản Gmail cá nhân: Tài khoản Google Workspace của công ty hoặc trường học không thể nhận tín dụng cho sự kiện hội thảo.

1. Mở đường liên kết nhận tín dụng hội thảo trong cửa sổ Ẩn danh rồi đăng nhập bằng tài khoản @gmail.com của bạn.
2. Nhấp vào Nhận tín dụng trên trang Nhận lợi ích:

3. Nếu được nhắc tạo hồ sơ Google Developer Program, hãy hoàn tất biểu mẫu.
4. Khi thông báo Quét để xác minh bạn là người thật xuất hiện, hãy quét mã QR bằng điện thoại và hoàn tất quy trình xác minh (làm mới và nhấp lại vào Nhận tín dụng nếu mã QR không xuất hiện):

5. Xác nhận thông báo Đã nhận thành công khoản tín dụng cho sự kiện! xuất hiện, sau đó nhấp vào Mở tài khoản thanh toán:

🔍 Kiểm tra bài làm

Quá trình thiết lập tài khoản thanh toán mất tối đa 3 phút:

1. Mở Google Cloud Billing (hoặc sao chép URL vào cửa sổ ẩn danh) rồi chọn Tài khoản thanh toán của bạn:

https://console.cloud.google.com/billing

2. Làm mới cho đến khi tài khoản GDP Credit của bạn có trạng thái Đang hoạt động:

3. Tạo một dự án trên Google Cloud (Không bắt buộc)

Tạo một dự án Google Cloud chuyên biệt để tất cả tài nguyên trong lớp học lập trình này được tách biệt và dễ dọn dẹp.

Bạn đã có dự án? Nếu bạn đã có một dự án đã bật tính năng thanh toán hoặc một dự án hội thảo được cấp phép trước, hãy chuyển sang phần Thiết lập môi trường.

1. Mở trang Tạo dự án (hoặc sao chép URL vào cửa sổ ẩn danh):

https://console.cloud.google.com/projectcreate

2. Nhập thông tin chi tiết về dự án:
   • Tên dự án: Ví dụ: google-cloud-workshop
   • Tài khoản thanh toán (nếu có): Chọn GDP Credit (hoặc tài khoản thanh toán đang hoạt động của bạn)
   • Tài nguyên gốc: Không có tổ chức (hoặc tổ chức của bạn nếu cần)
3. Ghi lại Mã dự án được tạo bên dưới tên dự án, sau đó nhấp vào Tạo:

🔍 Kiểm tra bài làm

Nhấp vào Notifications (Thông báo) trong thanh công cụ trên cùng bên phải rồi nhấp vào Select Project (Chọn dự án) sau khi tạo xong dự án:

4. Thiết lập môi trường

Định cấu hình Google Cloud Shell, bật Agent Platform API và tạo một môi trường ảo Python 3.12 tách biệt bằng uv.

Mẹo về thiết bị đầu cuối cục bộ: Bạn đang chạy trên máy cục bộ thay vì Cloud Shell? Chạy gcloud auth application-default login một lần, thay thế các lệnh cloudshell edit filename bằng trình chỉnh sửa bạn muốn (ví dụ: code hoặc nano) và mở http://localhost:8000 ngay trong trình duyệt.

Định cấu hình Cloud Shell

1. Nhấp vào Activate Cloud Shell (Kích hoạt Cloud Shell) (>_) trên thanh công cụ của Google Cloud Console hoặc mở trực tiếp Google Cloud Shell (hoặc sao chép URL vào cửa sổ ẩn danh):

https://shell.cloud.google.com/?show=ide,terminal

2. Nhấp vào Authorize (Uỷ quyền) nếu được nhắc:

3. Chọn Mã dự án Google Cloud đang hoạt động trong trình đơn được đánh số trong dòng lệnh:

unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
  [ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done

Bạn sẽ thấy kết quả tương tự như sau (các dự án chưa được gắn thẻ cũng in một dòng thông tin [environment: untagged]):

1) google-cloud-workshop-4210
2) my-cloud-project-8812
Select your project (e.g. 1): 1
Updated property [core/project].

Xác minh rằng Mã dự án bạn chọn xuất hiện được đánh dấu bằng màu vàng trong lời nhắc của Cloud Shell:

Bật các API bắt buộc

Bật Agent Platform API để tác nhân ADK có thể gọi các mô hình Gemini:

gcloud services enable aiplatform.googleapis.com

Bạn sẽ thấy kết quả tương tự như sau:

Operation "operations/acat.p2-..." finished successfully.

Tạo môi trường ảo Python và cài đặt ADK

Tại sao uv? Được viết bằng Rust, uv tạo môi trường Python và cài đặt các gói chỉ trong vài giây. Tìm hiểu thêm trong tài liệu về uv.

Tạo thư mục không gian làm việc ~/ai-agents-adk và kích hoạt môi trường ảo Python 3.12:

cd ~
mkdir -p ai-agents-adk && cd ~/ai-agents-adk

which uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

uv venv .venv --python 3.12
source .venv/bin/activate

Xác nhận tiền tố (.venv) xuất hiện ở đầu lời nhắc của thiết bị đầu cuối:

Cài đặt ADK trong môi trường ảo đang hoạt động:

uv pip install --no-cache "google-adk==2.14.0"

🔍 Kiểm tra bài làm

Xác minh phiên bản adk CLI đã cài đặt:

adk --version

Bạn sẽ thấy kết quả tương tự như sau:

adk, version 2.14.0

Mẹo khôi phục phiên: Nếu sau này thẻ Cloud Shell của bạn bị ngắt kết nối, hãy quay lại không gian làm việc và kích hoạt lại môi trường bằng cd ~/ai-agents-adk && source .venv/bin/activate.

5. Tạo khung cho tác nhân

Tạo gói tác nhân personal_assistant khởi đầu bằng adk create. ADK tạo 4 tệp bên trong personal_assistant/:

• agent.py: Xác định root_agent bằng mô hình, tên, nội dung mô tả và chỉ dẫn hệ thống.
• __init__.py: Đánh dấu personal_assistant là một gói Python để ADK có thể khám phá và nhập agent.py.
• .env: Lưu trữ cờ phụ trợ (GOOGLE_GENAI_USE_ENTERPRISE=1), mã dự án và vị trí (global).
• .gitignore: Loại trừ các tệp phiên SQLite .env và .adk/ cục bộ khỏi hệ thống quản lý phiên bản.

Chạy adk create

Tạo khung cho gói personal_assistant từ ~/ai-agents-adk:

cd ~/ai-agents-adk
adk create personal_assistant

Chọn các tuỳ chọn sau khi được nhắc (nếu được nhắc bằng Enable telemetry? [Y/n]: trong lần chạy đầu tiên, hãy nhấn phím Enter hoặc nhập n rồi nhấn phím Enter):

1. Chọn một mô hình cho tác nhân gốc: Nhập 2 để chọn gemini-3.8-flash (lựa chọn 1 chọn gemini-3.5-flash) rồi nhấn phím Enter.
2. Chọn một phần phụ trợ: Nhập 2 để chọn phần phụ trợ Nền tảng tác nhân của Google Cloud (mục 2 trong trình đơn CLI bên dưới) rồi nhấn phím Enter.
3. Nhập mã dự án trên đám mây của Google: Nhấn phím Enter để chấp nhận Mã dự án được phát hiện trong dấu ngoặc (hoặc nhập Mã dự án nếu khác).
4. Nhập khu vực Google Cloud: Nhập global (bắt buộc để phân phát gemini-3.8-flash trên Nền tảng tác nhân) rồi nhấn phím Enter.

🔍 Kiểm tra bài làm

Bạn sẽ thấy kết quả tương tự như sau:

Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2
1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [google-cloud-workshop-4210]:
Enter Google Cloud region [us-central1]: global

Agent created in /home/your_username/ai-agents-adk/personal_assistant:
- .env
- .gitignore
- __init__.py
- agent.py

⚠️  WARNING: Secrets (like GOOGLE_API_KEY) are stored in .env.

Next steps:
- Chat with your agent in the terminal: adk run personal_assistant
- Or in the browser: adk web .
- Have your coding agent evaluate and deploy it: uvx google-agents-cli setup
  (other install options: https://adk.dev/get-started/agents-cli/)

6. Khám phá mã đã tạo

Mở ~/ai-agents-adk trong Trình chỉnh sửa Cloud Shell để có thể kiểm tra các tệp được tạo cùng với dòng lệnh:

which cloudshell >/dev/null 2>&1 && cloudshell workspace ~/ai-agents-adk || true

Lưu ý về việc khởi động lại Terminal: Việc chạy cloudshell workspace sẽ tải lại cửa sổ Cloud Shell và khởi động lại shell của bạn. Kích hoạt lại .venv sau khi ngăn dòng lệnh tải lại.

Kích hoạt lại môi trường ảo trong thiết bị đầu cuối đã tải lại:

cd ~/ai-agents-adk
source .venv/bin/activate

Bạn cũng có thể mở không gian làm việc theo cách thủ công trong Trình chỉnh sửa Cloud Shell bằng cách nhấp vào biểu tượng Trình khám phá (hoặc File > Open Folder... (Tệp > Mở thư mục...)) rồi chọn ai-agents-adk:

Theo mặc định, các tệp có dấu chấm như .env sẽ bị ẩn trong cây Explorer. Nhấp vào View > Toggle Hidden Files (Xem > Chuyển đổi tệp ẩn) trong thanh trình đơn trên cùng để hiện personal_assistant/.env:

Đánh giá agent.py

Mở ~/ai-agents-adk/personal_assistant/agent.py trong Trình chỉnh sửa Cloud Shell:

cloudshell edit ~/ai-agents-adk/personal_assistant/agent.py

Kiểm tra tệp được tạo tự động (không cần chỉnh sửa):

from google.adk.agents.llm_agent import Agent

root_agent = Agent(
    model='gemini-3.8-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

• from google.adk.agents.llm_agent import Agent: Nhập lớp Agent của ADK (bí danh của LlmAgent; ADK 2 cũng hiển thị from google.adk import Agent dưới dạng viết tắt cấp cao nhất khi viết mã tuỳ chỉnh).
• model='gemini-3.8-flash': Chọn gemini-3.8-flash làm mô hình hỗ trợ khả năng suy luận và trả lời.
• name='root_agent': Chỉ định giá trị nhận dạng mà ADK sử dụng trong nhật ký, dấu vết và biểu đồ đa tác nhân.
• description='...': Tóm tắt những việc tác nhân thực hiện khi một điều phối viên chính quyết định có uỷ quyền cho tác nhân đó hay không.
• instruction='...': Đặt câu lệnh hệ thống chi phối giọng điệu và hành vi của tác nhân.

Xem __init__.py và .env

Mở personal_assistant/__init__.py để xác nhận rằng tệp này xuất lại agent để adk run và adk web có thể khám phá root_agent:

from . import agent as agent

Mở personal_assistant/.env để kiểm tra cấu hình thời gian chạy:

GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=google-cloud-workshop-4210
GOOGLE_CLOUD_LOCATION=global

• GOOGLE_GENAI_USE_ENTERPRISE=1: Định tuyến các lệnh gọi mô hình ADK thông qua Nền tảng tác nhân bằng thông tin đăng nhập Google Cloud của bạn thay vì khoá API.
• GOOGLE_CLOUD_PROJECT: Liên kết các yêu cầu về mô hình và thông tin thanh toán với dự án trên đám mây của bạn trên Google Cloud.
• GOOGLE_CLOUD_LOCATION=global: Nhắm đến điểm cuối chung nơi gemini-3.8-flash được phân phát.

🔍 Kiểm tra bài làm

Xác minh từ thiết bị đầu cuối rằng personal_assistant/agent.py nhập sạch và .env trỏ đến global:

cd ~/ai-agents-adk && source .venv/bin/activate
python3 -c "from personal_assistant.agent import root_agent; print(root_agent.name, root_agent.model)"
cat ~/ai-agents-adk/personal_assistant/.env

Bạn sẽ thấy kết quả tương tự như sau:

root_agent gemini-3.8-flash
GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=google-cloud-workshop-4210
GOOGLE_CLOUD_LOCATION=global

7. Chạy tác nhân trong dòng lệnh

Kiểm thử trực tiếp tác nhân personal_assistant của bạn từ dòng lệnh bằng adk run:

cd ~/ai-agents-adk && source .venv/bin/activate
adk run personal_assistant

Tại câu lệnh [user]:, hãy gửi một thông báo như hello. What can you do for me? và xác minh rằng tác nhân có phản hồi.

🔍 Kiểm tra bài làm

Bạn sẽ thấy kết quả tương tự như sau:

Running agent root_agent, type exit to exit.
[user]: hello. What can you do for me?
[root_agent]: Hello! I can help answer questions, explain concepts, summarize text, brainstorm ideas, and assist with writing or coding tasks. How can I help you today?
[user]: exit

Nhập exit rồi nhấn Enter để đóng phiên CLI tương tác và quay lại lời nhắc shell trước khi tiếp tục.

Khắc phục sự cố

• This API method requires billing to be enabled: Xác nhận GOOGLE_CLOUD_PROJECT trong personal_assistant/.env khớp với dự án đang hoạt động của bạn, sau đó mở Tài khoản thanh toán được liên kết (hoặc sao chép URL bên dưới vào cửa sổ ẩn danh) rồi liên kết GDP Credit hoặc Tài khoản thanh toán Cloud đang hoạt động của bạn:

https://console.cloud.google.com/billing/linkedaccount

• API has not been used in project: Bật Agent Platform API trong dòng lệnh rồi thử lại sau vài giây:

gcloud services enable aiplatform.googleapis.com

8. Chạy tác nhân trong Giao diện người dùng web của ADK

Bạn có thể dễ dàng kiểm tra các phản hồi Markdown, tải trọng sự kiện và trạng thái nhiều lượt trong sân chơi trình duyệt tích hợp sẵn của ADK 2. Khởi động Giao diện người dùng web của ADK từ thư mục mẹ ~/ai-agents-adk (trên personal_assistant/):

cd ~/ai-agents-adk && source .venv/bin/activate
adk web --allow_origins "*"

Tại sao --allow_origins "*"? Việc truyền --allow_origins "*" cho phép các yêu cầu được gửi qua proxy thông qua miền Xem trước trên web của Cloud Shell (*.cloudshell.dev).

Mở Giao diện người dùng web của ADK trong trình duyệt:

1. Nhấp vào biểu tượng Xem trước trên web trong thanh công cụ Cloud Shell ở trên cùng bên phải rồi chọn Thay đổi cổng.
2. Nhập cổng 8000 rồi nhấp vào Change and Preview (Thay đổi và xem trước):

3. Xác nhận rằng personal_assistant được chọn trong trình đơn thả xuống của nhân viên hỗ trợ ở trên cùng bên trái, gửi "Hello. What can you do?" và nhấp vào sự kiện phản hồi của nhân viên hỗ trợ để kiểm tra siêu dữ liệu của sự kiện đó:

Giao diện người dùng web của ADK 2 kết hợp nút bật/tắt luồng Sự kiện và Dấu vết với các thẻ kiểm tra Thông tin, Trạng thái, Cấu phần phần mềm và Đánh giá (cộng với biểu tượng biểu đồ Cấu trúc tác nhân trong thanh công cụ trên cùng) và tự động duy trì các phiên cục bộ trong personal_assistant/.adk/session.db.

🔍 Kiểm tra bài làm

Trong cửa sổ dòng lệnh Cloud Shell, bạn sẽ thấy kết quả tương tự như sau:

INFO:     Started server process [4978]
INFO:     Waiting for application startup.
+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Khi bạn kiểm thử xong, hãy nhấn Ctrl + C trong thiết bị đầu cuối để dừng máy chủ adk web và quay lại dấu nhắc lệnh.

9. Dọn dẹp (Không bắt buộc)

⚠️ Tiếp tục bộ sách? Bỏ qua bước này nếu bạn tiếp tục chuyển sang phần Xây dựng tác nhân AI bằng ADK: Cung cấp các công cụ, phần này được xây dựng trực tiếp trên ~/ai-agents-adk/personal_assistant.

Lớp học lập trình này không tạo ra cơ sở hạ tầng có thể tính phí liên tục ngoài các lệnh gọi Gemini trả phí theo yêu cầu. Đảm bảo adk web đã dừng (Ctrl + C).

Xoá tệp không gian làm việc trên thiết bị

Cách xoá thư mục ~/ai-agents-adk khỏi Cloud Shell:

cd ~
rm -rf ~/ai-agents-adk

Xoá dự án chuyên dụng (Không bắt buộc)

⚠️ Hành động có tính huỷ diệt: Chỉ xoá dự án nếu bạn đã tạo một dự án dành riêng cho lớp học lập trình này và không tiếp tục chuỗi bài học. Tuyệt đối không xoá dự án hội thảo đã chia sẻ hoặc được cung cấp trước.

gcloud projects delete "$(gcloud config get-value project)" --quiet

10. Xin chúc mừng

Bạn đã thiết lập môi trường Python ADK 2 trên Google Cloud, tạo một tác nhân personal_assistant dựa trên gemini-3.8-flash trên Nền tảng tác nhân, khám phá cấu trúc gói được tạo và thử nghiệm tác nhân đó trong cả CLI của thiết bị đầu cuối và Giao diện người dùng web ADK.

Thành tích bạn đạt được

• Đã định cấu hình Google Cloud Shell, bật API Nền tảng tác nhân và tạo môi trường Python 3.12 bằng uv
• Tạo khung personal_assistant bằng adk create và khám phá cách agent.py, __init__.py và .env hoạt động cùng nhau
• Đã thử nghiệm các cuộc trò chuyện nhiều lượt qua adk run và kiểm tra các sự kiện, dấu vết cũng như phiên được SQLite hỗ trợ trong adk web

Các bước tiếp theo

• Tiếp tục đến Phần 2: Xây dựng tác nhân AI bằng ADK: Cung cấp các công cụ
• Tiếp tục chuyển sang Phần 3: Xây dựng tác nhân AI bằng ADK: Điều phối quy trình làm việc của tác nhân
• Tiếp tục đến Phần 4: Xây dựng tác nhân AI bằng ADK: Điều phối quy trình làm việc dạng đồ thị
• Khám phá tài liệu về Bộ công cụ phát triển tác nhân và chương trình học GEAR