Xây dựng chuyên gia nếm sầu riêng đa phương thức bằng ADK và Antigravity

1. Tổng quan

Chọn được một quả sầu riêng ngon tại quầy hàng ven đường là một thử thách về giác quan. Người mua cần phân biệt được sầu riêng Musang King (D197) thật với sầu riêng giả, đánh giá xem quả sầu riêng rụng sáng nay hay đã rụng từ nhiều ngày trước và đoán xem liệu họ có thích hương vị của quả sầu riêng đó hay không.

Trong lớp học lập trình này, bạn sẽ xây dựng và thử nghiệm một hệ thống đa tác nhân Durian Sommelier đa phương thức bằng Bộ công cụ phát triển tác nhân (ADK) và Agents CLI, đồng thời có thể triển khai hệ thống đó lên Cloud Run bằng Antigravity CLI (các bước chính mất khoảng 45 phút; hai bước Antigravity không bắt buộc mất thêm khoảng 20 phút). Việc chọn sầu riêng cho thấy ranh giới giữa khả năng nhận thức của AI và giác quan của con người:

  • Những gì AI có thể nhìn thấy: Gemini có thể kiểm tra ảnh chụp vỏ sầu riêng và phát hiện các dấu hiệu của giống cây trồng, chẳng hạn như ngôi sao năm cánh ở đáy quả Musang King, phần đỉnh lõm màu tối của quả Black Thorn (D200), vòng tròn có kích thước bằng đồng xu của quả D24 hoặc cuống khô, héo.
  • Những điều chỉ con người mới cảm nhận được: Mô hình không thể ngửi đường nối để tìm mùi rượu, gõ vào vỏ để nghe tiếng gõ rỗng hoặc ấn vào hai chiếc gai để cảm nhận xem chúng có bật lại hay không.
  • Điều nhân viên hỗ trợ cần nhớ: Hai quả sầu riêng chín hoàn hảo vẫn khiến người mua chia rẽ. Có người thích vị đắng, nồng nàn của sầu riêng XO D24 từ cây cổ thụ, nhưng cũng có người lại thích vị ngọt, không đắng của sầu riêng Red Prawn (D175).

Ranh giới cảm quan của sầu riêng: Thị giác AI so với giác quan của con người

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

  • Giai đoạn 1 – Tác nhân thị giác đơn: Một tác nhân ADK, được tạo khung bằng CLI của tác nhân, giúp xác định giống sầu riêng và độ tươi của sầu riêng từ một bức ảnh.
  • Giai đoạn 2 – Giác quan của con người và trí nhớ về khẩu vị: Các công cụ chấm điểm những gì người mua ngửi, nghe và cảm nhận, cùng với một công cụ lưu hồ sơ khẩu vị của họ qua các phiên.
  • Giai đoạn 3 – Điều phối viên và chuyên gia: Một điều phối viên durian_advisor gọi cho một thanh tra thị giác và một chuyên gia cảm quan, sau đó đưa ra một phán quyết rõ ràng.
  • Giai đoạn 4 – Dịch vụ tác nhân Cloud Run: Trong một bước không bắt buộc, Antigravity CLI sẽ triển khai tác nhân của bạn bằng các kỹ năng của Agents CLI.
  • Giai đoạn 5 – Chatbot web Cloud Run: Trong một bước không bắt buộc khác, Antigravity CLI sẽ xây dựng và triển khai một ứng dụng trò chuyện phù hợp với thiết bị di động để trò chuyện với tác nhân của bạn.

Kiến trúc

Kiến trúc của Durian Sommelier: một chatbot web trên Cloud Run gọi trình điều phối durian_advisor trên Cloud Run, trình điều phối này gọi các chuyên gia về thị giác và cảm quan, đồng thời lưu giữ khẩu vị của người mua trong trạng thái phiên ADK

Hai dịch vụ Cloud Run này đến từ các bước Antigravity không bắt buộc. Nếu không có các quyền này, bạn sẽ chạy cùng một tác nhân trong sân chơi ADK trong Cloud Shell.

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

  • Thành thạo cơ bản về lập trình Python
  • Quen thuộc với các công cụ dòng lệnh và khái niệm AI tạo sinh
  • Không cần có kinh nghiệm sử dụng ADK, Agents CLI hoặc Antigravity CLI

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

  • Cách tạo khung cho một dự án ADK bằng agents-cli create và xây dựng một tác nhân đa phương thức có thể đọc ảnh
  • Giới hạn nhận thức của AI (khứu giác, thính giác, xúc giác và sở thích cá nhân) và cách thiết kế các công cụ có con người nằm trong quy trình cho những giác quan đó
  • Cách ghi nhớ lựa chọn ưu tiên của từng người dùng trong các phiên bằng trạng thái ADK trong phạm vi user:
  • Cách chia một tác nhân thành một điều phối viên và các tác nhân chuyên biệt một lượt mà điều phối viên gọi như các công cụ
  • (Không bắt buộc) Cách cung cấp cho Antigravity CLI các kỹ năng của Agents CLI để công cụ này có thể triển khai tác nhân và chatbot web của bạn lên Cloud Run

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)

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

Nếu bạn đang tự hoàn thành lớp học lập trình này và đủ điều kiện, hãy sử dụng biểu ngữ tín dụng của Google Developer Program trên trang này để nhận tín dụng mà không cần thẻ tín dụng. Nếu bạn đang tham dự một hội thảo có đường liên kết đến tín dụng sự kiện do người hướng dẫn cung cấp, hãy làm theo các bước về tín dụng sự kiện trong phần này.

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

