إنشاء وكيل ذكاء اصطناعي يعمل نيابةً عن المستخدم باستخدام "هوية الوكيل" و"مدير المصادقة"

1. مقدمة

يرى الوكيل الذي لديه بيانات اعتماد خاصة به مع إذن واسع النطاق بيانات الجميع. في هذا الدرس التطبيقي حول الترميز، ستنشئ وكيلاً يستدعي واجهة برمجة تطبيقات تابعة لجهة خارجية باستخدام بيانات اعتماد المستخدم الذي سجّل الدخول، وبالتالي سيتمكّن الوكيل من رؤية المحتوى الذي يمكن لهذا المستخدم رؤيته فقط.

ستنشئ هذا التطبيق باستخدام حزمة تطوير الوكلاء (ADK) من Google وGemini Enterprise.

على وجه التحديد، ستتعرّف على كيفية تصميم بنية ذات هوية مزدوجة حيث:

  1. يعمل الوكيل نيابةً عن نفسه (هوية الوكيل): باستخدام هوية وكيل مستندة إلى SPIFFE، يستدعي الوكيل خدمة Auth Manager ويخزّن بيانات القياس عن بُعد ويطلب بيانات من Google Cloud APIs.
  2. يعمل الوكيل نيابةً عن المستخدم (الهوية المفوضة من المستخدم): للوصول إلى موارد خارجية مثل GitHub، يبدأ الوكيل عملية الحصول على موافقة OAuth الثلاثية الأطراف (3LO) من أجل الاستعلام عن الأدوات بشكل آمن باستخدام بيانات اعتماد المستخدم.

بنية الهوية المزدوجة

لتحقيق ذلك، ستتعرّف على كيفية:

  1. إنشاء وكيل ADK يتصل بخادم بروتوكول سياق النموذج (MCP) من GitHub
  2. عدِّل أداة الوكيل من رمز PAT ثابت على GitHub (رمز مميّز للوصول الشخصي) إلى مسار بروتوكول OAuth الثلاثي (3LO) باستخدام Google Cloud Auth Manager.
  3. نشر الوكيل بشكل آمن في بيئة تشغيل الوكيل وتوفير هوية الوكيل
  4. اضبط أدوار إدارة الهوية وإمكانية الوصول (IAM) لمنح الوكيل إذن الوصول إلى مخزن الرموز المميزة نيابةً عن المستخدم.
  5. التعرّف على مسار المصادقة الثلاثية الأطراف الكامل في "إدارة المصادقة" على Google Cloud

المتطلبات الأساسية

قبل البدء، تأكَّد من توفّر ما يلي:

  • مشروع Google Cloud تم تفعيل الفوترة فيه
  • يجب أن تكون حزمة تطوير البرامج (SDK) من Google Cloud‏ (gcloud CLI) مثبّتة ومصدَّقة لمشروعك على جهازك. يجب استخدام الإصدار 586.0.0 أو إصدار أحدث — شغِّل gcloud components update.
  • يجب أن يكون الإصدار 3.10 إلى 3.13 من Python مثبَّتًا على الجهاز.
  • تم تثبيت uv أداة إدارة الحِزم (pip install uv).
  • حساب على GitHub لتسجيل تطبيق OAuth وإنشاء رموز مميزة إذا لم يكن لديك حساب على GitHub، يمكنك استخدام أي خادم بروتوكول سياق النموذج (MCP) تابع لجهة خارجية يتيح مصادقة OAUTH على ثلاث مراحل.

2. إعداد المشروع

1. المصادقة على Google Cloud

يمكنك المصادقة على Google Cloud من سطر الأوامر المحلي للتأكّد من أنّ بيئتك لديها الأذونات اللازمة للنشر في Agent Runtime وتوفير Agent Identity وإعداد Auth Manager أثناء هذا المختبر:

نفِّذ الأوامر التالية لتسجيل الدخول إلى حسابك على Google Cloud من أجل إعداد "بيانات الاعتماد التلقائية للتطبيق" (ADC):

