Trang này được dịch bởi Cloud Translation API.

Sử dụng Máy chủ MCP trên Cloud Run với một ADK Agent

1. Giới thiệu

Phòng thí nghiệm này tập trung vào việc triển khai và triển khai một dịch vụ tác nhân khách hàng. Bạn sẽ sử dụng Bộ phát triển tác nhân (ADK) để tạo một tác nhân AI sử dụng các công cụ từ xa, chẳng hạn như máy chủ MCP được tạo trong Phòng thí nghiệm 1. Nguyên tắc chính về cấu trúc được minh hoạ là sự phân tách các mối lo ngại, với một lớp lý luận riêng biệt (tác nhân) giao tiếp với một lớp công cụ riêng biệt (máy chủ MCP) thông qua một API bảo mật.

Trong phòng thí nghiệm 1, bạn đã tạo một máy chủ MCP cung cấp dữ liệu về các loài động vật trong một vườn thú giả tưởng cho các LLM, chẳng hạn như khi sử dụng Gemini CLI. Trong lớp học lập trình này, chúng ta sẽ tạo một tác nhân hướng dẫn viên du lịch cho vườn thú giả tưởng. Trợ lý sẽ sử dụng cùng một máy chủ MCP từ phòng thí nghiệm 1 để truy cập thông tin chi tiết về các loài động vật trong vườn thú, đồng thời sử dụng Wikipedia để tạo trải nghiệm hướng dẫn tham quan tốt nhất.

Cuối cùng, chúng ta sẽ triển khai tác nhân hướng dẫn tham quan cho Google Cloud Run để tất cả khách tham quan vườn thú đều có thể truy cập chứ không chỉ chạy cục bộ.

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

Một máy chủ MCP đang chạy trên Cloud Run hoặc URL dịch vụ được liên kết của máy chủ đó.
Một dự án trên Google Cloud đã bật tính năng thanh toán.

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

Cách cấu trúc dự án Python để triển khai ADK.
Cách triển khai một tác nhân sử dụng công cụ bằng google-adk.
Cách kết nối một tác nhân với máy chủ MCP từ xa cho bộ công cụ của tác nhân đó.
Cách triển khai một ứng dụng Python dưới dạng vùng chứa không máy chủ cho Cloud Run.
Cách thiết lập xác thực an toàn giữa các dịch vụ bằng cách sử dụng vai trò IAM.
Cách xoá tài nguyên trên Cloud để tránh phát sinh chi phí trong tương lai.

Bạn cần có

Tài khoản Google Cloud và dự án trên Google Cloud
Một trình duyệt web như Chrome

2. Tại sao nên triển khai lên Cloud Run?

Cloud Run là lựa chọn phù hợp để lưu trữ các tác nhân ADK vì đây là một nền tảng không máy chủ. Điều này có nghĩa là bạn có thể tập trung vào mã của mình mà không cần quản lý cơ sở hạ tầng cơ bản. Chúng tôi sẽ xử lý công việc vận hành cho bạn.

Hãy coi đây như một cửa hàng tạm thời: cửa hàng này chỉ mở và sử dụng tài nguyên khi khách hàng (yêu cầu) đến. Khi không có khách hàng, cửa hàng sẽ đóng cửa hoàn toàn và bạn không phải trả tiền cho một cửa hàng trống.

Các tính năng chính

Chạy vùng chứa ở mọi nơi:

Bạn mang theo một vùng chứa (hình ảnh Docker) có ứng dụng của bạn bên trong.
Cloud Run chạy ứng dụng đó trên cơ sở hạ tầng của Google.
Không cần vá hệ điều hành, thiết lập máy ảo hoặc lo lắng về việc mở rộng quy mô.

Tự động mở rộng quy mô:

Nếu không có người dùng nào sử dụng ứng dụng của bạn → 0 phiên bản chạy (bạn trả 0 USD khi không hoạt động).
Nếu có 1.000 yêu cầu truy cập vào đó → nó sẽ tạo ra nhiều bản sao nếu cần.

