ADK: Từ kiến thức cơ bản đến các tác nhân đa công cụ

1. Giới thiệu

Bắt đầu từ những kiến thức cơ bản và tiến tới việc phát triển các tác nhân đa năng, lớp học lập trình này cung cấp phần giới thiệu toàn diện về cách xây dựng tác nhân bằng ADK.

Ở dạng đơn giản nhất, tác nhân AI là một hệ thống phần mềm sử dụng mô hình ngôn ngữ lớn (LLM) làm "công cụ suy luận" để đạt được mục tiêu bằng cách tự động thực hiện một chuỗi nhiệm vụ.

Nếu LLM là một chuyên gia tư vấn có năng lực cao, có thể đưa ra lời khuyên cho bạn, thì Tác nhân AI là một kỹ sư chủ động có thể sử dụng các công cụ để thực hiện lời khuyên đó.

LLM so với Tác nhân

Bộ não (LLM): Cung cấp khả năng suy luận, lập kế hoạch và hiểu ngôn ngữ tự nhiên. Bộ não này quyết định những việc cần làm.

Bàn tay (Công cụ): Đây là các API, SDK và hàm tuỳ chỉnh cho phép tác nhân tương tác với thế giới thực. Bàn tay này thực hiện kế hoạch.

Bộ công cụ phát triển tác nhân (ADK)

Bộ công cụ phát triển tác nhân (ADK) là một khung chuyên biệt được thiết kế để đơn giản hoá việc tạo, triển khai và điều phối các tác nhân AI. Bộ công cụ này cung cấp các khối xây dựng tiêu chuẩn cần thiết để chuyển đổi Mô hình ngôn ngữ lớn tĩnh thành một tác nhân động có khả năng thực thi mã, gọi API và quản lý quy trình làm việc nhiều bước.

Tác nhân đa năng là một trình điều phối có thể chọn và sắp xếp các hàm chuyên biệt khác nhau (như công cụ tìm kiếm, cơ sở dữ liệu và máy tính) để giải quyết các vấn đề phức tạp. Tác nhân này xác định một cách thông minh công cụ cần sử dụng cho từng bước và có thể truyền kết quả của một hành động làm dữ liệu đầu vào cho hành động tiếp theo để đạt được mục tiêu cuối cùng.

Sản phẩm bạn sẽ tạo ra

Trong lớp học lập trình này, bạn sẽ tạo Tác nhân "Healthy Hints" (Gợi ý lành mạnh), một chuyên gia tư vấn dinh dưỡng thông minh chuyển từ khả năng suy luận văn bản đơn giản sang một công cụ đa năng mạnh mẽ. Bạn sẽ bắt đầu bằng cách tạo một tác nhân trò chuyện cơ bản có khả năng hiểu các khái niệm về dinh dưỡng, sau đó dần dần trang bị cho tác nhân này một công cụ SDK lưu trữ để lưu trữ hình ảnh thành phần và một công cụ Vision để "đọc" và phân tích những hình ảnh đó. Khi kết thúc lớp học lập trình này, bạn sẽ có một trình điều phối hoạt động đầy đủ chức năng, có thể lấy ảnh nhãn thực phẩm đã tải lên, lưu trữ ảnh đó trong một vùng chứa trên đám mây để lưu giữ hồ sơ và cung cấp ngay "Healthy Hints" (Gợi ý lành mạnh) cho từng thành phần.

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

Một Dự án trên Google Cloud đã bật tính năng Thanh toán
Một trình duyệt web

Tạo dự án

Trong Google Cloud Console, trên trang bộ chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
Đảm bảo rằng tính năng thanh toán được bật trên Dự án trên đám mây. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên một dự án hay không.

Kích hoạt Cloud Shell

Bạn sẽ sử dụng Cloud Shell, một môi trường dòng lệnh chạy trong Google Cloud Console và được tải sẵn các ngôn ngữ cần thiết đã cài đặt. Trên Cloud Console, hãy nhấp vào Kích hoạt Cloud Shell ở góc trên cùng bên phải:

Sau khi kết nối với Cloud Shell, bạn sẽ thấy rằng mình đã được xác thực và dự án được đặt thành mã dự án của bạn. Chạy lệnh sau trong Cloud Shell để xác nhận rằng bạn đã được xác thực:

gcloud auth list

Chạy lệnh sau trong Cloud Shell để xác nhận rằng lệnh gcloud biết về dự án của bạn:

gcloud config list project

Nếu dự án của bạn chưa được thiết lập, hãy sử dụng lệnh sau để thiết lập:

gcloud config set project <YOUR_PROJECT_ID>

Tham khảo tài liệu để biết các lệnh và cách sử dụng gcloud.

Mở trình chỉnh sửa

Trong lớp học lập trình này, chúng ta sẽ sử dụng trình chỉnh sửa Cloud tích hợp. Trong cửa sổ Cloud Shell, hãy nhấp vào nút Open editor (Mở trình chỉnh sửa) ở góc trên cùng bên phải. Thao tác này sẽ mở Trình chỉnh sửa VSCode cho bạn.

3. Thiết lập ADK