gcloud auth login
gcloud auth application-default login

2. تفعيل خدمات Google Cloud المطلوبة

فعِّل واجهات برمجة التطبيقات اللازمة في مشروعك على Google Cloud لتنفيذ هذا الدرس العملي. نفِّذ الأمر التالي في الوحدة الطرفية:

gcloud services enable \
    agentidentity.googleapis.com \
    agentregistry.googleapis.com \
    aiplatform.googleapis.com \
    apphub.googleapis.com

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

3- تثبيت واجهة سطر الأوامر للوكلاء وإعداد المشروع

agents-cli هي أداة سطر الأوامر المستخدَمة لإنشاء بنية أساسية لوكلاء ADK وإدارتهم واختبارهم ونشرهم على Gemini Enterprise. ثبِّت التطبيق على جهازك باتّباع الخطوات التالية:

uvx google-agents-cli setup

التحقّق من عملية التثبيت:

agents-cli --help

من المفترض أن تظهر قائمة تعليمات واجهة سطر الأوامر تعرض الأوامر المتاحة (مثل deploy وrun وstatus).

إنشاء بنية المشروع الأولية ستبدأ بنموذج أولي محلي ثم تحسّنه لاحقًا لنشره في Agent Runtime:

agents-cli create secure-agent-demo --prototype --yes

يؤدي ذلك إلى إنشاء الدليل secure-agent-demo الذي يحتوي على رمز الوكيل الأساسي والتبعيات وملفات الاختبار.

4. إضافة إضافات ADK المطلوبة

يتم شحن pyproject.toml الذي تم إنشاؤه google-adk[gcp,otel-gcp]، والذي ينقصه عنصران إضافيان يحتاج إليهما هذا الوكيل: mcp لمجموعة أدوات GitHub، وagent-identity لـ "مدير المصادقة" لاحقًا في المختبر. افتح ملف secure-agent-demo/pyproject.toml وغيِّر السطر google-adk إلى ما يلي:

"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",

بعد ذلك، ثبِّت ما يلي:

cd secure-agent-demo
agents-cli install

3- إنشاء الوكيل واختباره

1. إنشاء الوكيل

داخل مشروعك، استبدِل الرمز في ملف agent.py بما يلي:

# app/agent.py

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from app.tools import github_toolset

import os
import google.auth

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.

Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=INSTRUCTION,
    tools=[github_toolset()],
)

app = App(
    root_agent=root_agent,
    name="app",
)

يحدّد هذا الملف ثلاثة مكوّنات رئيسية للوكيل:

  • تعليمات النظام (INSTRUCTION): تحدّد هذه التعليمات الشخصية ونطاق المساعد في عملية الفرز في GitHub، وتفرض قواعد أمان صارمة (مثل الوصول للقراءة فقط وتوجيه المستخدمين إلى المصادقة في حال حدوث أخطاء).
  • إعدادات الوكيل (root_agent): تنشئ هذه الإعدادات حزمة تطوير تطبيقات (ADK) Agent باستخدام نموذج gemini-3.8-flash، وتضبط منطق إعادة المحاولة في HTTP، وتزوّد الوكيل بمجموعة أدوات GitHub.
  • غلاف التطبيق (app): يغلّف العنصر الأساسي في حاوية App ADK، ما يجعله قابلاً للنشر في Agent Runtime.

2. إضافة أداة بروتوكول سياق النموذج (MCP) في GitHub

يربط الوكيل GitHub من خلال بروتوكول سياق النموذج (MCP). أنشئ ملفًا جديدًا باسم tools.py ضمن المجلد app/ لتسجيل مَعلمات ربط بوابة MCP. انسخ الرمز التالي والصِقه:

# app/tools.py

from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")

