نشر وكيل Enterprise Governance-Aware Agent باستخدام MCP وCloud Run

1- مقدمة

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

(يمكنك قراءة الجزء الأول من هذه السلسلة الذي يوضّح كيفية وضع الأساس للبيانات من خلال تطبيق جوانب Knowledge Catalog على جداول BigQuery واختبار القواعد محليًا من خلال Gemini CLI. 👈 قراءة الجزء الأول)

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

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

be15d5f41f0d716c.png

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

  • مشروع على Google Cloud تم تفعيل الفوترة فيه
  • فهم أساسي لـ Cloud Run وحسابات الخدمة في IAM ولغة Python
  • مجموعات بيانات BigQuery وجوانب Knowledge Catalog التي تم إنشاؤها في الجزء الأول (لا تقلق إذا حذفتها، لأنّنا نوفّر لك نصًا برمجيًا سريعًا لإعادة إنشائها أدناه)

ما ستتعلمه

  • كيفية استخدام بروتوكول سياق النموذج (MCP) لتوحيد طريقة تفاعل وكلاء الذكاء الاصطناعي مع بيانات Google Cloud
  • كيفية نشر خادم MCP آمن على Cloud Run
  • كيفية إنشاء وكيل ذكاء اصطناعي باستخدام حزمة تطوير الوكلاء (ADK) وربطه بواجهة MCP الخلفية
  • كيفية تشغيل واجهة مستخدم المطوّرين المضمّنة في حزمة تطوير الوكلاء (ADK) للتفاعل مع الوكيل الخاضع للحوكمة

ما ستحتاج إليه

  • الوصول إلى Google Cloud Shell

المفاهيم الأساسية

  • بروتوكول سياق النموذج (MCP): يمكنك اعتبار بروتوكول سياق النموذج (MCP) بمثابة "كابل USB-C عالمي" لوكلاء الذكاء الاصطناعي. بدلاً من كتابة رمز برمجي مخصّص لدمج واجهة برمجة التطبيقات لكل نموذج ذكاء اصطناعي، يوفّر بروتوكول سياق النموذج (MCP) طريقة موحّدة للذكاء الاصطناعي للاتصال بأمان بأدوات بيانات مؤسستك (مثل Knowledge Catalog وBigQuery).
  • حزمة تطوير الوكلاء (ADK): هي إطار عمل مرن ومفتوح المصدر من Google مصمّم لتبسيط عملية تطوير وكلاء الذكاء الاصطناعي من البداية إلى النهاية. يطبّق هذا الإطار مبادئ هندسة البرامج على عملية إنشاء الوكلاء، ما يتيح لك تنسيق الأدوات المعقّدة وإدارة الحالة وتشغيل واجهة مستخدم المطوّرين المضمّنة بسهولة للاختبار والنشر.

2. الإعداد والمتطلبات

بدء Cloud Shell

على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس التطبيقي حول الترميز Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.

من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات العلوي الأيسر:

تفعيل Cloud Shell

سيستغرق توفير البيئة والاتصال بها بضع لحظات فقط. عند الانتهاء، من المفترض أن يظهر لك ما يلي:

لقطة شاشة لواجهة سطر الأوامر في Google Cloud Shell توضّح أنّه تم ربط البيئة

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

إعداد البيئة

افتح Cloud Shell واضبط متغيّرات مشروعك لضمان استهداف جميع الأوامر للبنية التحتية الصحيحة.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

نقطة تفتيش: هل تريد استئناف العمل أو إعادة إنشائه؟

بما أنّ هذا هو الجزء الثاني، يحتاج الوكيل إلى البيانات الخاضعة للحوكمة من الجزء الأول لكي يعمل. يُرجى اختيار المسار:

المسار "أ": لقد انتهيتُ للتو من الجزء الأول ولا تزال مواردي قيد التشغيل.

رائع! انتقِل إلى دليل العمل وأنت جاهز للمتابعة.

cd ~/devrel-demos/data-analytics/governance-context

