Xây dựng một Trợ lý AI Google Workspace bằng ADK và MCP

1. Giới thiệu

Trong lớp học lập trình này, bạn sẽ tìm hiểu cách xây dựng một tác nhân AI chuyên nghiệp bằng Bộ công cụ phát triển tác nhân (ADK) kết nối trực tiếp với máy chủ MCP chính thức của Google Workspace.

Giao thức ngữ cảnh mô hình (MCP) là một tiêu chuẩn mở cho phép các mô hình AI sử dụng một cách an toàn các công cụ do máy chủ từ xa cung cấp. ADK là khung lập trình chuyên nghiệp của Google để xây dựng các tác nhân tự động. Bằng cách kết hợp các tiện ích này, bạn có thể tạo ra các tác nhân được tuỳ chỉnh cao dựa trên dữ liệu của bạn trong Gmail, Google Drive, Lịch Google, Google Chat và Danh bạ.

Để xem tài liệu đầy đủ về các công cụ và cấu hình hiện có, hãy xem bài viết Định cấu hình máy chủ MCP của Google Workspace.

Bạn sẽ thực hiện

  • Bật các dịch vụ MCP của Google Workspace trong dự án trên đám mây của Google.
  • Định cấu hình sự đồng ý của OAuth và tạo thông tin xác thực cho cả quá trình kiểm thử cục bộ và triển khai chính thức.
  • Xây dựng một tác nhân ADK cục bộ kết nối với máy chủ MCP của Google Workspace bằng mã thông báo tĩnh.
  • Xây dựng và triển khai một tác nhân ADK sẵn sàng cho môi trường thực tế vào Môi trường thời gian chạy tác nhân của Nền tảng tác nhân Gemini Enterprise (GEAP) sử dụng tính năng chèn mã thông báo động.
  • Đăng ký và thử nghiệm tác nhân tuỳ chỉnh ngay trong Gemini Enterprise.

Bạn cần có

  • Trình duyệt web (ví dụ: Chrome).
  • Một dự án trên đám mây của Google Cloud đã bật tính năng thanh toán.
  • Tài khoản Google Workspace (đã bật các tính năng thông minh).
  • Python 3.11 trở lên được cài đặt trên máy cục bộ của bạn.
  • Đã cài đặt và khởi chạy Google Cloud CLI (gcloud).

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

Tạo hoặc chọn một dự án trên Google Cloud

Lựa chọn về bảng điều khiển

Trong Google Cloud Console, hãy chọn hoặc tạo một dự án trên đám mây của Google Cloud.

Lựa chọn CLI

Tạo một dự án mới và đặt dự án đó ở trạng thái hoạt động:

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

Bật API

Để sử dụng máy chủ MCP của Google Workspace, bạn phải bật cả API Google Workspace tiêu chuẩn và các dịch vụ MCP chuyên dụng.

Lựa chọn về bảng điều khiển

Nhấp vào các nút sau để bật các nút đó bằng trình duyệt web:

Tuỳ chọn CLI Thực thi các lệnh sau trong cửa sổ dòng lệnh:

# Enable standard GWS APIs
gcloud services enable chat.googleapis.com \
  drive.googleapis.com \
  calendar-json.googleapis.com \
  people.googleapis.com \
  gmail.googleapis.com
# Enable dedicated MCP services
gcloud services enable calendarmcp.googleapis.com \
  chatmcp.googleapis.com \
  drivemcp.googleapis.com \
  gmailmcp.googleapis.com \
  workspacemcp.googleapis.com

Định cấu hình ứng dụng Chat

