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

1. مقدمة

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

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

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

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

.

عندما يتفاعل المستخدم مع واجهة مستخدم حزمة تطوير التطبيقات، يحدث التسلسل التالي:

أهداف الدورة التعليمية

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

المتطلبات

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

المفاهيم الرئيسية

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

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

بدء Cloud Shell

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

من Google Cloud Console، انقر على رمز 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"

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

فعِّل الحد الأدنى من واجهات Google Cloud APIs المطلوبة لإدارة أساس بياناتك وتشغيل نماذج Vertex AI واستضافة وكيل ADK على Cloud Run.

gcloud services enable \
    dataplex.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

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

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

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

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

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

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

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

# 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 BigQuery datasets and tables
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

# 3. Register the Knowledge Catalog aspect type
gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --metadata-template-file-name="aspect_template.json"

# 4. Generate and apply aspects (governance rules)
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3- مستوى التحكّم المركزي في البيانات (MCP المُدار)

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

من خلال استخدام نقطة النهاية المُدارة هذه، نحقّق ما يلي:

1. عدم الحاجة إلى الصيانة: لا حاجة إلى إدارة الحاويات أو تغيير حجمها أو تصحيح خادم MCP.
2. التوحيد: يتصل الوكيل بنقطة نهاية عادية وآمنة لواجهة برمجة تطبيقات Google باستخدام بروتوكول سياق النموذج (نقل SSE).
3. النطاق الخاضع للرقابة: لا يعرض خادم MCP سوى أدوات البيانات الوصفية الضرورية (search_entries وlookup_context وlookup_entry)، ما يفرض حلقة استدلال للقراءة فقط مع إعطاء الأولوية للحوكمة.

يمكن الوصول إلى خادم MCP الخاص بـ "كتالوج المعرفة" المُدار من Google من خلال عنوان URL الآمن التالي:

https://dataplex.googleapis.com/mcp

بما أنّ هذه واجهة برمجة تطبيقات تابعة لجهة أولى من Google، يجب أن يصادق الوكيل باستخدام رمز دخول OAuth2 عادي من Google Cloud بدلاً من رمز مميّز للمعرّف. سنتولّى عملية المصادقة هذه تلقائيًا في الرمز البرمجي للتطبيق.

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

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

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

فتح رمز الوكيل في "محرِّر Cloud Shell"

بدلاً من إدراج الملف بأكمله في الوحدة الطرفية، لنفتحه في محرِّر Cloud Shell حتى تتمكّن من فحصه وتعديله وفهم الرمز البرمجي بسهولة.

نفِّذ الأمر التالي في الوحدة الطرفية واطّلِع على بنية الرمز في أداة التعديل. تم إنشاء التطبيق باستخدام حزمة تطوير الوكلاء (ADK) من Google:

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

# Copy the governance skill directory inside the application bundle so it packages during Cloud Run deployment
mkdir -p skills
cp -r ../.agents/skills/knowledge-catalog-governance skills/

cloudshell edit agent.py

(ملاحظة: يحتوي agent.py على رمز النص النموذجي في الأعلى للتعامل مع مصادقة OAuth2 وتحديث الرمز المميز في Google Cloud، ما يضمن قدرة الوكيل على التواصل بشكل آمن مع واجهة برمجة التطبيقات Knowledge Catalog التي تديرها Google).

1. تحميل المهارات الأصلية

لإنشاء وكيل محسّن للغاية، نحمّل تعليمات الحوكمة من دليل مهارات الوكيل الخارجي باستخدام load_skill_from_dir الأصلي في ADK. يتيح هذا النهج الكشف التدريجي عن المعلومات:

• البيانات الوصفية من المستوى 1: لا يحمّل الوكيل سوى اسم المهارة ووصفها عند بدء التشغيل. يسمح هذا السياق البسيط للنموذج اللغوي الكبير بتحديد الوقت المناسب لاستخدام المهارة بدون استهلاك كميات كبيرة من الرموز المميزة مسبقًا.
• تعليمات المستوى 2: يتم جلب مجموعة التعليمات الكاملة داخل SKILL.md بشكل ديناميكي في وقت التشغيل فقط عندما يحدّد النموذج أنّها ذات صلة.

base_dir = Path(__file__).parent
governance_skill = load_skill_from_dir(
    base_dir / "skills" / "knowledge-catalog-governance"
)

# Bundle the skill and MCP tools together into a SkillToolset
governance_skill_toolset = skill_toolset.SkillToolset(
    skills=[governance_skill],
    additional_tools=[tools]
)

2. تنظيم الوكلاء

