تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

إنشاء وكيل مستند إلى الذكاء الاصطناعي في Google Workspace باستخدام حزمة تطوير الوكلاء (ADK) وMCP

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية إنشاء وكيل ذكاء اصطناعي احترافي باستخدام حزمة تطوير الوكلاء (ADK) التي تتصل مباشرةً بخوادم MCP الرسمية في Google Workspace.

‫Model Context Protocol (MCP) هو معيار مفتوح يتيح لنماذج الذكاء الاصطناعي استخدام الأدوات التي توفّرها الخوادم البعيدة بأمان. ‫ADK هو إطار عمل من Google مخصّص للمطوّرين المحترفين لإنشاء وكلاء مستقلين. ومن خلال الجمع بينهما، يمكنك إنشاء وكلاء مخصّصين للغاية يستندون إلى بياناتك في Gmail وGoogle Drive و"تقويم Google" وGoogle Chat و"جهات اتصال Google".

للحصول على مستندات كاملة حول الأدوات والإعدادات المتاحة، يُرجى الاطّلاع على مقالة ضبط خوادم MCP في Google Workspace.

الإجراءات التي ستنفذّها

فعِّل خدمات MCP في Google Workspace في مشروعك على Google Cloud.
اضبط موافقة OAuth وأنشئ بيانات اعتماد لكل من الاختبار المحلي ونشر الإصدار العلني.
إنشاء وكيل ADK محلي يتصل بخوادم MCP في Google Workspace باستخدام رموز مميّزة ثابتة
إنشاء ونشر وكيل ADK جاهز للإنتاج في بيئة تشغيل وكيل Gemini Enterprise Agent Platform (GEAP) يستخدم ميزة إدخال الرموز المميزة الديناميكية.
تسجيل الوكيل المخصّص واختباره مباشرةً داخل Gemini Enterprise

المتطلبات

متصفّح ويب (مثل Chrome)
مشروع على Google Cloud تم تفعيل الفوترة فيه
حساب على Google Workspace (مع تفعيل الميزات الذكية)
يجب تثبيت الإصدار 3.11 من Python أو إصدار أحدث على جهازك.
تثبيت Google Cloud CLI (gcloud) وإعداده

2. قبل البدء

إنشاء مشروع على Google Cloud أو اختياره

Console Option

في Google Cloud Console، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا جديدًا.

خيار واجهة سطر الأوامر

أنشِئ مشروعًا جديدًا واضبطه على أنّه نشط:

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

تفعيل واجهات برمجة التطبيقات

لاستخدام خوادم MCP في Google Workspace، يجب تفعيل كل من واجهات برمجة التطبيقات العادية في Google Workspace وخدمات MCP المخصّصة.

Console Option

انقر على الأزرار التالية لتفعيلها باستخدام متصفّح الويب:

خيار واجهة سطر الأوامر (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.

في Google Cloud Console، ابحث عن Google Chat API، وانقر على Google Chat API > إدارة > الإعدادات.
إعداد تطبيق Chat:
- اسم التطبيق: ADK Workspace Agent
- عنوان URL الخاص بالأفاتار: 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 وإنشاء معرّفَي عميل منفصلَين: أحدهما للتطوير المحلي والآخر للوكيل الذي تم نشره.

في وحدة تحكّم Google Cloud، انقر على قائمة التنقّل (رمز القائمة) في أعلى يمين الصفحة. اختَر Google Auth Platform > العلامة التجارية (أو واجهات برمجة التطبيقات والخدمات > شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth إذا لم تظهر Google Auth Platform).
اضبط معلومات التطبيق:
- اسم التطبيق: Workspace ADK Agent
- البريد الإلكتروني المخصّص لدعم المستخدمين: اختَر عنوان بريدك الإلكتروني.
إعداد الجمهور: اختَر داخلي.
اضبط معلومات الاتصال: أدخِل عنوان بريدك الإلكتروني، ثم انقر على إنشاء.

انتقِل إلى الوصول إلى البيانات > إضافة نطاقات أو إزالتها. ضمن إضافة النطاقات يدويًا، أضِف النطاقات التالية لمنح إذن الوصول إلى الخدمات المطلوبة:

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

انقر على الإضافة إلى الجدول، ثم على تعديل، وأخيرًا على حفظ.

إنشاء معرِّف عميل للتطوير المحلي (تطبيق متوافق مع الكمبيوتر المكتبي)

عند إعداد عميل OAuth 2.0 لخوادم MCP في Google Workspace، يجب تفعيل إعداد التصنيف المستند إلى الوكلاء (is_agentic) من خلال اختيار استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي. يتم حظر عملاء OAuth الذين لم يتم تفعيل هذا الإعداد لهم من طلب نقاط نهاية MCP في Google Workspace.

في وحدة تحكّم Google Cloud، انتقِل إلى Google Auth Platform > العملاء (أو واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد). انقر على إنشاء عميل (أو إنشاء بيانات اعتماد > معرِّف عميل OAuth).
اختَر تطبيق متوافق مع الكمبيوتر المكتبي كنوع التطبيق.
أدخِل الاسم Workspace Agent Local.
اختَر استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي لتفعيل علامة تصنيف is_agentic في عميل OAuth.
انقر على إنشاء ونزِّل ملف JSON. احفظه على جهازك باسم client_secret.json.

4. تطوير الوكلاء واختبارهم

يصف هذا القسم كيفية إنشاء بيئة الوكيل. سنستخدم نهج الرمز المميّز الثابت للاختبار، حيث نجلب رمز OAuth المميّز باستخدام gcloud ونمرّره إلى McpToolset في ADK. يمكنك اتّباع هذه الخطوات باستخدام جهازك المحلي أو Google Cloud Shell.

اختَر بيئتك: الجهاز المحلي أو Google Cloud Shell لإعداد بيئة التطوير. ستستخدم كلتا الطريقتَين نص Python برمجيًا مشتركًا للمصادقة لضمان الاتساق على جميع المنصّات.

1. إعداد دليل البيئة

نفِّذ الأوامر التالية في الوحدة الطرفية لإنشاء دليل مشروع وتثبيت الحِزم المطلوبة.

بالنسبة إلى Google Cloud Shell: أولاً، انقر على رمز تفعيل Cloud Shell (>_) في شريط الأدوات في أعلى يسار Google Cloud Console.
بالنسبة إلى الجهاز المحلي: افتح الوحدة الطرفية العادية.

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، ويحفظ "بيانات الاعتماد التلقائية للتطبيق" (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]
)

تشغيل الوكيل واختباره

يمكنك التفاعل مع الوكيل باستخدام واجهة مستخدم الويب التفاعلية أو مباشرةً داخل Terminal/Shell.

الخيار 1: واجهة مستخدم تفاعلية على الويب

إذا كنت تستخدم جهازًا محليًا:

من الدليل الجذري لمشروع gws-adk-agent، ابدأ واجهة الويب الخاصة بـ ADK:
```
adk web
```
افتح http://localhost:8000 في متصفّحك للدردشة مع موظّف الدعم.

إذا كنت تستخدم Google Cloud Shell:

من الدليل الجذري لمشروع gws-adk-agent، ابدأ واجهة الويب الخاصة بـ ADK مع فرض المنفذ 8080 بشكل صريح:
```
adk web --port 8080 --allow_origins=*
```
انقر على زر معاينة الويب في أعلى يسار شريط أدوات Cloud Shell واختَر معاينة على المنفذ 8080 لفتح الواجهة في علامة تبويب جديدة.

الخيار 2: وضع واجهة سطر الأوامر (CLI) في Terminal (بديل)

إذا كنت تفضّل البقاء في الوحدة الطرفية أو تريد تجنُّب إعداد معاينات متصفّح الويب، توفّر 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

انشر وكيلك المبرمَج باستخدام واجهة سطر الأوامر في ADK:

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

6. التسجيل في Gemini Enterprise

والآن، نقدّم وكيل ADK المخصّص في Gemini Enterprise ليتمكّن المستخدمون من الدردشة معه بشكلٍ أصلي.

إنشاء معرّف عميل للإنتاج (تطبيق ويب)