Để sử dụng máy chủ MCP của Google Chat, bạn phải định cấu hình một ứng dụng Chat trong dự án trên đám mây của Google.

  1. Trong Google Cloud Console, hãy tìm Google Chat API rồi nhấp vào Google Chat API > Quản lý > Cấu hình.
  2. Thiết lập ứng dụng Chat:
    • Tên ứng dụng: ADK Workspace Agent
    • URL hình đại diện: https://developers.google.com/chat/images/quickstart-app-avatar.png
    • Nội dung mô tả: MCP server connection for ADK Agent
    • Trong phần Chức năng, hãy tắt chế độ Bật các tính năng tương tác.
    • Trong phần Nhật ký, hãy chọn Ghi lỗi vào Logging.
  3. Nhấp vào Lưu.

3. Định cấu hình màn hình xin phép bằng OAuth và ứng dụng OAuth

Máy chủ MCP của Google Workspace sử dụng OAuth 2.0 để xác thực an toàn. Bạn phải định cấu hình màn hình xin phép bằng OAuth và tạo hai mã ứng dụng khách riêng biệt: một mã cho quá trình phát triển cục bộ và một mã cho tác nhân đã triển khai.

  1. Trong Google Cloud Console, hãy nhấp vào Trình đơn điều hướng (biểu tượng ba dấu gạch ngang) ở góc trên cùng bên trái. Chọn Nền tảng xác thực của Google > Xây dựng thương hiệu (hoặc API và dịch vụ > Màn hình xin phép bằng OAuth nếu bạn không thấy Nền tảng xác thực của Google).
  2. Định cấu hình Thông tin ứng dụng:
    • Tên ứng dụng: Workspace ADK Agent
    • Email hỗ trợ người dùng: Chọn email của bạn.
  3. Định cấu hình Đối tượng: Chọn Nội bộ.
  4. Định cấu hình Thông tin liên hệ: Nhập địa chỉ email của bạn, sau đó nhấp vào Tạo.
  5. Chuyển đến phần Truy cập dữ liệu > Thêm hoặc xoá phạm vi. Trong mục Thêm phạm vi theo cách thủ công, hãy thêm các phạm vi sau để cấp quyền truy cập vào các dịch vụ bắt buộc:
    https://www.googleapis.com/auth/calendar.events
    https://www.googleapis.com/auth/calendar.calendars
    https://www.googleapis.com/auth/calendar.readonly
    https://www.googleapis.com/auth/chat.spaces
    https://www.googleapis.com/auth/chat.messages
    https://www.googleapis.com/auth/drive.readonly
    https://www.googleapis.com/auth/drive.file
    https://www.googleapis.com/auth/gmail.readonly
    https://www.googleapis.com/auth/gmail.compose
    https://www.googleapis.com/auth/directory.readonly
    https://www.googleapis.com/auth/userinfo.profile
    https://www.googleapis.com/auth/contacts.readonly
    https://www.googleapis.com/auth/cloud-platform
    
  6. Nhấp vào Thêm vào bảng, sau đó nhấp vào Cập nhật, rồi nhấp vào Lưu.

Tạo mã ứng dụng khách để phát triển cục bộ (Ứng dụng dành cho máy tính)

Khi định cấu hình ứng dụng OAuth 2.0 cho máy chủ MCP của Google Workspace, bạn phải bật chế độ cài đặt phân loại tác nhân (is_agentic) bằng cách chọn Sử dụng ứng dụng này cho tác nhân dựa trên AI. Những ứng dụng OAuth không bật chế độ cài đặt này sẽ bị chặn gọi các điểm cuối MCP của Google Workspace.

  1. Trong Google Cloud Console, hãy chuyển đến Google Auth Platform > Clients (hoặc APIs & Services > Credentials). Nhấp vào Create Client (Tạo ứng dụng OAuth) (hoặc Create Credentials (Tạo thông tin đăng nhập) > OAuth client ID (Mã ứng dụng OAuth)).
  2. Chọn Ứng dụng dành cho máy tính làm loại ứng dụng.
  3. Đặt tên tệp này là Workspace Agent Local.
  4. Chọn Sử dụng ứng dụng này cho một tác nhân dựa trên AI để bật cờ phân loại is_agentic trên ứng dụng OAuth.
  5. Nhấp vào Tạo rồi tải tệp JSON xuống. Lưu tệp đó trên thiết bị dưới dạng client_secret.json.

