1. مقدمة
يتمكّن الوكيل الذي لديه بيانات اعتماد خاصة به مع إذن واسع من الاطّلاع على بيانات الجميع. في هذا الدرس التطبيقي حول الترميز، ستنشئ وكيلًا يستدعي واجهة برمجة تطبيقات تابعة لجهة خارجية باستخدام بيانات اعتماد المستخدم الذي سجّل الدخول، ليرى بالضبط ما يمكن لهذا الشخص رؤيته وليس أكثر من ذلك.
يمكنك إنشاؤه باستخدام Google Agent Development Kit (ADK) وGemini Enterprise.
على وجه التحديد، ستتعرّف على كيفية تصميم بنية هوية مزدوجة حيث:
- يعمل الوكيل نيابةً عن نفسه (هوية الوكيل): باستخدام هوية وكيل مستندة إلى SPIFFE، يستدعي الوكيل Auth Manager ويخزّن بيانات القياس عن بُعد ويطلب بيانات من Google Cloud APIs.
- يتصرّف الوكيل نيابةً عن المستخدم (هوية مفوَّضة من المستخدم): للوصول إلى الموارد الخارجية مثل GitHub، يشغّل الوكيل مسار موافقة OAuth الثلاثي (3LO) لطلب البحث عن الأدوات بأمان باستخدام بيانات اعتماد المستخدم.

