Создание ИИ-агента Google Workspace с помощью ADK и MCP

1. Введение

В этой практической работе вы узнаете, как создать ИИ-агента с помощью Agent Development Kit (ADK), который подключается напрямую к официальным серверам MCP Google Workspace.

Model Context Protocol (MCP) – это открытый стандарт, который позволяет ИИ-моделям безопасно использовать инструменты, предоставляемые удаленными серверами. ADK – это фреймворк Google для создания автономных агентов с помощью кода. Объединив их, вы можете создавать агентов, которые будут использовать данные из Gmail, Google Диска, Google Календаря, Google Chat и Google Контактов.

Полная документация по доступным инструментам и настройке приведена в статье Как настроить MCP-серверы Google Workspace.

Что вам предстоит сделать

  • Включите сервисы MCP Google Workspace в своем облачном проекте Google Cloud.
  • Настройте окно запроса доступа OAuth и создайте учетные данные для локального тестирования и развертывания рабочей версии.
  • Создайте локального агента ADK, который подключается к серверам MCP Google Workspace с помощью статических токенов.
  • Создайте и разверните готового к работе агента ADK в Gemini Enterprise Agent Platform (GEAP) Agent Runtime, который использует динамическую вставку токенов.
  • Зарегистрируйте и протестируйте своего агента в Gemini Enterprise.

Что вам понадобится

  • Браузер (например, Chrome).
  • Проект Google Cloud с включенными платежными функциями.
  • Аккаунт Google Workspace (с включенными умными функциями).
  • На локальном компьютере установлена версия Python 3.11 или более поздняя.
  • Установлен и инициализирован Google Cloud CLI (gcloud).

2. Подготовка

Создайте или выберите проект Google Cloud

Вариант для консоли

В консоли Google Cloud выберите или создайте облачный проект Google Cloud.

Вариант CLI

Создайте новый проект и сделайте его активным:

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

Включение API

Чтобы использовать MCP-серверы Google Workspace, необходимо включить стандартные API Google Workspace и специальные MCP-сервисы.

Вариант для консоли

Чтобы включить их в браузере, нажмите следующие кнопки:

Вариант CLI Выполните следующие команды терминала:

# 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

Как настроить приложение Chat

Чтобы использовать сервер MCP Google Chat, необходимо настроить приложение Chat в облачном проекте Google Cloud.

  1. В консоли Google Cloud найдите Google Chat API и нажмите Google Chat API > Управление > Конфигурация.
  2. Настройте приложение Chat:
    • Название приложения: ADK Workspace Agent
    • URL аватара: https://developers.google.com/chat/images/quickstart-app-avatar.png
    • Описание: MCP server connection for ADK Agent
    • В разделе Функциональность отключите параметр Включить интерактивные функции.
    • В разделе Журналы выберите Записывать ошибки в журнал.
  3. Нажмите Сохранить.

3. Настройка запроса доступа OAuth и клиентов

MCP-серверы Google Workspace используют OAuth 2.0 для безопасной аутентификации. Вам нужно настроить окно запроса доступа OAuth и создать два отдельных идентификатора клиента: один для локальной разработки, а другой – для развернутого агента.

  1. В консоли Google Cloud нажмите на меню навигации (значок в виде трех горизонтальных линий) в левом верхнем углу. Выберите Google Auth Platform (Платформа Google Auth) > Branding (Брендинг) (или APIs & Services (API и сервисы) > OAuth consent screen (Окно запроса доступа OAuth), если Google Auth Platform не отображается).
  2. Настройте информацию о приложении:
    • Название приложения: Workspace ADK Agent
    • User support email (Адрес электронной почты службы поддержки) – выберите свой адрес электронной почты.
  3. В разделе Audience (Аудитория) выберите Internal (Внутренний).
  4. Заполните раздел Contact Information (Контактная информация): укажите адрес электронной почты и нажмите Create (Создать).
  5. Перейдите в раздел Доступ к данным > Добавить или удалить области действия. В разделе Добавить области действия вручную добавьте следующие области действия, чтобы предоставить доступ к нужным сервисам:
    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. Нажмите Добавить в таблицу, затем Обновить и Сохранить.