4. Phát triển và thử nghiệm tác nhân

Phần này mô tả cách xây dựng môi trường tác nhân. Chúng ta sẽ sử dụng phương pháp mã thông báo tĩnh để thử nghiệm, trong đó chúng ta tìm nạp mã thông báo OAuth bằng gcloud và truyền mã thông báo đó đến McpToolset của ADK. Bạn có thể làm theo các bước này bằng Máy cục bộ hoặc Google Cloud Shell.

Chọn môi trường: Máy cục bộ hoặc Google Cloud Shell để thiết lập môi trường phát triển. Cả hai phương thức đều sẽ sử dụng một tập lệnh Python chung để xác thực nhằm đảm bảo tính nhất quán trên các nền tảng.

1. Thiết lập thư mục môi trường

Thực thi các lệnh sau trong dòng lệnh để tạo thư mục dự án và cài đặt các gói cần thiết.

  • Đối với Google Cloud Shell: Trước tiên, hãy nhấp vào biểu tượng Kích hoạt Cloud Shell (>_) trên thanh công cụ trên cùng bên phải của Google Cloud Console.
  • Đối với máy cục bộ: Mở cửa sổ dòng lệnh tiêu chuẩn.
mkdir -p gws-adk-agent/workspace_agent
cd gws-adk-agent
python3 -m venv .venv
source .venv/bin/activate
pip install google-adk poetry google-auth-oauthlib

2. Chuẩn bị tệp thông tin xác thực

Bạn phải đặt tệp client_secret.json đã tải xuống ở bước trước vào thư mục gốc của thư mục gws-adk-agent.

  • Máy cục bộ: Di chuyển hoặc sao chép tệp client_secret.json đã tải xuống vào thư mục gws-adk-agent.
  • Google Cloud Shell: Tạo tệp bằng cách chạy lệnh sau trong Cloud Shell (thay thế [PASTE_JSON_HERE] bằng nội dung JSON thực tế của bạn):
cat << 'EOF' > client_secret.json
[PASTE_JSON_HERE]
EOF

3. Xác thực và tạo .env (auth.py)

Để xử lý việc xác thực một cách nhất quán và tránh các vấn đề về định tuyến CLI theo môi trường cụ thể, chúng tôi sử dụng một tập lệnh Python tuỳ chỉnh dựa trên các thư viện xác thực chính thức của Google. Tập lệnh này quản lý quy trình OAuth, lưu Thông tin xác thực mặc định của ứng dụng (ADC) trên thiết bị và tạo tệp .env cần thiết.

Tạo một tệp có tên auth.py trong thư mục gws-adk-agent rồi thêm đoạn mã sau:

import json
import os
from urllib.parse import urlparse, parse_qs
import google.auth
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRET_FILE = 'client_secret.json'

SCOPES = [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/chat.spaces.readonly",
    "https://www.googleapis.com/auth/chat.messages",
    "https://www.googleapis.com/auth/drive.readonly",
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.compose",
    "https://www.googleapis.com/auth/directory.readonly",
    "https://www.googleapis.com/auth/contacts.readonly"
]

# Initialize the flow from the client secrets JSON
flow = InstalledAppFlow.from_client_secrets_file(
    CLIENT_SECRET_FILE,
    scopes=SCOPES,
    redirect_uri='http://localhost:8085/'
)

# Generate the Auth URL
auth_url, expected_state = flow.authorization_url(prompt='consent', access_type='offline')

print("\n=== GOOGLE OAUTH OFFICIAL LIBRARY FLOW ===")
print("1. Copy the following link and paste it into your browser (or click it if supported):\n")
print(auth_url)
print("\n2. Authorize the application.")
print("3. Your browser will redirect to a 'localhost' page (it will show a 'Site can't be reached' error, which is EXPECTED and normal).")
print("4. Copy the ENTIRE URL from your browser's address bar (including the http://localhost:8085/ part).\n")

