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

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستنشئ عملية نشر آمنة لوكيل واحد أو أدوات متعددة باستخدام "حزمة تطوير الوكلاء" (ADK) وAgent Engine وGoogle Kubernetes Engine. ستتعرّف على كيفية تنقّل وكيل الذكاء الاصطناعي الذي يبدأه المستخدم في Gemini Enterprise بأمان في Google Cloud، وذلك بالاستناد إلى GKE Gateway مع "إضافات الخدمة" لإخفاء البيانات الحسّاسة أثناء نقلها من ردود أداة MCP.

ما ستتعلمه

نشر وكيل مساعد للرهن العقاري ADK على Agent Engine باستخدام قياس حالة التطبيق OpenTelemetry
نشر خوادم MCP الخلفية على Google Kubernetes Engine (GKE) خلف بوابة داخلية
ربط Agent Engine بشبكة VPC في مشروع باستخدام واجهة PSC وتبادل معلومات بين الشبكات عبر نظام أسماء النطاقات (DNS)
عرض واجهات REST API كأدوات MCP باستخدام خادم وكيل Apigee لاكتشاف MCP
ضبط GKE Gateway لخروج الوكيل المُدار باستخدام إضافات الخدمة لإخفاء DLP ومنح إذن MCP
تطبيق ضوابط أمان الذكاء الاصطناعي باستخدام Model Armor لفحص الطلبات والردود

ما تحتاج إليه

متصفّح ويب، مثل Chrome
مشروع Google Cloud تم تفعيل الفوترة فيه
معرفة أساسية بـ Terraform وKubernetes وPython

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

2. قبل البدء

أنشئ مشروعًا على Google Cloud وفعِّل واجهات برمجة التطبيقات المطلوبة.

في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروع Google Cloud أو أنشِئه.
تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع.

أدوار "إدارة الهوية وإمكانية الوصول" المطلوبة

يفترض هذا الدرس العملي أنّ لديك دور مالك المشروع لمشروعك على Google Cloud.

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

في "وحدة تحكّم Google Cloud"، انقر على تفعيل Cloud Shell: إذا لم يسبق لك استخدام Cloud Shell، سيظهر جزء يتيح لك اختيار بدء Cloud Shell في بيئة موثوقة مع أو بدون تعزيز. إذا طُلب منك تفويض Cloud Shell، انقر على تفويض.

في Cloud Shell، فعِّل جميع واجهات برمجة التطبيقات المطلوبة:

gcloud services enable \
compute.googleapis.com \
container.googleapis.com \
dns.googleapis.com \
certificatemanager.googleapis.com \
dlp.googleapis.com \
aiplatform.googleapis.com \
discoveryengine.googleapis.com \
apigee.googleapis.com

تثبيت الحِزم التابعة

في Cloud Shell، تأكَّد من تثبيت الأدوات المطلوبة. عادةً ما تكون أدوات Terraform وkubectl وGo مثبّتة مسبقًا. يجب تثبيت uv (أداة إدارة حِزم Python) وSkaffold:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
sudo install skaffold /usr/local/bin/

ضبط متغيرات البيئة

اضبط متغيرات البيئة التالية المستخدَمة في هذا الدرس التطبيقي حول الترميز:

export PROJECT_ID=$(gcloud config get project)
export REGION=us-central1
export LOCATION=${REGION}

إنشاء منطقة نظام أسماء نطاقات عامة

يتطلّب هذا الدرس البرمجي وجود منطقة نظام أسماء نطاقات عامة في مشروعك قبل تطبيق إعدادات Terraform. هذه المنطقة مطلوبة لتفويض خادم الأسماء حتى يتمكّن الإعداد من إنشاء السجلات المطلوبة في Certificate Manager تلقائيًا.

نفِّذ الأمر التالي في Cloud Shell لإنشاء المنطقة:

gcloud dns managed-zones create "inference-gateway-zone" \
    --dns-name="gateway.example.com." \
    --description="Public zone for Inference Gateway" \
    --visibility="public" \
    --project="${PROJECT_ID}"

