این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

۱. مقدمه

در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه یک عامل هوش مصنوعی پیش‌کدنویسی‌شده با استفاده از کیت توسعه عامل (ADK) بسازید که مستقیماً به سرورهای رسمی Google Workspace MCP متصل می‌شود.

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

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

کاری که انجام خواهید داد

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

آنچه نیاز دارید

یک مرورگر وب (مثلاً کروم).
یک پروژه گوگل کلود با قابلیت پرداخت.
یک حساب Google Workspace (با ویژگی‌های هوشمند فعال).
پایتون ۳.۱۱+ روی دستگاه محلی شما نصب شده باشد.
رابط خط فرمان گوگل کلود ( gcloud ) نصب و راه‌اندازی شد.

۲. قبل از شروع

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

گزینه کنسول

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

گزینه CLI

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

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

فعال کردن APIها

برای استفاده از سرورهای MCP گوگل ورک‌اسپیس، باید هم APIهای استاندارد گوگل ورک‌اسپیس و هم سرویس‌های اختصاصی 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

پیکربندی برنامه چت

برای استفاده از سرور Google Chat MCP، باید یک برنامه چت را در پروژه Google Cloud خود پیکربندی کنید.

به Google Chat API > مدیریت > پیکربندی بروید.
برنامه چت را تنظیم کنید:
- نام برنامه : ADK Workspace Agent
- آدرس آواتار : https://developers.google.com/chat/images/quickstart-app-avatar.png
- توضیحات : MCP server connection for ADK Agent
- در بخش عملکرد (Functionality) ، گزینه‌ی فعال کردن ویژگی‌های تعاملی (Enable interactive features) را خاموش کنید.
- در قسمت گزارش‌ها ، گزینه ثبت خطاها را برای ثبت گزارش‌ها انتخاب کنید.
روی ذخیره کلیک کنید.

۳. پیکربندی رضایت‌نامه OAuth و کلاینت‌ها

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

در کنسول گوگل کلود، روی منوی ناوبری (آیکون همبرگر) در گوشه بالا سمت چپ کلیک کنید. Google Auth Platform > Branding (یا APIs & Services > OAuth consent screen اگر Google Auth Platform قابل مشاهده نیست) را انتخاب کنید.
پیکربندی اطلاعات برنامه :
- نام برنامه : Workspace ADK Agent
- ایمیل پشتیبانی کاربر : ایمیل خود را انتخاب کنید.
پیکربندی مخاطب : داخلی را انتخاب کنید.
پیکربندی اطلاعات تماس : آدرس ایمیل خود را وارد کنید، سپس روی ایجاد کلیک کنید.

به بخش دسترسی به داده‌ها > افزودن یا حذف محدوده‌ها بروید. در قسمت افزودن دستی محدوده‌ها ، محدوده‌های زیر را برای اعطای دسترسی به هر 5 سرویس اضافه کنید:

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

روی افزودن به جدول ، سپس به‌روزرسانی و در نهایت ذخیره کلیک کنید.

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

در کنسول گوگل کلود، به مسیر Google Auth Platform > Clients (یا APIs & Services > Credentials ) بروید. روی Create Credentials (یا Create Client ) کلیک کنید و OAuth client ID را انتخاب کنید.
نوع برنامه را روی Desktop app انتخاب کنید.
نام آن را Workspace Agent Local بگذارید.
روی «ایجاد» کلیک کنید و فایل JSON را دانلود کنید. آن را به صورت محلی با نام client_secret.json ذخیره کنید.

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

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

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

۱. تنظیم دایرکتوری محیط

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

برای پوسته ابری گوگل: ابتدا، روی آیکون فعال‌سازی پوسته ابری ( >_ ) در نوار ابزار بالا سمت راست کنسول ابری گوگل کلیک کنید.
برای دستگاه محلی: ترمینال استاندارد خود را باز کنید.

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 منتقل یا کپی کنید.
پوسته ابری گوگل: با اجرای دستور زیر در پوسته ابری، فایل را ایجاد کنید ( [PASTE_JSON_HERE] را با محتوای JSON واقعی خود جایگزین کنید):

cat << 'EOF' > client_secret.json
[PASTE_JSON_HERE]
EOF

۳. احراز هویت و تولید فایل .env ( `auth.py` )