Как создать идентификатор клиента для локальной разработки (компьютерное приложение)

При настройке клиента OAuth 2.0 для MCP-серверов Google Workspace необходимо включить параметр агентной классификации (is_agentic), выбрав Использовать этот клиент для агента на основе искусственного интеллекта. Клиенты OAuth, у которых не включена эта настройка, не смогут вызывать конечные точки MCP Google Workspace.

  1. В консоли Google Cloud выберите Google Auth Platform (Платформа Google Auth) > Clients (Клиенты) или APIs & Services (API и сервисы) > Credentials (Учетные данные). Нажмите Создать клиент (или Создать учетные данные > Идентификатор клиента OAuth).
  2. В качестве типа приложения выберите Компьютерное приложение.
  3. Назовите его Workspace Agent Local.
  4. Выберите Использовать этот клиент для агента на основе искусственного интеллекта, чтобы включить флаг классификации is_agentic для клиента OAuth.
  5. Нажмите Создать и скачайте JSON-файл. Сохраните его на локальном диске под названием client_secret.json.

4. Разработка и тестирование агентов

В этом разделе описывается, как создать среду агента. Для тестирования мы будем использовать статический токен. Мы получим токен OAuth с помощью gcloud и передадим его в McpToolset ADK. Вы можете выполнить эти действия на локальном компьютере или в Google Cloud Shell.

Выберите среду разработки: Локальный компьютер или Google Cloud Shell. В обоих методах для аутентификации используется общий скрипт Python, что обеспечивает согласованность на разных платформах.

1. Настроить каталог среды

Чтобы создать каталог проекта и установить необходимые пакеты, выполните в терминале следующие команды:

  • Для Google Cloud Shell: нажмите на значок Активировать Cloud Shell >_ на панели инструментов в правом верхнем углу консоли Google Cloud.
  • Для локального компьютера: откройте стандартный терминал.
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. Подготовка файла учетных данных

Поместите файл client_secret.json, скачанный на предыдущем шаге, в корневой каталог gws-adk-agent.

  • Локальный компьютер. Переместите или скопируйте скачанный файл client_secret.json в каталог gws-adk-agent.
  • Google Cloud Shell. Создайте файл, выполнив в Cloud Shell следующую команду (замените [PASTE_JSON_HERE] на фактическое содержимое JSON):
cat << 'EOF' > client_secret.json
[PASTE_JSON_HERE]
EOF

3. Аутентификация и создание файла .env (auth.py)

Чтобы обеспечить единообразную аутентификацию и избежать проблем с маршрутизацией CLI, связанных со средой, мы используем собственный скрипт Python на основе официальных библиотек аутентификации Google. Этот скрипт управляет процессом OAuth, сохраняет Application Default Credentials (ADC) локально и генерирует необходимый файл .env.

Создайте файл с названием auth.py в каталоге gws-adk-agent и добавьте следующий код:

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")

Запустите скрипт в терминале:

python3 auth.py

Создайте код агента

Независимо от того, какую среду вы выбрали на предыдущем шаге, код агента остается неизменным. Создайте файл с названием agent.py в ранее созданном подкаталоге workspace_agent и добавьте следующий код. Этот скрипт использует Application Default Credentials (ADC) для авторизации, автоматически проверяя и обновляя учетные данные в памяти с помощью поставщика динамических заголовков.

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

Как запустить и протестировать агент

Вы можете взаимодействовать с агентом, используя интерактивный веб-интерфейс или непосредственно в терминале/оболочке.

Вариант 1. Интерактивный веб-интерфейс

Если вы используете локальный компьютер:

  1. Запустите веб-интерфейс ADK из корневого каталога проекта gws-adk-agent:
    adk web
    
  2. Чтобы пообщаться с агентом, откройте http://localhost:8000 в браузере.