3- استنساخ مستودع GitHub

في وحدة طرفية على جهازك، استنسِخ مستودع cloud-networking-solutions:
```
git clone https://github.com/googleCloudPlatform/cloud-networking-solutions.git
```
انتقِل إلى دليل المستودع الذي تم تنزيله:
```
cd cloud-networking-solutions/demos/service-extensions-gke-gateway
```

4. نشر البنية الأساسية باستخدام Terraform

ستستخدِم Terraform لتوفير الشبكة الأساسية ومجموعة GKE وإعدادات الهوية المطلوبة.

انتقِل إلى الدليل terraform في المستودع الذي تم إنشاؤه:
```
cd terraform
```
ضبط الواجهة الخلفية لـ Terraform أنشئ ملف backend.conf لإعداد الواجهة الخلفية بشكل جزئي. استبدِل باسم حزمة فريد وعام.
```
cat <<EOF > backend.conf
bucket = "<YOUR_TERRAFORM_STATE_BUCKET>"
prefix = "terraform"
EOF
```

انسخ ملف المتغيّرات النموذجي وعدِّله بقيم مشروعك:
```
cp example.tfvars terraform.tfvars
```
عدِّل terraform.tfvars واستبدِل قيم العناصر النائبة.استبدِل ما يلي:
- استبدِل project_id برقم تعريف مشروعك على Google Cloud.
- organization_id: رقم تعريف مؤسستك في GCP.
- dns_zone_domain: نطاق تتحكّم فيه (مثل demo.example.com.)، ويجب أن ينتهي بنقطة.
تأكَّد من تفعيل علامات الميزات التالية (تم إعدادها مسبقًا في ملف المثال):
- enable_certificate_manager = true
- enable_model_armor = true
- enable_agent_engine = true
- enable_psc_interface = true

تهيئة إعداد Terraform وتطبيقه:

terraform init -backend-config=backend.conf
terraform plan -out=tfplan
terraform apply "tfplan"

5- نشر أحمال عمل نموذجية باستخدام Skaffold

بعد ذلك، يمكنك نشر خوادم MCP وخدمات المعالجة الخارجية في مجموعة GKE.

اتّبِع الخطوات التالية للاتصال بمجموعة GKE التي تم إنشاؤها باستخدام Terraform:
```
gcloud container clusters get-credentials gateway-cluster \
    --region=${REGION} \
    --project=${PROJECT_ID}
```
ارجع إلى جذر المشروع واضبط إعدادات نماذج بيان Kubernetes. انسخ نموذج الإعدادات واضبط رقم تعريف مشروعك والنطاق الأساسي:اضبط BASE_DOMAIN ليطابق بيئتك. يجب أن يتطابق BASE_DOMAIN مع متغيّر dns_zone_domain Terraform (بدون النقطة الأخيرة).
```
export BASE_DOMAIN=example.com
```

إنشاء بيانات Kubernetes وskaffold.yaml من النماذج:

bash k8s/generate.sh
envsubst '${PROJECT_ID}' < skaffold.yaml.tmpl > skaffold.yaml

نشر جميع خدمات الخلفية:

skaffold run -m legacy-dms,income-verification-api,corporate-email,dlp-ext-proc

نفِّذ إعدادات Gateway وHTTPRoute:
```
kubectl apply -k k8s/gateway-internal/
```

6. تطبيق ضوابط الذكاء الاصطناعي الوقائية باستخدام Model Armor

يمكنك تفويض اتّخاذ قرارات بشأن أمان المحتوى، مثل إزالة الطلبات الضارة أو منع تسرُّب البيانات، إلى Model Armor.

المتطلبات الأساسية: منح أدوار "إدارة الهوية وإمكانية الوصول"

يجب منح الأدوار المطلوبة لحساب خدمة GKE Gateway. يتّبع حساب الخدمة التنسيق التالي: service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com.

نفِّذ الأوامر التالية لمنح الأذونات اللازمة:

export GATEWAY_PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# Grant roles in the Gateway project
gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member=serviceAccount:service-${GATEWAY_PROJECT_NUMBER}@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.calloutUser

gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member=serviceAccount:service-${GATEWAY_PROJECT_NUMBER}@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/serviceusage.serviceUsageConsumer

# Grant role in the project containing Model Armor templates
gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member=serviceAccount:service-${GATEWAY_PROJECT_NUMBER}@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.user

إنشاء إضافة Model Armor Authorization

حدِّد إضافة تشير إلى خدمة Model Armor في منطقتك. احفظ هذا الإعداد باسم ma-content-authz-extension.yaml.

صدِّر رقم تعريف نموذج Model Armor الذي أنشأته أداة Terraform.

export MA_TEMPLATE_ID=$(cd terraform && terraform output -raw model_armor_template_id)

cat >ma-content-authz-extension.yaml <<EOF
name: ma-ext
service: modelarmor.$LOCATION.rep.googleapis.com
metadata:
  model_armor_settings: '[
  {
  "response_template_id": "projects/${PROJECT_ID}/locations/$LOCATION/templates/${MA_TEMPLATE_ID}",
  "request_template_id": "projects/${PROJECT_ID}/locations/$LOCATION/templates/${MA_TEMPLATE_ID}"
  }
  ]'
failOpen: true
EOF

gcloud beta service-extensions authz-extensions import ma-ext \
    --source=ma-content-authz-extension.yaml \
    --location=$LOCATION

إنشاء سياسة تفويض Model Armor

أنشئ سياسة تربط إضافة Model Armor ببوابة Agent Gateway. احفظ هذا الإعداد باسم ma-content-authz-policy.yaml.

cat >ma-content-authz-policy.yaml <<EOF
name: ma-content-authz-policy
target:
  resources:
  -   "projects/$PROJECT_ID/locations/$LOCATION/gateways/mortgage-gateway"
policyProfile: CONTENT_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
    -   "projects/$PROJECT_ID/locations/$LOCATION/authzExtensions/ma-ext"
EOF

gcloud network-security authz-policies import ma-content-authz-policy \
    --source=ma-content-authz-policy.yaml \
    --location=$LOCATION

7. ضبط إعدادات Gemini Enterprise

تفعيل إمكانية تتبّع البيانات

يتم نشر وكيل الرهن العقاري مع أدوات قياس حالة التطبيق OpenTelemetry وتفعيل متغيرات بيئة القياس عن بُعد التالية تلقائيًا:

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
OTEL_TRACES_SAMPLER=parentbased_traceidratio

للحصول على تفاصيل حول ضبط عمليات التتبُّع والنطاقات في Gemini Enterprise، يُرجى الاطّلاع على إدارة إعدادات إمكانية المراقبة.

تفعيل ميزة Model Armor في Gemini Enterprise

تطبيق فلترة Model Armor على مساعد Gemini Enterprise لفحص طلبات المستخدمين وردود النموذج تتطلّب تطبيقات Gemini Enterprise العالمية نموذج Model Armor في المنطقة المتعددة us، لذا ينشر Terraform نموذجًا منفصلاً لهذا الغرض.

استرداد اسم النموذج من ناتج Terraform:

cd terraform
export GE_MA_TEMPLATE_NAME=$(terraform output -raw model_armor_gemini_enterprise_template_name)

استرجِع معرّف التطبيق الخاص بمثيل Gemini Enterprise:

في Google Cloud Console، انتقِل إلى صفحة Gemini Enterprise.
من قائمة التنقّل، انقر على "التطبيقات".
نسخ رقم تعريف مثيل Gemini Enterprise

صدِّر المعرّف كمتغيّر بيئة.

export APP_ID=<PASTE_APP_ID>

