ساختن «عامل هوش مصنوعی Google Workspace» با ADK و MCP

۱. مقدمه

در این codelab، با نحوه ساختن عامل هوش مصنوعی pro-code بااستفاده از Agent Development Kit (ADK) که مستقیماً به سرورهای MCP رسمی Google Workspace متصل می‌شود آشنا خواهید شد.

«پروتکل بافتار مدل» (MCP) یک استاندارد باز است که به مدل‌های هوش مصنوعی امکان می‌دهد به‌طور ایمن از ابزارهای ارائه‌شده توسط سرورهای راه دور استفاده کنند. ‫ADK چارچوب کدنویسی حرفه‌ای Google برای ساختن عامل‌های خودکار است. با ترکیب کردن آن‌ها، می‌توانید عامل‌های بسیار سفارشی‌سازی‌شده‌ای ایجاد کنید که بر داده‌های Gmail،‏ Google Drive، «تقویم Google»،‏ Google Chat، و «افراد» شما مبتنی هستند.

برای مستندات کامل درباره ابزارها و پیکربندی‌های دردسترس، به پیکربندی سرورهای MCP در Google Workspace مراجعه کنید.

آنچه انجام خواهید داد

  • سرویس‌های Google Workspace MCP را در پروژه Google Cloud خود فعال کنید.
  • رضایت OAuth را پیکربندی کنید و اعتبارنامه‌هایی برای آزمایش محلی و استقرار تولید ایجاد کنید.
  • ساختن عامل ADK محلی که بااستفاده از توکن‌های ایستا به سرورهای Google Workspace MCP متصل می‌شود.
  • ساختن و مستقر کردن عامل ADK آماده تولید در Gemini Enterprise Agent Platform (GEAP) Agent Runtime که از تزریق توکن پویا استفاده می‌کند.
  • عامل سفارشی‌تان را به‌طور بومی در Gemini Enterprise ثبت و آزمایش کنید.

آنچه نیاز خواهید داشت

  • مرورگر وب (مثلاً Chrome).
  • پروژه Google Cloud با صورت‌حساب فعال.
  • حساب Google Workspace (با ویژگی‌های هوشمند روشن).
  • Python 3.11+‎ در ماشین محلی‌تان نصب شده باشد.
  • Google Cloud CLI (gcloud) نصب و مقداردهی اولیه شده است.

۲. قبل‌از شروع

ایجاد یا انتخاب پروژه Google Cloud

گزینه کنسول

در کنسول Google Cloud، پروژه Google Cloud را انتخاب یا ایجاد کنید.

گزینه CLI

پروژه جدیدی ایجاد کنید و آن را به‌عنوان فعال تنظیم کنید:

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

فعال کردن میاناهای برنامه‌سازی کاربردی

برای استفاده از سرورهای Google Workspace MCP، باید هم میاناهای برنامه‌سازی کاربردی استاندارد 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
    • نشانی وب چهرهک: https://developers.google.com/chat/images/quickstart-app-avatar.png
    • شرح: MCP server connection for ADK Agent
    • در بخش عملکرد، فعال کردن ویژگی‌های تعاملی را خاموش کنید.
    • در بخش گزارش‌ها، گزارش کردن خطاها در Logging را انتخاب کنید.
  3. روی ذخیره کلیک کنید.

۳. پیکربندی «رضایت OAuth» و «کارخواه‌ها»

سرورهای MCP در Google Workspace از OAuth 2.0 برای اصالت‌سنجی ایمن استفاده می‌کنند. باید صفحه کسب رضایت OAuth را پیکربندی کنید و دو شناسه کارخواه جداگانه ایجاد کنید: یکی برای توسعه محلی و دیگری برای نماینده مستقرشده.

  1. در کنسول Google Cloud، روی منو پیمایش (نماد همبرگری) در گوشه بالا کلیک کنید. پلاتفرم Google Auth > نمانام‌سازی (یا میاناهای برنامه‌سازی کاربردی و سرویس‌ها > صفحه کسب رضایت OAuth اگر پلاتفرم Google Auth قابل‌مشاهده نیست) را انتخاب کنید.
  2. اطلاعات برنامه را پیکربندی کنید:
    • نام برنامه: Workspace ADK Agent
    • ایمیل پشتیبانی کاربر: ایمیلتان را انتخاب کنید.
  3. مخاطب را پیکربندی کنید: داخلی را انتخاب کنید.
  4. اطلاعات تماس را پیکربندی کنید: نشانی ایمیلتان را وارد کنید، سپس روی ایجاد کلیک کنید.
  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 > کارخواه‌ها (یا میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اطلاعات کاربری) بروید. روی ایجاد کارخواه (یا ایجاد اطلاعات کاربری > شناسه کارخواه OAuth) کلیک کنید.
  2. برنامه رایانه‌ای را به‌عنوان نوع برنامه انتخاب کنید.
  3. نام آن را Workspace Agent Local بگذارید.
  4. استفاده از این کارخواه برای عامل مجهز به هوش مصنوعی را انتخاب کنید تا پرچم طبقه‌بندی is_agentic در کارخواه OAuth فعال شود.
  5. روی ایجاد کلیک کنید و فایل JSON را بارگیری کنید. آن را به‌صورت محلی با نام client_secret.json ذخیره کنید.