المسار "ب": لقد تخطيتُ الجزء الأول أو حذفتُ مواردي (نظّفتُها).

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

# 1. Clone the repo and navigate to the working directory
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

# 2. Rebuild the messy data lake with Terraform
cd terraform
terraform init
terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

# 3. Generate and apply Knowledge Catalog Aspects (Governance rules)
cd ..
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3. التوسّع باستخدام بروتوكول سياق النموذج (MCP): إنشاء مستوى التحكّم في البيانات

حتى الآن، اختبرت منطق الحوكمة بنجاح باستخدام Gemini CLI. هذا ممتاز لإنشاء النماذج الأولية بسرعة، ولكنّه يعمل محليًا باستخدام بيانات اعتماد المستخدم الشخصية.

في بيئة المؤسسة الفعلية، تحتاج إلى مستوى تحكّم مركزي في البيانات. لإنشاء ذلك، سنستخدم GenAI Toolbox for Databases، وهو مشروع رسمي مفتوح المصدر من Google. توفّر هذه الحزمة خادم MCP تم إنشاؤه مسبقًا ومصمّمًا خصيصًا لربط وكلاء الذكاء الاصطناعي بأمان بقواعد بيانات Google Cloud وخدمات البيانات الوصفية مثل Knowledge Catalog.

من خلال نشر هذه الحزمة كخادم MCP على Cloud Run، نحقق ما يلي:

  1. هوية مركزية: يتم تشغيل الوكيل كحساب خدمة محدود، وليس كحساب المستخدم الشخصي.
  2. التوحيد: يمكن لأي عميل (حزمة تطوير الوكلاء (ADK) أو Gemini أو التطبيقات المخصّصة) "الاتصال" بهذا الخادم باستخدام بروتوكول MCP العادي.
  3. النطاق الخاضع للتحكّم (الحد الأدنى من الامتيازات): لا نمنح النموذج اللغوي الكبير إذن وصول مفتوح إلى BigQuery. بل نلزمه بالتنقل أولاً خلال كتالوج البيانات الوصفية في Knowledge Catalog.

ضبط تعريف الأداة (tools.yaml)

تتطلب حزمة GenAI Toolbox ملف إعداد تصريحيًا، وهو tools.yaml. يحدّد هذا الملف sources (مكان الاتصال) وtools (ما يُسمح للذكاء الاصطناعي بفعله).

  1. انتقِل إلى دليل الخادم وأدخِل رقم تعريف مشروعك في ملف الإعداد:
cd ~/devrel-demos/data-analytics/governance-context/mcp_server
envsubst < tools.yaml > tools.tmp && mv tools.tmp tools.yaml
cat tools.yaml

من المفترض أن يكون مطابقًا للمقتطف التالي. تأكَّد من أنّ حقل المشروع يتطابق الآن مع رقم تعريف مشروع Google Cloud الفعلي.

sources:
  dataplex:
    kind: dataplex
    project: YOUR-PROJECT-ID

tools:
  search_entries:
    kind: dataplex-search-entries
    source: dataplex
    description: Search for entries in Knowledge Catalog.

  lookup_entry:
    kind: dataplex-lookup-entry
    source: dataplex
    description: Retrieve a specific entry from Knowledge Catalog.

  search_aspect_types:
    kind: dataplex-search-aspect-types
    source: dataplex
    description: Find aspect types relevant to a query.

toolsets:
  dataplex-toolset:
    - search_entries
    - lookup_entry
    - search_aspect_types

من خلال تحديد هذه الأدوات الثلاث، يمكننا إجبار الذكاء الاصطناعي على أن يكون "للقراءة فقط" و"يركّز على الحوكمة أولاً".

تأمين الإعداد (Secret Manager)

في بنية المؤسسة، يجب ألا يتم تضمين ملفات الإعداد مباشرةً في صور الحاويات. سنخزّن tools.yaml بأمان في Google Cloud Secret Manager.

gcloud services enable secretmanager.googleapis.com
gcloud secrets create dataplex-tools-config --data-file=tools.yaml