تصحيح "المساعد" لتفعيل Model Armor:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_ID}" \
  "https://global-discoveryengine.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/collections/default_collection/engines/${APP_ID}/assistants/default_assistant?update_mask=customerPolicy" \
  -d '{
    "customerPolicy": {
      "modelArmorConfig": {
        "userPromptTemplate": "'"$GE_MA_TEMPLATE_NAME"'",
        "responseTemplate": "'"$GE_MA_TEMPLATE_NAME"'",
        "failureMode": "FAIL_OPEN"
      }
    }
  }'

اضبط failureMode على FAIL_OPEN للسماح بالطلبات عندما لا يتوفّر Model Armor، أو على FAIL_CLOSED لحظرها.

8. نشر "الوكيل" وإضافة "وكيل" في Gemini Enterprise

الحصول على تفاصيل التفويض

اتّبِع الخطوات التالية للحصول على تفاصيل التفويض.

في وحدة تحكّم Google Cloud، انتقِل إلى صفحة "بيانات الاعتماد" ضمن صفحة "واجهات برمجة التطبيقات والخدمات".
انتقِل إلى بيانات الاعتماد
انقر على "إنشاء بيانات اعتماد" واختَر "معرّف عميل OAuth".
في "نوع التطبيق"، اختَر "تطبيق الويب".
في قسم "معرّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه"، أضِف معرّفات الموارد المنتظمة (URI) التالية:

https://vertexaisearch.cloud.google.com/oauth-redirect
https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

انقر على "إنشاء".
تصدير معرّف العميل وسر العميل للنشر

export OAUTH_CLIENT_ID=<Client ID>
export OAUTH_CLIENT_SECRET=<Client Secret>

نشر وكيل الرهن العقاري

ينشر النص البرمجي src/mortgage-agent/deploy_agent.py وكيل ADK إلى Agent Engine ويسجّله اختياريًا في Gemini Enterprise. راجِع مقالة تسجيل وكيل A2A وإدارته للحصول على معلومات أساسية حول عملية تسجيل Gemini Enterprise.

تصدير المتغيّرات من عملية نشر Terraform

export VPC_NAME=$(cd terraform && terraform output -raw vpc_name)
export PSC_ATTACHMENT=$(cd terraform && terraform output -raw psc_interface_network_attachment_id)
export DNS_PEERING_DOMAIN=$(cd terraform && terraform output -raw psc_interface_dns_peering_domain)

تثبيت التبعيات ونشرها:

cd src/mortgage-agent
uv sync

نشر Agent في Vertex Agent Engine وتسجيله في Gemini Enterprise:

uv run python deploy_agent.py \
    --project=${PROJECT_ID} \
    --dms-mcp-url=https://dms.${DNS_PEERING_DOMAIN%%.}/mcp \
    --income-verification-url=https://income-verification.${DNS_PEERING_DOMAIN%%.} \
    --email-mcp-url=https://email.${DNS_PEERING_DOMAIN%%.}/mcp \
    --network-attachment=projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/${PSC_ATTACHMENT} \
    --dns-peering-domain=${DNS_PEERING_DOMAIN} \
    --dns-peering-target-project=${PROJECT_ID} \
    --dns-peering-target-network=${VPC_NAME} \
    --enable-agent-identity \
    --ge-deploy \
    --app-id=${APP_ID} \
    --oauth-client-id=${OAUTH_CLIENT_ID} \
    --agent-name=mortgage-agent

مرجع العلامة