Không trạng thái theo mặc định:

Mỗi yêu cầu có thể chuyển đến một phiên bản khác.
Nếu cần lưu trữ trạng thái, hãy sử dụng một dịch vụ bên ngoài như Cloud SQL, Firestore hoặc Redis.

Hỗ trợ mọi ngôn ngữ hoặc khung:

Miễn là chạy trong một vùng chứa Linux, Cloud Run không quan tâm đến việc đó là Python, Go, Node.js, Java hay .Net.

Chỉ thanh toán cho những gì bạn sử dụng:

Tính phí theo yêu cầu + thời gian tính toán (xuống đến 100 mili giây).
Bạn không phải trả tiền cho các tài nguyên không hoạt động như khi dùng một máy ảo truyền thống.

3. Thiết lập và yêu cầu

Thiết lập môi trường theo tốc độ của riêng bạn

Đăng nhập vào Google Cloud Console rồi tạo một dự án mới hoặc sử dụng lại một dự án hiện có. Nếu chưa có tài khoản Gmail hoặc Google Workspace, bạn phải tạo một tài khoản.

Tên dự án là tên hiển thị của những người tham gia dự án này. Đây là một chuỗi ký tự mà các API của Google không sử dụng. Bạn luôn có thể cập nhật thông tin này.
Mã dự án là giá trị duy nhất trên tất cả các dự án trên Google Cloud và không thể thay đổi (bạn không thể thay đổi mã này sau khi đã đặt). Cloud Console sẽ tự động tạo một chuỗi duy nhất; thường thì bạn không cần quan tâm đến chuỗi này. Trong hầu hết các lớp học lập trình, bạn sẽ cần tham chiếu đến Mã dự án (thường được xác định là PROJECT_ID). Nếu không thích mã nhận dạng được tạo, bạn có thể tạo một mã nhận dạng ngẫu nhiên khác. Hoặc bạn có thể thử tên người dùng của riêng mình để xem tên đó có được chấp nhận hay không. Bạn không thể thay đổi tên này sau bước này và tên này sẽ tồn tại trong suốt thời gian của dự án.
Để bạn nắm được thông tin, có một giá trị thứ ba là Số dự án mà một số API sử dụng. Tìm hiểu thêm về cả 3 giá trị này trong tài liệu.

Tiếp theo, bạn cần bật tính năng thanh toán trong Cloud Console để sử dụng các tài nguyên/API trên Cloud. Việc thực hiện lớp học lập trình này sẽ không tốn nhiều chi phí, nếu có. Để tắt các tài nguyên nhằm tránh bị tính phí ngoài phạm vi hướng dẫn này, bạn có thể xoá các tài nguyên đã tạo hoặc xoá dự án. Người dùng mới của Google Cloud đủ điều kiện tham gia chương trình Dùng thử miễn phí 300 USD.

Khởi động Cloud Shell

Chuyển đến Trình chỉnh sửa Cloud Shell

Nếu thiết bị đầu cuối không xuất hiện ở cuối màn hình, hãy mở thiết bị đầu cuối:

Nhấp vào Terminal (Thiết bị đầu cuối)
Nhấp vào Thiết bị đầu cuối mới

Trong thiết bị đầu cuối, hãy thiết lập dự án bằng lệnh này. Nếu bạn đã hoàn thành phòng thí nghiệm 1, hãy đảm bảo rằng bạn đang sử dụng cùng một mã dự án:

gcloud config set project [YOUR-PROJECT-ID]

Nếu không nhớ mã dự án, bạn có thể liệt kê tất cả mã dự án bằng cách dùng lệnh:

gcloud projects list | awk '/PROJECT_ID/{print $2}'

4. Nếu được nhắc uỷ quyền, hãy nhấp vào Uỷ quyền để tiếp tục.