برای مدیریت یکپارچه احراز هویت و جلوگیری از مشکلات مسیریابی CLI مختص محیط، ما از یک اسکریپت پایتون سفارشی که توسط کتابخانه‌های رسمی احراز هویت گوگل پشتیبانی می‌شود، استفاده می‌کنیم. این اسکریپت جریان 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 که از قبل ایجاد کرده‌اید، ایجاد کنید و کد زیر را به آن اضافه کنید. این اسکریپت از Application Default Credentials (ADC) برای ارائه مجوز استفاده می‌کند و به طور خودکار اعتبارسنجی و به‌روزرسانی اعتبارنامه‌ها را صرفاً در حافظه از طریق یک ارائه‌دهنده هدر پویا انجام می‌دهد.

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

عامل خود را اجرا و آزمایش کنید

شما می‌توانید با استفاده از رابط کاربری وب تعاملی یا مستقیماً درون ترمینال/شل خود با عامل خود تعامل داشته باشید.

گزینه ۱: رابط کاربری وب تعاملی

اگر روی یک دستگاه محلی هستید:

از دایرکتوری ریشه پروژه gws-adk-agent خود، رابط وب ADK را اجرا کنید:
```
adk web
```
برای گفتگو با نماینده خود، http://localhost:8000 در مرورگر خود باز کنید.

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

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

گزینه ۲: حالت رابط خط فرمان ترمینال (جایگزین)

اگر ترجیح می‌دهید در ترمینال بمانید یا می‌خواهید از تنظیم پیش‌نمایش‌های مرورگر وب خودداری کنید، ADK یک حالت چت تعاملی بومی REPL ارائه می‌دهد.

از دایرکتوری ریشه پروژه gws-adk-agent خود، دستور زیر را اجرا کنید (این دستور هم روی ماشین محلی و هم روی پوسته ابری گوگل به طور یکسان کار می‌کند):

adk run workspace_agent

شما مستقیماً در پوسته خود وارد یک جلسه چت تعاملی خواهید شد:

Running agent gws_adk_agent, type exit to exit.
[user]:

سعی کنید از نماینده خود درخواست کنید

صرف نظر از رابط کاربری که انتخاب کرده‌اید، سعی کنید عامل را با پرس‌وجوهایی که از ابزارهای Workspace MCP استفاده می‌کنند، آزمایش کنید:

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

استقرار در زمان اجرای عامل GEAP

عامل کد حرفه‌ای خود را با استفاده از 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 ).

۶. در Gemini Enterprise ثبت نام کنید

اکنون، ما عامل ADK سفارشی را به Gemini Enterprise آورده‌ایم تا کاربران بتوانند به صورت بومی با آن چت کنند.

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

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

در کنسول گوگل کلود، روی منوی ناوبری (آیکون همبرگر) در گوشه بالا سمت چپ کلیک کنید. Google Auth Platform > Clients (یا APIs & Services > Credentials را در صورت عدم نمایش Google Auth Platform انتخاب کنید). روی Create Credentials (یا Create Client ) کلیک کنید و OAuth client ID را انتخاب کنید.
نوع برنامه را Web application انتخاب کنید.
نام آن را Workspace Agent Production بگذارید.
در بخش Authorized redirect URIs ، URI های زیر را اضافه کنید:
- روی افزودن آدرس اینترنتی (Add URI) کلیک کنید و آدرس https://vertexaisearch.cloud.google.com/oauth-redirect را وارد کنید.
- دوباره روی افزودن آدرس اینترنتی (Add URI) کلیک کنید و https://vertexaisearch.cloud.google.com/static/oauth/oauth.html را وارد کنید.
روی ایجاد کلیک کنید. در پنجره بازشو "OAuth client created" (یا از لیست Clients )، شناسه کلاینت و رمز کلاینت را کپی کنید. هنگام ثبت نام نماینده در Gemini Enterprise به این موارد نیاز خواهید داشت.

یک برنامه سازمانی Gemini ایجاد کنید

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

در زیر کارت Gemini Enterprise ، روی مدیریت کلیک کنید.
روی ایجاد برنامه کلیک کنید.
در بخش Gemini Enterprise ، روی ایجاد کلیک کنید.
در فیلد نام برنامه شما ، یک نام برای برنامه خود وارد کنید. شناسه برنامه شما زیر نام برنامه ظاهر می‌شود.
در فیلد نام خارجی شرکت یا سازمان خود ، نام شرکت یا سازمان را وارد کنید. برای این آموزش، می‌توانید Cymbal Bank استفاده کنید.
سراسری (Global) را به عنوان مکان برنامه خود انتخاب کنید.
روی ادامه کلیک کنید.