Bạn có thể nhận tín dụng cho sự kiện hội thảo thông qua Trung tâm Nhà phát triển của Google (thuộc Google Developer Program).

Để nhận khoản tín dụng cho sự kiện, hãy làm theo các bước sau:

  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á nhân của bạn.
  2. Trên thẻ Nhận lợi ích, hãy nhấp vào Nhận tín dụng.

Thẻ Nhận lợi ích của Trung tâm Nhà phát triển Google cho thấy nút Nhận tín dụng.

  1. Không bắt buộc: Nếu bạn thấy lời nhắc tạo hồ sơ Google Developer Program, hãy hoàn tất biểu mẫu.
  2. Khi hộp thoại Quét để xác minh bạn là người 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. Nếu mã QR không xuất hiện, hãy làm mới trang rồi nhấp lại vào Yêu cầu nhận tín dụng.
  3. Xác nhận rằng thông báo Successfully claimed your event credit! (Đã 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 Open Billing Account (Mở tài khoản thanh toán).

Thẻ xác nhận của Trung tâm Nhà phát triển Google cho biết bạn đã nhận được khoản tín dụng cho sự kiện và nút Mở tài khoản thanh toán.

🔍 Kiểm tra bài làm

Quá trình cấp phép tài khoản thanh toán có thể mất đến 5 phút. Để xác nhận rằng khoản tín dụng của bạn đang hoạt động, hãy hoàn tất các bước sau:

  1. Nếu trang Quản lý tài khoản thanh toán chưa mở, hãy mở Google Cloud Billing (hoặc sao chép URL vào cửa sổ ẩn danh):
https://console.cloud.google.com/billing
  1. Nhấp vào thẻ Tài khoản thanh toán của bạn rồi làm mới trang cho đến khi một tài khoản có chứa Tín dụng GDP hiển thị trạng thái Đang hoạt động trong cột Trạng thái.

Trang quản lý tài khoản thanh toán trên Google Cloud cho thấy một tài khoản thanh toán có khoản tín dụng GDP đ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 trên đám mây chuyên biệt của Google Cloud để tách biệt tất cả tài nguyên khỏi lớp học lập trình này, nhờ đó bạn có thể xoá hoàn toàn các tài nguyên đó khi hoàn tất.

Để tạo một dự án trên Google Cloud, hãy làm theo các bước sau:

  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
  1. Nhập thông tin chi tiết về dự án:
    • Tên dự án: Nhập tên mô tả, chẳng hạn như google-cloud-workshop.
    • Tài khoản thanh toán (nếu có): Chọn tài khoản Tín dụng GDP (hoặc tài khoản thanh toán đang hoạt động của bạn).
    • Tài nguyên gốc: Chọn Không có tổ chức (hoặc chọn tổ chức của bạn nếu cần).
  2. Ghi lại Mã dự án đã tạo, rồi nhấp vào Tạo.

Biểu mẫu Tạo dự án trên Google Cloud cho thấy Tên dự án, Mã dự án được tạo, Tài nguyên gốc và nút Tạo.

🔍 Kiểm tra bài làm

Sau khi tạo xong dự án, hãy mở Thông báo trên thanh công cụ của Google Cloud Console, rồi nhấp vào Chọn dự án.

Trình đơn Thông báo của Google Cloud Console cho thấy mục Tạo dự án và đường liên kết Chọn dự án.

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

Trong phần này, bạn sẽ thiết lập Google Cloud Shell, bật API Nền tảng tác nhân và cài đặt CLI tác nhân bằng uv.

Định cấu hình Cloud Shell

Chạy Cloud Shell

Mở Google Cloud Shell khi bật cả trình soạn thảo mã và chế độ xem dòng lệnh (hoặc sao chép URL vào cửa sổ ẩn danh) rồi nhấp vào Authorize (Uỷ quyền) nếu được nhắc:

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

Hộp thoại uỷ quyền Cloud Shell

Đặt mã dự án trên Google Cloud

Sao chép và dán đoạn mã sau vào thiết bị đầu cuối Cloud Shell. Thao tác này sẽ hiển thị một trình đơn được đánh số gồm các dự án trên đám mây của Google Cloud hiện có của bạn. Nhập số bên cạnh dự án của bạn (ví dụ: 1) rồi nhấn phím Enter:

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

Câu lệnh dự kiến:

1) durian-sommelier-workshop-4210
2) my-cloud-project-8812
Select your project (e.g. 1): 1
Updated property [core/project].
[environment: untagged] Read more to tag: g.co/cloud/project-env-tag.

Bây giờ, bạn sẽ thấy Mã dự án đã chọn được đánh dấu màu vàng trong lời nhắc của thiết bị đầu cuối Cloud Shell:

Thiết bị đầu cuối Cloud Shell cho thấy Mã dự án đã chọn được đánh dấu bằng màu vàng

Bật Agent Platform API

Bật Agent Platform API mà các tác nhân của bạn sử dụng để gọi Gemini:

gcloud services enable aiplatform.googleapis.com

🔍 Kiểm tra bài làm

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

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

Cài đặt Agents CLI

Đảm bảo uv có sẵn và thư mục công cụ của nó nằm trên PATH:

which uv || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

