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 đến việc phát triển các tác nhân đa công cụ, lớp học lập trình này cung cấp một phần giới thiệu toàn diện về cách xây dựng các tác nhân bằng ADK.

Nói một cách đơn giản, AI Agent 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ột mục tiêu bằng cách tự động thực hiện một chuỗi các tác vụ.

Nếu LLM là một chuyên gia tư vấn có năng lực cao và có thể đưa ra lời khuyên cho bạn, thì AI Agent 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 các tác nhân

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

Bàn tay (Công cụ): Đây là những 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. Nó thực thi 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á quá trình tạo, triển khai và điều phối các tác nhân AI. Đây là các khối xây dựng tiêu chuẩn cần thiết để chuyển đổi một 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.

Trợ lý đa năng là một công cụ điều phối có thể chọn và sắp xếp các chức năng chuyên biệt khác nhau (chẳng hạn 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. Công cụ này xác định một cách thông minh công cụ cần dùng cho từng bước và có thể truyền đầu ra của một hành động làm đầ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ẽ xây dựng một Agent "Healthy Hints" (Gợi ý lành mạnh), một chuyên gia tư vấn dinh dưỡng thông minh chuyển đổi từ suy luận văn bản đơn giản sang một công cụ đa năng. Bạn sẽ bắt đầu bằng cách tạo một tác nhân đàm thoại cơ bản có thể 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ụ Storage SDK để 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 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 chụp nhãn thực phẩm đã tải lên, lưu trữ trong một vùng lưu trữ trên đám mây để lưu giữ hồ sơ và cung cấp ngay "Gợi ý về sức khoẻ" 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
• Trình duyệt web

Tạo dự án

• Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
• Đảm bảo bạn đã bật tính năng thanh toán cho dự án trên đám mây của bạn. 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. Trong 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 bạn chưa đặt dự án, hãy dùng lệnh sau để đặt dự án:

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)

Trong Cloud Shell Terminal, 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 biểu tượng Get API Key trong trình đơn dưới cùng bên trái

• Bạn sẽ thấy 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 "Chọn một dự án đã nhập"

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

Nhấp vào Nhập

• Giờ đây, danh sách 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 Tạo khoá ngay. Lúc này, 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

• Trong Cloud Shell Terminal, hãy tạo một thư mục gốc cho tác nhân của bạn ở vị trí dự án mà bạn 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ẽ tiếp tục với 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 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 bên trái, hãy nhấp vào biểu tượng , nhấp vào Tệp -> 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 Google. Bạn có thể dùng tệp này để thiết lập mọi biến môi trường.
• 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 một 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 và 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 biết những gì mà tác nhân cần làm bằng ngôn ngữ tự nhiên.
• Tác nhân mẫu này khá chung chung, nó sẽ 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 có thể 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 kết quả tương tự:

Hãy viết "xin chào" 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 AI tạo sinh.

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

adk web

6. Tác nhân đa công cụ

Công cụ là một đoạn mã theo mô-đun (thường là một hàm hoặc API) cho phép một 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 nó.

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

• Công cụ hàm: Logic tuỳ chỉnh do 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 chức năng có sẵn 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ụ RAG của Google.
• Agents-as-Tools: Trong các hệ thống "Nhiều công cụ" hoặc "Nhiều tác nhân" nâng cao, một tác nhân chuyên biệt có thể đóng vai trò là công cụ cho một tác nhân khác. Ví dụ: "Tác nhân tìm kiếm" có thể là một công cụ được "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ẽ tìm hiểu về Công cụ hàm. Bây giờ, hãy nâng cấp tác nhân của chúng ta và biến tác nhân này thành một công cụ đa năng.

Hãy thêm một phương thức get_weather mới vào 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ả cũng như 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 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 tôi đã 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 chạy tác nhân đã cập nhật này. Lần này, trợ lý ảo cũng sẽ phản hồi bằng thông tin về thời gian và thời tiết hiện tại.

7. Tích hợp SDK

Giờ đây, chúng ta đã biết cách sử dụng nhiều công cụ. Hãy cùng xem xét một số ví dụ thực tế. Hãy tạo một 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 cho trợ lý ảo và trợ lý ảo 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 bộ chứa để tải hình ảnh lên trong bộ nhớ đám mây của Google. Hãy mở một thẻ mới và chuyển đến https://console.cloud.google.com/ rồi nhập cloud storage vào thanh tìm kiếm. Bây giờ, hãy chọn Bộ nhớ trên đám mây trong mục Sản phẩm và trang:

Thao tác này sẽ đưa bạn đến trang tổng quan của Google Cloud Storage. Nhấp vào nút Create bucket. Trong trang tạo vùng lưu trữ, hãy nhập tên của vùng lưu trữ. Bạn có thể đặt tên bất kỳ, 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.

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

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 Storage API. Để 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 này:

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],
)

• Giờ đây, 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ó thể cần bật Vision API. Để 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

Bây giờ, hãy cập nhật tác nhân để 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 đã biến đổi thành công một AI tiêu chuẩn từ một công cụ tạo văn bản thành một Trợ lý đa năng chủ động. Bằng cách sử dụng ADK để tích hợp Vision API và Cloud Storage SDK, bạn đã cung cấp cho tác nhân của mình "mắt" để đọc nhãn và "bộ nhớ" để lưu trữ 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 dụng và cho phép 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, chẳng hạn như "Cơ sở dữ liệu dinh dưỡng" hoặc "Công cụ email" để mở rộng phạm vi tác động của trợ lý.