علم	تلقائي	الوصف
`--project`	`$PROJECT_ID`	رقم تعريف مشروع Google Cloud Platform
`--dms-mcp-url`	(معلومات مطلوبة)	عنوان URL لخادم MCP الخاص بنظام إدارة الأجهزة الجوّالة (DMS)
`--income-verification-url`	(معلومات مطلوبة)	عنوان URL الأساسي لواجهة برمجة التطبيقات الخاصة بالتحقّق من الدخل، ويتم إلحاق `/mcp` تلقائيًا
`--email-mcp-url`	(معلومات مطلوبة)	عنوان URL لخادم MCP الخاص بالبريد الإلكتروني
`--region`	`$REGION`	منطقة Google Cloud Platform
`--staging-bucket`	`gs://PROJECT-staging`	حزمة GCS للتخزين المؤقت
`--display-name`	`Mortgage Assistant Agent`	الاسم المعروض للوكيل الذي تم نشره
`--update`	(اختياري)	تعديل وكيل حالي في مكانه (يجب تمرير الاسم الكامل للمورد)
`--network-attachment`	(اختياري)	ملحق الشبكة لواجهة PSC (المسار الكامل أو الاسم)
`--dns-peering-domain`	(اختياري)	نطاق نظام أسماء النطاقات (DNS) لإقران نظام أسماء النطاقات في PSC-I (يجب أن ينتهي بنقطة)
`--dns-peering-target-project`	(اختياري)	المشروع الذي يستضيف شبكة VPC المستهدَفة لتبادل المعلومات بين نظام أسماء النطاقات
`--dns-peering-target-network`	(اختياري)	اسم شبكة VPC لتبادل المعلومات بين شبكات نظام أسماء النطاقات
`--enable-agent-identity`	`false`	تفعيل بيانات اعتماد الحدّ الأدنى من الأذونات المميّزة لكل وكيل
`--ge-deploy`	`false`	تسجيل الوكيل في Gemini Enterprise بعد النشر
`--app-id`	(اختياري)	معرّف محرّك Gemini Enterprise (مطلوب مع `--ge-deploy`)
`--oauth-client-id`	`$OAUTH_CLIENT_ID`	معرّف عميل OAuth2 (مطلوب مع `--ge-deploy`)
`--oauth-client-secret`	`$OAUTH_CLIENT_SECRET`	سر عميل OAuth2 (مطلوب مع `--ge-deploy`)
`--model`	`gemini-3.1-flash-lite-preview`	اسم نموذج Gemini الخاص بالوكيل
`--agent-name`	`mortgage-agent`	تفويض Gemini Enterprise واسم الوكيل
`--ge-deploy-only`	(اختياري)	تسجيل محرك استدلال حالي في Gemini Enterprise بدون إعادة النشر (يجب إدخال الاسم الكامل للمورد)

إضافة مستخدمين لديهم أذونات

لإضافة مستخدمين لديهم أذونات إلى وكيل ADK باستخدام Google Cloud Console، راجِع مقالة إضافة مستخدمين وأذوناتهم أو تعديلها.

9- اختبار الوكيل

بعد نشر الوكيل وGKE Gateway وجميع خدمات الخلفية وإعدادها، اختبِر التدفق الكامل للتحقّق من أنّ سياسات الأمان تعمل على النحو المتوقّع. سوف تتفاعل مع "وكيل الرهن العقاري" ضمن واجهة Gemini Enterprise.

الوصول إلى الوكيل

انتقِل إلى صفحة Gemini Enterprise في Google Cloud Console.
اختَر تطبيق Gemini Enterprise الذي سبق لك إعداده، والذي تم فيه تسجيل "وكيل الرهن العقاري".
في علامة التبويب "نظرة عامة"، انتقِل إلى عنوان URL المعروض في قسم "تطبيق Gemini Enterprise على الويب جاهز".
انقر على علامة التبويب "الوكيل" من القائمة على اليمين باسم معرض الوكلاء
من المفترض أن تتمكّن الآن من الدردشة مع "مساعد قروض الرهن العقاري".

إطار الاختبار 1: "المسار الخالي من المشاكل" - تلخيص البيانات مع إخفاء محتوى معلومات تكشف الهوية الشخصية

يتحقّق هذا الاختبار من إمكانية وصول الوكيل إلى أنظمة الخلفية من خلال "بوابة الوكيل"، ومن تطبيق سياسات "منع فقدان البيانات" (DLP) لإخفاء المعلومات الحساسة.

أرسِل الطلب التالي إلى "مساعد الرهن العقاري":

I'm reviewing the Sterling family's current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