تتيح لك "حزمة تطوير البرامج" تنسيق سلوكيات الوكلاء المعقّدة من خلال ربط عدّة وكلاء معًا. نحدّد SequentialAgent سير عمل يتألف من وكيلَين متخصصَين:

• governance_researcher: مزوَّد بـ governance_skill_toolset وKnowledge Catalog MCP tools. يتحقّق مما إذا كان طلب البحث يندرج ضمن نطاق فهرس البيانات والامتثال، ثم يطلب بيانات من "فهرس المعرفة" باستخدام متغيرات البيئة التي تم إدخالها في تعليمات النظام.
• compliance_formatter: مسؤولة عن ترجمة نتائج البحث عن البيانات الوصفية بتنسيق JSON الأولي إلى استجابة واضحة، أو شرح حدود النطاق بشكل سليم إذا كان الطلب خارج النطاق.

# 1. Researcher Agent (has access to the encapsulated SkillToolset)
governance_researcher = LlmAgent(
    name="governance_researcher",
    model=model_name,
    description="Dynamically interprets metadata schema (Booleans/Enums) and searches for assets using strict syntax.",
    instruction=f"""
    You are a governance researcher. Your job is to verify Knowledge Catalog metadata rules and find compliant assets for the user's query.
    
    YOUR ACTIVE ENVIRONMENT CONTEXT:
    - Google Cloud Project ID: {project_id}
    - Location (Region): {location}

    YOUR WORKFLOW:
    1. First, check if the user query is related to data analytics assets, database tables, or data compliance.
       - If YES: Call `load_skill` with `name="knowledge-catalog-governance"` to load the rules, then use search/lookup tools to locate a certified compliant table.
       - If NO (e.g., general chit-chat, unrelated tasks): Skip skill loading and output a JSON object indicating it is out of scope:
         {"error": "out_of_scope", "message": "The query does not pertain to data catalog search or governance compliance."}
    2. Populate the required projectId and location parameters in tool calls with the active environment parameters.
    3. Return the verified table's metadata in JSON format as your final research output.
    """,
    tools=[governance_skill_toolset, tools],
    output_key="research_data"
)

# 2. Formatter Agent (formats the output or explains out-of-scope errors)
compliance_formatter = LlmAgent(
    name="compliance_formatter",
    model=model_name,
    description="Formats the JSON research data into a helpful response for the user.",
    instruction="""
    You are the **Intelligent Data Governance Specialist**.
    Your job is to explain the findings of the governance research clearly to the user.

    **YOUR GOAL:**
    1. If the researcher found a matching table (valid JSON with table metadata):
       - Explain the logical connection between the User's Request, the Governance Schema (translated criteria), and the Recommended Table.
       - Use the following RESPONSE TEMPLATE:
         - **Analysis:** "I analyzed the metadata schema and translated your request into the following technical criteria:..."
         - **Recommendation:** "Based on this, I recommend the following table:"
           - **Table:** [Insert Table Name]
           - **Description:** [Insert Table Description]
         - **Verification:** "This asset is a verified match because: [Explain the verification details]."
    2. If the researcher returned an 'out_of_scope' error or no matching tables were found:
       - Apologize politely and explain that no data asset currently matches the strict governance criteria defined in `official-data-product-spec`.
       - Clearly state what domain of questions this agent is certified to answer (e.g., Data Catalog Search and Data Governance compliance).
    """
)

# 3. Orchestrated Workflow (Exported as root_agent)
root_agent = SequentialAgent(
    name="governance_workflow",
    description="Workflow to learn metadata rules, search with strict syntax, and recommend assets.",
    sub_agents=[
        governance_researcher,
        compliance_formatter,
    ]
)

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

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

نفِّذ الأمر التالي لإنشاء ملف .env. يُرجى العِلم أنّ MCP_SERVER_URL يشير مباشرةً إلى نقطة نهاية Knowledge Catalog API التي تديرها Google:

export MCP_SERVER_URL="https://dataplex.googleapis.com/mcp"

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

5- تشغيل الوكيل واختباره محليًا

قبل نشر وكيلك على السحابة الإلكترونية، يجب تشغيله محليًا في Cloud Shell للتحقّق من سلوكه. بما أنّ العامل يعتمد على العديد من حِزم Python (بما في ذلك مكتبات Google Cloud Logging وADK)، سنُعدّ بيئة افتراضية محلية لتثبيت هذه التبعيات.

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

1. انتقِل إلى الدليل mcp_server، وأنشئ بيئة افتراضية، وثبِّت الموارد التابعة:

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