# Get the redirected URL from the user
redirected_url = input("Paste the full localhost URL here: ").strip()

# Exchange the redirect URL for tokens
print("\nExchanging code for tokens...")
try:
    parsed_url = urlparse(redirected_url)
    query_params = parse_qs(parsed_url.query)

    returned_state = query_params.get('state', [None])[0]
    code = query_params.get('code', [None])[0]

    if not code:
        raise ValueError("No 'code' parameter found in the URL.")
    if returned_state != expected_state:
        raise ValueError("CSRF Warning! State mismatch.")

    flow.fetch_token(code=code)
    creds = flow.credentials
except Exception as e:
    print(f"Authentication failed: {e}")
    exit(1)

if not creds.refresh_token:
    print("\nError: No refresh token returned. You may need to revoke access and try again.")
    exit(1)

# Save Application Default Credentials
adc_data = {
    "client_id": creds.client_id,
    "client_secret": creds.client_secret,
    "refresh_token": creds.refresh_token,
    "type": "authorized_user"
}

adc_dir = os.path.expanduser("~/.config/gcloud")
os.makedirs(adc_dir, exist_ok=True)
adc_path = os.path.join(adc_dir, "application_default_credentials.json")

with open(adc_path, "w") as f:
    json.dump(adc_data, f, indent=2)

# Detect Project ID
try:
    _, project_id = google.auth.default()
except Exception:
    project_id = None

project_id = project_id or os.environ.get("GOOGLE_CLOUD_PROJECT", "YOUR_PROJECT_ID")

# Save to .env for local development (relative to project root)
env_dir = "workspace_agent"
os.makedirs(env_dir, exist_ok=True)
env_path = os.path.join(env_dir, ".env")

with open(env_path, "w") as f:
    f.write("GOOGLE_GENAI_USE_VERTEXAI=1\n")
    f.write(f"GOOGLE_CLOUD_PROJECT={project_id}\n")
    f.write("GOOGLE_CLOUD_LOCATION=us-central1\n")

print(f"\nSuccess! Application Default Credentials saved to: {adc_path}")
print(f"Environment variables saved to: {env_path}")
if project_id == "YOUR_PROJECT_ID":
    print("NOTE: Could not automatically detect Project ID. Please update it manually in .env")

Chạy tập lệnh trong dòng lệnh:

python3 auth.py

Tạo mã tác nhân

Bất kể bạn chọn môi trường nào trong bước trước, mã của nhân viên hỗ trợ vẫn giữ nguyên. Tạo một tệp có tên agent.py bên trong thư mục con workspace_agent đã tạo sẵn và thêm mã sau. Tập lệnh này sử dụng Thông tin xác thực mặc định của ứng dụng (ADC) để cung cấp thông tin uỷ quyền, tự động xác thực và làm mới thông tin xác thực hoàn toàn trong bộ nhớ thông qua một trình cung cấp tiêu đề động.

import os
import datetime

import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Enable graceful error handling so timeouts return as tool outputs instead of crashing
os.environ["ADK_ENABLE_MCP_GRACEFUL_ERROR_HANDLING"] = "1"

MODEL = "gemini-2.5-flash"

# Inject User ADC path globally so both ADK and underlying GenAI SDKs
# load it safely, bypassing broken Compute Engine metadata fallbacks.
_adc_path = os.path.expanduser(
    "~/.config/gcloud/application_default_credentials.json"
)
if not os.path.exists(_adc_path):
    raise FileNotFoundError(
        f"User ADC not found at {_adc_path}. "
        "Please run 'python3 auth.py' first to generate credentials."
    )
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = _adc_path

creds, _ = google.auth.default()