Cài đặt Agents CLI dưới dạng công cụ uv:

uv tool install google-agents-cli==1.7.0

uv cài đặt từng công cụ trong môi trường riêng biệt và chỉ thêm lệnh agents-cli vào PATH, vì vậy, Python trong hệ thống của bạn sẽ không bị ảnh hưởng. Bạn cũng không cần phải tự cài đặt ADK. Mỗi dự án mà Agents CLI tạo đều có môi trường ảo riêng với phiên bản ADK mà mẫu đã được kiểm thử.

🔍 Kiểm tra bài làm

Xác nhận rằng Giao diện dòng lệnh (CLI) của tác nhân đã sẵn sàng:

agents-cli --version

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

agents-cli, version 1.7.0

5. Tạo một tác nhân thị giác đa phương thức

Bắt đầu từ những bước nhỏ: sử dụng Agents CLI để tạo một dự án ADK, sau đó biến tác nhân mẫu của dự án thành một trình phân loại hình ảnh sầu riêng.

Tạo khung dự án

Tạo dự án durian-advisor. --agent adk_python chọn mẫu ADK Python, --deployment-target cloud_run và --region us-central1 chuẩn bị mẫu đó cho Cloud Run, --prototype bỏ qua bước thiết lập CI/CD và --yes chấp nhận các giá trị mặc định:

cd ~ && agents-cli create durian-advisor \
  --agent adk_python \
  --deployment-target cloud_run \
  --region us-central1 \
  --prototype \
  --yes

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

> Verifying GCP credentials...
> ✓ Connected to project: your-project-id

✅ Success! Your agent project is ready.

Mở dự án trong Trình chỉnh sửa Cloud Shell. Thao tác này sẽ tải lại cửa sổ và khởi động lại thiết bị đầu cuối:

cloudshell workspace ~/durian-advisor

Cài đặt các phần phụ thuộc của dự án vào thư mục .venv của dự án:

cd ~/durian-advisor && agents-cli install

Kiểm tra tệp môi trường

Agents CLI cũng đã viết một tệp .env để yêu cầu ADK gọi Gemini thông qua dự án trên đám mây của Google Cloud của bạn:

grep GOOGLE_ ~/durian-advisor/.env

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

GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global

Giữ gói GOOGLE_CLOUD_LOCATION=global. Gemini 3.8 Flash được phân phát từ điểm cuối global, chứ không phải từ các điểm cuối theo khu vực như us-central1, mặc dù các dịch vụ Cloud Run của bạn chạy trong us-central1.

Nếu GOOGLE_CLOUD_PROJECT cho thấy your-gcp-project-id, thì CLI của tác nhân không phát hiện được dự án của bạn. Đặt bằng:

sed -i "s/your-gcp-project-id/$(gcloud config get-value project)/" ~/durian-advisor/.env

Viết trình phân loại thị giác máy tính

Mỗi giống cây trồng đều có các dấu hiệu trên vỏ mà Gemini có thể phát hiện trong ảnh:

Hướng dẫn trực quan về giống sầu riêng cho thấy các điểm đánh dấu phần đáy và gai của Musang King, Black Thorn, Red Prawn và D24

Mở app/agent.py:

cloudshell edit ~/durian-advisor/app/agent.py

Thay thế nội dung của tệp bằng mã sau:

"""A single multimodal agent that inspects durian photos."""

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

MODEL = "gemini-3.8-flash"

INSTRUCTION = """You are a durian visual classifier. Inspect the durian photo or shell description.
1. Base seam: a 5-point star means Musang King (D197). A dark sunken tip means Black Thorn (D200). A coin-sized brown ring means D24. An oval body with widely spaced, hooked thorns means Red Prawn (D175).
2. Stem: plump, moist, and greenish means it fell within about 12 hours. Dry and shriveled means it is days old.
3. Husk: closed seams mean natural ripening. Wide splits or mold mean it is past its best.
Give the likely cultivar and a visual freshness score from 1 to 10. Then list what a photo cannot tell you: the aroma, the tap sound, the thorn springiness, and whether the buyer will enjoy the taste."""

root_agent = Agent(
    name="durian_advisor",
    model=Gemini(model=MODEL, retry_options=types.HttpRetryOptions(attempts=3)),
    description="Classifies durian cultivars and visual freshness from photos.",
    instruction=INSTRUCTION,
)

app = App(root_agent=root_agent, name="app")

Sau đây là một vài thông tin quan trọng:

  • MODEL là nơi duy nhất mã nhận dạng mẫu xuất hiện. Mỗi tác nhân bạn thêm sau này đều kế thừa tác nhân đó, vì vậy, việc chuyển đổi mô hình chỉ là một thay đổi một dòng.
  • retry_options thử lại tối đa 3 lần đối với các lỗi tạm thời, chẳng hạn như giới hạn số lượng yêu cầu.
  • app = App(...) gói tác nhân cho cả sân chơi và máy chủ Cloud Run. Giữ nguyên tên ứng dụng app và tên tác nhân durian_advisor, khớp với máy chủ được tạo và agents-cli-manifest.yaml.

Thử nghiệm tác nhân trong sân chơi

Bắt đầu sử dụng ADK Playground:

cd ~/durian-advisor && agents-cli playground

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

INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