ما يحدث وراء الكواليس:
- يصيغ الوكيل في Gemini Enterprise الطلبات إلى الأدوات اللازمة (مثل نظام إدارة المستندات (DMS) للإقرارات الضريبية، وواجهة برمجة التطبيقات للتحقّق من الدخل).
- تفحص Model Armor حمولات الطلبات والاستجابات بحثًا عن التهديدات.
- تؤدي "سياسة التفويض المستندة إلى المحتوى" التي أعددتها إلى تشغيل إضافة "منع فقدان البيانات" المخصّصة (dlp-content-authz-ext). تفحص هذه الإضافة البيانات التي يتم جلبها من الأنظمة الخلفية.
- تُخفي خدمة منع فقدان البيانات أي معلومات تكشف الهوية الشخصية (PII)، مثل أرقام التأمين الاجتماعي (SSNs)، من بيانات الإقرار الضريبي قبل وصولها إلى الموظف.
النتيجة المتوقّعة: سيعرض الوكيل ملخّصًا لإقرارات ضريبة الدخل وحالة التحقّق من الدخل. من المهم فحص الملخّص الذي يقدّمه وكيل المحادثة. ستلاحظ أنّه تم استبدال المعلومات الحسّاسة، مثل أرقام تعريف دافعي الضرائب (أرقام التأمين الاجتماعي)، بعناصر نائبة (مثل [REDACTED]). يؤكّد ذلك تنفيذ سياسة "منع فقدان البيانات" من خلال البوابة.

إمكانية تتبُّع البيانات والتدقيق

خلال هذه الاختبارات، تجمع "منصة الوكيل" والخدمات المرتبطة بها بيانات القياس عن بُعد:

‫Cloud Logging: تقدّم السجلّات التفصيلية من GKE Gateway وأحمال عمل GKE والخدمات الأخرى سجلّ تدقيق للطلبات وعمليات تقييم السياسات والنتائج.
Cloud Trace: تتيح لك أداة OpenTelemetry التي تم ضبطها في خدمات الوكيل والخلفية عرض مسار المكالمة بالكامل، بدءًا من Gemini Enterprise ومرورًا ببوابة GKE وصولاً إلى أدوات الخلفية. وهذا أمر قيّم للغاية لتصحيح الأخطاء وفهم دورة حياة الطلب.

عرض عمليات التتبُّع لجلساتك:

في Google Cloud Console، انتقِل إلى صفحة Vertex AI Agent Engine.
انتقِل إلى Agent Engine. تظهر في القائمة مثيلات Agent Engine التي تشكّل جزءًا من المشروع المحدّد. يمكنك استخدام حقل "الفلتر" لفلترة القائمة حسب العمود الذي تحدّده.
انقر على اسم نسخة Agent Engine.
انقر على علامة التبويب "عمليات التتبُّع".
يمكنك اختيار "عرض الجلسة" أو "عرض الفترة الزمنية".
انقر على جلسة أو فترة زمنية لفحص تفاصيل التتبُّع، بما في ذلك الرسم البياني الموجّه غير الدوري (DAG) للفترات الزمنية والمدخلات والمخرجات وسمات البيانات الوصفية.

10. اختياري: تحويل ترميز واجهات برمجة تطبيقات REST إلى MCP باستخدام Apigee

مع أنّ خدمة إثبات الدخل تتوافق تلقائيًا مع بروتوكول Model Context، لا توفّر العديد من أنظمة المؤسسات القديمة سوى واجهات برمجة تطبيقات RESTful. في هذه الخطوة الاختيارية، ستستخدم خادم Apigee MCP Discovery الوكيل لتحويل ترميز نقطة نهاية REST الخاصة بخدمة التحقّق من الدخل إلى أداة MCP. يتيح لك ذلك تطبيق سياسات الحوكمة المتقدّمة والحدّ من المعدّل والأمان في Apigee على أدواتك القديمة.

لمزيد من المعلومات، اطّلِع على نظرة عامة على Apigee MCP.

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

قبل المتابعة، تأكَّد من توفير Apigee API Hub وإعداده. اتّبِع الخطوات الواردة في مستندات Provision API Hub لإعدادها وربط مثيل Apigee.