def github_toolset() -> McpToolset:
    """Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=GITHUB_MCP_URL,
            headers={
                "Authorization": f"Bearer {GITHUB_TOKEN}",
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        )
    )

تنشئ هذه الدالة أداة تستدعي خادم MCP الخاص بمنصة GitHub:

  • مجموعة أدوات MCP (McpToolset): تكتشف إمكانات GitHub وتسجّلها بشكل ديناميكي كأدوات وكيل قابلة للاستدعاء.
  • مَعلمات الاتصال (StreamableHTTPConnectionParams): تشير إلى مجموعة الأدوات إلى بوابة MCP العامة في GitHub.
  • عناوين التفويض: يتم إدخال GITHUB_TOKEN كرمز مميز من النوع Bearer ويتم فرض وضع القراءة فقط (X-MCP-Readonly: true) مباشرةً في طبقة النقل.

3- الاختبار محليًا باستخدام رمز PAT (رمز الوصول الشخصي) من GitHub

لتشغيل البرنامج المساعد محليًا باستخدام بيانات اعتماد ثابتة، اتّبِع الخطوات التالية:

  1. أنشئ رمز دخول شخصي في GitHub. امنحه إذن الوصول للقراءة إلى مستودعاتك، وإلا لن يتمكّن الوكيل من الاطّلاع على البيانات العامة فقط ولن يعرض الطلب أدناه أي نتائج.
  2. اضبطها في بيئتك: 
    export GITHUB_TOKEN="your_github_pat_here"
  3. انتقِل إلى المجلد secure-agent-demo. التشغيل: 
    cd secure-agent-demo
agents-cli playground
  4. افتح واجهة Playground، واختَر المجلد "app" من القائمة المنسدلة. في مربّع الدردشة، اكتب "Fetch my contributions across my private repositories over the last 6 months"، وتأكَّد من أنّ الوكيل يستدعي أداة GitHub ويعرض بيانات من مستودعاتك الخاصة.

4. ضبط Auth Manager

على الرغم من أنّ الترميز الثابت لبيانات الاعتماد الثابتة (مثل رمز PAT) مناسب لإنشاء النماذج الأولية، إلا أنّه يعرّض تطبيقات الإنتاج لتسرُّب بيانات الاعتماد ووقت تعذُّر إعادة تحميل الرمز المميز يدويًا وعدم توفُّر عناصر تحكّم في الوصول متوافقة مع السحابة الإلكترونية.

لحلّ هذه المشكلة، توفّر Google Cloud خدمة Agent Identity Auth Manager. مدير مصادقة هوية الوكيل هو خزينة بيانات اعتماد مصمّمة للمساعدة في حماية بيانات الاعتماد. تتيح هذه الواجهة للوكلاء المصادقة باستخدام مفتاح واجهة برمجة التطبيقات أو معرّف عميل OAuth وسرّه، أو نيابةً عن مستخدم من خلال تفويض OAuth باستخدام رموز مميّزة للوصول خاصة بالمستخدم النهائي.

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

سير عمل Auth Manager

  1. اعتراض الموافقة الديناميكي: عندما يحاول الوكيل تنفيذ أداة نيابةً عن مستخدم، يتحقّق ADK من "مدير المصادقة" بحثًا عن بيانات اعتماد صالحة حالية. إذا لم يكن هناك أيّ رمز، يعرض Auth Manager عنوان URL لمنح الإذن لبدء مسار الموافقة على OAuth ذي الثلاث خطوات (3LO).
  2. ميزة "تخزين آمن": بعد أن يمنح المستخدم النهائي الإذن للتطبيق، يعترض "مدير المصادقة" تلقائيًا عملية معاودة الاتصال ببروتوكول OAuth ويخزّن رموز الوصول والتحديث الناتجة للمستخدم في مخزن بيانات اعتماد آمن تديره Google.
  3. دورة حياة الرمز المميّز الآلية: يدير Auth Manager بالكامل انتهاء صلاحية الرمز المميّز وتدويره في الخلفية، ما يغنيك عن الحاجة إلى منطق يدوي لإعادة تحميل الرمز المميّز أو التوقف عن العمل.
  4. تنفيذ الأدوات بدون مفتاح سرّي: بالنسبة إلى الإجراءات اللاحقة، يطلب الوكيل (الذي تتم المصادقة عليه من خلال هوية وكيل SPIFFE) بشكل ديناميكي رمز الوصول المفوَّض الخاص بالمستخدم من "مدير المصادقة" في وقت التشغيل، ما يحافظ على سرية كلّ من رمز العميل والوكيل تمامًا.

الخطوة أ: ضبط GitHub كموفّر مصادقة

نفِّذ الأمر gcloud التالي لإنشاء موفّر مصادقة GitHub في مشروعك على Google Cloud. عليك تقديم معرّف العميل وسرّه لاحقًا، إذ لن تصدرهما GitHub إلا بعد معرفة عنوان URL لرد الاتصال الخاص بموفّر الهوية هذا.

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1" \
    --three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
    --three-legged-oauth-token-url="https://github.com/login/oauth/access_token"

قدِّم وصفًا لموفّر الخدمة لاسترداد عنوان URL لإعادة التوجيه عبر بروتوكول OAuth الذي تم إنشاؤه:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1"

الحقل هو redirectUrl، وهو مُضمَّن ضمن authProviderTypeParams.threeLeggedOauth. لقراءتها مباشرةً، اتّبِع الخطوات التالية:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" --location="us-central1" \
    --format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"

يبدو أنّها https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.

الخطوة ب: تسجيل تطبيق OAuth في GitHub

  1. انتقِل إلى صفحة إعدادات المطوّرين في GitHub وانقر على تسجيل تطبيق OAuth جديد.
  2. بالنسبة إلى عنوان URL للصفحة الرئيسية، أدخِل عنوان URL لتطبيق الواجهة الأمامية (مثل http://localhost:8501 للنماذج الأولية المحلية). يمكنك تغييرها لاحقًا إلى عنوان URL الذي تم نشره في مرحلة الإنتاج.
  3. اضبط معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه على redirectUrl الذي تم استرداده في الخطوة السابقة.
  4. انقر على تسجيل التطبيق، ثمّ انقر على إنشاء سرّ عميل جديد واحفظ كلّاً من معرّف العميل وسرّ العميل.

الخطوة C: إضافة بيانات اعتماد GitHub إلى موفّر المصادقة

استبدِل رقم تعريف مشروعك ومعرّف العميل وسر العميل، ثم نفِّذ هذا الأمر:

gcloud agent-identity auth-providers update github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
    --three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"

يعرض الأمر المزوّد مع clientId، ولكن لا يتم عرض السرّ.

👉 بعد إكمال هذه الخطوة، تم الآن إعداد Google Cloud Auth Manager بالكامل باستخدام بيانات اعتماد تطبيق GitHub OAuth، ما يتيح إعداد Google Cloud ليعمل كمخزن آمن يتعامل مع الموافقة ودورات حياة الرموز المميزة.

5- تبديل رمز PAT إلى Auth Manager

بعد إعداد "مدير المصادقة" بالكامل، الخطوة التالية هي تعديل رمز أداة الوكيل. استبدِل app/tools.py بالرمز التالي.

👉 استبدِل رقم تعريف المشروع والموقع الجغرافي في المتغيّر OAUTH_PROVIDER_NAME أدناه.

# app/tools.py

from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())

# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"

# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
    "OAUTH_CONTINUE_URI", 
    "http://localhost:8501/validateUserId"
)

def github_toolset() -> McpToolset:
    """Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
    auth_scheme = GcpAuthProviderScheme(
        name=OAUTH_PROVIDER_NAME,
        # Required to read private repositories. Auth Manager currently supports a
        # single scope for GitHub.
        scopes=["repo"],
        continue_uri=OAUTH_CONTINUE_URI,
    )
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://api.githubcopilot.com/mcp/",
            headers={
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        ),
        auth_scheme=auth_scheme,
    )