Nhấp vào Web Preview (Xem trước trên web) trong thanh công cụ Cloud Shell rồi chọn Preview on port 8080 (Xem trước trên cổng 8080). Nếu Giao diện người dùng của ADK Dev yêu cầu bạn chọn một tác nhân, hãy chọn app. Sau đó, hãy gửi câu lệnh này hoặc đính kèm ảnh sầu riêng của bạn bằng nút tải lên:

I'm at a stall looking at a round durian with pyramid-shaped thorns and a 5-point star at the base. The stem is green and moist. What cultivar is this, and will it taste sweet?

🔍 Kiểm tra bài làm

Tác nhân xác định đây là sầu riêng Musang King (D197) và cho điểm độ tươi cao vì cuống xanh ẩm. Sau đó, Gemini thừa nhận những điều mà một bức ảnh không thể cho biết: mùi hương, âm thanh khi gõ, độ đàn hồi của gai và liệu bạn có thích hương vị đó hay không.

Nhấn Ctrl + C trong dòng lệnh để dừng Playground trước khi tiếp tục.

6. Thêm các giác quan và khả năng ghi nhớ hương vị của con người

Camera không thể ngửi, nghe hoặc cảm nhận, vì vậy, bạn sẽ xây dựng các công cụ yêu cầu người mua thực hiện việc đó. Bạn cũng sẽ cung cấp cho nhân viên hỗ trợ thông tin về sở thích lâu dài của từng người mua. Trong bước này, bạn sẽ viết các công cụ; trong bước tiếp theo, bạn sẽ kết nối các công cụ đó với tác nhân.

Thêm danh mục giống cây trồng

Tạo app/durian_data.py:

cloudshell edit ~/durian-advisor/app/durian_data.py

Dán danh mục tham khảo này. Việc giữ dữ liệu trong mô-đun riêng giúp mã tác nhân ngắn gọn:

"""Reference catalog of durian cultivars."""

CULTIVAR_CATALOG = {
    "musang_king": {
        "code": "D197",
        "name": "Musang King (Mao Shan Wang)",
        "visual_markers": "5-point star seam at the base, pyramid-shaped thorns",
        "flavor": "rich, bittersweet, buttery custard",
        "bitterness": "medium",
    },
    "black_thorn": {
        "code": "D200",
        "name": "Black Thorn (Ochee)",
        "visual_markers": "Dark sunken tip at the base, round pumpkin-like body",
        "flavor": "sweet, creamy, slightly winey",
        "bitterness": "low",
    },
    "red_prawn": {
        "code": "D175",
        "name": "Red Prawn (Udang Merah)",
        "visual_markers": "Oval body, widely spaced and slightly hooked thorns",
        "flavor": "sweet, floral, soft and sticky",
        "bitterness": "none",
    },
    "xo_d24": {
        "code": "D24",
        "name": "XO D24 (Sultan, old tree)",
        "visual_markers": "Coin-sized brown ring at the base, dense sharp thorns",
        "flavor": "intense, bitter, with a boozy finish",
        "bitterness": "high",
    },
}

Thêm công cụ cảm quan

Tạo app/sensory_tools.py:

cloudshell edit ~/durian-advisor/app/sensory_tools.py

Dán mã sau:

"""Tools for cultivar lookup and human-in-the-loop sensory checks."""

from typing import Any, Literal

from .durian_data import CULTIVAR_CATALOG

AROMA_POINTS = {"sweet_fragrant": 4, "boozy_fermented": 3, "faint_grassy": 0, "sour_rotten": 0}
TAP_POINTS = {"hollow": 3, "solid": 0}
THORN_POINTS = {"springy": 3, "rigid": 0}


def get_cultivar_profile(cultivar_key: str) -> dict[str, Any]:
    """Looks up the visual markers, flavor, and bitterness of a durian cultivar.

    Args:
        cultivar_key: One of 'musang_king', 'black_thorn', 'red_prawn', or 'xo_d24'.
    """
    key = cultivar_key.strip().lower().replace(" ", "_").replace("-", "_")
    if key not in CULTIVAR_CATALOG:
        return {"status": "NOT_FOUND", "supported": list(CULTIVAR_CATALOG)}
    return {"status": "OK", "cultivar": CULTIVAR_CATALOG[key]}


def evaluate_human_sensory_clues(
    aroma: Literal["sweet_fragrant", "boozy_fermented", "faint_grassy", "sour_rotten"],
    tap_sound: Literal["hollow", "solid"],
    thorn_feel: Literal["springy", "rigid"],
) -> dict[str, Any]:
    """Scores the ripeness clues that only a human buyer can smell, hear, and feel.

    Args:
        aroma: What the buyer smells at the seam of the husk.
        tap_sound: What the buyer hears when tapping the husk.
        thorn_feel: How two thorns feel when the buyer presses them together.
    """
    score = AROMA_POINTS[aroma] + TAP_POINTS[tap_sound] + THORN_POINTS[thorn_feel]
    if aroma == "sour_rotten":
        verdict = "SPOILED"
    elif score >= 7:
        verdict = "RIPE"
    elif score >= 4:
        verdict = "NOT_QUITE_READY"
    else:
        verdict = "UNRIPE"
    return {"status": "OK", "ripeness_score": score, "max_score": 10, "verdict": verdict}