Если вы используете Google Cloud Shell:

  1. В корневом каталоге проекта gws-adk-agent запустите веб-интерфейс ADK, принудительно указав порт 8080:
    adk web --port 8080 --allow_origins=*
    
  2. Нажмите кнопку Web Preview (Предварительный просмотр) в правом верхнем углу панели инструментов Cloud Shell и выберите Preview on port 8080 (Предварительный просмотр на порте 8080), чтобы открыть интерфейс в новой вкладке.

Вариант 2. Режим CLI в терминале (альтернативный)

Если вы предпочитаете оставаться в терминале или не хотите настраивать предварительный просмотр в браузере, ADK предоставляет нативный интерактивный режим чата REPL.

В корневом каталоге проекта gws-adk-agent выполните следующую команду (она работает одинаково на локальном компьютере и в Google Cloud Shell):

adk run workspace_agent

В оболочке откроется интерактивный чат.

Running agent gws_adk_agent, type exit to exit.

[user]:

Попробуйте отправить запрос агенту

Независимо от выбранного интерфейса, попробуйте протестировать агента с помощью запросов, в которых используются инструменты MCP для Workspace:

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

5. Развертывание рабочей версии

Чтобы развернуть агент в рабочей среде, нельзя использовать локальный токен, заданный в коде. Вместо этого мы используем header_provider ADK, чтобы динамически извлекать токен доступа OAuth, внедренный платформой Gemini Enterprise, когда пользователь взаимодействует с агентом.

Создайте код рабочего агента

Создайте пакет каталога с названием enterprise_ai и файл agent.py в нем:

mkdir -p enterprise_ai

Запишите следующий контент в 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]
)

Развертывание в GEAP Agent Runtime

Разверните агент с помощью ADK CLI:

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

Дождитесь завершения развертывания и скопируйте сгенерированное название ресурса Reasoning Engine из выходных данных терминала (например, projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID).

6. Зарегистрируйтесь в Gemini Enterprise

Теперь мы добавляем пользовательского агента ADK в Gemini Enterprise, чтобы пользователи могли общаться с ним напрямую.

Создание идентификатора клиента для рабочей версии (веб-приложение)

Чтобы развернуть агент в рабочей среде, необходимо создать идентификатор клиента Веб-приложение. В отличие от клиента для компьютеров, который используется для локального тестирования, клиент веб-приложения обеспечивает безопасный процесс OAuth на стороне сервера. Это позволяет агенту, размещенному в GEAP Agent Runtime, безопасно получать токены аутентификации пользователя, пересылаемые Gemini Enterprise, с помощью указанного URI перенаправления. Это необходимо, чтобы агент мог безопасно получать доступ к данным Google Workspace от имени пользователя в рабочей среде.

  1. В консоли Google Cloud нажмите на меню навигации (значок в виде трех горизонтальных линий) в левом верхнем углу. Выберите Google Auth Platform (Платформа Google Auth) > Clients (Клиенты). Если вы не видите Google Auth Platform, выберите APIs & Services (API и сервисы) > Credentials (Учетные данные). Нажмите Создать клиент (или Создать учетные данные > Идентификатор клиента OAuth).
  2. В качестве типа приложения выберите Веб-приложение.
  3. Назовите его Workspace Agent Production.
  4. В разделе Authorized redirect URIs (Авторизованные URI перенаправления) добавьте следующие URI:
    • Нажмите Add URI (Добавить URI) и введите https://vertexaisearch.cloud.google.com/oauth-redirect.
    • Снова нажмите Add URI (Добавить URI) и введите https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
  5. Выберите Использовать этот клиент для агента на основе искусственного интеллекта, чтобы включить флаг классификации is_agentic для клиента OAuth.
  6. Нажмите Создать. В диалоговом окне "Клиент OAuth создан" (или в списке Клиенты) скопируйте идентификатор клиента и секретный код клиента. Они понадобятся вам при регистрации агента в Gemini Enterprise.