فهم رمز الأداة

التغيير الرئيسي هو auth_scheme. يعني ربطها بمجموعة الأدوات أنّه كلما طلب الوكيل GitHub، يطلب ADK أولاً الرمز المميز للمستخدم من Auth Manager، وإذا لم يكن هناك رمز مميز بعد، يطلب من المستخدم تسجيل الدخول بدلاً من حدوث خطأ. تمت إزالة GITHUB_TOKEN المضمّنة في الرمز بالكامل.

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

بعد تعديل أداة MCP في GitHub لاستخدام "إدارة المصادقة" بدلاً من ذلك، تتمثّل الخطوة التالية في نشر الوكيل إلى Agent Runtime. يؤدي نشرها مع تفعيل "هوية الوكيل" إلى توفير معرّف SPIFFE فريد للوكيل.

لنبدأ بتهيئة إعدادات النشر للمشروع. نفِّذ ما يلي في الوحدة الطرفية:

agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes

يفحص هذا الأمر بنية مشروعك للتأكّد من توافقه مع ADK، ويُعدّ إعدادات حِزم الحاويات الأساسية، وينشئ ملف agents-cli-manifest.yaml في جذر مشروعك معبأ مسبقًا بإعدادات النشر التلقائية.

👉 افتح ملف agents-cli-manifest.yaml الذي تم إنشاؤه حديثًا وتحقّق من الحقل region أو عدِّله إلى us-central1 للتأكّد من نشر الوكيل في المنطقة نفسها التي تم فيها نشر موفّر المصادقة:

region: "us-central1"

نشر الوكيل باستخدام هوية وكيل

تفعيل باستخدام adk deploy agent_engine. يوفّر ذلك للوكيل هوية وكيل خاصة به، وهي هوية تشفير فريدة تستند إلى SPIFFE وتخصّ عملية النشر هذه، ويستخدمها الوكيل للمصادقة على Auth Manager وخدمات Google Cloud الأخرى.

👉 استبدِل YOUR_PROJECT_ID قبل تشغيل هذه الأوامر:

# Request a SPIFFE-backed Agent Identity for this deployment
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json

# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
    --output-file app/requirements.txt

uv run adk deploy agent_engine app \
    --project="YOUR_PROJECT_ID" \
    --region="us-central1"

تستغرق عملية النشر بضع دقائق لإنشاء الحاوية وتحميلها. بعد الانتهاء، تطبع واجهة سطر الأوامر اسم المورد الذي تم نشره. دوِّن قيمة reasoningEngines/ENGINE_ID، لأنّك ستحتاج إليها لتفويض الوكيل وتوجيه عميل واجهة المستخدم إليها.

تفويض هوية الوكيل

بعد تشغيل وكيلك في السحابة الإلكترونية، يحتاج إلى إذن للوصول إلى بيانات الاعتماد المخزّنة في Auth Manager. تلقائيًا، لا يمكن الوصول إلى موارد السحابة الخارجية باستخدام هوية SPIFFE الخاصة بالوكيل.

نفِّذ الأمر gcloud التالي لمنح الدور roles/agentidentity.user لهوية وكيلك في مورد موفّر المصادقة. يمنح هذا الإعداد الوكيل الأذونات التي يحتاجها بالضبط لطلب رموز مميّزة للمستخدمين من الخزنة، ولا يمنحه أي أذونات أخرى.

👉 استبدِل YOUR_PROJECT_ID وYOUR_ORG_ID وYOUR_PROJECT_NUMBER وYOUR_ENGINE_ID (يظهر رقم تعريف المحرّك في ناتج النشر أعلاه).

للحصول على YOUR_ORG_ID، نفِّذ الأمر أدناه:

gcloud projects get-ancestors $(gcloud config get-value project) \
  --filter="type=organization" \
  --format="value(id)"

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"

الآن، امنح حسابك الدور نفسه على مقدّم الخدمة. يطلب عميل واجهة المستخدم الذي تشغّله في الخطوة التالية واجهة برمجة التطبيقات الخاصة بإكمال بيانات الاعتماد باستخدام بيانات الاعتماد التلقائية للتطبيق، لذا بدون ذلك، سيتعذّر تنفيذ مسار الموافقة مع ظهور الخطأ 403 على agentidentity.authProviders.retrieveCredentials:

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="user:YOUR_EMAIL_ADDRESS"

