1. Trước khi bắt đầu
Chào mừng bạn đến với phần đầu tiên của loạt video "Tạo các tác nhân AI bằng ADK"! Trong chuỗi lớp học lập trình thực hành này, bạn sẽ bắt đầu hành trình thú vị để tạo ra tác nhân AI thông minh của riêng mình bằng Bộ công cụ phát triển tác nhân (ADK) của Google.
Chúng ta sẽ bắt đầu với những điều cơ bản nhất, hướng dẫn bạn thiết lập môi trường phát triển và tạo một tác nhân đàm thoại cơ bản. Khi kết thúc lớp học lập trình này, bạn sẽ tạo được AI tương tác đầu tiên, sẵn sàng được mở rộng trong các phần tiếp theo của loạt bài này khi chúng ta chuyển đổi AI đó thành một Hệ thống đa tác nhân (MAS) tinh vi.
Bạn có thể hoàn tất lớp học lập trình này trong môi trường cục bộ hoặc trên Google Cloud. Để có trải nghiệm nhất quán nhất, bạn nên sử dụng Cloud Shell trong môi trường Google Cloud. Cloud Shell cũng cung cấp 5 GB bộ nhớ liên tục trong thư mục $HOME. Điều này hữu ích khi lưu trữ tập lệnh, tệp cấu hình hoặc kho lưu trữ được sao chép.
Bạn cũng có thể truy cập vào lớp học lập trình này thông qua URL rút gọn sau: goo.gle/adk-foundation.
Điều kiện tiên quyết
- Hiểu rõ về các khái niệm về AI tạo sinh
- Có kiến thức cơ bản về lập trình Python
- Quen thuộc với dòng lệnh / thiết bị đầu cuối
Kiến thức bạn sẽ học được
- Cách thiết lập môi trường Python
- Cách tạo một Trợ lý cá nhân đơn giản bằng ADK
- Cách chạy, kiểm thử và gỡ lỗi tác nhân
Bạn cần có
- Máy tính hoạt động và Wi-Fi đáng tin cậy
- Một trình duyệt, chẳng hạn như Chrome, để truy cập vào Google Cloud Console
- Có trí tò mò và ham học hỏi
2. Giới thiệu
Thế giới AI tạo sinh (GenAI) đang phát triển nhanh chóng và các AI Agent hiện là một chủ đề nóng. Tác nhân AI là một chương trình máy tính thông minh được thiết kế để hành động thay mặt cho bạn, giống như một trợ lý cá nhân. AI có thể nhận biết môi trường kỹ thuật số của chính nó, đưa ra quyết định và hành động để đạt được các mục tiêu cụ thể mà không cần sự kiểm soát trực tiếp của con người. Hãy coi đây là một thực thể chủ động, tự chủ, có thể học hỏi và thích ứng để hoàn thành công việc.
Về cơ bản, một tác nhân AI sử dụng mô hình ngôn ngữ lớn (LLM) làm "bộ não" để hiểu và suy luận. Nhờ đó, mô hình này có thể xử lý thông tin từ nhiều nguồn, chẳng hạn như văn bản, hình ảnh và âm thanh. Sau đó, tác nhân sẽ sử dụng thông tin này để lập kế hoạch và thực hiện một loạt nhiệm vụ nhằm đạt được mục tiêu đã xác định trước.
Giờ đây, bạn có thể dễ dàng tạo các tác nhân AI của riêng mình, ngay cả khi không có chuyên môn sâu, nhờ các khung sẵn sàng sử dụng như Bộ công cụ phát triển tác nhân (ADK). Chúng ta sẽ bắt đầu hành trình này bằng cách xây dựng một trợ lý cá nhân để giúp bạn hoàn thành các nhiệm vụ. Bắt đầu nào!
3. Định cấu hình các dịch vụ của Google Cloud
Tạo một dự án trên Google Cloud
Bắt đầu bằng cách tạo một dự án Google Cloud mới để các hoạt động trong lớp học lập trình này chỉ diễn ra trong dự án mới này.
- Truy cập vào console.cloud.google.com/projectcreate
- Nhập thông tin bắt buộc:
- Tên dự án – bạn có thể nhập tên bất kỳ mà bạn muốn (ví dụ: genai-workshop)
- Vị trí – giữ nguyên là Không có tổ chức
- Tài khoản thanh toán – Nếu bạn thấy lựa chọn này, hãy chọn Tài khoản thanh toán dùng thử Google Cloud Platform. Đừng lo lắng nếu bạn không thấy lựa chọn này. Hãy chuyển sang bước tiếp theo.
- Sao chép Mã dự án đã tạo, bạn sẽ cần mã này sau.
- Nếu mọi thứ đều ổn, hãy nhấp vào nút Tạo
Định cấu hình Cloud Shell
Sau khi tạo dự án thành công, hãy làm theo các bước sau để thiết lập Cloud Shell.
1. Chạy Cloud Shell
Truy cập vào shell.cloud.google.com và nếu bạn thấy một cửa sổ bật lên yêu cầu bạn uỷ quyền, hãy nhấp vào Uỷ quyền.
2. Đặt mã dự án
Thực thi lệnh sau trong cửa sổ dòng lệnh Cloud Shell để đặt Mã dự án chính xác. Thay thế <your-project-id> bằng mã dự án thực tế mà bạn đã sao chép ở bước tạo dự án nêu trên.
gcloud config set project <your-project-id>
Bây giờ, bạn sẽ thấy dự án chính xác được chọn trong thiết bị đầu cuối Cloud Shell. Mã dự án đã chọn được đánh dấu bằng màu vàng.
3. Bật các API bắt buộc
Để sử dụng các dịch vụ của Google Cloud, trước tiên, bạn phải kích hoạt các API tương ứng cho dự án của mình. Chạy các lệnh bên dưới trong thiết bị đầu cuối Cloud Shell để bật các dịch vụ cho Lớp học lập trình này:
gcloud services enable aiplatform.googleapis.com
Nếu thao tác thành công, bạn sẽ thấy Operation/... finished successfully được in trong thiết bị đầu cuối.
4. Tạo môi trường ảo Python
Trước khi bắt đầu bất kỳ dự án Python nào, bạn nên tạo một môi trường ảo. Điều này giúp tách biệt các phần phụ thuộc của dự án, ngăn chặn xung đột với các dự án khác hoặc các gói Python toàn cục của hệ thống.
1. Tạo thư mục dự án và chuyển đến thư mục đó:
mkdir ai-agents-adk
cd ai-agents-adk
2. Tạo và kích hoạt môi trường ảo:
uv venv --python 3.12
source .venv/bin/activate
Bạn sẽ thấy tiền tố (ai-agents-adk) trước dấu nhắc của thiết bị đầu cuối, cho biết môi trường ảo đang hoạt động.
3. Trang cài đặt adk
uv pip install google-adk
5. Tạo một nhân viên hỗ trợ
Khi môi trường đã sẵn sàng, đã đến lúc bạn tạo nền tảng cho tác nhân AI. ADK yêu cầu một số tệp để xác định logic và cấu hình của tác nhân:
agent.py: Chứa mã Python chính của tác nhân, xác định tên, LLM mà tác nhân sử dụng và các hướng dẫn cốt lõi.__init__.py: Đánh dấu thư mục là một gói Python, giúp ADK khám phá và tải định nghĩa tác nhân của bạn..env: Lưu trữ thông tin nhạy cảm và các biến cấu hình như khoá API, mã dự án và vị trí.
Lệnh này sẽ tạo một thư mục mới có tên personal_assistant chứa 3 tệp thiết yếu.
adk create personal_assistant
Sau khi thực thi lệnh, bạn sẽ được yêu cầu chọn một số lựa chọn để định cấu hình tác nhân.
Đối với bước đầu tiên, hãy chọn lựa chọn 1 để sử dụng mô hình gemini-2.5-flash, một mô hình nhanh chóng và hiệu quả, phù hợp với các tác vụ đàm thoại.
Choose a model for the root agent: 1. gemini-2.5-flash 2. Other models (fill later) Choose model (1, 2): 1
Đối với bước thứ hai, hãy chọn Vertex AI (lựa chọn 2), nền tảng AI được quản lý mạnh mẽ của Google Cloud, làm nhà cung cấp dịch vụ phụ trợ.
1. Google AI 2. Vertex AI Choose a backend (1, 2): 2
Sau đó, bạn cần xác minh rằng mã dự án xuất hiện trong dấu ngoặc vuông [...] được đặt chính xác. Nếu có, hãy nhấn Enter. Nếu không, hãy nhập mã dự án chính xác vào lời nhắc sau:
Enter Google Cloud project ID [your-project-id]:
Cuối cùng, hãy nhấn Enter ở câu hỏi tiếp theo để dùng us-central1 làm khu vực cho lớp học lập trình này.
Enter Google Cloud region [us-central1]:
Bạn sẽ thấy một kết quả tương tự trong thiết bị đầu cuối.
Agent created in /home/<your-username>/ai-agent-adk/personal_assistant: - .env - __init__.py - agent.py
6. Khám phá mã đại lý
Để xem các tệp đã tạo, hãy mở thư mục ai-agents-adk trong Cloud Shell Editor.
- Nhấp vào File > Open Folder... (Tệp > Mở thư mục...) trong trình đơn trên cùng.
- Tìm và chọn thư mục
ai-agents-adk - Nhấp vào OK.
Nếu thanh trình đơn trên cùng không xuất hiện, bạn cũng có thể nhấp vào biểu tượng thư mục rồi chọn Mở thư mục.
Sau khi cửa sổ Editor (Trình chỉnh sửa) tải xong, hãy chuyển đến thư mục personal-assistant. Bạn sẽ thấy các tệp cần thiết như đã đề cập ở trên (agent.py, __init__.py và .env).
Theo mặc định, tệp .env thường bị ẩn. Cách hiển thị trong Cloud Shell Editor:
- chuyển đến thanh trình đơn ở trên cùng,
- nhấp vào Xem, rồi
- chọn Toggle Hidden Files (Hiện/ẩn tệp).
Khám phá nội dung của từng tệp.
agent.py
Tệp này khởi tạo tác nhân của bạn bằng cách sử dụng lớp Agent từ thư viện google.adk.agents.
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-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 import Agent: Dòng này nhập lớpAgentcần thiết từ thư viện ADK.root_agent = Agent(...): Tại đây, bạn đang tạo một phiên bản của tác nhân AI.name="root_agent": Giá trị nhận dạng duy nhất cho tác nhân của bạn. Đây là cách ADK sẽ nhận dạng và đề cập đến trợ lý của bạn.model="gemini-2.5-flash": Đây là tham số quan trọng, chỉ định Mô hình ngôn ngữ lớn (LLM) mà tác nhân của bạn sẽ sử dụng làm "bộ não" cơ bản để hiểu, suy luận và tạo câu trả lời.gemini-2.5-flashlà một mô hình nhanh chóng và hiệu quả, phù hợp với các tác vụ đàm thoại.description="...": Phần này cung cấp thông tin tóm tắt ngắn gọn về mục đích hoặc khả năng của trợ lý. Nội dung mô tả này chủ yếu để con người hiểu hoặc để các tác nhân khác trong hệ thống nhiều tác nhân hiểu được chức năng của tác nhân cụ thể này. Thường được dùng để ghi nhật ký, gỡ lỗi hoặc khi hiển thị thông tin về tác nhân.instruction="...": Đây là câu lệnh hệ thống hướng dẫn hành vi của trợ lý và xác định tính cách của trợ lý. Câu lệnh này cho biết LLM nên hành động như thế nào và mục đích chính của nó là gì. Trong trường hợp này, câu lệnh này thiết lập tác nhân là một "trợ lý hữu ích". Chỉ dẫn này đóng vai trò quan trọng trong việc định hình phong cách và khả năng trò chuyện của trợ lý.
init.py
Tệp này là cần thiết để Python nhận dạng personal-assistant là một gói, cho phép ADK nhập chính xác tệp agent.py của bạn.
from . import agent
from . import agent: Dòng này thực hiện một thao tác nhập tương đối, yêu cầu Python tìm một mô-đun có tên làagent(tương ứng vớiagent.py) trong gói hiện tại (personal-assistant). Dòng đơn giản này đảm bảo rằng khi ADK cố gắng tải tác nhânpersonal-assistantcủa bạn, ADK có thể tìm và khởi tạoroot_agentđược xác định trongagent.py. Ngay cả khi trống, sự hiện diện của__init__.pylà yếu tố giúp thư mục trở thành một gói Python.
.env
Tệp này chứa các cấu hình dành riêng cho môi trường và thông tin đăng nhập nhạy cảm.
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION
GOOGLE_GENAI_USE_VERTEXAI: Thông tin này cho ADK biết rằng bạn dự định sử dụng dịch vụ Vertex AI của Google cho các hoạt động liên quan đến AI tạo sinh. Điều này rất quan trọng để tận dụng các dịch vụ có quản lý và mô hình nâng cao của Google Cloud.GOOGLE_CLOUD_PROJECT: Biến này sẽ lưu trữ giá trị nhận dạng duy nhất của Dự án trên Google Cloud. ADK cần thông tin này để liên kết chính xác tác nhân của bạn với các tài nguyên trên đám mây và để bật tính năng thanh toán.GOOGLE_CLOUD_LOCATION: Tham số này chỉ định khu vực Google Cloud nơi các tài nguyên Vertex AI của bạn được đặt (ví dụ:us-central1). Việc sử dụng đúng vị trí sẽ giúp tác nhân của bạn giao tiếp hiệu quả với các dịch vụ Vertex AI ở khu vực đó.
7. Chạy tác nhân trên Thiết bị đầu cuối
Khi đã có cả 3 tệp, bạn có thể chạy tác nhân ngay từ thiết bị đầu cuối. Để thực hiện việc này, hãy chạy lệnh adk run sau đây trong dòng lệnh:
adk run personal_assistant
Nếu thiết lập đúng mọi thứ, bạn sẽ thấy kết quả tương tự trong thiết bị đầu cuối. Tạm thời đừng lo lắng về các cảnh báo, miễn là bạn thấy [user]: thì bạn có thể tiếp tục.
... Running agent personal_assistant, type exit to exit. [user]: ...
Hãy trò chuyện với nhân viên hỗ trợ! Nhập nội dung như "xin chào. Bạn có thể làm gì cho tôi?" và bạn sẽ nhận được câu trả lời.
... Running agent personal_assistant, type exit to exit. [user]: hello. What can you do for me? [personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as: ...
Bạn sẽ nhận thấy đôi khi đầu ra được định dạng bằng Markdown, khiến bạn khó đọc trong thiết bị đầu cuối. Ở bước tiếp theo, chúng ta sẽ sử dụng Giao diện người dùng phát triển để có trải nghiệm phong phú hơn nhiều, giống như ứng dụng trò chuyện.
Khắc phục sự cố
Phương thức API này yêu cầu bạn bật tính năng thanh toán
Nếu bạn nhận được thông báo {‘message': ‘This API method requires billing to be enabled'}, hãy làm như sau:
- Kiểm tra xem bạn có đang sử dụng đúng mã dự án trong tệp
.envhay không - Chuyển đến trang tài khoản thanh toán được liên kết và xem tài khoản thanh toán đó đã được liên kết hay chưa
- Nếu không, hãy chọn Tài khoản thanh toán dùng thử Google Cloud Platform trong số các lựa chọn
Vertex AI API chưa được dùng trong dự án
Nếu bạn nhận được thông báo lỗi có chứa {'message': 'Vertex AI API has not been used in project...'}, hãy bật Vertex AI API bằng cách nhập nội dung sau vào thiết bị đầu cuối:
gcloud services enable aiplatform.googleapis.com
Nếu thao tác thành công, bạn sẽ thấy Operation/... finished successfully được in trong thiết bị đầu cuối.
Các lỗi khác
Nếu bạn gặp phải bất kỳ lỗi nào khác không được đề cập ở trên, hãy thử tải lại thẻ Cloud Shell trong trình duyệt (và uỷ quyền lại nếu được nhắc).
8. Chạy tác nhân trên Giao diện người dùng web dành cho nhà phát triển
Agent Development Kit cũng cung cấp một cách thuận tiện để chạy tác nhân dưới dạng một ứng dụng trò chuyện bằng cách sử dụng giao diện người dùng phát triển của tác nhân. Bạn chỉ cần dùng lệnh adk web thay vì adk run.
Nếu thiết bị đầu cuối của bạn vẫn đang chạy adk run, hãy nhập exit để đóng thiết bị đầu cuối trước khi nhập lệnh này:
adk web
Bạn sẽ thấy kết quả tương tự trong thiết bị đầu cuối:
... 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)
Bạn có 2 lựa chọn để truy cập vào giao diện người dùng phát triển:
- Mở qua Terminal (Thiết bị đầu cuối)
- Nhấn tổ hợp phím Ctrl + Nhấp hoặc Cmd + Nhấp vào đường liên kết (ví dụ:
http://localhost:8000) như minh hoạ trong cửa sổ dòng lệnh.
- Mở qua Chế độ xem trước trên web
- Nhấp vào nút Xem trước trên web,
- Chọn Thay đổi cổng.
- Nhập số cổng (ví dụ: 8000)
- Nhấp vào Thay đổi và xem trước
Sau đó, bạn sẽ thấy giao diện người dùng giống như ứng dụng trò chuyện xuất hiện trong trình duyệt. Hãy trò chuyện với trợ lý cá nhân của bạn thông qua giao diện này!
Bạn sẽ nhận thấy rằng định dạng Markdown hiện hiển thị chính xác và giao diện người dùng này cũng cho phép bạn gỡ lỗi và điều tra từng sự kiện nhắn tin, trạng thái của tác nhân, yêu cầu của người dùng và nhiều thông tin khác. Chúc bạn trò chuyện vui vẻ!
9. Dọn dẹp (Không bắt buộc)
Vì lớp học lập trình này không liên quan đến bất kỳ sản phẩm nào chạy trong thời gian dài, nên bạn chỉ cần dừng các phiên tác nhân đang hoạt động (ví dụ: phiên bản adk web trong thiết bị đầu cuối) bằng cách nhấn tổ hợp phím Ctrl + C hoặc Cmd + C trong thiết bị đầu cuối.
Xoá thư mục và tệp dự án của nhân viên hỗ trợ
Nếu bạn chỉ muốn xoá mã khỏi môi trường Cloud Shell, hãy sử dụng các lệnh sau:
cd ~
rm -rf ai-agents-adk
Tắt Vertex AI API
Để tắt Vertex AI API đã được bật trước đó, hãy chạy lệnh sau:
gcloud services disable aiplatform.googleapis.com
Tắt toàn bộ dự án trên Google Cloud
Nếu bạn muốn tắt hoàn toàn dự án Google Cloud, hãy tham khảo hướng dẫn chính thức để biết hướng dẫn chi tiết.
10. Kết luận
Xin chúc mừng! Bạn đã tạo thành công một tác nhân trợ lý cá nhân đơn giản bằng Bộ công cụ phát triển tác nhân (ADK). Giờ đây, bạn đã có kiến thức nền tảng vững chắc và hiểu rõ các thành phần cốt lõi của một tác nhân ADK.
Trong bước tiếp theo, bạn có thể mở rộng đáng kể các chức năng của trợ lý bằng cách cung cấp cho trợ lý các công cụ để truy cập thông tin theo thời gian thực và tương tác với các dịch vụ bên ngoài. Nếu bạn muốn tiếp tục hành trình này, lớp học lập trình tiếp theo trong loạt lớp học lập trình này, Xây dựng các tác nhân AI bằng ADK: Trang bị các công cụ, sẽ hướng dẫn bạn thực hiện quy trình này.