Cách hoạt động của các công cụ này:

  • ADK biến mỗi hàm thành một công cụ mà mô hình có thể gọi. Docstring trở thành nội dung mô tả công cụ và phần Args giải thích từng tham số.
  • Gợi ý về loại Literal[...] trở thành lựa chọn cố định trong giản đồ công cụ, vì vậy, Gemini phải liên kết "có mùi hơi say" với đúng một giá trị được phép, chẳng hạn như boozy_fermented.
  • get_cultivar_profile trả về trạng thái NOT_FOUND rõ ràng bằng các khoá được hỗ trợ thay vì tạo ra một giống cây trồng.

Thêm công cụ ghi nhớ khẩu vị

Tạo app/memory_tools.py:

cloudshell edit ~/durian-advisor/app/memory_tools.py

Dán mã sau:

"""Tool that remembers each buyer's durian palate across sessions."""

from typing import Any, Literal

from google.adk.tools import ToolContext


def save_palate_preference(
    favorite_flavors: str,
    bitterness_tolerance: Literal["none", "low", "medium", "high"],
    tool_context: ToolContext,
) -> dict[str, Any]:
    """Saves the buyer's durian taste preferences to their long-term profile.

    Args:
        favorite_flavors: Flavors and textures the buyer enjoys, such as
            'sweet, creamy custard'.
        bitterness_tolerance: How much bitterness the buyer enjoys.
    """
    profile = {
        "favorite_flavors": favorite_flavors,
        "bitterness_tolerance": bitterness_tolerance,
    }
    # The "user:" prefix scopes this key to the buyer, so it follows them
    # into every future session of this app.
    tool_context.state["user:palate_profile"] = profile
    return {"status": "SAVED", "palate_profile": profile}

Cách hoạt động của tính năng ghi nhớ khẩu vị:

  • ADK tự động truyền vào tool_context và ẩn tham số này khỏi mô hình, vì vậy Gemini chỉ thấy hai tham số về khẩu vị.
  • Tiền tố user: đặt phạm vi khoá trạng thái cho người dùng thay vì phiên hiện tại, vì vậy, hồ sơ sẽ theo người mua vào mọi cuộc trò chuyện mới.
  • Bạn không cần một công cụ "get" riêng biệt. Tác nhân đọc hồ sơ ngay trong phần hướng dẫn bằng phần giữ chỗ {user:palate_profile?}. ? sẽ làm trống phần giữ chỗ khi chưa có hồ sơ nào, thay vì báo lỗi.

🔍 Kiểm tra bài làm

Chọn một quả sầu riêng có mùi nồng, gõ vào nghe tiếng rỗng và gai đàn hồi:

cd ~/durian-advisor && uv run python -c "from app.sensory_tools import evaluate_human_sensory_clues as score; print(score('boozy_fermented', 'hollow', 'springy'))"

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

{'status': 'OK', 'ripeness_score': 9, 'max_score': 10, 'verdict': 'RIPE'}

7. Điều phối các tác nhân chuyên trách

Một tác nhân duy nhất xử lý các quy tắc về thị giác, chấm điểm cảm quan và kết hợp khẩu vị trong một câu lệnh thường bị nhầm lẫn. Thay vào đó, bạn sẽ giao từng công việc cho một chuyên gia chuyên trách và để một điều phối viên kết hợp các câu trả lời của họ:

  • vision_inspector_agent đọc giống cây trồng và độ tươi từ ảnh, sau đó trả về một báo cáo có cấu trúc.
  • sensory_sommelier_agent chấm điểm cho những gì người mua ngửi, nghe và cảm nhận, đồng thời kiểm tra giống cây trồng theo khẩu vị của họ.
  • durian_advisor nói chuyện với người mua, lưu lại khẩu vị của họ, gọi cho từng chuyên gia và viết phán quyết cuối cùng.

Tạo trình kiểm tra thị giác máy tính

Tạo app/vision_agent.py:

cloudshell edit ~/durian-advisor/app/vision_agent.py

Dán mã sau:

"""Vision inspector: reads the cultivar and freshness from a durian photo."""

from google.adk.agents import Agent
from pydantic import BaseModel, Field


class VisionReport(BaseModel):
    cultivar_key: str = Field(
        description="musang_king, black_thorn, red_prawn, xo_d24, or unknown"
    )
    visual_freshness: int = Field(description="1 (stale) to 10 (freshly fallen)")
    evidence: str = Field(description="The visual markers behind your answer")


vision_inspector_agent = Agent(
    name="vision_inspector_agent",
    description="Identifies a durian's cultivar and visual freshness from the buyer's photo or shell description.",
    mode="single_turn",
    # Specialists only see their tool-call input by default. Opt in to the
    # conversation history so this agent can see the uploaded photo.
    include_contents="default",
    # Report back to the coordinator instead of taking over the conversation.
    disallow_transfer_to_parent=True,
    disallow_transfer_to_peers=True,
    output_schema=VisionReport,
    instruction="""You are a durian vision inspector. Examine the durian photo or shell description in the conversation.
Cultivar markers:
- 5-point star seam at the base: musang_king
- Dark sunken tip at the base: black_thorn
- Oval body with widely spaced, slightly hooked thorns: red_prawn
- Coin-sized brown ring at the base and dense, sharp thorns: xo_d24
Freshness: a plump, moist, greenish stem and closed seams score high. A dry, shriveled stem or a split, moldy husk scores low.
If the markers are unclear, use 'unknown'.""",
)
  • output_schema=VisionReport giúp chuyên gia trả về dữ liệu có cấu trúc mà điều phối viên có thể dựa vào.
  • include_contents="default" cho phép chuyên gia này xem cuộc trò chuyện, bao gồm cả ảnh đã tải lên. Nếu không có, chuyên gia một lượt chỉ thấy yêu cầu mà điều phối viên chuyển vào.
  • disallow_transfer_to_parent và disallow_transfer_to_peers xoá công cụ transfer_to_agent mà ADK sẽ cung cấp cho tác nhân phụ này. Một chuyên gia nhìn thấy toàn bộ cuộc trò chuyện có thể muốn chuyển cuộc trò chuyện lại cho điều phối viên thay vì trả lại báo cáo.