Hãy chuyển đến Cloud Shell Terminal mà chúng ta đã kích hoạt ở phần trước:

Tạo và kích hoạt môi trường ảo (Nên dùng)

Từ Cửa sổ dòng lệnh Cloud Shell, hãy tạo một Môi trường ảo:

python -m venv .venv

Kích hoạt Môi trường ảo:

source .venv/bin/activate

Cài đặt ADK

pip install google-adk

4. Khoá API của Google

Tạo khoá API của Google bằng AI Studio:

Truy cập vào https://aistudio.google.com/ rồi nhấp vào Get API Key trong trình đơn dưới cùng bên trái

Bạn sẽ thấy một cửa sổ API Keys (Khoá API), hãy nhấp vào Create API key (Tạo khoá API) trong cửa sổ này:

Bạn sẽ thấy một cửa sổ bật lên để tạo khoá mới. Đặt tên cho khoá là: healthy-hints-key

Chuyển đến trình đơn thả xuống "Choose an imported project" (Chọn một dự án đã nhập)

Nhấp vào Import Project (Nhập dự án). Một cửa sổ bên sẽ xuất hiện, liệt kê tất cả các dự án trên Google Cloud của bạn. Hãy chọn dự án mà bạn muốn làm việc.

Nhấp vào Import (Nhập)

Trình đơn thả xuống sẽ được cập nhật với dự án mà bạn vừa nhập. Chọn dự án trong trình đơn thả xuống. Nhấp vào Create Key now (Tạo khoá ngay bây giờ). Bây giờ, bạn sẽ thấy danh sách các khoá API đã tạo. Nhấp vào biểu tượng sao chép của khoá API mà bạn vừa tạo.

5. Tác nhân mẫu

Từ Cửa sổ dòng lệnh Cloud Shell, hãy tạo một thư mục gốc cho tác nhân ở vị trí dự án mong muốn:

adk create healthy_hints

Bạn có thể chọn bất kỳ mô hình nào, nhưng trong lớp học lập trình này, chúng ta sẽ sử dụng gemini-2.5-flash

Trong lớp học lập trình này, chúng ta sẽ sử dụng AI của Google. Dán khoá API mà bạn đã tạo ở bước trước.

Hãy mở thư mục mà chúng ta vừa tạo. Trên trình đơn ở ngoài cùng bên trái, hãy nhấp vào biểu tượng , nhấp vào File (Tệp) -> Open Folder (Mở thư mục). Chọn thư mục healthy_hints vừa được tạo. Thư mục này thường nằm trong thư mục /home/<username>.
Cấu trúc thư mục healthy_hints thường có dạng như sau:

Bạn sẽ thấy một tệp .env có khoá API của Google. Bạn có thể sử dụng tệp này để thiết lập bất kỳ biến môi trường nào.
Một tệp khác có tên là agent.py cũng được tạo và đó là tệp tác nhân chính của chúng ta. Đây là nơi tạo tác nhân gốc mẫu. Hãy xem xét kỹ nội dung của tệp này. Trước tiên, chúng ta sẽ nhập llm_agent từ ADK. Sau đó, chúng ta sử dụng ADK DSL để tạo tác nhân gốc. Chúng ta chỉ định tên mô hình là Gemini-2.5-flash, đặt tên cho tác nhân, cung cấp nội dung mô tả hay về tác nhân đó. Hướng dẫn là điều quan trọng nhất ở đây. Đây là nơi chúng ta cho tác nhân biết những việc cần làm bằng ngôn ngữ tự nhiên.
Tác nhân mẫu này khá chung chung, chỉ trả lời mọi câu hỏi của người dùng.
Bây giờ, hãy chạy tác nhân này cục bộ. Có 2 cách để bạn tương tác với tác nhân này : CLI và Web.
CLI: Chạy lệnh sau từ bên ngoài thư mục healthy_hints

adk run healthy_hints

Hoặc nếu bạn đang ở trong thư mục healthy_hints, hãy chạy lệnh sau:

adk run .

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

Hãy tiếp tục và viết "hi" hoặc bất kỳ câu hỏi nào bạn có. Câu trả lời có thể khác nhau đối với từng người, đó là bản chất của GenAI.

Web: Chạy lệnh sau từ thư mục mẹ của healthy_hints :

adk web

6. Tác nhân đa năng

Công cụ là một đoạn mã mô-đun (thường là một hàm hoặc một API) cho phép tác nhân tương tác với thế giới bên ngoài kiến thức nội bộ của tác nhân.

Các loại công cụ trong ADK

Công cụ hàm: Logic tuỳ chỉnh mà bạn tự viết. Ví dụ: một hàm kết nối với cơ sở dữ liệu cụ thể của bạn hoặc một "Trình phân tích cú pháp nhật ký" tuỳ chỉnh cho định dạng riêng của công ty bạn.
Công cụ tích hợp: Các tính năng sẵn sàng sử dụng do Google hoặc ADK cung cấp, chẳng hạn như Google Tìm kiếm, Trình thông dịch mã hoặc Công cụ Google RAG.
Agents-as-Tools: Trong các hệ thống "Đa năng" hoặc "Đa tác nhân" nâng cao, một tác nhân chuyên biệt có thể hoạt động như một công cụ cho tác nhân khác. Ví dụ: "Tác nhân tìm kiếm" có thể là một công cụ do "Tác nhân quản lý nghiên cứu" sử dụng.