Создать приложение Gemini Enterprise

  1. В консоли Google Cloud перейдите на страницу Gemini Enterprise.

  1. На карточке Gemini Enterprise нажмите Настройки.
  2. Нажмите Создать приложение.
  3. В разделе Gemini Enterprise нажмите Создать.
  4. В поле Название приложения введите название приложения. Идентификатор приложения появится под его названием.
  5. В поле Внешнее название компании или организации введите название компании или организации. В этом руководстве используется Cymbal Bank.
  6. В качестве местоположения приложения выберите global (Global).
  7. Нажмите Продолжить.

Зарегистрируйте специального агента

  1. Откройте консоль Gemini Enterprise.

  1. Выберите активное приложение, перейдите в раздел Агенты и нажмите + Добавить агента > Добавить собственного агента через среду выполнения агента.
  2. В разделе Авторизации нажмите Добавить авторизацию.
    • Название авторизации: workspace-adk-auth (должно точно совпадать с CLIENT_AUTH_NAME в коде Python).
    • Идентификатор клиента. Вставьте идентификатор клиента рабочего веб-приложения, созданный ранее.
    • Client secret (Секретный код клиента): вставьте секретный код клиента Production Web Application (Рабочее веб-приложение), созданный выше.
    • URI токена: https://oauth2.googleapis.com/token
    • URI авторизации. Создайте URI, заменив YOUR_CLIENT_ID на идентификатор клиента, скопированный на шаге 5:
      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. Нажмите Готово, а затем – Далее.
  4. В разделе Конфигурация:
    • Имя агента: Workspace Pro Agent.
    • Описание
      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.
      
    • Agent Runtime reasoning engine (Механизм рассуждений среды выполнения агента): вставьте название ресурса механизма, скопированное из выходных данных adk deploy.
  5. Нажмите Создать.

Попробовать агент в Gemini Enterprise

Вы можете взаимодействовать с агентом в предварительной версии консоли Google Cloud (самый быстрый способ для разработчиков) или в веб-приложении Gemini Enterprise (интерфейс для конечных пользователей).

Вариант 1. Предварительная версия консоли Google Cloud

  1. В консоли Google Cloud перейдите на страницу Gemini Enterprise.

  1. В меню навигации нажмите Apps (Приложения) и выберите приложение, которое вы только что создали.
  2. Нажмите Предварительный просмотр или Открыть предварительный просмотр в правом верхнем углу.
  3. В строке поиска введите следующий запрос:
    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. Нажмите Ввод, чтобы отправить запрос и посмотреть результаты в консоли.

Вариант 2. Веб-приложение Gemini Enterprise

  1. Откройте интерфейс веб-приложения Gemini Enterprise.
  2. Нажмите на значок меню ☰ > Агенты и выберите Workspace Pro Agent в разделе Из вашей организации.
  3. Введите тот же запрос, что и в предварительной версии консоли Google Cloud.
  4. Когда появится запрос, нажмите Авторизовать, чтобы пройти процедуру получения согласия пользователя OAuth.
  5. Агент будет выполнять задачи в нескольких сервисах, используя протокол MCP.

7. Организовать

Чтобы избежать лишних расходов, удалите ресурсы:

Вариант "Консоль"

Перейдите на панель управления API и сервисами, выберите включенные сервисы MCP (например, Calendar MCP, Gmail MCP) и нажмите Отключить API. Удалите идентификаторы клиентов OAuth в разделе Google Auth Platform > Clients (Клиенты), а также развертывание Reasoning Engine в Gemini Enterprise Console.

Параметр CLI

Чтобы отключить сервисы MCP, выполните в терминале следующие команды:

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

8. Поздравляю!

Поздравляем! Вы создали, протестировали и развернули ИИ-агента на основе ADK, который напрямую подключен к официальным серверам MCP Google Workspace.

Что вы узнали

  • Как включить сервисы MCP Google Workspace в Google Cloud.
  • Как обрабатывать учетные данные OAuth для локального тестирования ADK с помощью статических заголовков.
  • Как реализовать динамическую вставку токенов с помощью header_provider для рабочих агентов.
  • Как развернуть агента ADK в GEAP Agent Runtime и зарегистрировать его в Gemini Enterprise.

Справочная документация