تطبيق مبدأ الحد الأدنى من الامتيازات (IAM)

بعد ذلك، ننشئ حساب خدمة مخصّصًا لخادم MCP في GenAI Toolbox. لن يكون لدى هذه الهوية سوى الأذونات المطلوبة تمامًا لقراءة كتالوج Knowledge Catalog والوصول إلى بيانات BigQuery.

export MCP_SA=mcp-sa
gcloud iam service-accounts create ${MCP_SA} \
    --display-name="Service Account for Knowledge Catalog MCP"
export MCP_SERVICE_ACCOUNT="${MCP_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

# Allow the server to read its own config from Secret Manager
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor"

# Allow the server to read Knowledge Catalog Metadata and BigQuery Data
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

نشر خادم MCP على Cloud Run

الآن، ننشر GenAI Toolbox. نستخدم صورة الحاوية التي تم إنشاؤها مسبقًا من Google (database-toolbox/toolbox) ونحمّل إعداداتنا من Secret Manager (--set-secrets) في وقت التشغيل.

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

gcloud run deploy governance-mcp \
    --image=$IMAGE \
    --service-account $MCP_SERVICE_ACCOUNT \
    --region=$REGION \
    --no-allow-unauthenticated \
    --set-secrets="/app/tools.yaml=dataplex-tools-config:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080"

لقد أنشأت الآن واجهة برمجة تطبيقات خاضعة للحوكمة. بدلاً من منح واجهة GenAI الأمامية إذن الوصول المباشر إلى قاعدة البيانات، ستتصل بعنوان URL هذا على Cloud Run. لا يمكن للوكيل الاطّلاع إلا على ما تسمح له هذه الحزمة بالاطّلاع عليه.

4. إنشاء واجهة الوكيل الخلفية باستخدام حزمة تطوير الوكلاء (ADK)

لقد أنشأت مستوى تحكّم آمنًا وخاضعًا للحوكمة في البيانات (MCP) يعمل على Cloud Run. يحتاج وكيل الذكاء الاصطناعي الآن إلى إطار عمل لتنسيق منطق الوكيل، مثل معالجة إدخالات المستخدمين وتحديد وقت استدعاء خادم MCP وتنسيق الناتج.

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

فحص منطق الوكيل (agent.py)

قبل ضبط البنية التحتية، لنلقِ نظرة على جوهر هذا التطبيق.

انتقِل إلى الدليل واعرض محتويات agent.py. هذا الملف هو "عقل" عملية نشر حزمة تطوير الوكلاء (ADK).

cd ~/devrel-demos/data-analytics/governance-context/mcp_server
cat agent.py

ألقِ نظرة على بنية الرمز البرمجي. ينفّذ هذا الرمز ثلاث وظائف مهمة بأقل قدر من الرمز البرمجي:

  1. دمج MCPToolset: بدلاً من كتابة برامج HTTP مخصّصة للتفاعل مع أدوات Knowledge Catalog، تستخدم حزمة تطوير الوكلاء (ADK) الرمز MCPToolset(server_url=mcp_url). يؤدي ذلك إلى استرداد تعريف tools.yaml ديناميكيًا من خادم MCP الذي تم نشره وترجمته إلى استدعاءات وظائف أصلية للنموذج اللغوي الكبير.
  2. تعليمات النظام: تحتوي المَعلمة instructions على قواعد الحوكمة الصارمة (المنطق نفسه الذي استخدمناه في CLI GEMINI.md). وتطلب بشكل صريح من النموذج تنفيذ حلقة الاستنتاج من المرحلة 1 (البحث عن البيانات الوصفية) إلى المرحلة 2 (طلب البيانات).
  3. تنسيق الوكيل: يربط الصف Agent(...) نموذج Gemini وموجّه النظام وأدوات MCP معًا. عند النشر، تحوّل حزمة تطوير الوكلاء (ADK) هذا الكائن تلقائيًا إلى نقطة نهاية قابلة للتوسّع في FastAPI.

فصل المهام: ضبط هوية الواجهة الأمامية