7. التعرّف على مسار الموافقة الخاص بالجهات الخارجية

بعد نشر الوكيل في "بيئة تشغيل الوكيل" باستخدام "هوية وكيل" آمنة، تتمثّل الخطوة التالية في توفير واجهة أمامية مخصّصة للمستخدمين للدردشة مع الوكيل. والأهم من ذلك، يتطلّب Google Cloud Auth Manager معالج ردّ الاتصال لتطبيق العميل لإكمال حلقة المصادقة.

على الرغم من أنّ Google Cloud Auth Manager يدير بيانات اعتماد المستخدمين بشكل آمن داخل خزنة، لا يمكنه إكمال عملية تبادل رموز OAuth المميزة بمفرده. تعتمد عملية المصافحة الثلاثية على تطبيق العميل لسدّ الفجوة:

  1. عندما يمنح المستخدم إذنًا لتطبيق GitHub، يعيد GitHub توجيهه إلى الخاص بموفّر مصادقة هوية الوكيل redirectUrl.
  2. بعد ذلك، يعيد "مدير المصادقة" توجيه النافذة المنبثقة للمتصفّح إلى عنوان URL لبرنامج معالجة على جهة العميل (continue_uri).
  3. يقع على عاتق تطبيق العميل مسؤولية اعتراض عملية إعادة التوجيه هذه وقراءة الرقم الخاص من ملفات تعريف الارتباط في المتصفّح واستدعاء نقطة النهاية credentials:finalize في Google Cloud لإكمال عملية تأكيد الاتصال.
  4. بعد أن ينهي العميل عملية التبادل، يحفظ Google Cloud الرمز المميز بشكل آمن في خزنة موفّر المصادقة، ما يسمح للوكيل باستدعاء أداة GitHub.

وبدون هذا العميل المخصّص الذي يستضيف نقطة نهاية معاودة الاتصال، تظل عملية المصافحة غير مكتملة، ولا يمكن لمخزن المفاتيح تخزين بيانات الاعتماد.

يمتد مسار OAuth 3LO التفاعلي على عدة طبقات. في ما يلي دورة التنفيذ الكاملة لطلب أداة. سنشرح ذلك بالتفصيل أدناه وفي الخطوة التالية.

👉 انقر على الصورة لتكبيرها.

مسار تسلسل OAuth ذو الخطوات الثلاث

المسؤوليات الأساسية للعميل في اتفاقية Handshake

  • نقل طلب الموافقة (الخطوتان 5 و6): يرسل الوكيل adk_request_credential يتضمّن عنوان URL الخاص بالموافقة ورقمًا خاصًا يُستخدَم مرة واحدة، ويفتح العميل النافذة المنبثقة ويخزّن الرقم الخاص كملف تعريف ارتباط.
  • استضافة معاودة الاتصال لإعادة التوجيه (الخطوتان 10 و11): /validateUserId، حيث يرسل "مدير المصادقة" النافذة المنبثقة بعد الحصول على الموافقة.
  • إنهاء الرمز المميّز (الخطوات من 12 إلى 14): ادمِج حالة التحقّق من صحة البيانات من عملية إعادة التوجيه مع الرقم الخاص المخزّن مؤقتًا، واستدعِ credentials:finalize، ما يؤدي إلى تخزين الرمز المميّز في الخزنة.

إنشاء تطبيق العميل الخاص بك

لست بحاجة إلى كتابة هذا العميل للتمرين المعملي، لأنّ الخطوة التالية ستشغّل عميلاً تم إنشاؤه مسبقًا. عندما تريد تنفيذ ذلك في تطبيقك، إليك مرجعان يمكنك الاستعانة بهما:

8. تشغيل واجهة مستخدم العميل محليًا