5. Bạn sẽ thấy thông báo sau:

Updated property [core/project].

If you see a `WARNING` and are asked `Do you want to continue (Y/n)?`,

then you have likely entered the project ID incorrectly. Press `n`,

press `Enter`, and try to run the `gcloud config set project` command again.

4. Trước khi bắt đầu

Bật API và đặt các biến môi trường

Bật tất cả các dịch vụ cần thiết:

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

Kết quả đầu ra dự kiến

Operation "operations/acat.p2-[GUID]" finished successfully.

Định cấu hình khu vực mặc định để sử dụng các mô hình nhúng Vertex AI. Đọc thêm về các địa điểm có Vertex AI. Trong ví dụ này, chúng ta sẽ sử dụng khu vực europe-west1.

gcloud config set compute/region europe-west1

5. Tải và cài đặt ADK, đồng thời tạo thư mục dự án

Tạo thư mục dự án.

Lệnh này tạo một thư mục chính cho lớp học lập trình chứa mã nguồn của tác nhân.

cd && mkdir zoo_guide_agent && cd zoo_guide_agent

Tạo môi trường ảo.

python3 -m venv .venv

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

source .venv/bin/activate

Tạo tệp requirements.txt. Tệp này liệt kê các thư viện Python mà tác nhân của bạn cần. Lệnh sau đây sẽ tạo và điền sẵn nội dung cho tệp.

cloudshell edit requirements.txt

google-adk==1.12.0
langchain-community
wikipedia

Bạn nên chạy lệnh này từ thư mục dự án chính, zoo_guide_agent.

pip install -r requirements.txt

Đặt các biến cho dự án, khu vực và người dùng hiện tại. Đây là một cách mạnh mẽ hơn để chạy các lệnh này.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_REGION=$(gcloud config get-value compute/region)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

Tạo và mở tệp .env để xác thực tác nhân trong thư mục zoo_guide_agent.

cloudshell edit .env

Lệnh chỉnh sửa cloudshell sẽ mở tệp .env trong trình chỉnh sửa ở phía trên cửa sổ dòng lệnh. Nhập nội dung sau vào tệp .env rồi quay lại dòng lệnh.

MODEL="gemini-2.5-flash"
SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

Thêm URL máy chủ MCP. Nếu bạn đã hoàn thành phòng thực hành 1, hãy làm theo các bước sau để sử dụng máy chủ MCP mà bạn đã tạo trong phòng thực hành 1:

Cấp cho danh tính dịch vụ Cloud Run quyền gọi máy chủ MCP từ xa

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

Lưu URL máy chủ MCP từ Lab 1 vào một biến môi trường.

echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp/" >> .env

Nếu bạn đang sử dụng đường liên kết đến máy chủ MCP công khai, hãy chạy lệnh sau và thay thế PROJECT_NUMBER bằng nội dung được cung cấp.

echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp/" >> .env

6. Tạo quy trình công việc của nhân viên hỗ trợ

Tạo tệp init.py

Tạo tệp init.py. Tệp này cho Python biết rằng thư mục zoo_guide_agent là một gói.

cloudshell edit __init__.py

Lệnh trên sẽ mở trình chỉnh sửa mã. Thêm mã sau vào __init__.py:

from . import agent

Tạo tệp agent.py chính

Tạo tệp agent.py chính. Lệnh này sẽ tạo tệp Python và dán mã hoàn chỉnh cho hệ thống nhiều tác nhân của bạn.

cloudshell edit agent.py

Bước 1: Nhập và thiết lập ban đầu

Khối đầu tiên này sẽ đưa tất cả các thư viện cần thiết từ ADK và Google Cloud vào. Thao tác này cũng thiết lập tính năng ghi nhật ký và tải các biến môi trường từ tệp .env của bạn. Đây là bước quan trọng để truy cập vào mô hình và URL máy chủ.

Thêm đoạn mã sau vào tệp agent.py:

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")