لنشر وكيلك في مرحلة الإنتاج، عليك إنشاء معرّف عميل تطبيق ويب. على عكس عميل الكمبيوتر المكتبي المستخدَم للاختبار المحلي، يتيح عميل تطبيق الويب مسار OAuth آمنًا من جهة الخادم. يتيح ذلك للوكيل المستضاف على GEAP Agent Runtime تلقّي رموز المصادقة الخاصة بالمستخدم بأمان والتي تتم إعادة توجيهها من خلال Gemini Enterprise، باستخدام معرّف الموارد المنتظم (URI) المحدّد لإعادة التوجيه. هذا الإعداد ضروري ليتمكّن الوكيل من الوصول بأمان إلى بيانات Google Workspace نيابةً عن المستخدم في بيئة التشغيل الفعلي.

في وحدة تحكّم Google Cloud، انقر على قائمة التنقّل (رمز القائمة) في أعلى يمين الصفحة. اختَر Google Auth Platform > العملاء (أو واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد إذا لم تظهر Google Auth Platform). انقر على إنشاء عميل (أو إنشاء بيانات اعتماد > معرِّف عميل OAuth).
اختَر تطبيق ويب كنوع التطبيق.
أدخِل الاسم Workspace Agent Production.
في قسم معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه، أضِف معرّفات الموارد المنتظمة (URI) التالية:
- انقر على إضافة معرّف موارد منتظم (URI) وأدخِل https://vertexaisearch.cloud.google.com/oauth-redirect.
- انقر على إضافة معرّف موارد منتظم (URI) مرة أخرى وأدخِل https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
اختَر استخدام هذا العميل لوكيل مستنِد إلى الذكاء الاصطناعي لتفعيل علامة تصنيف is_agentic في عميل OAuth.
انقر على إنشاء. في مربّع الحوار "تم إنشاء عميل OAuth" (أو من قائمة العملاء)، انسخ معرّف العميل وسر العميل. ستحتاج إلى هذه المعلومات عند تسجيل الوكيل في Gemini Enterprise.

إنشاء تطبيق Gemini Enterprise

في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Gemini Enterprise:

ضمن بطاقة Gemini Enterprise، انقر على إدارة.
انقر على إنشاء تطبيق.
في قسم Gemini Enterprise، انقر على إنشاء.
في حقل اسم تطبيقك، أدخِل اسمًا لتطبيقك، وسيظهر معرّف تطبيقك أسفل اسم التطبيق.
في حقل الاسم الخارجي لشركتك أو مؤسستك، أدخِل اسم الشركة أو المؤسسة. في هذا البرنامج التعليمي، يمكنك استخدام Cymbal Bank.
اختَر عالمي (Global) كموقع جغرافي لتطبيقك.
انقر على متابعة.

تسجيل الوكيل المخصّص

افتح وحدة تحكّم Gemini Enterprise:

اختَر تطبيقك النشط، وانتقِل إلى الوكلاء، ثم انقر على + إضافة وكيل > إضافة وكيل مخصّص من خلال Agent Runtime.

في قسم التفويضات، انقر على إضافة تفويض:

اسم التفويض: workspace-adk-auth (يجب أن يتطابق تمامًا مع CLIENT_AUTH_NAME في رمز Python البرمجي)
معرّف العميل: الصِق معرّف العميل الخاص بتطبيق الويب الإنتاجي الذي تم إنشاؤه أعلاه.
سر العميل: الصِق سر العميل الخاص بتطبيق الويب الإنتاجي الذي تم إنشاؤه أعلاه.
معرّف الموارد المنتظم (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

انقر على تم، ثم على التالي.

في قسم الإعدادات:

اسم الوكيل: 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

يمكنك التفاعل مع وكيلك إما باستخدام النسخة الحصرية من Google Cloud Console (الأسرع للمطوّرين) أو تطبيق Gemini Enterprise للويب (تجربة المستخدم النهائي).

الخيار 1: النسخة الحصرية من Google Cloud Console

في وحدة تحكّم 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 لإرسال طلب البحث وعرض النتائج مباشرةً في وحدة التحكّم.

الخيار 2: تطبيق الويب Gemini Enterprise

افتح واجهة تطبيق Gemini Enterprise للويب.
انتقِل إلى القائمة ☰ > الوكلاء واختَر Workspace Pro Agent ضمن من مؤسستك.
اكتب طلب البحث نفسه كما في خيار "معاينة Google Cloud Console".
انقر على تفويض عندما يُطلب منك الانتقال إلى مسار موافقة المستخدم في OAuth.
سينفّذ الوكيل المهام بسلاسة على مستوى خدمات متعددة باستخدام بروتوكول MCP.

7. تَنظيم

لتجنُّب تحصيل رسوم غير ضرورية، عليك تنظيف مواردك:

الخيار "وحدة التحكّم"

انتقِل إلى لوحة بيانات واجهات برمجة التطبيقات والخدمات، واختَر خدمات MCP التي فعّلتها (مثل Calendar MCP وGmail MCP)، ثم انقر على إيقاف واجهة برمجة التطبيقات. احذف معرّفات عملاء OAuth ضمن Google Auth Platform > العملاء، واحذف عملية نشر Reasoning Engine من Gemini Enterprise Console.

خيار CLI

نفِّذ أوامر Terminal التالية لإيقاف خدمات 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.

ما تعلّمته

كيفية تفعيل خدمات Google Workspace MCP في Google Cloud
كيفية التعامل مع بيانات اعتماد OAuth لاختبار ADK المحلي باستخدام العناوين الثابتة
كيفية تنفيذ عملية إدخال الرموز المميّزة الديناميكية باستخدام header_provider للوكلاء في مرحلة الإنتاج
كيفية نشر وكيل ADK في GEAP Agent Runtime وتسجيله في Gemini Enterprise

إنشاء وكيل مستند إلى الذكاء الاصطناعي في Google Workspace باستخدام حزمة تطوير الوكلاء (ADK) وMCP تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

1. مقدمة

الإجراءات التي ستنفذّها

المتطلبات

2. قبل البدء

إنشاء مشروع على Google Cloud أو اختياره

Console Option

خيار واجهة سطر الأوامر

تفعيل واجهات برمجة التطبيقات

Console Option

خيار واجهة سطر الأوامر (CLI): نفِّذ أوامر الوحدة الطرفية التالية:

ضبط إعدادات تطبيق Chat

3- ضبط موافقة OAuth والعملاء

إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

إنشاء معرِّف عميل للتطوير المحلي (تطبيق متوافق مع الكمبيوتر المكتبي)

4. تطوير الوكلاء واختبارهم

1. إعداد دليل البيئة

2. إعداد ملف بيانات الاعتماد

3- المصادقة وإنشاء ملف ‎ .env ‏(auth.py)

إنشاء رمز الوكيل

تشغيل الوكيل واختباره

الخيار 1: واجهة مستخدم تفاعلية على الويب

إذا كنت تستخدم جهازًا محليًا:

إذا كنت تستخدم Google Cloud Shell:

الخيار 2: وضع واجهة سطر الأوامر (CLI) في Terminal (بديل)

جرِّب إدخال طلبات إلى وكيلك

5- النشر في مرحلة الإنتاج

إنشاء رمز الوكيل الإنتاجي

النشر في بيئة تشغيل وكيل GEAP

6. التسجيل في Gemini Enterprise

إنشاء معرّف عميل للإنتاج (تطبيق ويب)

إنشاء تطبيق Gemini Enterprise

تسجيل الوكيل المخصّص

تجربة الوكيل في Gemini Enterprise

الخيار 1: النسخة الحصرية من Google Cloud Console

الخيار 2: تطبيق الويب Gemini Enterprise

7. تَنظيم

الخيار "وحدة التحكّم"

خيار CLI

8. تهانينا

ما تعلّمته

المستندات المرجعية

إنشاء وكيل مستند إلى الذكاء الاصطناعي في Google Workspace باستخدام حزمة تطوير الوكلاء (ADK) وMCP

3- المصادقة وإنشاء ملف ‎ .env ‏(`auth.py`)