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

إنشاء وكيل مستند إلى الذكاء الاصطناعي في 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 الخمسة في Workspace باستخدام الرموز المميزة الثابتة
إنشاء وكيل ADK جاهز للاستخدام ونشره في وقت تشغيل الوكيل في "منصة وكلاء Gemini Enterprise" ‏ (GEAP) الذي يستخدم إدخال الرموز المميزة الديناميكية
يمكنك تسجيل وكيلك المخصّص واختباره مباشرةً في Gemini Enterprise.

المتطلبات

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

2. قبل البدء

إنشاء مشروع على السحابة الإلكترونية أو اختياره

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

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

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

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

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

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

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

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

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

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

# 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

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

لاستخدام خادم "منصّة إدارة الموافقة" في Google Chat، عليك إعداد تطبيق Chat في مشروعك على Google Cloud.

انتقِل إلى واجهة برمجة تطبيقات Google Chat > إدارة > الإعدادات.
إعداد تطبيق Chat:
- اسم التطبيق: ADK Workspace Agent
- عنوان URL الخاص بالصورة الرمزية: https://developers.google.com/chat/images/quickstart-app-avatar.png
- الوصف: MCP server connection for ADK Agent
- ضمن الوظائف، أوقِف تفعيل الميزات التفاعلية.
- ضمن السجلات، اختَر تسجيل الأخطاء في خدمة تسجيل البيانات.
انقر على حفظ.

3- ضبط موافقة OAuth والبرامج التي تعتمد على بروتوكول OAuth

تستخدم خوادم MCP في Google Workspace بروتوكول OAuth 2.0 للمصادقة الآمنة. يجب ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth وإنشاء معرّفَي عميل منفصلَين: أحدهما للتطوير المحلي والآخر للعامل الذي تم نشره.

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

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

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 Cloud Console، انتقِل إلى منصة Google للمصادقة > العملاء (أو واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد). انقر على إنشاء بيانات اعتماد (أو إنشاء عميل) واختَر معرِّف عميل OAuth.
اختَر تطبيق على الكمبيوتر كنوع التطبيق.
أطلِق عليها الاسم Workspace Agent Local.
انقر على إنشاء ونزِّل ملف 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`)

للتعامل مع المصادقة بشكلٍ متّسق وتجنُّب مشاكل توجيه واجهة سطر الأوامر الخاصة بالبيئة، نستخدم نصًا برمجيًا مخصّصًا بلغة 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 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]
)

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

يمكنك التفاعل مع وكيلك باستخدام واجهة المستخدم التفاعلية على الويب أو مباشرةً داخل 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: وضع واجهة سطر الأوامر (بديل)

إذا كنت تفضّل البقاء في نافذة الأوامر أو أردت تجنُّب إعداد معاينات متصفّح الويب، يوفّر "مجموعة أدوات تطوير Android" وضع محادثة REPL تفاعليًا أصليًا.

من دليل جذر مشروع gws-adk-agent، نفِّذ الأمر التالي (يعمل هذا الأمر بشكل مماثل على كل من الجهاز المحلي وGoogle Cloud Shell):

adk run workspace_agent

ستدخل إلى جلسة محادثة تفاعلية مباشرةً في shell:

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

يمكنك نشر وكيلك الذي يتضمّن رمزًا برمجيًا باستخدام واجهة سطر الأوامر (CLI) لحزمة نشر الوكلاء (ADK) باتّباع الخطوات التالية:

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 بشكل آمن، وذلك باستخدام معرّف الموارد المنتظم لإعادة التوجيه المحدّد. هذا الإعداد ضروري لكي يتمكّن الوكيل من الوصول بأمان إلى بيانات 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.
انقر على إنشاء. في النافذة المنبثقة "تم إنشاء عميل OAuth" (أو من قائمة العملاء)، انسخ معرّف العميل وسر العميل. ستحتاج إلى هذه المعلومات عند تسجيل الوكيل في Gemini Enterprise.

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

في Google Cloud Console، انتقِل إلى صفحة 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.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.

محرك الاستدلال في Agent Runtime: الصِق اسم مورد المحرك الذي نسخته من ناتج adk deploy.

انقر على إنشاء.

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

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

الخيار 1: معاينة Google Cloud Console

في Google Cloud Console، انتقِل إلى صفحة 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 ضمن من مؤسستك.
اكتب طلب البحث نفسه كما في خيار "المعاينة" في Google Cloud Console.
انقر على تفويض عندما يُطلب منك اتّباع مسار موافقة المستخدم على بروتوكول OAuth.
سينفّذ الوكيل المهام بسلاسة على مستوى خدمات متعددة باستخدام بروتوكول MCP.

7. تَنظيم

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

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

انتقِل إلى لوحة بيانات واجهات برمجة التطبيقات والخدمات، واختَر خدمات MCP التي فعّلتها (مثل Calendar MCP وGmail MCP)، ثم انقر على إيقاف واجهة برمجة التطبيقات. احذف معرّفات عميل OAuth ضِمن منصة Google للمصادقة > العملاء، واحذف عملية نشر 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

8. تهانينا

تهانينا! لقد أنشأت واختبرت ونشرت بنجاح وكيل الذكاء الاصطناعي ADK الذي يتضمّن رموزًا برمجية احترافية والمرتبط مباشرةً بخوادم MCP الرسمية في Google Workspace.

ما تعلّمته

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

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

1. مقدمة

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

المتطلبات

2. قبل البدء

إنشاء مشروع على السحابة الإلكترونية أو اختياره

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

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

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

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

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

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

3- ضبط موافقة OAuth والبرامج التي تعتمد على بروتوكول OAuth

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

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

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

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

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

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

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

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

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

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

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

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

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

5- نشر الإصدار العلني

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

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

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

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

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

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

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

الخيار 1: معاينة Google Cloud Console

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

7. تَنظيم

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

خيار CLI

8. تهانينا

ما تعلّمته

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

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