Bước 2: Xác định các công cụ (Khả năng của đặc vụ)

Một tác nhân chỉ hoạt động hiệu quả khi nhận được các công cụ hữu ích. Trong phần này, chúng ta sẽ xác định tất cả các chức năng mà tác nhân của chúng ta sẽ có, bao gồm cả một hàm tuỳ chỉnh để lưu dữ liệu, một Công cụ MCP kết nối với máy chủ MCP bảo mật của chúng ta cùng với một Công cụ Wikipedia.

Thêm mã sau vào cuối agent.py:

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}


# Configuring the MCP Tool to connect to the Zoo MCP server

mcp_server_url = os.getenv("MCP_SERVER_URL")
if not mcp_server_url:
    raise ValueError("The environment variable MCP_SERVER_URL is not set.")

def get_id_token():
    """Get an ID token to authenticate with the MCP server."""
    target_url = os.getenv("MCP_SERVER_URL")
    audience = target_url.split('/mcp/')[0]
    request = google.auth.transport.requests.Request()
    id_token = google.oauth2.id_token.fetch_id_token(request, audience)
    return id_token

"""
# Use this code if you are using the public MCP Server and comment out the code below defining mcp_tools
mcp_tools = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url=mcp_server_url
    )
)
"""

mcp_tools = MCPToolset(
            connection_params=StreamableHTTPConnectionParams(
                url=mcp_server_url,
                headers={
                    "Authorization": f"Bearer {get_id_token()}",
                },
            ),
        )

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

Giải thích về 3 công cụ

add_prompt_to_state 📝

Công cụ này ghi nhớ những câu hỏi của khách tham quan vườn thú. Khi khách truy cập hỏi "Sư tử ở đâu?", công cụ này sẽ lưu câu hỏi cụ thể đó vào bộ nhớ của nhân viên hỗ trợ để các nhân viên hỗ trợ khác trong quy trình làm việc biết cần nghiên cứu thông tin gì.

Cách thức: Đây là một hàm Python ghi câu lệnh của khách truy cập vào từ điển tool_context.state dùng chung. Ngữ cảnh công cụ này thể hiện bộ nhớ ngắn hạn của trợ lý cho một cuộc trò chuyện duy nhất. Dữ liệu do một tác nhân lưu vào trạng thái có thể được tác nhân tiếp theo đọc trong quy trình.

MCPToolset 🦁

Thao tác này dùng để kết nối tác nhân hướng dẫn viên du lịch với máy chủ MCP của vườn thú được tạo trong Bài tập 1. Máy chủ này có các công cụ đặc biệt để tra cứu thông tin cụ thể về động vật của chúng tôi, chẳng hạn như tên, tuổi và chuồng của chúng.

Cách thức: Kết nối an toàn với URL máy chủ riêng của vườn thú. Nó sử dụng get_id_token để tự động lấy "thẻ khoá" bảo mật (mã thông báo nhận dạng tài khoản dịch vụ) nhằm chứng minh danh tính và giành quyền truy cập.

LangchainTool 🌍

Điều này giúp tác nhân hướng dẫn viên du lịch có kiến thức chung về thế giới. Khi khách truy cập đặt câu hỏi không có trong cơ sở dữ liệu của vườn thú, chẳng hạn như "Sư tử ăn gì trong tự nhiên?", công cụ này cho phép nhân viên tìm câu trả lời trên Wikipedia.

Cách thức: Nó hoạt động như một bộ chuyển đổi, cho phép tác nhân của chúng tôi sử dụng công cụ WikipediaQueryRun được tạo sẵn từ thư viện LangChain.

Tài nguyên:

Bước 3: Xác định các Đặc vụ chuyên trách