class TokenRelay:
    """Manages in-memory caching of Google OAuth access tokens.

    Decouples token refresh logic from credentials validation states to
    prevent infinite refresh loops during automated tool retries.
    """

    def __init__(self, credentials):
        self._creds = credentials
        self._cached_token: str | None = None
        self._expiry: datetime.datetime | None = None

    def get_token(self) -> str:
        now = datetime.datetime.now()
        # Refresh if no cache or expiring within 5 minutes
        if (
            self._cached_token is None
            or self._expiry is None
            or now >= (self._expiry - datetime.timedelta(minutes=5))
        ):
            self._creds.refresh(Request())
            self._cached_token = self._creds.token
            # Token lives for 60 mins; cache for 50 mins safely
            self._expiry = now + datetime.timedelta(minutes=50)
            print("\n[Agent Runtime] Access token refreshed from ADC.")
        return self._cached_token or ""


# Initialize auth relay and perform startup safety check
token_relay = TokenRelay(creds)
token_relay.get_token()


def auth_header_provider(tool_context=None) -> dict[str, str]:
    return {"Authorization": f"Bearer {token_relay.get_token()}"}


# Initialize the Google Workspace MCP servers with dynamic runtime provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://calendarmcp.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://chatmcp.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://drivemcp.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://gmailmcp.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://people.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)
universal_search_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://workspacemcp.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)

current_date = datetime.datetime.now().strftime("%Y-%m-%d")