نماینده سفارشی را ثبت کنید

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

برنامه فعال خود را انتخاب کنید، به Agents بروید و روی + Add agent > Add Custom agent via Agent Runtime کلیک کنید.

در بخش مجوزها ، روی افزودن مجوز کلیک کنید:

نام مجوز : workspace-adk-auth (باید دقیقاً با CLIENT_AUTH_NAME در کد پایتون شما مطابقت داشته باشد)
شناسه کلاینت : شناسه کلاینت برنامه وب تولیدی که در بالا ایجاد شده است را جایگذاری کنید.
رمز کلاینت : رمز کلاینت برنامه وب عملیاتی که در بالا ایجاد شد را جایگذاری کنید.
Token URI : https://oauth2.googleapis.com/token

URI مربوط به احراز هویت : با جایگزینی YOUR_CLIENT_ID با شناسه کلاینتی که در مرحله ۵ بالا کپی کرده‌اید، URI را بسازید:

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

روی «انجام شد» کلیک کنید، سپس روی «بعدی» کلیک کنید.

در بخش پیکربندی :

نام نماینده : 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.

موتور استدلال زمان اجرای عامل : نام منبع موتور را که از خروجی adk deploy کپی کرده‌اید، جایگذاری کنید.

روی ایجاد کلیک کنید.

نماینده را در Gemini Enterprise امتحان کنید

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

گزینه ۱: پیش‌نمایش کنسول ابری گوگل

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

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

در نوار جستجو، عبارت زیر را وارد کنید:

Search for files in Drive related to 'Project Milestone', summarize them, and tell me if I have any meetings with the project owner today.

برای ارسال پرس و جو و مشاهده نتایج مستقیماً در کنسول، Enter را فشار دهید.

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

رابط کاربری برنامه وب Gemini Enterprise خود را باز کنید.
به منو ☰ > نمایندگان بروید و در قسمت «از سازمان شما» گزینه «نماینده فضای کاری حرفه‌ای» را انتخاب کنید.
همان عبارت جستجو شده در گزینه پیش‌نمایش کنسول ابری گوگل را تایپ کنید.
وقتی از شما خواسته شد تا مراحل رضایت کاربر OAuth را طی کنید، روی «مجاز کردن» کلیک کنید.
این عامل وظایف را به طور یکپارچه در چندین سرویس با استفاده از پروتکل MCP اجرا خواهد کرد!

۷. تمیز کردن

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

گزینه کنسول

به داشبورد API & Services بروید، سرویس‌های MCP که فعال کرده‌اید (مثلاً Calendar MCP، Gmail MCP) را انتخاب کنید و روی غیرفعال کردن API کلیک کنید. شناسه‌های OAuth Client را در زیر Google Auth Platform > Clients حذف کنید و استقرار Reasoning Engine را از کنسول Gemini Enterprise حذف کنید.

گزینه CLI

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

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

۸. تبریک

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

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

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

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

۱. مقدمه

کاری که انجام خواهید داد

آنچه نیاز دارید

۲. قبل از شروع

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

گزینه کنسول

گزینه CLI

فعال کردن APIها

گزینه کنسول

گزینه CLI این دستورات ترمینال را اجرا کنید:

پیکربندی برنامه چت

۳. پیکربندی رضایت‌نامه OAuth و کلاینت‌ها

صفحه رضایت OAuth را تنظیم کنید

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

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

۱. تنظیم دایرکتوری محیط

۲. فایل مدارک تحصیلی را آماده کنید

۳. احراز هویت و تولید فایل .env ( auth.py )

کد عامل را ایجاد کنید

عامل خود را اجرا و آزمایش کنید

گزینه ۱: رابط کاربری وب تعاملی

اگر روی یک دستگاه محلی هستید:

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

گزینه ۲: حالت رابط خط فرمان ترمینال (جایگزین)

سعی کنید از نماینده خود درخواست کنید

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

کد عامل تولید را ایجاد کنید

استقرار در زمان اجرای عامل GEAP

۶. در Gemini Enterprise ثبت نام کنید

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

یک برنامه سازمانی Gemini ایجاد کنید

نماینده سفارشی را ثبت کنید

نماینده را در Gemini Enterprise امتحان کنید

گزینه ۱: پیش‌نمایش کنسول ابری گوگل

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

۷. تمیز کردن

گزینه کنسول

گزینه CLI

۸. تبریک

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

اسناد مرجع

۳. احراز هویت و تولید فایل .env ( `auth.py` )