لتحقيق ذلك، ستتعرّف على كيفية:
- يمكنك إنشاء وكيل ADK يتصل بخادم "بروتوكول سياق النموذج" (MCP) في GitHub.
- حدِّث أداة الوكيل من رمز مميز للوصول الشخصي (PAT) ثابت في GitHub إلى مسار OAuth الثلاثي (3LO) باستخدام Google Cloud Auth Manager.
- انشر الوكيل بأمان في بيئة تشغيل الوكيل وأعِدّ هوية الوكيل.
- اضبط أدوار "إدارة الهوية وإمكانية الوصول" (IAM) لمنح هوية الوكيل إذن الوصول إلى مخزن الرموز المميّزة نيابةً عن المستخدم.
- فهم عملية تفويض OAuth الثلاثي الأطراف (3LO) الشاملة لـ Auth Manager في Google Cloud
المتطلبات الأساسية
قبل البدء، تأكَّد من توفّر ما يلي:
- مشروع على Google Cloud مع تفعيل الفوترة
- تثبيت حزمة تطوير البرامج (SDK) في Google Cloud (
gcloudواجهة سطر الأوامر) والمصادقة على مشروعك على جهازك المحلي يجب استخدام الإصدار 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، وضبط مشروعك النشط (استبدِل YOUR_PROJECT_ID برقم تعريف مشروعك على Google Cloud)، وضبط "بيانات الاعتماد التلقائية للتطبيق" (ADC):
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
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- تثبيت واجهة سطر الأوامر (CLI) للوكلاء وإعداد المشروع
agents-cli هي أداة سطر الأوامر المستخدَمة لإنشاء وكلاء ADK وإدارتهم واختبارهم ونشرهم في Gemini Enterprise. ثبِّته على الجهاز:
uvx google-agents-cli setup
التحقّق من عملية التثبيت:
agents-cli --help
من المفترض أن تظهر قائمة المساعدة الخاصة بواجهة سطر الأوامر (CLI) التي تعرض الأوامر المتاحة (مثل deploy وrun وstatus).
أنشئ الهيكل الأولي للمشروع. ستبدأ بنموذج أوّلي محلي وتحسّنه لاحقًا لنشره في بيئة تشغيل الوكيل:
agents-cli create secure-agent-demo --prototype --yes
يؤدي ذلك إلى إنشاء دليل secure-agent-demo الذي يحتوي على رمز الوكيل الأساسي والتبعيات وملفات الاختبار.
4. إضافة إضافات ADK المطلوبة
أضِف الإضافتَين الناقصتَين في ملف pyproject.toml الذي تم إنشاؤه: mcp لمجموعة أدوات GitHub، وagent-identity لـ Auth Manager الذي سيتم استخدامه لاحقًا في التمرين العملي. افتح 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. إنشاء الوكيل
داخل مشروعك، استبدِل الرمز في secure-agent-demo/app/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): ينشئ مثيلاً لـAgentفي ADK باستخدام نموذجgemini-3.8-flash، ويضبط منطق إعادة محاولة HTTP، ويزوّد الوكيل بمجموعة أدوات GitHub. - برنامج تضمين التطبيق (
app): يغلّف الوكيل الجذر في حاوية ADKApp، ما يجعله قابلاً للنشر في Agent Runtime.
2. إضافة أداة GitHub MCP
يتصل الوكيل بـ GitHub باستخدام بروتوكول سياق النموذج (MCP). أنشئ ملفًا جديدًا في secure-agent-demo/app/tools.py لتسجيل مَعلمات اتصال بوابة 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 Toolset (
McpToolset): تكتشف إمكانات GitHub وتسجّلها ديناميكيًا كأدوات وكيل قابلة للاستدعاء. - مَعلمات الربط (
StreamableHTTPConnectionParams): توجّه مجموعة الأدوات إلى بوابة MCP العلنية في GitHub. - عناوين التفويض: يتم إدخال
GITHUB_TOKENكرمز حامل مميز وفرض وضع القراءة فقط (X-MCP-Readonly: true) مباشرةً في طبقة النقل.
3- الاختبار محليًا باستخدام رمز دخول شخصي (PAT) من GitHub
لتشغيل الوكيل محليًا باستخدام بيانات اعتماد ثابتة:
- أنشِئ رمز وصول شخصي دقيق في صفحة رموز الوصول الشخصية على GitHub:
- انقر على إنشاء رمز مميّز جديد وأدخِل اسمًا للرمز المميّز.
- ضمن الوصول إلى المستودع (Repository access)، اختَر جميع المستودعات (All repositories) (أو اختَر مستودعات معيّنة تريد إجراء الاختبار عليها).
- ضمن الأذونات > المستودعات، انقر على +إضافة أذونات واختَر المحتوى والمشاكل وطلبات السحب إلى للقراءة فقط (يتم ضبط البيانات الوصفية تلقائيًا على "للقراءة فقط").
- انقر على إنشاء رمز مميّز وانسخ قيمة الرمز المميّز الذي تم إنشاؤه. (بدلاً من ذلك، إذا كنت تستخدم رمز دخول شخصي (كلاسيكي)، اختَر نطاق
repo.)
- اضبطه في بيئتك:
export GITHUB_TOKEN="your_github_pat_here" - انتقِل إلى المجلد
secure-agent-demo(إذا لم تكن فيه حاليًا) وابدأ تشغيل البيئة التجريبية المحلية:cd secure-agent-demo agents-cli playground - افتح واجهة Playground واختَر المجلد
appمن القائمة المنسدلة. في مربّع المحادثة، جرِّب طلبًا موجّهًا مثل"Get the last 2 GitHub issues reported against my name"أو"List my 3 most recently updated repositories"، وتأكَّد من أنّ الوكيل يستدعي مجموعة أدوات GitHub MCP ويعرض بيانات GitHub. لاختبار ما إذا كان الوكيل يستخدم رمز PAT الخاص بك فعليًا لاتّخاذ إجراء نيابةً عنك، جرِّب سؤاله عن مستودعاتك أو مساهماتك الخاصة.
4. ضبط إعدادات Auth Manager
على الرغم من أنّ الترميز الثابت لبيانات الاعتماد الثابتة (مثل رمز PAT) يُعدّ مناسبًا لإنشاء النماذج الأولية، إلا أنّه يعرّض تطبيقات الإنتاج لتسريب بيانات الاعتماد، وفترة توقّف تحديث الرموز المميّزة يدويًا، وعدم توفّر عناصر التحكّم في الوصول المستندة إلى السحابة الإلكترونية.
لحلّ هذه المشكلة، توفّر Google Cloud خدمة Agent Identity Auth Manager. "مدير مصادقة هوية الوكيل" (Agent Identity auth manager) هو مخزن بيانات اعتماد مصمّم للمساعدة في حماية بيانات الاعتماد. ويتيح للوكلاء المصادقة باستخدام مفتاح واجهة برمجة التطبيقات أو معرّف عميل OAuth وسرّه، أو نيابةً عن مستخدم من خلال تفويض OAuth باستخدام رموز الدخول المميزة للمستخدم النهائي.
في Auth Manager، يمكنك ضبط مقدّمي خدمات المصادقة الذين يحدّدون نوع المصادقة وبيانات الاعتماد لتطبيقات خارجية معيّنة. مقدّمو المصادقة هم إقليميون، ويجب أن تتطابق المنطقة مع المنطقة التي تنشر الوكيل فيها. يعمل سير عمل "مدير المصادقة" الشامل على النحو التالي:

- الاعتراض الديناميكي للموافقة: عندما يحاول الوكيل تنفيذ أداة نيابةً عن مستخدم، تتحقّق حزمة ADK من Auth Manager بحثًا عن بيانات اعتماد صالحة حالية. وفي حال عدم توفّر أي منها، يعرض Auth Manager عنوان URL للمصادقة لبدء عملية موافقة OAuth الثلاثية (3LO).
- تخزين آمن في Vault: بعد أن يمنح المستخدم النهائي الإذن للتطبيق، يعترض Auth Manager تلقائيًا طلب معاودة الاتصال عبر OAuth ويخزّن الرموز المميزة الناتجة عن وصول المستخدم والرمز المميز لإعادة التحميل في مخزن بيانات اعتماد آمن تديره Google.
- دورة حياة الرموز المميّزة المبرمَجة: يدير Auth Manager انتهاء صلاحية الرموز المميّزة وتغييرها بالكامل في الخلفية، ما يلغي الحاجة إلى منطق إعادة تحميل الرموز المميّزة يدويًا أو فترة التوقّف.
- تنفيذ الأدوات بدون مفاتيح سرية: بالنسبة إلى الإجراءات اللاحقة، يطلب الوكيل (الذي تتم مصادقته من خلال هوية وكيل SPIFFE) ديناميكيًا رمز الوصول المفوَّض للمستخدم من Auth Manager في وقت التشغيل، ما يحافظ على سرية رمز العميل والوكيل بالكامل.
الخطوة أ: ضبط GitHub كموفّر مصادقة
نفِّذ أمر gcloud التالي لإنشاء موفِّر مصادقة GitHub في مشروعك على Google Cloud. يجب تقديم معرّف العميل والسر لاحقًا: لن يصدرهما GitHub إلا بعد معرفة عنوان URL لمعاودة الاتصال الخاص بموفّر الهوية هذا.
gcloud agent-identity auth-providers create github-oauth-provider \
--project="YOUR_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="YOUR_PROJECT_ID" \
--location="us-central1"
الحقل هو redirectUrl، وهو مُدمج ضمن authProviderTypeParams.threeLeggedOauth. لقراءتها مباشرةً:
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_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
- انتقِل إلى صفحة إعدادات مطوّري GitHub، واختَر تطبيقات OAuth في الشريط الجانبي الأيمن، ثم انقر على تطبيق OAuth جديد (أو تسجيل تطبيق جديد إذا لم يسبق لك إنشاء تطبيق).
- املأ حقول نموذج طلب OAuth:
- اسم التطبيق: أدخِل اسمًا لتطبيقك (مثلاً،
secure-agent-demo). - عنوان URL للصفحة الرئيسية: أدخِل عنوان URL لتطبيق الواجهة الأمامية (
http://localhost:8501للنماذج الأولية المحلية، ويمكنك تعديله إلى عنوان URL المنشور في مرحلة الإنتاج). - وصف التطبيق: اختياري (يمكنك ترك هذا الحقل فارغًا).
- عنوان URL لمعاودة الاتصال الخاص بالتفويض (معرّف الموارد المنتظم لإعادة التوجيه): الصِق
redirectUrlالذي تم استرداده في الخطوة "أ". - تفعيل مسار الجهاز: اترك المربّع بدون علامة.
- اسم التطبيق: أدخِل اسمًا لتطبيقك (مثلاً،
- انقر على تسجيل التطبيق (Register application).
- في صفحة التطبيق الناتجة، انسخ معرّف العميل، ثم انقر على إنشاء سر عميل جديد وانسخ سر العميل الذي تم إنشاؤه. احفظ القيمتَين، فستستخدمهما كـ
YOUR_GITHUB_CLIENT_IDوYOUR_GITHUB_CLIENT_SECRETفي الخطوة التالية.
الخطوة ج: إضافة بيانات اعتماد GitHub إلى موفّر المصادقة
استبدِل YOUR_PROJECT_ID وYOUR_GITHUB_CLIENT_ID وYOUR_GITHUB_CLIENT_SECRET بقيمك وشغِّل هذا الأمر:
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 بالكامل، تتمثّل الخطوة التالية في تعديل رمز أداة الوكيل. استبدِل محتوى secure-agent-demo/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. وعند إرفاقها بمجموعة الأدوات، سيطلب ADK من "مدير المصادقة" الحصول على الرمز المميّز الخاص بالمستخدم في كل مرة يتصل فيها الوكيل بـ GitHub. وإذا لم يكن هناك رمز مميّز بعد، سيطلب من المستخدم تسجيل الدخول بدلاً من إظهار رسالة خطأ. تمت إزالة السمة GITHUB_TOKEN المضمّنة بالكامل.
6. نشر الوكيل في بيئة تشغيل الوكيل
بعد تعديل أداة GitHub MCP لاستخدام Auth Manager، تتمثّل الخطوة التالية في نشر الوكيل في Agent Runtime. ويؤدي نشرها مع تفعيل "هوية الوكيل" إلى توفير معرّف SPIFFE فريد للوكيل.
ابدأ إعدادات النشر للمشروع. تأكَّد من أنّ الوحدة الطرفية في الدليل الجذري لمشروع secure-agent-demo، ثم شغِّل:
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 الأخرى.
👉 من دليل secure-agent-demo، استبدِل YOUR_PROJECT_ID وشغِّل الأوامر التالية:
# Write a config file inside the `app/` folder instructing Agent Runtime to provision 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 لهوية الوكيل في مورد موفِّر المصادقة. يمنح ذلك الوكيل الأذونات المحدّدة التي يحتاجها لطلب رموز المستخدمين المميّزة من المخزن، وليس أكثر من ذلك.
# Get YOUR_ORG_ID
gcloud projects get-ancestors $(gcloud config get-value project) \
--filter="type=organization" \
--format="value(id)"
# Get YOUR_PROJECT_NUMBER
gcloud projects describe $(gcloud config get-value project) \
--format="value(projectNumber)"
بعد ذلك، اربط سياسة "إدارة الهوية وإمكانية الوصول" بموفِّر المصادقة (مع استبدال YOUR_PROJECT_ID والمستخدم الرئيسي --member):
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"
👉 يمكنك أيضًا الحصول على قيمة --member="principal://..." الكاملة للوكيل الذي تم نشره من Google Cloud Console: انتقِل إلى وحدة تحكّم Agent Runtime، واختَر الوكيل الذي تم نشره، ثم انتقِل إلى علامة التبويب الهوية وانسخ سلسلة principal://... الكاملة مباشرةً.
امنح الآن حسابك الخاص الدور نفسه لدى مقدّم الخدمة. يستدعي عميل واجهة المستخدم الذي تشغّله في الخطوة التالية واجهة برمجة التطبيقات الخاصة بإنهاء بيانات الاعتماد باستخدام بيانات الاعتماد التلقائية للتطبيق، لذا بدون ذلك يتعذّر تدفق الموافقة مع ظهور الخطأ 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. فهم مسار الموافقة على بروتوكول OAuth الثلاثي الأطراف (3LO)
بعد نشر الوكيل في بيئة التشغيل Agent Runtime باستخدام هوية وكيل آمنة، تتمثّل الخطوة التالية في توفير واجهة أمامية مخصّصة تتيح للمستخدمين الدردشة معه. والأهم من ذلك، يتطلّب Google Cloud Auth Manager معالج رد اتصال لتطبيق العميل لإكمال حلقة المصادقة.
على الرغم من أنّ Google Cloud Auth Manager يدير بيانات اعتماد المستخدمين بأمان داخل مخزن، لا يمكنه إكمال عملية تبادل رمز OAuth المميّز بمفرده. تعتمد مصافحة 3LO على تطبيق العميل لسد الفجوة:
- عندما يفوّض مستخدم تطبيق GitHub، يعيد GitHub توجيهه إلى موفّر مصادقة هوية الوكيل
redirectUrl. - بعد ذلك، يعيد Auth Manager توجيه النافذة المنبثقة في متصفّح المستخدم إلى عنوان URL لمعاودة الاتصال من جهة العميل (
continue_uri). - تقع على عاتق تطبيق العميل مسؤولية اعتراض عملية إعادة التوجيه هذه وقراءة الرمز الخاص من ملفات تعريف الارتباط في المتصفّح واستدعاء نقطة نهاية
credentials:finalizeفي Google Cloud لإكمال عملية الاتصال. - بعد أن يكمل العميل عملية التبادل، يحفظ Google Cloud الرمز المميّز بأمان في مخزن مزوّد المصادقة، ما يسمح للوكيل باستدعاء أداة GitHub.
بدون هذا العميل المخصّص الذي يستضيف نقطة نهاية رد الاتصال، تظل عملية الاتصال غير مكتملة، ولا يمكن لـ Vault تخزين بيانات الاعتماد.
يمتد مسار OAuth 3LO التفاعلي عبر طبقات متعددة. في ما يلي مراحل النشاط الكاملة لتنفيذ طلب أداة. سنوضّح ذلك في الشرح أدناه وفي الخطوة التالية.
👉 يمكنك النقر على الصورة لتكبيرها.
مسؤوليات العميل الأساسية في عملية المصافحة
- نقل طلب الموافقة (الخطوتان 5 و6): يرسل الوكيل
adk_request_credentialيحمل عنوان URL للموافقة ورقمًا خاصًا للاستخدام الواحد، ويفتح العميل النافذة المنبثقة ويخزّن الرقم الخاص كملف تعريف ارتباط. - استضافة معاودة الاتصال لإعادة التوجيه (الخطوتان 10 و11):
/validateUserId، حيث يرسل Auth Manager النافذة المنبثقة بعد الموافقة. - إكمال الرمز المميّز (الخطوات 12-14): ادمج حالة التحقّق من إعادة التوجيه مع الرمز غير المتكرّر المخزَّن مؤقتًا واستخدِم
credentials:finalize، الذي يخزّن الرمز المميّز في المخزن الآمن.
إنشاء برنامج عميل خاص بك
لست بحاجة إلى كتابة هذا العميل للتمرين المعملي، فالخطوة التالية تشغّل عميلاً مُنشأ مسبقًا. عندما تبدأ في تنفيذ ذلك في تطبيقك، إليك المرجعان اللذان يمكنك الاستناد إليهما:
- تعديل تطبيقك من جهة العميل في مستندات Auth Manager، والتي تتناول التعامل مع تحدي الموافقة واستدعاء
credentials:finalize. - نموذج العميل القابل للتشغيل في مستودع adk-python يمكنك قراءة
main.pyهناك للحصول على تنفيذ كامل وفعّال للمسؤوليات الثلاث المذكورة أعلاه.
8. تشغيل عميل واجهة المستخدم محليًا
كما هو موضّح في مخطّط تسلسل مسار الموافقة على بروتوكول OAuth الثلاثي الأطراف، يعيد "مدير المصادقة" توجيه نافذة المتصفّح إلى نقطة نهاية لمعاودة الاتصال من جهة العميل. يستضيف نموذج العميل في مستودع adk-python نقطة النهاية هذه على /validateUserId. يمكنك تنزيلها وتشغيلها على جهازك باتّباع الخطوات التالية.
تنزيل ملفات العميل
يحتوي دليل contributing/samples/integrations/gcp_auth/client في adk-python على ثلاث مواد عرض رئيسية:
main.py: يشير هذا إلى الخلفية في FastAPI التي تتصل بنسخة Agent Engine المنشورة وتستضيف نقطة نهاية معاودة الاتصال/validateUserIdلإنهاء رموز OAuth المميّزة.static/: ملفات HTML وJavaScript لواجهة مستخدم المحادثة في المتصفّح-
requirements.txt: حِزم Python المطلوبة لتشغيل خادم العميل.
بما أنّ adk-python هو مستودع كبير، استخدِم ميزة sparse checkout في Git لتنزيل المجلد contributing/samples/integrations/gcp_auth/client فقط:
- أولاً، انتقِل إلى الدليل السابق خارج
secure-agent-demoلنسخ العميل إلى مجلد شقيق:cd .. - شغِّل الأوامر التالية لنسخ البيانات الوصفية للمستودع بدون تنزيل جميع الملفات (
--no-checkout)، وحصر مسار السحب علىcontributing/samples/integrations/gcp_auth/client، وسحب هذا المجلد فقط: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
تشغيل العميل
- من داخل دليل
adk-pythonالذي أدخلته للتو، انتقِل إلى المجلدclient:cd contributing/samples/integrations/gcp_auth/client - أنشئ بيئة Python افتراضية وفعِّلها، ثم ثبِّت تبعيات العميل من
requirements.txt:uv venv --python 3.13 .venv source .venv/bin/activate uv pip install --python .venv/bin/python -r requirements.txt - اضبط متغيّرات البيئة التي توجّه العميل إلى مشروع على السحابة الإلكترونية على Google Cloud والمنطقة (
us-central1) ورقم تعريف Agent Engine الذي تم تفعيله (YOUR_ENGINE_ID)، ثم ابدأ تشغيل خادم FastAPI المحلي على المنفذ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 - تأكَّد من بدء تشغيل الخادم بنجاح ومن أنّه يستمع إلى
http://localhost:8501.
9. اختبار مسار OAuth
بعد نشر جميع الخدمات وضبط عمليات ربط "إدارة الهوية وإمكانية الوصول" وضبط متغيّرات البيئة، يمكنك الآن اختبار مسار التفويض الآمن والشامل الذي يفوّضه المستخدم.
الخطوة (أ): بدء تنفيذ الأداة
- افتح علامة تبويب متصفّح وانتقِل إلى عنوان URL الخاص بالعميل:
http://localhost:8501. - في اللوحة اليمنى ضمن إعدادات الضبط، اضبط نوع الوكيل على
Remote Agent (Vertex AI)(أوRemote Agent Engine). - أدخِل رقم تعريف المشروع والموقع الجغرافي (
us-central1) في Google Cloud، ثم انقر على تحميل الوكلاء البعيدين. يؤدي ذلك إلى تحميل الوكلاء الذين تم نشرهم في مشروعك. - اختَر وكيل
appالذي تم نشره من القائمة المنسدلة اختيار المحرّك (Select Engine) وانقر على حفظ الإعدادات وتطبيقها (Save & Apply Settings). - في مربّع المحادثة، اكتب طلبًا مستهدفًا (مثل جلب المشاكل أو المستودعات الأخيرة):
(أو جرِّبGet the last 2 GitHub issues reported against my name"List my 3 most recently updated repositories") واضغط على Enter. - لاحظ واجهة مستخدم المحادثة: بما أنّ الوكيل لا يملك بيانات اعتماد لجلسة المستخدم حتى الآن، يتلقّى طلب مصادقة ويعرض بطاقة "المصادقة مطلوبة" في سلسلة المحادثات.
الخطوة (ب): إكمال موافقة OAuth الثلاثية
- ستفتح نافذة منبثقة منفصلة في المتصفّح، وستعيد توجيهك من خلال Auth Manager في Google Cloud إلى صفحة تفويض GitHub OAuth.
- راجِع الأذونات المطلوبة وانقر على تفويض.
- سيعيد GitHub التوجيه إلى Google Cloud، الذي يعيد توجيه النافذة المنبثقة إلى
localhostعنوان URL لمعاودة الاتصال/validateUserId. - تعالج خدمة معاودة الاتصال عملية تأكيد الاتصال ببيانات الاعتماد وتُنهيها.
الخطوة ج: السيرة الذاتية
- بعد إغلاق النافذة المنبثقة، ترصد علامة تبويب المحادثة الرئيسية الإغلاق تلقائيًا.
- ترسل الواجهة الأمامية حمولة استئناف إلى الوكيل.
- يستردّ الوكيل الرمز المميّز الذي تم تبادله حديثًا بأمان من Google Cloud Auth Manager، ويستدعي أدوات GitHub MCP نيابةً عنك، وينقل بيانات GitHub مباشرةً إلى نافذة المحادثة، وهي بيانات لم يكن بإمكان الوكيل الوصول إليها بمفرده.
الخطوة د: فحص سجلّات Cloud
للتحقّق من أنّ عملية تبادل الرموز المميزة وإتمامها قد تمّت بأمان، اتّبِع الخطوات التالية:
- انتقِل إلى مستكشف السجلّات في Google Cloud Console.
- ابحث عن سجلّات الخادم التي تؤكّد استخراج الرمز الفريد والتحقّق منه بنجاح:
INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx INFO:secure-agent-client:Successfully finalized auth provider credentials. - فحص سجلّات وقت تشغيل الوكيل: يمكنك بدلاً من ذلك الاطّلاع على سجلّات التنفيذ مباشرةً داخل وحدة تحكّم Agent Platform:
- انتقِل إلى وحدة تحكّم Agent Runtime.
- انقر على الوكيل المنشور من القائمة.
- انتقِل إلى علامة التبويب 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
حذف الملفات المخزّنة على الجهاز
يمكنك اختياريًا تنظيف البيئة المحلية بالكامل:
- أوقِف خادم uvicorn المحلي بالضغط على Ctrl+C في الوحدة الطرفية التي يعمل فيها.
- أزِل أدلة المشروع التي تم إنشاؤها خلال هذا التمرين:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python
11. تهانينا!
لقد نجحت في إنشاء وكيل آمن يتصرف نيابةً عن المستخدم الذي سجّل الدخول.
ما تعلّمته:
- هوية نظام الوكيل: طريقة عمل الوكيل ضمن هوية حسابه للتفاعل بأمان مع البنية الأساسية لـ GCP وإدارة سجلّات القياس عن بُعد واستدعاء واجهات برمجة التطبيقات لإنهاء بيانات الاعتماد.
- هوية المستخدم المفوَّضة: كيف يطلب الوكيل الإذن بالتصرّف نيابةً عن المستخدم على منصات خارجية (مثل GitHub) من خلال تفعيل مسار موافقة OAuth الثلاثي الأطراف (3LO).
- دمج الأدوات الآمنة: كيفية ربط وكلاء ADK بخوادم "بروتوكول سياق النموذج" (MCP) باستخدام Google Cloud Auth Manager لاسترجاع رموز المستخدمين ديناميكيًا بدلاً من استخدام مفاتيح سرية مضمّنة في الرمز البرمجي
- إعداد سياسة "إدارة الهوية وإمكانية الوصول": كيفية إعداد عمليات ربط الأذونات الدقيقة لمنح الإذن لكل من هوية Agent Runtime وحسابك الخاص لدى موفّر المصادقة.
قراءات إضافية
- Agent Identity Auth Manager لفهم إعدادات مسار المصادقة والنطاقات
- نظرة عامة على Agent Runtime
- مستندات ADK
- بروتوكول سياق النموذج