Tiếp theo, chúng ta sẽ xác định tác nhân nghiên cứu và tác nhân định dạng phản hồi. Tác nhân nghiên cứu là "bộ não" của hoạt động này. Tác nhân này lấy câu lệnh của người dùng từ State dùng chung, kiểm tra các công cụ mạnh mẽ của câu lệnh (Công cụ máy chủ MCP của Zoo và Công cụ Wikipedia) rồi quyết định sử dụng công cụ nào để tìm câu trả lời.

Vai trò của tác nhân định dạng phản hồi là trình bày. Công cụ này không sử dụng bất kỳ công cụ nào để tìm thông tin mới. Thay vào đó, nó lấy dữ liệu thô do tác nhân Researcher thu thập (được truyền qua Trạng thái) và sử dụng kỹ năng ngôn ngữ của LLM để chuyển đổi dữ liệu đó thành một câu trả lời thân thiện, mang tính trò chuyện.

Thêm mã sau vào cuối agent.py:

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    {{ PROMPT }}
    """,
    tools=[
        mcp_tools,
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    {{ research_data }}
    """
)

Bước 4: Tác nhân quy trình công việc

Tác nhân quy trình công việc đóng vai trò là người quản lý "hậu trường" cho chuyến tham quan vườn thú. Công cụ này sẽ nhận yêu cầu nghiên cứu và đảm bảo rằng 2 tác nhân mà chúng ta đã xác định ở trên thực hiện công việc theo đúng thứ tự: đầu tiên là nghiên cứu, sau đó là định dạng. Điều này tạo ra một quy trình đáng tin cậy và dễ dự đoán để trả lời câu hỏi của khách truy cập.

Cách thức: Đây là một SequentialAgent, một loại tác nhân đặc biệt không tự suy nghĩ. Công việc duy nhất của nó là chạy danh sách sub_agents (nhà nghiên cứu và người định dạng) theo một trình tự cố định, tự động truyền bộ nhớ dùng chung từ người này sang người khác.

Thêm khối mã này vào cuối agent.py:

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

Bước cuối cùng: Tập hợp quy trình làm việc chính

Agent này được chỉ định là root_agent mà khung ADK dùng làm điểm bắt đầu cho mọi cuộc trò chuyện mới. Vai trò chính của nó là điều phối quy trình tổng thể. Nó đóng vai trò là bộ điều khiển ban đầu, quản lý lượt đầu tiên của cuộc trò chuyện.

Thêm khối mã cuối cùng này vào cuối agent.py:

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

Tệp agent.py của bạn hiện đã hoàn tất! Bằng cách xây dựng theo cách này, bạn có thể thấy cách mỗi thành phần (công cụ, tác nhân nhân viên và tác nhân quản lý) có một vai trò cụ thể trong việc tạo ra hệ thống thông minh cuối cùng. Tiếp theo là triển khai!

7. Chuẩn bị ứng dụng để triển khai

Sau khi chuẩn bị xong môi trường cục bộ, bước tiếp theo là chuẩn bị dự án Google Cloud để triển khai. Bước này bao gồm việc kiểm tra cấu trúc tệp của nhân viên hỗ trợ lần cuối để đảm bảo cấu trúc đó tương thích với lệnh triển khai. Quan trọng hơn, bạn sẽ định cấu hình một quyền IAM quan trọng cho phép dịch vụ Cloud Run đã triển khai thay mặt bạn thực hiện hành động và gọi các mô hình Vertex AI. Việc hoàn tất bước này sẽ đảm bảo môi trường đám mây đã sẵn sàng để chạy tác nhân của bạn một cách thành công.

Tải các biến vào phiên shell bằng cách chạy lệnh source.

source .env

Cấp cho tài khoản dịch vụ vai trò Người dùng Vertex AI để cấp cho tài khoản này quyền đưa ra dự đoán và gọi các mô hình của Google.

# Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

8. Triển khai tác nhân bằng ADK CLI