Tạo chuyên gia cảm quan

Tạo app/sensory_agent.py:

cloudshell edit ~/durian-advisor/app/sensory_agent.py

Dán mã sau:

"""Sensory sommelier: scores the buyer's senses and checks palate fit."""

from google.adk.agents import Agent
from pydantic import BaseModel, Field

from .sensory_tools import evaluate_human_sensory_clues, get_cultivar_profile


class SensoryClues(BaseModel):
    cultivar_key: str = Field(description="Cultivar from the vision inspector")
    aroma: str = Field(description="What the buyer smelled at the seam")
    tap_sound: str = Field(description="What the buyer heard when tapping the husk")
    thorn_feel: str = Field(description="How the thorns felt when pressed together")


sensory_sommelier_agent = Agent(
    name="sensory_sommelier_agent",
    description="Scores the smell, sound, and touch clues the buyer reports, and checks the cultivar against their palate.",
    mode="single_turn",
    # Report back to the coordinator instead of taking over the conversation.
    disallow_transfer_to_parent=True,
    disallow_transfer_to_peers=True,
    input_schema=SensoryClues,
    instruction="""You are a durian sensory sommelier.
Buyer palate profile: {user:palate_profile?}

1. Call evaluate_human_sensory_clues with the buyer's aroma, tap sound, and thorn feel.
2. Call get_cultivar_profile for the cultivar.
3. Compare the cultivar's bitterness with the buyer's bitterness tolerance.
Report the ripeness verdict, the palate fit, and one sentence of advice.""",
    tools=[evaluate_human_sensory_clues, get_cultivar_profile],
)
  • input_schema=SensoryClues xác định những thông tin mà điều phối viên phải truyền vào: giống cây trồng và ba báo cáo cảm quan của người mua, theo cách diễn đạt của riêng họ. Chuyên gia sẽ liên kết những từ đó với các giá trị được phép của công cụ.
  • {user:palate_profile?} đưa bảng màu đã lưu của người mua vào hướng dẫn để chuyên gia có thể đánh giá mức độ phù hợp mà không cần tra cứu bộ nhớ.
  • Không có bộ bài tập thực hành chuyên biệt nào model. Cả hai đều kế thừa MODEL của điều phối viên.
  • Cả hai chuyên gia đều sử dụng cùng hai cờ chuyển, vì vậy, mỗi chuyên gia luôn báo cáo lại cho điều phối viên.

Kết nối điều phối viên

Mở app/agent.py:

cloudshell edit ~/durian-advisor/app/agent.py

Thay thế nội dung của tệp bằng điều phối viên:

"""Durian advisor: a concierge that coordinates vision and sensory specialists."""

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from .memory_tools import save_palate_preference
from .sensory_agent import sensory_sommelier_agent
from .vision_agent import vision_inspector_agent

MODEL = "gemini-3.8-flash"

root_agent = Agent(
    name="durian_advisor",
    model=Gemini(model=MODEL, retry_options=types.HttpRetryOptions(attempts=3)),
    description="Durian concierge that combines what the camera sees with what the buyer senses.",
    instruction="""You are a friendly durian concierge helping a buyer at a fruit stall.
Buyer palate profile: {user:palate_profile?}

1. When the buyer shares taste preferences, call save_palate_preference.
2. When the buyer shows or describes a durian, call vision_inspector_agent.
3. A camera cannot smell, hear, or feel. Unless the buyer already reported the seam aroma, tap sound, and thorn feel, ask them to check. Then call sensory_sommelier_agent.
4. Call one specialist at a time. Finish with ONE verdict covering the cultivar, ripeness, and palate fit. If the durian does not suit their palate, suggest a cultivar that does.""",
    tools=[save_palate_preference],
    sub_agents=[vision_inspector_agent, sensory_sommelier_agent],
)

app = App(root_agent=root_agent, name="app")

Vì cả hai chuyên gia đều sử dụng mode="single_turn", nên ADK cung cấp cho điều phối viên hai công cụ bổ sung có tên là vision_inspector_agent và sensory_sommelier_agent. Hướng dẫn này đề cập đến các tệp đó bằng tên tương ứng.

Kiểm thử trình điều phối trong Playground

Bắt đầu lại sân chơi:

cd ~/durian-advisor && agents-cli playground

Mở Bản xem trước trên web trên cổng 8080 và trò chuyện ngắn với tác nhân.

Giúp Gemini hiểu khẩu vị của bạn:

Hi! Please remember my taste: I love sweet, creamy custard durians and I can't stand bitterness.

Mở thẻ State (Trạng thái). Bạn sẽ thấy hồ sơ đã lưu của mình, tương tự như:

{
  "user:palate_profile": {
    "favorite_flavors": "sweet, creamy custard",
    "bitterness_tolerance": "none"
  }
}