كما تتبّعنا في مخطط التسلسل لإجراءات الموافقة على 3LO، يحتاج Auth Manager إلى إعادة توجيه النافذة المنبثقة للمتصفّح إلى نقطة نهاية معاودة الاتصال من جهة العميل. يستضيف العميل النموذجي نقطة النهاية هذه على /validateUserId. لننفّذها محليًا.

نسخ ملفات العميل إلى "الملفات المحلية"

انتقِل إلى المجلد gcp_auth/client في مستودع adk-python على GitHub. يحتوي هذا المجلد على مواد العرض المطلوبة لإنشاء حاوية برنامج الدردشة.

👉 انسخ كل الملفات ضِمن gcp_auth/client إلى بيئتك المحلية:

  • main.py: نص برمجي لتطبيق FastAPI يحتوي على معاودة الاتصال الخاصة بإكمال الرمز المميّز (/validateUserId) التي ناقشناها في القسم السابق.
  • static/: يحتوي على صفحات HTML.

يمكنك بدلاً من ذلك إجراء عملية استخراج جزئي للمجلد:

git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git
cd adk-python
git sparse-checkout init --cone
git sparse-checkout set contributing/samples/integrations/gcp_auth/client
git checkout

تشغيل العميل

  1. انتقِل إلى المجلد client الذي نسخته للتو: 
    cd adk-python/contributing/samples/integrations/gcp_auth/client
  2. أنشئ بيئة افتراضية وثبِّت التبعيات الخاصة بالعميل. يحتوي المجلد على requirements.txt وليس على pyproject.toml، لذا سيتعذّر تنفيذ uv run uvicorn ... وحده وسيظهر الخطأ Failed to spawn: uvicorn: 
    uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install --python .venv/bin/python -r requirements.txt
  3. وجِّه العميل إلى الوكيل الذي نشرته، ثم ابدأه على المنفذ 8501: 
    export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_ID=YOUR_ENGINE_ID

.venv/bin/uvicorn main:app --port 8501
  4. تأكَّد من بدء تشغيل الخادم بنجاح والاستماع إلى http://localhost:8501.

9. اختبار مسار OAuth

بعد نشر جميع الخدمات وضبط عمليات ربط IAM وتحديد متغيّرات البيئة، أنت الآن جاهز لاختبار مسار التفويض الآمن من البداية إلى النهاية الذي يفوّضه المستخدم.

الخطوة (أ): بدء تنفيذ الأداة

  1. افتح علامة تبويب متصفّح وانتقِل إلى عنوان URL الخاص بالعميل: http://localhost:8501.
  2. في اللوحة اليمنى، اضبط "نوع الوكيل" على Remote Agent Engine.
  3. اكتب مشروع Google Cloud والموقع الجغرافي. انقر على Load Remote Agents. من المفترض أن يؤدي ذلك إلى تحميل جميع البرامج التي تم نشرها في مشروعك.
  4. اختَر الوكيل المناسب من القائمة المنسدلة واحفظ الإعدادات.
  5. في مربّع المحادثة، اكتب: 
    Fetch my contributions across my private repositories over the last 6 months
    واضغط على Enter.
  6. راقِب واجهة مستخدم المحادثة: بما أنّ الوكيل لا يملك بيانات اعتماد لجلسة المستخدم بعد، سيتلقّى طلب مصادقة ويعرض بطاقة "المصادقة مطلوبة" في سلسلة المحادثات.
  1. سيتم فتح نافذة منبثقة منفصلة في المتصفّح، وسيتم إعادة توجيهك من خلال "مدير المصادقة" في Google Cloud إلى صفحة منح إذن OAuth في GitHub.
  2. راجِع الأذونات المطلوبة وانقر على تفويض.
  3. ستتم إعادة توجيهك من GitHub إلى Google Cloud، التي ستعيد توجيه النافذة المنبثقة إلى localhost عنوان URL الخاص بعملية الاسترجاع /validateUserId.
  4. تعالج خدمة معاودة الاتصال عملية المصافحة لبيانات الاعتماد وتنهيها.