Trong lớp học lập trình này, chúng ta sẽ đề cập đến Công cụ hàm. Bây giờ, hãy nâng cao tác nhân của chúng ta và biến tác nhân đó thành tác nhân đa năng.

Hãy thêm một phương thức mới get_weather trong agent.py

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

Hãy sửa đổi agent.py và thay đổi tên, nội dung mô tả & hướng dẫn của tác nhân:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

Cho đến nay, chúng ta mới chỉ tạo một công cụ. Bây giờ, hãy tạo nhiều công cụ:

Hãy tạo một phương thức khác có tên là get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

Và hãy sửa đổi tác nhân của chúng ta để gọi công cụ này:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

Chúng ta đã sửa đổi nội dung mô tả, hướng dẫn và công cụ cho phù hợp. Bây giờ, hãy tiếp tục và chạy tác nhân đã cập nhật này. Lần này, tác nhân cũng sẽ phản hồi bằng thời gian và thời tiết hiện tại.

7. Tích hợp SDK

Bây giờ chúng ta đã biết cách sử dụng nhiều công cụ. Hãy cùng xem một số ví dụ thực tế. Hãy tạo tác nhân gợi ý lành mạnh. Mục tiêu của chúng ta ở đây là tải bất kỳ hình ảnh nào có danh sách thành phần lên tác nhân và tác nhân sẽ cho chúng ta biết từng thành phần có tốt cho sức khoẻ hay không.

Trước tiên, hãy tạo một vùng chứa để tải hình ảnh lên bộ nhớ trên Google Cloud. Hãy mở một thẻ mới và chuyển đến https://console.cloud.google.com/ rồi nhập bộ nhớ trên đám mây vào thanh tìm kiếm. Bây giờ, hãy chọn Cloud Storage (Bộ nhớ trên đám mây) trong phần Products &pages (Sản phẩm và trang):

Thao tác này sẽ đưa bạn đến trang tổng quan về Google Cloud Storage. Nhấp vào nút Create bucket (Tạo vùng chứa). Trên trang tạo vùng chứa, hãy nhập tên của vùng chứa. Tên có thể là bất kỳ tên nào, nhưng trong lớp học lập trình này, chúng ta sẽ đặt tên là healthy-hints-bucket-kolkata . Để mọi thứ khác như cũ rồi nhấp vào nút Create (Tạo).

Hãy tạo một tệp mới có tên là requirements.txt và thêm google-cloud-storage vào tệp đó. Chúng ta sẽ sử dụng SDK lưu trữ Python để tải hình ảnh lên Bộ nhớ.

Trước tiên, hãy cài đặt các phần phụ thuộc:

pip install -r requirements.txt

Trước tiên, bạn cần bật API lưu trữ. Để thực hiện việc này, hãy chạy lệnh sau trong cửa sổ dòng lệnh:

gcloud services enable storage.googleapis.com

Bây giờ, hãy thêm một công cụ mới để tải hình ảnh lên.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

Bây giờ, hãy cập nhật tác nhân để tác nhân sử dụng công cụ mới:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

Bây giờ, chúng ta sẽ thêm một công cụ khác để đọc các thành phần trong hình ảnh. Hãy thêm google-cloud-vision vào requirements.txt và cài đặt phần phụ thuộc mới.

pip install -r requirements.txt

Một lần nữa, trước tiên, bạn cần bật API Vision. Để thực hiện việc này, hãy chạy lệnh sau trong cửa sổ dòng lệnh:

gcloud services enable vision.googleapis.com

Bây giờ, hãy thêm một công cụ mới read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

Và bây giờ, hãy cập nhật tác nhân của chúng ta để sử dụng công cụ này

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. Kết luận

Chúc mừng bạn đã hoàn thành lớp học lập trình Healthy Hints! Bạn đã chuyển đổi thành công một AI tiêu chuẩn từ công cụ tạo văn bản thành một Tác nhân đa năng chủ động. Bằng cách sử dụng ADK để tích hợp API Vision và SDK Cloud Storage, bạn đã cung cấp cho tác nhân của mình "đôi mắt" để đọc nhãn và "bộ nhớ" để lưu trữ các nhãn đó. Bạn đã thấy cách tác nhân tự động quyết định thời điểm lưu tệp và cách diễn giải dữ liệu thô để đưa ra lời khuyên về sức khoẻ trong thế giới thực.

Trong tương lai, những nguyên tắc này sẽ đóng vai trò là bản thiết kế cho mọi hệ thống tự động. Cho dù bạn đang quản lý cơ sở hạ tầng đám mây hay xây dựng trợ lý cá nhân, thì cốt lõi vẫn là: xác định các công cụ chuyên biệt và để tác nhân điều phối logic. Bước tiếp theo, hãy thử thêm nhiều công cụ hơn như "Cơ sở dữ liệu dinh dưỡng" hoặc "Công cụ email" để mở rộng tác động của tác nhân.