Cho Gemini xem một quả sầu riêng (mô tả hoặc đính kèm ảnh):

The vendor is showing me a round durian with a coin-sized brown ring at the base and dense, sharp thorns. The stem is green and moist. Should I buy it?

Điều phối viên gọi vision_inspector_agent, xác định XO D24. Sau đó, Gemini yêu cầu bạn ngửi đường rãnh, gõ vào vỏ và ấn hai gai vào nhau.

Báo cáo những gì bạn cảm nhận được:

It smells a bit boozy, the knock sounds hollow, and the thorns spring back when I press them.

Bắt đầu từ đầu: nhấp vào Phiên mới rồi hỏi:

Which durian should I pick today?

🔍 Kiểm tra bài làm

  • Sau khi bạn báo cáo cảm nhận của mình, người điều phối sẽ gọi cho sensory_sommelier_agent và đưa ra một phán quyết: XO D24 đã chín (9/10), nhưng vị đắng nồng của nó không hợp với khẩu vị của bạn, vì vậy hãy yêu cầu Red Prawn (D175) hoặc Black Thorn (D200).
  • Trong thẻ Sự kiện, bạn có thể thấy durian_advisor gọi cho từng chuyên gia, còn sensory_sommelier_agent gọi cho evaluate_human_sensory_clues và get_cultivar_profile.
  • Trong phiên mới, nhân viên hỗ trợ đã biết khẩu vị của bạn và đề xuất một giống cà phê ngọt, không đắng mà không cần hỏi lại.

Nhấn Ctrl + C trong Terminal để dừng Playground.

8. Triển khai bằng Antigravity (Không bắt buộc)

Bạn đã tạo và thử nghiệm tác nhân theo cách thủ công. Bây giờ, bạn sẽ để Antigravity CLI (agy), tác nhân lập trình AI của Google cho thiết bị đầu cuối, triển khai ứng dụng. Kỹ năng CLI của tác nhân hướng dẫn Antigravity cách triển khai tác nhân ADK đúng cách.

Bật API triển khai

Bật các API Cloud Run, Cloud Build và Artifact Registry mà Agents CLI sử dụng để tạo và lưu trữ tác nhân:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com

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

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

Cài đặt các kỹ năng của Agents CLI

Cài đặt 7 kỹ năng CLI của Agents vào thư mục dự án của bạn, nơi Antigravity tự động phát hiện các kỹ năng đó:

cd ~/durian-advisor && agents-cli setup --workspace

🔍 Kiểm tra bài làm

ls -1 ~/durian-advisor/.agents/skills

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

google-agents-cli-adk-code
google-agents-cli-deploy
google-agents-cli-eval
google-agents-cli-observability
google-agents-cli-publish
google-agents-cli-scaffold
google-agents-cli-workflow

Bắt đầu Antigravity CLI

Antigravity CLI được cài đặt sẵn trong Cloud Shell. Bắt đầu từ thư mục dự án:

cd ~/durian-advisor && agy --dangerously-skip-permissions

Trong lần chạy đầu tiên, Antigravity sẽ yêu cầu bạn đăng nhập bằng Tài khoản Google, chọn một chủ đề màu sắc, chấp nhận điều khoản dịch vụ và tin tưởng thư mục hiện tại.

Yêu cầu Antigravity triển khai

Dán câu lệnh này vào Antigravity:

Use the google-agents-cli-deploy skill to deploy this ADK agent to Cloud Run in us-central1 as a private service. Keep GOOGLE_CLOUD_LOCATION=global so Gemini keeps working, save the exact service URL to .env as AGENT_BASE_URL, and smoke-test the deployed agent with agents-cli run.

Antigravity đọc kỹ năng và có thể chạy các bài kiểm thử của dự án trước. Sau đó, tập lệnh này sẽ chạy agents-cli deploy để tạo vùng chứa bằng Cloud Build và triển khai dịch vụ durian-advisor, đồng thời gửi một thông báo kiểm thử đến dịch vụ đang hoạt động. Toàn bộ quá trình chạy mất khoảng 5 đến 8 phút.

Khi Antigravity hoàn tất, hãy thoát bằng cách nhấn phím Ctrl + D hai lần.

🔍 Kiểm tra bài làm

Gửi tin nhắn cho tác nhân đã triển khai bằng URL mà Antigravity đã lưu:

cd ~/durian-advisor && source .env && agents-cli run --url "$AGENT_BASE_URL" --mode adk "Which durian suits a beginner?"

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

Querying remote agent: https://durian-advisor-123456789012.us-central1.run.app (mode: adk)
[user]: Which durian suits a beginner?
[durian_advisor]: For beginners, you want a durian that is sweet, creamy, and gentle on the palate, with little to no bitterness...

Bây giờ, hãy xác nhận rằng dịch vụ từ chối các lệnh gọi không có mã thông báo:

curl -s -o /dev/null -w "%{http_code}\n" "$AGENT_BASE_URL"

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

403

9. Lập trình theo cảm hứng cho chatbot trên web (Không bắt buộc)

Tác nhân của bạn đang hoạt động nhưng ở chế độ riêng tư. Bây giờ, bạn sẽ tiếp tục cuộc trò chuyện với Antigravity (vốn đã biết tác nhân, khoá trạng thái và URL của bạn) và yêu cầu Antigravity tạo và triển khai một chatbot web cho người mua sầu riêng.

