Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 các 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 an toàn các công cụ do máy chủ từ xa cung cấp. ADK là khung mã 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 công cụ này, bạn có thể tạo ra những trợ lý đượ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à People.

Để 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 Cloud của bạn.
Định cấu hình sự đồng ý OAuth và tạo thông tin đăng nhập cho cả hoạt động kiểm thử cục bộ và triển khai chính thức.
Tạo tác nhân ADK cục bộ kết nối với 5 máy chủ MCP Workspace bằng mã thông báo tĩnh.
Tạo và triển khai tác nhân ADK sẵn sàng cho hoạt động sản xuất vào 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à kiểm thử tác nhân tuỳ chỉnh ngay trong Gemini Enterprise.

Bạn cần có

Một trình duyệt web (ví dụ: Chrome).
Một dự án trên 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.
Google Cloud CLI (gcloud) đã được cài đặt và khởi chạy.

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 sử dụng Bảng điều khiển

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

Lựa chọn CLI

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

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

Bật các API

Để sử dụng các 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 sử dụng Bảng điều khiển

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

Lựa 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

Đị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.

Chuyển đến Google Chat API > Quản lý > Cấu hình.
Thiết lập ứng dụng Chat:
- Tên ứng dụng: ADK Workspace Agent
- URL của 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 mục Nhật ký, hãy chọn Ghi lỗi vào tính năng Ghi nhật ký.
Nhấp vào Lưu.

3. Định cấu hình màn hình đồng ý và ứng dụng OAuth

Các 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 riêng biệt: một cho quá trình phát triển cục bộ và một cho tác nhân được triển khai.

Trong bảng điều khiển Google Cloud, hãy nhấp vào Trình đơn điều hướng (biểu tượng trình đơn) ở góc trên cùng bên trái. Chọn Google Auth Platform > Branding (Thương hiệu) (hoặc APIs & Services (API và dịch vụ) > OAuth consent screen (màn hình xin phép bằng OAuth) nếu bạn không thấy Google Auth Platform).
Đị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.
Định cấu hình Đối tượng: Chọn Nội bộ.
Định cấu hình Thông tin liên hệ: Nhập địa chỉ email của bạn, rồi nhấp vào Tạo.

Chuyển đến Quyền truy cập vào 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ả 5 dịch vụ:

https://www.googleapis.com/auth/calendar.calendarlist.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.calendars
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/gmail.send
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

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 cho quá trình phát triển cục bộ (Ứng dụng dành cho máy tính)

Trong bảng điều khiển Cloud, hãy chuyển đến Nền tảng xác thực của Google > Ứng dụng (hoặc API và Dịch vụ > Thông tin xác thực). Nhấp vào Tạo thông tin đăng nhập (hoặc Tạo ứng dụng) rồi chọn Mã ứng dụng OAuth.
Chọn Ứng dụng dành cho máy tính làm loại ứng dụng.
Đặt tên tệp này là Workspace Agent Local.
Nhấp vào Tạo rồi tải tệp JSON xuống. Lưu tệp đó trên máy dưới dạng client_secret.json.

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

Phần này mô tả cách tạo 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 để kiểm thử, trong đó chúng ta tìm nạp mã thông báo OAuth bằng cách sử dụ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 của bạn: 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 này 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 thiết bị đầu cuối để tạo một 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 (>_) trong thanh công cụ trên cùng bên phải của Bảng điều khiển Google Cloud.
Đố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 trữ 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 bắt buộc.

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 thiết bị đầu cuối:

python3 auth.py

Tạo mã tác nhân

Bất kể môi trường bạn chọn ở bước trước, mã nhân viên hỗ trợ vẫn hoàn toàn giống nhau. Tạo một tệp có tên là agent.py trong thư mục con workspace_agent đã tạo trước đó rồi thêm đoạn 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 quyền 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 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

MODEL = "gemini-2.5-flash"

# Load credentials from Application Default Credentials (ADC) saved by auth.py
creds, _ = google.auth.default()