# Define the agent and attach all configured toolsets
root_agent = LlmAgent(
    model=MODEL,
    name='gws_adk_agent',
    instruction=f"""You are a helpful assistant grounded in the user's Google Workspace data.
    Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
    Use the provided MCP tools to answer questions about their Calendar, Chat, Drive, Gmail, Contacts, and perform Universal Search.
    If a tool returns an error indicating a timeout, inform the user that the service took too long to respond.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp, universal_search_mcp]
)

Chạy và kiểm thử tác nhân

Bạn có thể tương tác với tác nhân của mình bằng Giao diện người dùng web tương tác hoặc trực tiếp bên trong Terminal/Shell.

Cách 1: Giao diện người dùng tương tác trên web

Nếu bạn đang sử dụng máy cục bộ:

  1. Trong thư mục gốc của dự án gws-adk-agent, hãy khởi động giao diện web của ADK:
    adk web
    
  2. Mở http://localhost:8000 trong trình duyệt để trò chuyện với nhân viên hỗ trợ.

Nếu bạn đang ở trong Google Cloud Shell:

  1. Trong thư mục gốc của dự án gws-adk-agent, hãy khởi động giao diện web ADK, thực thi rõ ràng cổng 8080:
    adk web --port 8080 --allow_origins=*
    
  2. Nhấp vào nút Web Preview (Bản xem trước trên web) ở trên cùng bên phải thanh công cụ Cloud Shell rồi chọn Preview on port 8080 (Xem trước trên cổng 8080) để mở giao diện trong một thẻ mới.

Cách 2: Chế độ CLI của Terminal (Cách khác)

Nếu bạn muốn tiếp tục sử dụng thiết bị đầu cuối hoặc muốn tránh thiết lập bản xem trước trên trình duyệt web, ADK sẽ cung cấp chế độ trò chuyện REPL tương tác gốc.

Trong thư mục gốc của dự án gws-adk-agent, hãy thực thi lệnh sau (lệnh này hoạt động giống nhau trên cả Máy cục bộ và Google Cloud Shell):

adk run workspace_agent

Bạn sẽ tham gia một phiên trò chuyện tương tác ngay trong shell:

Running agent gws_adk_agent, type exit to exit.

[user]:

Thử ra lệnh cho tác nhân

Bất kể bạn chọn giao diện nào, hãy thử kiểm thử tác nhân bằng các truy vấn sử dụng các công cụ MCP của Workspace:

What are my upcoming meetings this week?
Summarize the last 3 unread emails in my Gmail.

5. Triển khai thực tế

Để triển khai tác nhân cho môi trường thực tế, chúng ta không thể sử dụng mã thông báo cục bộ được cố định giá trị trong mã. Thay vào đó, chúng tôi sử dụng header_provider của ADK để trích xuất động mã truy cập OAuth do nền tảng Gemini Enterprise chèn vào khi người dùng tương tác với tác nhân.

Tạo mã tác nhân chính thức

Tạo một gói thư mục có tên enterprise_ai và tạo một tệp agent.py bên trong gói đó:

mkdir -p enterprise_ai

Viết nội dung sau vào enterprise_ai/agent.py:

import os
import datetime
import re
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext

# Enable graceful error handling so timeouts return as tool outputs instead of crashing
os.environ["ADK_ENABLE_MCP_GRACEFUL_ERROR_HANDLING"] = "1"

MODEL = "gemini-2.5-flash"
# This name MUST match the Authorization Name used during Gemini Enterprise registration
CLIENT_AUTH_NAME = "workspace-adk-auth"

def _get_access_token_from_context(tool_context: ToolContext) -> str:
    """Dynamically parses the user bearer token injected into the ToolContext state."""
    escaped_name = re.escape(CLIENT_AUTH_NAME)
    pattern = re.compile(fr"^{escaped_name}_\d+$")
    state_dict = tool_context.state.to_dict() if hasattr(tool_context.state, 'to_dict') else tool_context.state
    matching_keys = [k for k in state_dict.keys() if pattern.match(k)]
    if matching_keys:
        return state_dict.get(matching_keys[0])
    raise Exception(f"No bearer token found in ToolContext state matching pattern {pattern.pattern}")

def auth_header_provider(tool_context: ToolContext) -> dict[str, str]:
    """Provides the dynamic Authorization header for MCP requests."""
    token = _get_access_token_from_context(tool_context)
    return {"Authorization": f"Bearer {token}"}

# Initialize toolsets using the dynamic header_provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://calendarmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://chatmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://drivemcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://gmailmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://people.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
universal_search_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://workspacemcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)

current_date = datetime.datetime.now().strftime("%Y-%m-%d")

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""You are an enterprise assistant grounded securely in the user's Workspace data.
    Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
    Always use the provided MCP tools to fetch context from Calendar, Chat, Drive, Gmail, People, and search for information across multiple Google Workspace products.
    If a tool returns an error indicating a timeout, inform the user that the service took too long to respond.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp, universal_search_mcp]
)

Triển khai cho Môi trường thời gian chạy của tác nhân GEAP

Triển khai tác nhân lập trình chuyên nghiệp bằng CLI của ADK:

adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Workspace ADK Agent" \
  enterprise_ai

Chờ quá trình triển khai hoàn tất rồi sao chép tên tài nguyên Reasoning Engine đã tạo từ kết quả của thiết bị đầu cuối (ví dụ: projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID).

6. Đăng ký trong Gemini Enterprise

Giờ đây, chúng tôi đưa tác nhân ADK tuỳ chỉnh vào Gemini Enterprise để người dùng có thể trò chuyện trực tiếp với tác nhân này.

Tạo mã ứng dụng khách cho phiên bản phát hành chính thức (Ứng dụng web)

Để triển khai tác nhân cho môi trường thực tế, bạn phải tạo mã ứng dụng khách Ứng dụng web. Không giống như ứng dụng khách dành cho máy tính dùng để kiểm thử cục bộ, ứng dụng khách ứng dụng web cho phép quy trình OAuth phía máy chủ an toàn. Điều này cho phép tác nhân được lưu trữ trên GEAP Agent Runtime nhận mã xác thực của người dùng một cách an toàn do Gemini Enterprise chuyển tiếp, bằng cách sử dụng URI chuyển hướng được chỉ định. Bạn cần thiết lập bước này để tác nhân có thể truy cập một cách an toàn vào dữ liệu trên Google Workspace thay mặt cho người dùng trong môi trường thực tế.

  1. Trong Google Cloud Console, hãy nhấp vào Trình đơn điều hướng (biểu tượng ba dấu gạch ngang) ở góc trên cùng bên trái. Chọn Google Auth Platform > Clients (hoặc APIs & Services > Credentials nếu bạn không thấy Google Auth Platform). Nhấp vào Create Client (Tạo ứng dụng OAuth) (hoặc Create Credentials (Tạo thông tin đăng nhập) > OAuth client ID (Mã ứng dụng OAuth)).
  2. Chọn Ứng dụng web làm loại ứng dụng.
  3. Đặt tên tệp này là Workspace Agent Production.
  4. Trong phần URI chuyển hướng được uỷ quyền, hãy thêm các URI sau:
    • Nhấp vào Add URI (Thêm URI) rồi nhập https://vertexaisearch.cloud.google.com/oauth-redirect.
    • Nhấp lại vào Thêm URI rồi nhập https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
  5. Chọn Sử dụng ứng dụng này cho một tác nhân dựa trên AI để bật cờ phân loại is_agentic trên ứng dụng OAuth.
  6. Nhấp vào Tạo. Trong hộp thoại "Đã tạo ứng dụng OAuth" (hoặc trong danh sách Ứng dụng), hãy sao chép Mã ứng dụng khách và Khoá bí mật của ứng dụng khách. Bạn sẽ cần những thông tin này khi đăng ký tác nhân trong Gemini Enterprise.

Tạo ứng dụng Gemini Enterprise

  1. Trong Google Cloud Console, hãy chuyển đến trang Gemini Enterprise:

  1. Trong thẻ Gemini Enterprise, hãy nhấp vào Quản lý.
  2. Nhấp vào Tạo ứng dụng.
  3. Trong mục Gemini Enterprise, hãy nhấp vào Tạo.
  4. Trong trường Tên ứng dụng của bạn, hãy nhập tên cho ứng dụng. Mã ứng dụng sẽ xuất hiện dưới tên ứng dụng.
  5. Trong trường Tên bên ngoài của công ty hoặc tổ chức của bạn, hãy nhập tên công ty hoặc tổ chức. Đối với hướng dẫn này, bạn có thể sử dụng Cymbal Bank.
  6. Chọn global (Toàn cầu) làm vị trí cho ứng dụng của bạn.
  7. Nhấp vào Tiếp tục.

Đăng ký tác nhân tuỳ chỉnh

  1. Mở bảng điều khiển Gemini Enterprise:

  1. Chọn ứng dụng đang hoạt động, chuyển đến phần Tác nhân rồi nhấp vào + Thêm tác nhân > Thêm tác nhân tuỳ chỉnh thông qua Môi trường thời gian chạy của tác nhân.
  2. Trong phần Uỷ quyền, hãy nhấp vào Thêm uỷ quyền:
    • Tên uỷ quyền: workspace-adk-auth (Phải khớp chính xác với CLIENT_AUTH_NAME trong mã Python của bạn)
    • Mã ứng dụng khách: Dán Mã ứng dụng khách của Ứng dụng web chính thức đã tạo ở trên.
    • Khoá bí mật của ứng dụng khách: Dán Khoá bí mật của ứng dụng khách cho Ứng dụng web chính thức đã tạo ở trên.
    • URI mã thông báo: https://oauth2.googleapis.com/token
    • URI uỷ quyền: Tạo URI bằng cách thay thế YOUR_CLIENT_ID bằng Mã ứng dụng khách mà bạn đã sao chép ở bước 5 ở trên:
      https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.events%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.calendars%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.spaces%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.messages%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.file%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.compose%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdirectory.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcontacts.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
      
  3. Nhấp vào Xong, rồi nhấp vào Tiếp theo.
  4. Trong mục Cấu hình:
    • Tên tác nhân: Workspace Pro Agent
    • Mô tả:
      Use this agent to answer questions about your Google Workspace data, including Gmail, Google Drive, Google Calendar, Google Chat, and Contacts. It can find files, summarize emails, check your schedule, and look up contact information.
      
    • Công cụ suy luận của Agent Runtime: Dán tên tài nguyên của công cụ mà bạn đã sao chép từ kết quả adk deploy.
  5. Nhấp vào Tạo.

Dùng thử Tác nhân trong Gemini Enterprise

Bạn có thể tương tác với tác nhân của mình bằng Bản xem trước của Google Cloud Console (nhanh nhất cho nhà phát triển) hoặc Ứng dụng web Gemini Enterprise (trải nghiệm của người dùng cuối).

Cách 1: Bản xem trước Google Cloud Console

  1. Trong Google Cloud Console, hãy chuyển đến trang Gemini Enterprise:

  1. Trong trình đơn điều hướng, hãy nhấp vào Ứng dụng rồi chọn ứng dụng bạn vừa tạo.
  2. Nhấp vào Xem trước hoặc nhấp vào Mở bản xem trước ở trên cùng bên phải.
  3. Trong thanh tìm kiếm, hãy nhập cụm từ tìm kiếm sau:
    Search for files in Drive related to 'Project Milestone', summarize them, and tell me if I have any meetings with the project owner today.
    
  4. Nhấn phím Enter để gửi truy vấn và xem kết quả ngay trong bảng điều khiển.

Lựa chọn 2: Ứng dụng web Gemini Enterprise

  1. Mở giao diện ứng dụng web Gemini Enterprise.
  2. Chuyển đến Trình đơn ☰ > Tác nhân rồi chọn Workspace Pro Agent trong phần Từ tổ chức của bạn.
  3. Nhập cùng một truy vấn như trong tuỳ chọn Xem trước Google Cloud Console.
  4. Nhấp vào Uỷ quyền khi được nhắc thực hiện quy trình lấy sự đồng ý của người dùng OAuth.
  5. Tác nhân sẽ thực thi các nhiệm vụ một cách liền mạch trên nhiều dịch vụ bằng giao thức MCP!

7. Dọn dẹp

Để tránh các khoản phí không cần thiết, hãy dọn dẹp tài nguyên của bạn:

Tuỳ chọn bảng điều khiển

Chuyển đến Trang tổng quan về API và dịch vụ, chọn các dịch vụ MCP bạn đã bật (ví dụ: MCP Lịch, MCP Gmail) rồi nhấp vào Tắt API. Xoá Mã ứng dụng OAuth trong phần Nền tảng xác thực của Google > Ứng dụng, rồi xoá bản triển khai Reasoning Engine khỏi Bảng điều khiển Gemini Enterprise.

Tuỳ chọn CLI

Thực thi các lệnh sau trong dòng lệnh để tắt các dịch vụ MCP:

# Disable Workspace MCP services
gcloud services disable calendarmcp.googleapis.com \
  chatmcp.googleapis.com \
  drivemcp.googleapis.com \
  gmailmcp.googleapis.com \
  workspacemcp.googleapis.com

8. Xin chúc mừng

Xin chúc mừng! Bạn đã xây dựng, kiểm thử và triển khai thành công một tác nhân AI ADK chuyên nghiệp được kết nối trực tiếp với các máy chủ MCP chính thức của Google Workspace.

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

  • Cách bật các dịch vụ MCP của Google Workspace trong Google Cloud.
  • Cách xử lý thông tin xác thực OAuth để kiểm thử ADK cục bộ bằng tiêu đề tĩnh.
  • Cách triển khai tính năng chèn mã thông báo động bằng header_provider cho các tác nhân chính thức.
  • Cách triển khai tác nhân ADK cho Môi trường thời gian chạy tác nhân GEAP và đăng ký tác nhân đó trong Gemini Enterprise.

Tài liệu tham khảo