الخطوة (ج): استئناف

  1. بعد إغلاق النافذة المنبثقة، سترصد علامة تبويب المحادثة الرئيسية عملية الإغلاق تلقائيًا.
  2. يرسل الواجهة الأمامية حمولة استئناف إلى الوكيل.
  3. يستردّ الوكيل الرمز المميز الذي تم تبادله حديثًا بشكل آمن من "مدير مصادقة Google Cloud"، ويطلب أدوات GitHub MCP نيابةً عنك، ويبث البيانات من مستودعاتك الخاصة مباشرةً إلى نافذة المحادثة، وهي بيانات ما كان بإمكان الوكيل الوصول إليها بمفرده.

الخطوة د: فحص سجلّات Cloud

للتأكّد من أنّه تمّت معالجة عملية استبدال الرمز المميز وإنهائها بشكل آمن، اتّبِع الخطوات التالية:

  1. انتقِل إلى مستكشف السجلّات في Google Cloud Console.
  2. ابحث عن سجلات الخادم التي تؤكّد استخراج الرقم العشوائي والتحقّق منه بنجاح: 
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
INFO:secure-agent-client:Successfully finalized auth provider credentials.
  3. فحص سجلّات وقت تشغيل الوكيل: يمكنك بدلاً من ذلك عرض سجلّات التنفيذ مباشرةً داخل "وحدة تحكّم منصة الوكيل":
    • انتقِل إلى وحدة تحكّم بيئة تشغيل الوكيل.
    • انقر على الوكيل الذي تم نشره من القائمة.
    • انتقِل إلى علامة التبويب Playground، وسيؤدي ذلك إلى عرض سجلّات الوكيل المباشر في اللوحة السفلية، ما يتيح لك الاطّلاع على حلقة الاستدلال الخاصة بالوكيل وتفاصيل تنفيذ الأداة ودورة حياة استرداد الرمز المميز في الوقت الفعلي.

10. تنظيف

لتجنُّب الرسوم المستمرة على Google Cloud، عليك إزالة الموارد التي تم نشرها:

# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3

# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
    --project=YOUR_PROJECT_ID --location=us-central1

# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.

# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID

# Optionally, delete the GitHub PAT Token and the OAuth app: 
# https://github.com/settings/personal-access-tokens

تنظيف الملفات المحلية

يمكنك اختياريًا تنفيذ ما يلي لتنظيف بيئتك المحلية بالكامل:

  1. أوقِف خادم uvicorn المحلي بالضغط على Ctrl+C في الوحدة الطرفية التي يتم تشغيله فيها.
  2. أزِل أدلة المشاريع التي تم إنشاؤها أثناء هذا المختبر:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. تهانينا!

لقد أنشأت وكيلًا آمنًا بنجاح يتصرّف نيابةً عن المستخدم الذي سجّل الدخول.

ما تعلّمته:

  • هوية نظام الوكيل: توضّح هذه السمة كيف يعمل الوكيل ضمن هوية حسابه الخاصة للتفاعل بشكل آمن مع البنية الأساسية لخدمة Google Cloud Platform، وإدارة سجلّات القياس عن بُعد، واستدعاء واجهات برمجة التطبيقات الخاصة بإكمال بيانات الاعتماد.
  • الهوية المفوضة للمستخدم: توضّح هذه السمة كيف يطلب الوكيل الحصول على إذن بالتصرّف نيابةً عن المستخدم على منصات خارجية (مثل GitHub) من خلال بدء عملية موافقة على بروتوكول OAuth الثلاثي (3LO).
  • عمليات دمج الأدوات الآمنة: كيفية ربط وكلاء ADK بخوادم بروتوكول سياق النموذج (MCP) باستخدام Google Cloud Auth Manager لاسترداد رموز المستخدمين ديناميكيًا بدلاً من استخدام المفاتيح السرية المرمّزة
  • إعداد سياسة إدارة الهوية والوصول (IAM): كيفية إعداد عمليات ربط الأذونات الدقيقة لمنح الإذن لكلّ من هوية Agent Runtime وحسابك على مقدّم خدمة المصادقة

محتوى إضافي للقراءة