الخطوة 1: إنشاء مرفق خدمة لـ Apigee

للسماح لخدمة Apigee بالوصول إلى خدماتك الداخلية التي تعمل على GKE، يجب إنشاء مرفق خدمة.

ابحث عن قاعدة إعادة التوجيه الداخلية في GKE Gateway:

export RULE_URI=$(gcloud compute forwarding-rules list \
  --filter="loadBalancingScheme=INTERNAL_MANAGED AND target~targetHttpsProxies" \
  --format="value(selfLink.segment(6), region.basename(), name)" | \
  awk '{print "projects/" $1 "/regions/" $2 "/forwardingRules/" $3}')

أنشئ مرفق الخدمة:

gcloud compute service-attachments create internal-gke-gateway-apigee \
    --region=${REGION} \
    --target-service=$RULE_URI \
    --connection-preference=ACCEPT_AUTOMATIC \
    --nat-subnets=gateway-psc-subnet

الخطوة 2: تفعيل Apigee باستخدام Terraform

الآن، عدِّل إعدادات البنية الأساسية لتوفير مؤسسة Apigee ومثيلها.

انتقِل إلى دليل terraform:
```
cd terraform
```
عدِّلوا terraform.tfvars واضبطوا enable_apigee = true.
طبِّق التغييرات باتّباع الخطوات التالية:
```
terraform apply
```

الخطوة 3: تحديد مواصفات OpenAPI

تستخدم Apigee تعريفات OpenAPI (OAS) العادية لاكتشاف الأدوات وتحويل ترميزها. أنشئ ملفًا باسم income-verification-oas.yaml يتضمّن المحتوى التالي:

openapi: 3.0.0
info:
  title: Income Verification API
  description: Verify applicant income through third-party employer records.
  version: 1.0.0
servers:
  -   url: https://income-verification.internal.${DNS_PEERING_DOMAIN%%.}/api
paths:
  /income-verification/verify:
    post:
      summary: Verify applicant income
      operationId: verifyApplicant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
      responses:
        '200':
          description: Successful verification
          content:
            application/json:
              schema:
                type: object

الخطوة 4: نشر خادم وكيل Apigee MCP Discovery

خادم وكيل استكشاف MCP هو خادم وكيل متخصص في Apigee يعمل كخادم MCP.

في واجهة مستخدم Apigee، انتقِل إلى تطوير (Develop) > خوادم وكيلة لواجهة برمجة التطبيقات (API Proxies).
انقر على إنشاء جديد واختَر خادم وكيل لاكتشاف MCP.
أدخِل اسمًا للخادم الوكيل income-verification-discovery.
في قسم مواصفات OpenAPI، حمِّل ملف income-verification-oas.yaml الذي أنشأته.
اضبط مجموعة البيئة على المجموعة التي يمكن الوصول فيها إلى البوابة الداخلية.
انقر على نشر.

(اختياري) إضافة سياسة أمان

قبل نشر الخادم الوكيل أو مشاركته، عليك تأمينه. يمكنك إضافة سياسات لفرض متطلبات الأمان، مثل رموز OAuth المميزة أو مفاتيح واجهة برمجة التطبيقات. للحصول على تعليمات حول كيفية إضافة سياسة أمان، يُرجى الاطّلاع على مستندات Apigee حول تأمين واجهات برمجة التطبيقات.

الخطوة 5: التحقّق من إمكانية الوصول إلى أداة "النسخ المحوّل"

بعد نشر نقطة النهاية POST /verify، تحوّلها Apigee تلقائيًا إلى أداة verifyApplicant MCP.

في ما يلي قائمة بالأدوات المتاحة من خلال نقطة نهاية Apigee MCP:

curl -X POST https://api.internal.${DNS_PEERING_DOMAIN%%.}/income-verification-discovery/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