Khi mã cục bộ đã sẵn sàng và dự án Google Cloud đã được chuẩn bị, đã đến lúc triển khai tác nhân. Bạn sẽ sử dụng lệnh adk deploy cloud_run, một công cụ tiện lợi giúp tự động hoá toàn bộ quy trình triển khai. Lệnh duy nhất này sẽ đóng gói mã của bạn, tạo một hình ảnh vùng chứa, đẩy hình ảnh đó vào Artifact Registry và khởi chạy dịch vụ trên Cloud Run, giúp bạn truy cập vào dịch vụ này trên web.

Tạo tệp .gcloudignore

Để giảm thời gian triển khai, chúng ta muốn tạo một tệp .gcloudignore. Chạy các lệnh sau để thực hiện việc này. Các lệnh sau để triển khai tác nhân của bạn.

cloudshell edit .gcloudignore

Lệnh chỉnh sửa cloudshell sẽ mở tệp .gcloudignore trong trình chỉnh sửa ở phía trên cửa sổ dòng lệnh. Viết nội dung sau vào tệp rồi lưu tệp đó. Sau đó, hãy quay lại thiết bị đầu cuối để chạy các lệnh triển khai trong phần tiếp theo.

.venv/

Triển khai

Chạy các lệnh sau để triển khai tác nhân.

# Run the deployment command
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  .

gcloud run services update zoo-tour-guide \
  --region=europe-west1 \
  --update-labels=dev-tutorial=codelab-adk

Chấp nhận câu lệnh

Bạn có thể thấy lời nhắc sau:

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?

Nhập Y rồi nhấn ENTER.

Bạn có thể thấy lời nhắc sau:

Allow unauthenticated invocations to [your-service-name] (y/N)?.

Đối với phòng thí nghiệm này, chúng ta muốn cho phép các lệnh gọi chưa được xác thực để dễ dàng kiểm thử, hãy nhập y rồi nhấn Enter.

Lấy đường liên kết triển khai