Tiếp tục Antigravity

cd ~/durian-advisor && agy --dangerously-skip-permissions

Trong Antigravity, hãy chạy lệnh dấu gạch chéo sau đây rồi chọn cuộc trò chuyện triển khai của bạn trong danh sách:

/resume

Yêu cầu Antigravity tạo chatbot

Dán câu lệnh này:

Build a mobile-friendly "Durian Sommelier" web chatbot in a new web/ folder that talks to our deployed agent at AGENT_BASE_URL (ADK app name "app").

- Add palate quick-set buttons, a photo upload, and one-tap sensory chips: Smells sweet, Smells boozy, Hollow knock, Solid knock, Thorns spring back, Thorns feel stiff.
- Use a small FastAPI server that proxies chat requests to the agent with a Google ID token, because the agent service is private.
- Show only durian_advisor's replies in the chat, not the specialists' intermediate output.
- Keep a stable user ID per browser and reuse one ADK session, creating a new one if it is missing.

Deploy it to Cloud Run as durian-sommelier-web in us-central1 with public access. Run it as a new service account named durian-sommelier-web that can invoke durian-advisor, and print the URL.

Antigravity viết ứng dụng, tạo tài khoản dịch vụ, cấp cho tài khoản đó vai trò Người gọi Cloud Run trên durian-advisor và triển khai ứng dụng bằng Cloud Build. Thường thì công cụ này sẽ kiểm tra điểm cuối trò chuyện trước khi hoàn tất. Toàn bộ quá trình chạy mất khoảng 10 phút. Khi URL được in ra, hãy thoát bằng cách nhấn phím Ctrl + D hai lần.

🔍 Kiểm tra bài làm

Mở URL https://durian-sommelier-web-....run.app mà Antigravity đã in, sau đó:

  1. Nhấn vào một nút hương vị, chẳng hạn như nút ngọt và béo. Tác nhân xác nhận rằng đã lưu bảng màu của bạn.
  2. Tải ảnh sầu riêng lên hoặc nhập nội dung mô tả ngắn về vỏ sầu riêng. Tác nhân xác định giống cây trồng và yêu cầu bạn kiểm tra cảm quan.
  3. Nhấn vào các thẻ cảm quan phù hợp với sầu riêng của bạn. Tác nhân trả lời bằng một kết quả đánh giá bao gồm độ chín và mức độ phù hợp với khẩu vị.

10. Dọn dẹp

Xoá các tài nguyên bạn đã tạo để ngừng phát sinh phí.

Xoá các dịch vụ Cloud Run

Xoá chatbot trên web:

gcloud run services delete durian-sommelier-web --region us-central1 --quiet

Xoá dịch vụ tác nhân:

gcloud run services delete durian-advisor --region us-central1 --quiet

Xoá tài khoản dịch vụ

Xoá tài khoản dịch vụ mà chatbot web đã chạy dưới danh nghĩa:

gcloud iam service-accounts delete "durian-sommelier-web@$(gcloud config get-value project).iam.gserviceaccount.com" --quiet

Xoá hình ảnh vùng chứa

Các bản triển khai nguồn Cloud Run sẽ đẩy hình ảnh vùng chứa của mỗi dịch vụ vào một kho lưu trữ Artifact Registry có tên là cloud-run-source-deploy. Các bản triển khai khác trong dự án của bạn có thể dùng chung kho lưu trữ này. Chỉ xoá hai hình ảnh của lớp học lập trình này và giữ lại kho lưu trữ.

Xoá hình ảnh của nhân viên hỗ trợ:

gcloud artifacts packages delete durian-advisor --repository cloud-run-source-deploy --location us-central1 --quiet

Xoá hình ảnh của chatbot trên web:

gcloud artifacts packages delete durian-sommelier-web --repository cloud-run-source-deploy --location us-central1 --quiet

🔍 Kiểm tra bài làm

gcloud run services list --region us-central1

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

Listed 0 items.

Xoá các tệp trên thiết bị

Xoá thư mục dự án, bao gồm cả các kỹ năng và môi trường ảo:

rm -rf ~/durian-advisor

Nếu muốn, bạn có thể gỡ cài đặt Giao diện dòng lệnh (CLI) của tác nhân:

uv tool uninstall google-agents-cli

Xoá toàn bộ dự án trên đám mây của Google (Không bắt buộc)

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

11. Xin chúc mừng

Xin chúc mừng! Bạn đã xây dựng và thử nghiệm một hệ thống đa tác nhân Durian Sommelier đa phương thức bằng ADK và Agents CLI. Nếu thực hiện các bước không bắt buộc, bạn cũng đã triển khai ứng dụng lên Cloud Run bằng Antigravity CLI.

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

  • Tạo một dự án ADK bằng agents-cli create và xây dựng một tác nhân thị giác đa phương thức bằng một chế độ cài đặt MODEL duy nhất
  • Tạo các công cụ có con người nằm trong quy trình cho khứu giác, thính giác và xúc giác, cùng với bộ nhớ vị giác được lưu trữ trong trạng thái ADK trong phạm vi user:
  • Chia tác nhân thành một điều phối viên durian_advisor và hai chuyên gia single_turn mà tác nhân gọi như các công cụ
  • (Không bắt buộc) Sử dụng Antigravity CLI với các kỹ năng của Agents CLI để triển khai tác nhân và chatbot web lên Cloud Run

Các bước tiếp theo