من المفترض أن تظهر الأداة verifyApplicant في الردّ، بعد إعادة ترميزها من مواصفات REST. يمكنك الآن استدعاء هذه الأداة من خلال Apigee، وستتولّى Apigee عملية الترجمة إلى خدمة REST الأساسية مع تطبيق أي سياسات أمان ضبطتها.

الخطوة 6: تعديل تطبيق Mortgage Agent لاستخدام Apigee

بعد أن نجحت Apigee في تحويل ترميز واجهة REST API إلى أداة متوافقة مع MCP، عليك تعديل إعدادات نشر الوكيل. من خلال توجيه الوكيل إلى نقطة نهاية Apigee، ستستفيد الآن جميع طلبات التحقّق من الدخل من الأمان والتسجيل وإدارة الزيارات على مستوى المؤسسة في Apigee.

تحديد عنوان URL الخاص بخادم MCP في Apigee: يجب أن تتّبع نقطة النهاية النمط التالي: https://api.internal.${DNS_PEERING_DOMAIN%%.}/income-verification-discovery/mcp.

أعِد تشغيل نص النشر: استخدِم العلامة --update مع --income-verification-url الجديدة. يؤدي ذلك إلى تعديل الوكيل الحالي في Agent Engine بدون الحاجة إلى حذفه بالكامل.

cd src/mortgage-agent

# Update the agent to route income verification through Apigee
uv run python deploy_agent.py \
    --project=${PROJECT_ID} \
    --update \
    --agent-name=mortgage-agent \
    --dms-mcp-url=https://dms.${DNS_PEERING_DOMAIN%%.}/mcp \
    --income-verification-url=https://api.internal.${DNS_PEERING_DOMAIN%%.}/income-verification-discovery/mcp \
    --email-mcp-url=https://email.${DNS_PEERING_DOMAIN%%.}/mcp \
    --network-attachment=projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/${PSC_ATTACHMENT} \
    --dns-peering-domain=${DNS_PEERING_DOMAIN} \
    --dns-peering-target-project=${PROJECT_ID} \
    --dns-peering-target-network=${VPC_NAME} \
    --ge-deploy \
    --app-id=${APP_ID} \
    --oauth-client-id=${OAUTH_CLIENT_ID}

تأكيد التغيير: ارجع إلى واجهة Gemini Enterprise واطلب من الوكيل التحقّق من دخل مقدّم الطلب.
```
"Can you verify the joint income for the Sterlings using the verification service?"
```
في علامة التبويب Apigee Debug، من المفترض أن ترى الآن طلب JSON-RPC الوارد من GKE Gateway يتم تحويله إلى طلب REST POST عادي إلى خدمة GKE الخلفية.

11. تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد التي تم إنشاؤها في هذا الدرس التطبيقي حول الترميز، احذفها عند الانتهاء.

احذف مرفق الخدمة إذا تم إنشاؤه يدويًا:

gcloud compute service-attachments delete internal-gke-gateway \
    --region=${REGION} --quiet

انتقِل إلى الدليل terraform وأزِل جميع الموارد:
```
cd terraform
terraform destroy
```
يمكنك اختياريًا حذف مشروع Google Cloud بالكامل باتّباع الخطوات التالية:
```
gcloud projects delete ${PROJECT_ID}
```

12. تهانينا

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

المواضيع التي تناولتها

نشر وكيل مساعد بشأن القروض العقارية من حزمة ADK إلى Agent Engine باستخدام أداة OpenTelemetry
نشر خوادم MCP الخلفية على GKE خلف بوابة داخلية
ربط Agent Engine بشبكة VPC الخاصة بمشروع باستخدام واجهة PSC وتبادل معلومات بين الشبكات عبر نظام أسماء النطاقات
تم ضبط GKE Gateway للسماح بخروج الوكيل المُدار مع إخفاء البيانات الحساسة في "منع فقدان البيانات" وتفويض MCP
ضوابط أمان الذكاء الاصطناعي التطبيقي باستخدام Model Armor لفحص الطلبات والردود
اختياريًا، يتم تحويل واجهات REST API إلى MCP باستخدام Apigee MCP Discovery Proxy