Sau khi thực thi thành công, lệnh này sẽ cung cấp URL của dịch vụ Cloud Run đã triển khai. (Đường dẫn này sẽ có dạng như https://zoo-tour-guide-123456789.europe-west1.run.app). Sao chép URL này cho nhiệm vụ tiếp theo.

9. Kiểm thử nhân viên hỗ trợ đã triển khai

Giờ đây, khi nhân viên hỗ trợ của bạn đang hoạt động trên Cloud Run, bạn sẽ thực hiện một kiểm thử để xác nhận rằng quá trình triển khai đã thành công và nhân viên hỗ trợ đang hoạt động như mong đợi. Bạn sẽ dùng URL dịch vụ công khai (chẳng hạn như https://zoo-tour-guide-123456789.europe-west1.run.app/) để truy cập vào giao diện web của ADK và tương tác với tác nhân.

Mở URL của dịch vụ Cloud Run công khai trong trình duyệt web. Vì bạn đã dùng --with_ui flag, nên bạn sẽ thấy giao diện người dùng dành cho nhà phát triển ADK.

Bật Token Streaming ở trên cùng bên phải.

Giờ đây, bạn có thể tương tác với nhân viên hỗ trợ của Zoo.

Nhập hello rồi nhấn phím Enter để bắt đầu một cuộc trò chuyện mới.

Quan sát kết quả. Nhân viên hỗ trợ ảo phải nhanh chóng phản hồi bằng lời chào:

"Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"

Giải thích về quy trình của nhân viên hỗ trợ

Hệ thống của bạn hoạt động như một nhóm đa tác nhân thông minh. Quy trình này được quản lý theo một trình tự rõ ràng để đảm bảo luồng thông tin diễn ra suôn sẻ và hiệu quả từ câu hỏi của người dùng đến câu trả lời chi tiết cuối cùng.

1. Nhân viên đón tiếp tại sở thú (Bàn đón tiếp)

Toàn bộ quy trình bắt đầu bằng nhân viên chào hỏi.

Công việc của nó: Bắt đầu cuộc trò chuyện. Hướng dẫn của ứng dụng là chào người dùng và hỏi họ muốn tìm hiểu về loài động vật nào.

Công cụ của nó: Khi người dùng trả lời, Greeter sẽ sử dụng công cụ add_prompt_to_state để ghi lại chính xác những gì họ nói (ví dụ: cho tôi biết về sư tử") và lưu chúng vào bộ nhớ của hệ thống.

Handoff (Bàn giao): Sau khi lưu câu lệnh, câu lệnh này sẽ ngay lập tức chuyển quyền kiểm soát cho tác nhân phụ của nó là tour_guide_workflow.

2. Nhà nghiên cứu toàn diện (Nhà siêu nghiên cứu)

Đây là bước đầu tiên trong quy trình làm việc chính và là "bộ não" của hoạt động. Thay vì một nhóm lớn, giờ đây bạn có một nhân viên hỗ trợ duy nhất có kỹ năng cao và có thể truy cập vào tất cả thông tin hiện có.

Công việc: Phân tích câu hỏi của người dùng và lập một kế hoạch thông minh. Công cụ này sử dụng khả năng sử dụng công cụ mạnh mẽ của mô hình ngôn ngữ để quyết định xem có cần:

Dữ liệu nội bộ từ hồ sơ của vườn thú (thông qua MCP Server).
Kiến thức chung từ web (thông qua API Wikipedia).
Hoặc cả hai đối với các câu hỏi phức tạp.

Hành động của nó: Nó thực thi(các) công cụ cần thiết để thu thập tất cả dữ liệu thô bắt buộc. Ví dụ: nếu được hỏi "Sư tử của chúng ta bao nhiêu tuổi và chúng ăn gì trong tự nhiên?", thì mô hình này sẽ gọi máy chủ MCP để biết tuổi và gọi công cụ Wikipedia để biết thông tin về chế độ ăn.

3. Trình định dạng phản hồi (Người trình bày)

Sau khi Nhà nghiên cứu toàn diện thu thập tất cả các thông tin, đây là tác nhân cuối cùng cần chạy.

Công việc: Đóng vai trò là giọng nói thân thiện của Hướng dẫn viên tham quan vườn thú. Thao tác này lấy dữ liệu thô (có thể từ một hoặc cả hai nguồn) và tinh chỉnh dữ liệu đó.

Hành động của Gemini: Tổng hợp tất cả thông tin thành một câu trả lời mạch lạc, hấp dẫn. Theo hướng dẫn này, trước tiên, mô hình sẽ trình bày thông tin cụ thể về vườn thú, sau đó thêm các thông tin chung thú vị.

Kết quả cuối cùng: Văn bản do tác nhân này tạo là câu trả lời đầy đủ và chi tiết mà người dùng thấy trong cửa sổ trò chuyện.

Nếu bạn muốn tìm hiểu thêm về cách tạo các Đặc vụ, hãy tham khảo các tài nguyên sau:

10. Dọn dẹp môi trường

gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet

11. Xin chúc mừng

Chúc mừng bạn đã hoàn thành lớp học lập trình này.

Nội dung đã đề cập

Cách cấu trúc một dự án Python để triển khai bằng giao diện dòng lệnh ADK.
Cách triển khai quy trình làm việc có nhiều tác nhân bằng SequentialAgent và ParallelAgent.
Cách kết nối với một máy chủ MCP từ xa bằng MCPToolset để sử dụng các công cụ của máy chủ đó.
Cách tăng cường dữ liệu nội bộ bằng cách tích hợp các công cụ bên ngoài như Wikipedia API.
Cách triển khai một tác nhân hỗ trợ dưới dạng vùng chứa không máy chủ vào Cloud Run bằng lệnh triển khai adk.

12. Khảo sát

Kết quả:

Bạn sẽ sử dụng hướng dẫn này như thế nào?

Chỉ đọc qua

Đọc và hoàn thành bài tập