# 1. STARTUP SAFETY: Ensure valid token at import time for static tool discovery (e.g. adk web UI load)
if not creds.valid:
    creds.refresh(Request())
    print("\n[Agent Startup] Access token refreshed from ADC.")

def auth_header_provider(tool_context=None) -> dict[str, str]:
    """2. RUNTIME SAFETY: Dynamically provides auth headers, refreshing if expired during the session."""
    if not creds.valid:
        creds.refresh(Request())
        print("\n[Agent Runtime] Access token refreshed from ADC.")
    return {"Authorization": f"Bearer {creds.token}"}

# Initialize the 5 GWS MCP servers with combined startup headers and dynamic runtime provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://calendarmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://chatmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://drivemcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://gmailmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://people.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)

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

# Define the agent and attach all 5 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, and Contacts.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

Chạy và kiểm thử nhân viên hỗ trợ

Bạn có thể tương tác với trợ lý ảo bằng Giao diện người dùng web tương tác hoặc ngay 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ộ:

Trong thư mục gốc của dự án gws-adk-agent, hãy khởi động giao diện web ADK:
```
adk web
```
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 sử dụng Google Cloud Shell:

Từ thư mục gốc của dự án gws-adk-agent, hãy khởi động giao diện web ADK một cách rõ ràng bằng cách thực thi cổng 8080:
```
adk web --port 8080 --allow_origins=*
```
Nhấp vào nút Xem trước trên web ở trên cùng bên phải thanh công cụ Cloud Shell rồi chọn 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 thiết bị đầu cuối (Cách thay thế)

Nếu bạn muốn ở lại trong thiết bị đầu cuối hoặc muốn tránh thiết lập bản xem trước của trình duyệt web, thì ADK cung cấp chế độ trò chuyện REPL tương tác gốc.

Từ 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]:

Hãy thử ra lệnh cho nhân viên hỗ trợ

Bất kể bạn chọn giao diện nào, hãy thử kiểm tra tác nhân bằng các truy vấn tận 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 bản phát hành công khai

Để triển khai tác nhân cho bản phát hành, chúng ta không thể sử dụng mã thông báo cục bộ được mã hoá cứng. 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 khi người dùng tương tác với tác nhân.

Tạo Mã tác nhân phát hành công khai

Tạo một gói thư mục có tên là 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 datetime
import os
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

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
)

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, and People.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

Triển khai vào Thời gian chạy tác nhân GEAP

Triển khai tác nhân chuyên nghiệp bằng ADK CLI:

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 và sao chép tên tài nguyên Reasoning Engine đã tạo từ đầu ra 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 với tác nhân này một cách tự nhiên.

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

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

Trong bảng điều khiển Google Cloud, hãy nhấp vào Trình đơn điều hướng (biểu tượng trình đơn) ở góc trên cùng bên trái. Chọn Google Auth Platform > Clients (Khách hàng) (hoặc APIs & Services (API và Dịch vụ) > Credentials (Thông tin xác thực) nếu bạn không thấy Google Auth Platform). Nhấp vào Tạo thông tin đăng nhập (hoặc Tạo ứng dụng) rồi chọn Mã ứng dụng OAuth.
Chọn Ứng dụng web làm loại ứng dụng.
Đặt tên tệp này là Workspace Agent Production.
Trong mục URI chuyển hướng được uỷ quyền, hãy thêm các URI sau:
- Nhấp vào 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.
Nhấp vào Tạo. Trong cửa sổ bật lên "OAuth client created" (Ứng dụng OAuth đã được tạo) (hoặc trong danh sách Clients (Ứng dụng OAuth)), hãy sao chép Client ID (Mã ứng dụng khách) và Client Secret (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 một ứng dụng Gemini Enterprise

Trong bảng điều khiển Google Cloud, hãy chuyển đến trang Gemini Enterprise:

Trong thẻ Gemini Enterprise, hãy nhấp vào Quản lý.
Nhấp vào Tạo ứng dụng.
Trong phần Gemini Enterprise, hãy nhấp vào Tạo.
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 của bạn sẽ xuất hiện bên dưới tên ứng dụng.
Trong trường Tên bên ngoài của công ty hoặc tổ chức, hãy nhập tên công ty hoặc tổ chức. Trong hướng dẫn này, bạn có thể sử dụng Cymbal Bank.
Chọn toàn cầu (Global) làm vị trí cho ứng dụng của bạn.
Nhấp vào Tiếp tục.

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

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

Chọn ứng dụng đang hoạt động, chuyển đến Agents (Tác nhân) rồi nhấp vào + Add agent (+ Thêm tác nhân) > Add Custom agent via Agent Runtime (Thêm tác nhân tuỳ chỉnh thông qua Thời gian chạy tác nhân).

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 hoàn toàn khớp với CLIENT_AUTH_NAME trong mã Python)
Mã ứng dụng: Dán Mã ứng dụng Ứng dụng web sản xuất mà bạn đã tạo ở trên.
Mật khẩu ứng dụng khách: Dán Mật khẩu ứng dụng khách của Ứng dụng web phát hành công khai mà bạn đã 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.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.calendars%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.events%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.send%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.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%2Fdirectory.readonly&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