لتشغيل هذا الرمز البرمجي بأمان، يجب إعلام الوكيل بمكان خادم MCP. سننشئ عنوان URL ديناميكيًا ونحفظه في ملف .env الذي ستقرأه حزمة تطوير الوكلاء (ADK) في وقت التشغيل.

سننشئ أيضًا هوية منفصلة (dataplex-agent-sa) لهذا التطبيق الذي يواجه المستخدمين. يضمن فصل المهام هذا أنّ وكيل الواجهة الأمامية لديه أذونات مختلفة عن خادم الحوكمة في الواجهة الخلفية.

نفِّذ الأوامر التالية لضبط البيئة والهوية:

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export MCP_SERVER_URL=https://governance-mcp-${PROJECT_NUMBER}.${REGION}.run.app/mcp

export AGENT_SA=knowledge-catalog-agent-sa
export AGENT_SERVICE_ACCOUNT="${AGENT_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create ${AGENT_SA} \
    --display-name="Service Account for Knowledge Catalog Agent "

ضبط متغيّرات وقت التشغيل

يعتمد إطار عمل حزمة تطوير الوكلاء (ADK) على متغيّرات البيئة لفهم سياقه. علينا ضبط رقم تعريف المشروع والمنطقة بشكل صريح وتفعيل استخدام Agent Engine في Gemini Enterprise. سنلحق هذه المتغيّرات بملف .env نفسه.

echo MCP_SERVER_URL=$MCP_SERVER_URL > .env
echo GOOGLE_GENAI_USE_VERTEXAI=1 >> .env
echo GOOGLE_CLOUD_PROJECT=$PROJECT_ID >> .env
echo GOOGLE_CLOUD_LOCATION=$REGION >> .env

منح الأذونات

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

  1. مستخدِم Agent Engine في Gemini Enterprise: لاستدعاء نموذج Gemini لإنشاء ردود بلغة طبيعية
  2. مستدعي Cloud Run: لاستدعاء واجهة برمجة التطبيقات الخاصة بخادم MCP بأمان لا يحصل هذا الدور على إذن الوصول المباشر إلى BigQuery أو Knowledge Catalog.
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

gcloud run services add-iam-policy-binding governance-mcp \
  --region=$REGION \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

النشر على Cloud Run

أخيرًا، ننشر المكدس الكامل على Cloud Run.

نستخدم uvx لتشغيل أداة حزمة تطوير الوكلاء (ADK) بدون تثبيت التبعيات يدويًا. تؤدي الأوامر أدناه إلى تجميع منطق agent.py وإنشاء صورة حاوية وإدخال حساب الخدمة وتشغيل خادم FastAPI. من خلال إضافة العلامة --with_ui، يتم أيضًا تجميع ADK Web Playground لتصحيح الأخطاء.

ينشئ هذا الأمر الحاوية وينشرها. قد يستغرق إكمال هذا الإجراء من دقيقة إلى 3 دقائق.

uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service_name=knowledge-catalog-agent \
  --with_ui \
  . \
  -- \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated

بعد اكتمال هذا الأمر، سيتم عرض عنوان URL للخدمة (e.g., https://dataplex-agent-xyz.run.app). انقر على هذا الرابط لفتح واجهة محادثة الذكاء الاصطناعي التوليدي الخاضعة للحوكمة بالكامل.

12a5fa4c2aaf381f.png

سير العمل المعماري من البداية إلى النهاية

لقد أكملت الآن النظام. عندما يتفاعل المستخدم مع واجهة مستخدم حزمة تطوير الوكلاء (ADK)، يحدث التسلسل التالي:

  1. يُرسِل المستخدم طلبًا في وكيل حزمة تطوير الوكلاء (ADK) (واجهة مستخدم المطوّرين).
  2. يعالج وكيل حزمة تطوير الوكلاء (ADK) (agent.py) الإدخال ويستدعي نموذج Gemini.
  3. يحدّد Gemini أنّه بحاجة إلى سياق ويطلب من خادم MCP تنفيذ أدوات Knowledge Catalog.
  4. يفرض خادم MCP قواعد حوكمة Knowledge Catalog ويعرض البيانات الوصفية.
  5. يُنشئ Gemini الإجابة الموثوق بها استنادًا إلى البيانات الوصفية ويعرضها للمستخدم.

5. اختبار وكيل المؤسسة

بعد أن أصبح الوكيل متاحًا، لنعد إلى سيناريوهات الحوكمة التي تم اختبارها سابقًا باستخدام CLI. يبقى المنطق كما هو، ولكنّك تتفاعل الآن مع ADK Web Playground الذي تم نشره، والذي يعرض الحالة الداخلية وعمليات تنفيذ الأدوات.

  1. التنسيق: يتلقّى وكيل حزمة تطوير الوكلاء (ADK) (الذي يعمل على Cloud Run) النص الذي أدخلته.
  2. توجيه الأداة: يدرك Gemini أنّ سؤالك يتطلب سياق بيانات ويُعيد توجيه الطلب إلى خادم MCP.
  3. التحقّق من الحوكمة: يستعلم خادم MCP (الذي يعمل على مثيل منفصل من Cloud Run) عن أنواع جوانب محدّدة في Knowledge Catalog.
  4. الإنشاء: يتم عرض البيانات الوصفية ذات الصلة على Gemini لإنشاء الإجابة النهائية.

التحقّق من منطق الحوكمة

افتح عنوان URL للخدمة الذي أنشأته في الخطوة السابقة (e.g., https://dataplex-agent-xyz.run.app) في متصفّحك. ألصِق الطلب التالي:

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

راقِب عملية الاستنتاج الخاصة بالوكيل في واجهة مستخدم المطوّرين:

  1. التعرّف على الغرض: يحلّل الوكيل عبارتَي "الآن" و"لا يمكنني الانتظار حتى الليل".
  2. البحث عن البيانات الوصفية: يستدعي الوكيل أداة MCP search_aspect_types. يبحث الوكيل عن مواد عرض البيانات التي تم ضبط جانب update_frequency فيها على REALTIME أو STREAMING، بدلاً من DAILY أو MONTHLY.
  3. الاختيار: يحدّد الوكيل أنّ الجدول mkt_realtime_campaign_performance يستوفي هذه المعايير، في حين أنّ الجدول fin_monthly_closing_internal (على الرغم من جودته العالية) بطيء جدًا بالنسبة إلى طلبك.
  4. الردّ: يقترح الوكيل الجدول في الوقت الفعلي.

e0da615724199e.png

أهمية ذلك:

بدون بيانات الحوكمة الوصفية هذه، من المرجّح أن يقترح النموذج اللغوي الكبير الجدول fin_monthly_closing_internal ببساطة لأنّه يحتوي على عمود باسم "ad_spend"، مع تجاهل حقيقة أنّ البيانات مضى عليها 24 ساعة. لقد منع سياق البيانات الوصفية حدوث خطأ تجاري.

يمكنك أيضًا اختبار الطلب "اجتماع مجلس الإدارة" لمعرفة كيف ينتقل الوكيل إلى جداول مختلفة استنادًا إلى جانب مستوى منتج البيانات:

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

6. تَنظيم

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

إتلاف مستودع البيانات (Terraform)

استخدِم Terraform لإزالة جداول BigQuery ومجموعات البيانات وتعريفات جوانب Knowledge Catalog.

cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

حذف خدمات Cloud Run

أزِل موارد الحوسبة لإيقاف أي فوترة نشطة للحاويات قيد التشغيل.

gcloud run services delete governance-mcp --region=$REGION --quiet
gcloud run services delete knowledge-catalog-agent --region=$REGION --quiet

تنظيف نواتج عملية الإنشاء ومساحة التخزين المؤقتة

عند نشر وكيل حزمة تطوير الوكلاء (ADK) باستخدام uvx، أنشأ النظام تلقائيًا صورة حاوية وحمّل الرمز البرمجي المصدر إلى حزمة مؤقتة في Cloud Storage. تبقى هذه النواتج حتى بعد حذف خدمة Cloud Run وسيتم تحصيل تكاليف التخزين المستمرة.

أزِل مستودع Artifact Registry وحزمة التخزين المؤقتة في Cloud Storage:

# Delete the repository used for the agent build
gcloud artifacts repositories delete cloud-run-source-deploy \
    --location=$REGION \
    --quiet

# Delete the staging bucket created by Cloud Run source deploy
gcloud storage rm --recursive gs://run-sources-${PROJECT_ID}-${REGION}

حذف الهوية والأذونات والأسرار

أزِل أولاً عمليات ربط سياسة IAM لمنع بقاء إدخالات "شاهد القبر" (السجلات غير المرتبطة) في صفحة IAM الخاصة بمشروعك. بعد ذلك، احذف حسابات الخدمة وأسرار الإعداد.

# Remove IAM roles granted to the MCP Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

# Remove IAM roles granted to the Agent Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" --quiet

# Delete the Service Accounts
gcloud iam service-accounts delete $MCP_SERVICE_ACCOUNT --quiet
gcloud iam service-accounts delete $AGENT_SERVICE_ACCOUNT --quiet

# Delete the Secret Manager entry
gcloud secrets delete dataplex-tools-config --quiet

إزالة الإعدادات المحلية

أخيرًا، نظِّف ملفات الإعداد المحلية ومتغيّرات البيئة في Cloud Shell.

# Uninstall the Gemini CLI extension (installed in Part 1)
gemini extensions uninstall dataplex

# Remove local repository files and unset variables
cd ~
rm -rf ~/devrel-demos
unset MCP_SERVER_URL
unset MCP_SERVICE_ACCOUNT
unset AGENT_SERVICE_ACCOUNT

7. تهانينا!

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

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

النقاط الرئيسية

  • ذكاء اصطناعي حتمي من خلال البيانات الوصفية: بدلاً من الاعتماد على النموذج اللغوي الكبير لتخمين الجدول الصحيح استنادًا إلى أسماء الأعمدة، فرضت حلقة استنتاج صارمة باستخدام GenAI Toolbox for Databases. من خلال عرض ثلاث أدوات فقط من Knowledge Catalog بشكل صريح (search_aspect_types وsearch_entries وlookup_entry)، أجبرت النموذج على التحقّق من شهادات البيانات قبل إنشاء الإجابات.
  • بنية غير مرتبطة (بروتوكول سياق النموذج (MCP)): من خلال نشر خادم بروتوكول سياق النموذج (MCP) على Cloud Run، جرّدت قواعد حوكمة البيانات في واجهة برمجة تطبيقات مركزية وموحّدة. لا يحتاج وكيل الواجهة الأمامية إلى احتواء منطق قاعدة البيانات، بل يحتاج فقط إلى التواصل من خلال بروتوكول MCP العادي. هذا يعني أنّه يمكنك ربط أي نموذج ذكاء اصطناعي أو عميل مستقبلي بالواجهة الخلفية نفسها الخاضعة للحوكمة.
  • فصل المهام: طبّقت مبدأ الحد الأدنى من الامتيازات من خلال عزل هويات IAM. يعمل وكيل حزمة تطوير الوكلاء (ADK) الذي يواجه المستخدمين بأذونات محدودة لاستدعاء النموذج وتوجيه واجهة برمجة التطبيقات، بينما يعالج خادم MCP في الواجهة الخلفية بأمان طلبات Knowledge Catalog واسترداد بيانات BigQuery.
  • تنسيق الوكيل الذي يعتمد على الرمز البرمجي أولاً: استخدمت حزمة تطوير الوكلاء (ADK) من Google لتغليف منطق وكيل Python على الفور في واجهة خلفية قابلة للتوسّع في FastAPI، مع الاستفادة من واجهة مستخدم المطوّرين المضمّنة لعرض عمليات تنفيذ الأدوات الداخلية للوكيل وتصحيح أخطائها.

ما هي الخطوة التالية؟