# Create a virtual environment using uv
uv venv
source .venv/bin/activate

# Install the dependencies listed in requirements.txt
uv pip install -r requirements.txt

2. ابدأ جلسة المحادثة التفاعلية في نافذة الوحدة الطرفية:

adk run .

3. بعد بدء الجلسة، سيظهر لك إشعار. اكتب طلب بحث لاختبار منطق إدارة الوكيل:

I need the Q1 revenue summary for our internal board meeting.

سيعالج الوكيل طلبك، ويستعلم عن "كتالوج المعرفة" من خلال خادم MCP المُدار، ويعرض اقتراحه واستدلاله مباشرةً في نافذة الأوامر.

4. للخروج من الجلسة التفاعلية، اكتب exit أو quit (أو اضغط على Ctrl+C). بعد الخروج، يمكنك إيقاف البيئة الافتراضية:

deactivate

6. نشر الوكيل في مرحلة الإنتاج

بعد إثبات صحة بيانات الوكيل محليًا، يمكنك الآن نشره على Google Cloud لاستخدامه في الإنتاج.

إنشاء حساب خدمة

لأسباب أمنية، يجب ألا يتم تشغيل الوكيل الذي تم نشره باستخدام بيانات الاعتماد الشخصية. سننشئ هوية منفصلة (knowledge-catalog-agent-sa) للوكيل، مع الالتزام بمبدأ الحدّ الأدنى من الأذونات المميزة.

نفِّذ الأوامر التالية لإنشاء حساب الخدمة:

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"

منح الأذونات

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

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogAdmin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/viewer"

النشر على Cloud Run

أخيرًا، ننشر الوكيل على Cloud Run. ينشئ الأمر التالي صورة الحاوية باستخدام Dockerfile في دليلك الحالي، ويحمّلها إلى Artifact Registry، ثم ينشرها على Cloud Run. قد يستغرق إكمال هذه العملية بين دقيقة واحدة و3 دقائق.

gcloud run deploy knowledge-catalog-agent \
  --source . \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated \
  --clear-base-image \
  --labels created-by=adk

بعد اكتمال هذا الأمر، سيتم عرض عنوان URL للخدمة (مثل https://knowledge-catalog-agent-xyz.run.app). انقر على هذا الرابط لفتح واجهة GenAI Chat الخاضعة للإدارة الكاملة.

7. اختبار موظّف الدعم المباشر

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

افتح عنوان URL للخدمة الذي أنشأته في الخطوة السابقة (مثل https://knowledge-catalog-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. البحث عن البيانات الوصفية: يتم استدعاء search_entries في أداة MCP باستخدام طلب البحث: [PROJECT_ID].us-central1.official-data-product-spec.update_frequency=REALTIME_STREAMING
3. الاختيار: يشير إلى أنّ الجدول mkt_realtime_campaign_performance يستوفي هذه المعايير.
4. الرد: يقترح الوكيل استخدام الجدول في الوقت الفعلي.

أهمية ذلك:

بدون بيانات وصفية لإدارة البيانات، من المرجّح أن تقترح نماذج اللغات الكبيرة الجدول 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?"

8. تَنظيم

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

محو بحيرة البيانات

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

cd ~/devrel-demos/data-analytics/governance-context
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

حذف خدمات Cloud Run

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

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

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

عند نشر وكيل ADK، أنشأ النظام تلقائيًا صورة حاوية وحمّل رمز المصدر إلى حزمة Cloud Storage مؤقتة.

أزِل مستودع 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}

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

أزِل أولاً عمليات ربط سياسات إدارة الهوية وإمكانية الوصول، ثم احذف حسابات الخدمة.

# 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

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

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

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

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

# Uninstall the AGY CLI plugin
agy plugin uninstall dataplex

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

9. تهانينا!

لقد نشرت بنجاح وكيل GenAI شاملًا ومراعيًا للحوكمة.

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

الخلاصات الرئيسية

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

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

• درس تطبيقي حول أساسيات إدارة البيانات في Knowledge Catalog: يمكنك إتقان أساسيات إدارة البيانات في Knowledge Catalog قبل إضافة طبقة الذكاء الاصطناعي.
• مستندات Agent Development Kit (ADK): يمكنك الاطّلاع على المستندات الرسمية لإنشاء الوكلاء وتفعيلهم باستخدام حزمة ADK.
• نظرة تفصيلية على MCP: يمكنك الاطّلاع على مواصفات MCP الرسمية للتعرّف على كيفية إنشاء خوادم مخصّصة لواجهات برمجة التطبيقات الداخلية في مؤسستك.