Nhấp vào Xong, rồi nhấp vào Tiếp theo.

Trong mục Cấu hình:

Tên tác nhân: Workspace Pro Agent

Nội dung 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 Thời gian chạy của tác nhân: Dán tên tài nguyên của công cụ mà bạn đã sao chép từ đầu ra adk deploy.

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 bằng Google Cloud Console Preview (nhanh nhất đối với nhà phát triển) hoặc Ứng dụng Gemini Enterprise trên web (trải nghiệm người dùng cuối).

Lựa chọn 1: Bản xem trước Google Cloud Console

Trong bảng điều khiển Google Cloud, hãy chuyển đến trang Gemini Enterprise:

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.
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.

Trong thanh tìm kiếm, hãy nhập truy vấn 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.

Nhấn 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

Mở giao diện Ứng dụng web Gemini Enterprise.
Chuyển đến Trình đơn ☰ > Trợ lý rồi chọn Trợ lý Workspace Pro trong mục Từ tổ chức của bạn.
Nhập cùng một truy vấn như trong lựa chọn Xem trước của Google Cloud Console.
Nhấp vào Uỷ quyền khi được nhắc để thực hiện quy trình sự đồng ý của người dùng OAuth.
Tác nhân sẽ thực hiện các tác 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 mà 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 khách OAuth trong phần Nền tảng xác thực của Google > Ứng dụng khách và xoá việc triển khai Reasoning Engine khỏi Bảng điều khiển Gemini Enterprise.

Lựa chọn CLI

Thực thi các lệnh sau trên thiết bị đầu cuối để 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

8. Xin chúc mừng

Xin chúc mừng! Bạn đã tạo, 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 đăng nhập 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 phát hành công khai.
Cách triển khai một tác nhân ADK vào Thời gian chạy tác nhân GEAP và đăng ký tác nhân đó trong Gemini Enterprise.

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

1. Giới thiệu

Bạn sẽ thực hiện

Bạn cần có

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 sử dụng Bảng điều khiển

Lựa chọn CLI

Bật các API

Lựa chọn sử dụng Bảng điều khiển

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

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

3. Định cấu hình màn hình đồng ý và ứng dụng OAuth

Thiết lập màn hình xin phép bằng OAuth

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

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

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

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

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

Tạo mã tác nhân

Chạy và kiểm thử nhân viên hỗ trợ

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ộ:

Nếu bạn đang sử dụng Google Cloud Shell:

Cách 2: Chế độ CLI của thiết bị đầu cuối (Cách thay thế)

Hãy thử ra lệnh cho nhân viên hỗ trợ

5. Triển khai bản phát hành công khai

Tạo Mã tác nhân phát hành công khai

Triển khai vào Thời gian chạy tác nhân GEAP

6. Đăng ký trong Gemini Enterprise

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

Tạo một ứng dụng Gemini Enterprise

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

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

Lựa chọn 1: Bản xem trước Google Cloud Console

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

7. Dọn dẹp

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

Lựa chọn CLI

8. Xin chúc mừng

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

Tài liệu tham khảo

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