۴. توسعه و آزمایش Agent

این بخش نحوه ساختن محیط عامل را شرح می‌دهد. برای آزمایش، از رویکرد کد ایستا استفاده خواهیم کرد که در آن کد OAuth را بااستفاده از gcloud واکشی می‌کنیم و آن را به McpToolset ADK ارسال می‌کنیم. می‌توانید این مراحل را بااستفاده از دستگاه محلی یا Google Cloud Shell دنبال کنید.

محیط خود را انتخاب کنید: دستگاه محلی یا Google Cloud Shell برای راه‌اندازی محیط توسعه نرم‌افزار. هر دو روش از یک اسکریپت Python مشترک برای اصالت‌سنجی استفاده می‌کنند تا از سازگاری در پلاتفرم‌های مختلف اطمینان حاصل شود.

۱. راه‌اندازی فهرست راهنمای محیط

فرمان‌های زیر را در پایانه خود اجرا کنید تا فهرست راهنمای پروژه ایجاد شود و بسته‌های لازم نصب شود.

  • برای 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

۲. آماده‌سازی فایل اعتبارنامه‌ها

باید فایل 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

۳. اصالت‌سنجی و تولید .env‏ (auth.py)

برای مدیریت اصالت‌سنجی به‌صورت یکپارچه و جلوگیری از مشکلات مسیریابی CLI مختص محیط، از یک اسکریپت Python سفارشی استفاده می‌کنیم که توسط کتابخانه‌های رسمی اصالت‌سنجی Google پشتیبانی می‌شود. این اسکریپت جریان OAuth را مدیریت می‌کند، «اعتبارنامه‌های پیش‌فرض برنامه» (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 که ازقبل ایجاد کرده‌اید بسازید و کد زیر را اضافه کنید. این اسکریپت از «اعتبارنامه‌های پیش‌فرض برنامه» (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. از دایرکتوری ریشه پروژه gws-adk-agent، میانای وب ADK را راه‌اندازی کنید:
    adk web
    
  2. برای گپ زدن با نماینده، http://localhost:8000 را در مرورگرتان باز کنید.

اگر در Google Cloud Shell هستید:

  1. از دایرکتوری ریشه پروژه gws-adk-agent، میانای وب ADK را با اجرای صریح درگاه ۸۰۸۰ راه‌اندازی کنید:
    adk web --port 8080 --allow_origins=*
    
  2. روی دکمه پیش‌نمایش وب در بالا سمت چپ نوارابزار Cloud Shell کلیک کنید و پیش‌نمایش در درگاه ۸۰۸۰ را انتخاب کنید تا میانای کاربری در برگه جدیدی باز شود.

گزینه ۲: حالت 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.

۵. استقرار تولید

برای استقرار عامل در مرحله تولید، نمی‌توانیم از کدنویسی ثابت برای توکن محلی استفاده کنیم. به‌جای آن، از 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

مستقر کردن عامل pro-code بااستفاده از ADK CLI:

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

منتظر بمانید تا استقرار به‌پایان برسد و نام منبع «موتور استدلال» تولیدشده را از خروجی پایانه (مثلاً projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID) کپی کنید.

‫۶. ثبت‌نام در Gemini Enterprise

اکنون، نماینده ADK سفارشی را به Gemini Enterprise می‌آوریم تا کاربران بتوانند به‌طور بومی با آن گپ بزنند.

ایجاد شناسه کارخواه برای تولید (برنامه وب)

برای استقرار عاملتان در محیط تولید، باید شناسه کارخواه برنامه وب ایجاد کنید. برخلاف کارخواه رایانه که برای آزمایش محلی استفاده می‌شود، کارخواه برنامه وب جریان OAuth امن و سمت سرور را فعال می‌کند. این کار به عامل میزبانی‌شده در GEAP Agent Runtime اجازه می‌دهد تا بااستفاده از URI هدایت مشخص‌شده، توکن‌های اصالت‌سنجی کاربر را که توسط Gemini Enterprise بازارسال شده است به‌طور ایمن دریافت کند. این راه‌اندازی برای اینکه عامل بتواند به‌طور ایمن ازطرف کاربر در محیط تولید به داده‌های Google Workspace دسترسی داشته باشد ضروری است.

  1. در کنسول Google Cloud، روی منو پیمایش (نماد همبرگری) در گوشه بالا کلیک کنید. Google Auth Platform > Clients (یا APIs & Services > Credentials را درصورت نمایان نبودن Google Auth Platform) انتخاب کنید. روی ایجاد کارخواه (یا ایجاد اطلاعات کاربری > شناسه کارخواه OAuth) کلیک کنید.
  2. برنامه وب را به‌عنوان نوع برنامه انتخاب کنید.
  3. نام آن را Workspace Agent Production بگذارید.
  4. در بخش شناسه‌های URI هدایت مجاز، شناسه‌های URI زیر را اضافه کنید:
    • روی افزودن URI کلیک کنید و https://vertexaisearch.cloud.google.com/oauth-redirect را وارد کنید.
    • دوباره روی افزودن 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. جهانی (جهانی) را به‌عنوان مکان برنامه‌تان انتخاب کنید.
  7. روی ادامه کلیک کنید.

ثبت کردن «عامل سفارشی»

  1. کنسول Gemini Enterprise را باز کنید:

  1. برنامه فعال خود را انتخاب کنید، به عوامل بروید، و روی + افزودن عامل > افزودن عامل سفارشی ازطریق Agent Runtime کلیک کنید.
  2. در بخش مجوزها، روی افزودن مجوز کلیک کنید:
    • نام مجوز: workspace-adk-auth (باید دقیقاً با CLIENT_AUTH_NAME در کد Python شما مطابقت داشته باشد)
    • شناسه کارخواه: شناسه کارخواه برنامه وب تولید را که در بالا ایجاد کردید جای‌گذاری کنید.
    • رمز کارخواه: «رمز کارخواه» برنامه وب تولید را که در بالا ایجاد کردید جای‌گذاری کنید.
    • شناسه منبع یکسان توکن: https://oauth2.googleapis.com/token
    • URI مجوز: URI را با جایگزین کردن YOUR_CLIENT_ID با شناسه کارخواه که در مرحله ۵ بالا کپی کردید بسازید:
      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: نام منبع موتور را که از خروجی adk deploy کپی کرده‌اید جای‌گذاری کنید.
  5. روی ایجاد کردن کلیک کنید.

امتحان کردن «عامل» در Gemini Enterprise

می‌توانید بااستفاده از پیش‌نمایش کنسول Google Cloud (سریع‌ترین روش برای توسعه‌دهندگان) یا برنامه وب Gemini Enterprise (تجربه کاربر نهایی) با نماینده‌تان تعامل داشته باشید.

گزینه ۱: پیش‌نمایش «کنسول Google Cloud»

  1. در کنسول Google Cloud، به صفحه Gemini Enterprise بروید:

  1. در منو پیمایش، روی برنامه‌ها کلیک کنید و برنامه‌ای را که به‌تازگی ایجاد کرده‌اید انتخاب کنید.
  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. کلید ورود را فشار دهید تا پُرسمان ارسال شود و نتایج را مستقیماً در کنسول مشاهده کنید.

گزینه ۲: برنامه تحت وب Gemini Enterprise

  1. میانای برنامه تحت وب Gemini Enterprise را باز کنید.
  2. به منو ☰ > عوامل بروید و عامل Workspace Pro را در بخش از سازمان شما انتخاب کنید.
  3. همان پُرسمان را که در گزینه «پیش‌نمایش کنسول Google Cloud» وارد کرده بودید تایپ کنید.
  4. وقتی از شما خواسته شد که جریان رضایت کاربر OAuth را طی کنید، روی مجاز کردن کلیک کنید.
  5. این عامل بااستفاده از پروتکل MCP، تکالیف را به‌طور یکپارچه در چندین سرویس اجرا خواهد کرد!

‫۷. مرتب‌سازی

برای جلوگیری از هزینه‌های غیرضروری، منابعتان را پاک‌سازی کنید:

گزینه کنسول

به داشبورد API و سرویس‌ها بروید، سرویس‌های MCP را که فعال کرده‌اید (مثلاً MCP تقویم، MCP‏ Gmail) انتخاب کنید، و روی غیرفعال کردن API کلیک کنید. «شناسه‌های کارخواه OAuth» را در پلاتفرم Google Auth > کارخواه‌ها حذف کنید و استقرار «موتور استدلال» را از کنسول Gemini Enterprise حذف کنید.

گزینه CLI

فرمان‌های پایانه زیر را برای غیرفعال کردن سرویس‌های MCP اجرا کنید:

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

‫۸. تبریک می‌گوییم

تبریک! شما با موفقیت یک عامل هوشواره‌ای ADK با کد حرفه‌ای را که مستقیماً به سرورهای رسمی Google Workspace MCP متصل است، ساخته، آزمایش، و مستقر کرده‌اید.

آنچه آموخته‌اید

  • نحوه فعال کردن سرویس‌های Google Workspace MCP در Google Cloud.
  • نحوه مدیریت کردن اعتبارنامه‌های OAuth برای آزمایش ADK محلی بااستفاده از سرصفحه‌های ثابت.
  • نحوه پیاده‌سازی تزریق کد پویای توکن بااستفاده از header_provider برای عامل‌های تولید.
  • نحوه پیاده‌سازی عامل ADK در GEAP Agent Runtime و ثبت آن در Gemini Enterprise.

اسناد مرجع