إنشاء وكيل "جواز سفر الحيوانات الأليفة" ونشره على Cloud Run

1. نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستتعلّم كيفية نشر تطبيق جواز سفر الحيوانات الأليفة، وهو وكيل ذكاء اصطناعي يستخدم بروتوكول Model Context Protocol (MCP) للجمع بين تحليل البيانات وخدمات الموقع الجغرافي.

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

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

تم إنشاء الوكيل باستخدام إطار عمل google-adk وهو يستند إلى Gemini.

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

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

أولاً، لنتأكّد من إعداد بيئة التطوير بشكلٍ صحيح.

1. المصادقة باستخدام Google Cloud

اضبط مشروع Google Cloud النشط وصدِّق على هويتك. هذا الإذن مطلوب ليتمكّن الوكيل من الوصول إلى BigQuery والخدمات الأخرى.

gcloud config set project [YOUR-PROJECT-ID]
gcloud auth application-default login --project [YOUR-PROJECT-ID]

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

gcloud auth application-default login --disable-quota-project
gcloud auth application-default set-quota-project [YOUR-PROJECT-ID]

2. متطلبات البرامج

يجب تثبيت البرامج التالية على جهازك:

  • Python (يجب استخدام الإصدار 3.13 أو إصدار أحدث)
  • Git (لتنزيل المستودع)

تنزيل المستودع

يتوفّر رمز هذا المشروع في مستودع Google MCP. أنشئ نسخة طبق الأصل من المستودع وانتقِل إلى مجلد المشروع:

git clone https://github.com/google/mcp.git
cd examples/petpassport

3- تثبيت

بعد الحصول على الملفات، لنبدأ بإعداد بيئة Python.

  1. إنشاء بيئة افتراضية: يساعد ذلك في الحفاظ على استقلالية التبعيات.
    python3 -m venv .venv
  2. تفعيل البيئة الافتراضية:
    • على نظام التشغيل Linux/macOS: 
      source .venv/bin/activate
    • في نظام التشغيل Windows: 
      .venv\Scripts\activate
  3. تثبيت التبعيات:
    pip install google-adk==1.28.0 python-dotenv google-genai pillow uvicorn

تفعيل Cloud APIs

فعِّل واجهات برمجة التطبيقات التالية في مشروعك:

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

اختيار منطقة

اضبط المنطقة كمتغير بيئي في shell:

export REGION=us-central1

4. الحصول على مفاتيح واجهة برمجة التطبيقات

لاستخدام خدمات "خرائط Google" وGemini، عليك الحصول على مفاتيح واجهة برمجة التطبيقات وتخزينها في ملف .env في جذر المشروع.

1. مفتاح Google Maps API

  1. انتقِل إلى Google Cloud Console.
  2. انتقِل إلى واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.
  3. انقر على إنشاء بيانات اعتماد > مفتاح API.
  4. انسخ المفتاح الذي تم إنشاؤه وأضِفه إلى ملف .env كـ MAPS_API_KEY=[YOUR_KEY].
  5. (إجراء مقترَح) قصر استخدام المفتاح على واجهات Maps API التي يستخدمها خادم MCP فقط

2. مفتاح Gemini API (‫AI Studio)

  1. انتقِل إلى Google AI Studio.
  2. انقر على الحصول على مفتاح واجهة برمجة التطبيقات أو انتقِل إلى قسم "مفاتيح واجهة برمجة التطبيقات".
  3. انقر على إنشاء مفتاح واجهة برمجة تطبيقات.
  4. انسخ المفتاح وأضِفه إلى ملف .env كـ GEMINI_API_KEY=[YOUR_KEY].

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

إنشاء ملف requirements.txt في المجلد petpassport/:

google-adk==1.28.0
python-dotenv
google-genai
pillow

6. مصادقة خوادم MCP

يعتمد هذا التطبيق على خوادم Model Context Protocol (MCP) للتفاعل مع "خرائط Google" وBigQuery. لمصادقة هذه الخوادم، عليك ضبط متغيّرات البيئة والعناوين المناسبة.

  1. منصة Google Maps MCP: تتطلّب مفتاح Maps API صالحًا يتم تمريره في العنوان X-Goog-Api-Key.
  2. BigQuery MCP: يتطلّب بيانات اعتماد OAuth مع إذن بالوصول إلى خدمة BigQuery. يستخدم الوكيل حساب الخدمة التلقائي للحوسبة عند التشغيل على Cloud Run، أو بيانات الاعتماد المحلية عند التشغيل محليًا.

نوفّر نصًا برمجيًا للإعداد setup/setup_env.sh في المستودع يساعد في ضبط هذه المتغيّرات في ملف .env.

7. إنشاء جدول BigQuery

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

نوفّر برنامج نصيًا للإعداد setup/setup_bigquery.sh ينفّذ الخطوات التالية:

  1. يتم إنشاء حزمة Cloud Storage باسم pet-passport-data-[PROJECT_ID] لتخزين البيانات الأولية.
  2. تنزيل مجموعة بيانات ترخيص الكلاب العامة في مدينة نيويورك (ملف CSV)
  3. تحميل ملف CSV إلى الحزمة
  4. تنشئ هذه الطريقة مجموعة بيانات في BigQuery باسم nyc_dogs.
  5. تحميل البيانات من الحزمة إلى جدول باسم licenses في مجموعة البيانات

لتشغيل نص الإعداد البرمجي، نفِّذ الأمر التالي في الوحدة الطرفية:

bash setup/setup_bigquery.sh

8. الاتصال بخوادم MCP

أحد الأجزاء الرئيسية في هذا التطبيق هو استخدام MCP للاتصال بالبيانات والخدمات. في هذا القسم، ستضبط مجموعات أدوات MCP لكلّ من BigQuery و"خرائط Google" في ملف باسم petpassport/tools.py.

إكمال رمز tools.py

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

import os
import dotenv
import google.auth
import time
import datetime
from google.cloud import storage
from PIL import Image
from google import genai
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams 

MAPS_MCP_URL = "https://mapstools.googleapis.com/mcp" 
BIGQUERY_MCP_URL = "https://bigquery.googleapis.com/mcp" 

PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')
BUCKET_NAME = f"pet-passport-data-{PROJECT_ID}" 

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            },
            timeout=30.0,          
            sse_read_timeout=300.0
        )
    )
    print("Maps MCP Toolset configured.")
    return tools


def get_bigquery_mcp_toolset():   
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH,
            timeout=30.0,          
            sse_read_timeout=300.0
        )
    )
    print("BigQuery MCP Toolset configured.")
    return tools

def generate_pet_passport_photo(prompt: str, image_path: str = None) -> str:
    """Generates an image using gemini-3.1-flash-image-preview based on a prompt and a reference image."""
    client = genai.Client()
    output_path = f"/tmp/pet_passport_{int(time.time())}.png"
    
    try:
        image = Image.open(image_path)
        response = client.models.generate_content(
            model="gemini-3.1-flash-image-preview",
            contents=[prompt, image],
        )
        
        for part in response.parts:
            if part.inline_data is not None:
                generated_image = part.as_image()
                generated_image.save(output_path)
                
                # Upload to GCS and generate signed URL
                try:
                    storage_client = storage.Client()
                    bucket = storage_client.bucket(BUCKET_NAME)
                    blob_name = os.path.basename(output_path)
                    blob = bucket.blob(blob_name)
                    
                    blob.upload_from_filename(output_path)
                    
                    url = blob.generate_signed_url(
                        version="v4",
                        expiration=datetime.timedelta(hours=24),
                        method="GET",
                    )
                    return url
                except Exception as e:
                    print(f"Error uploading image to GCS: {e}")
                    return output_path
                
        raise ValueError("No image was returned by the model.")
    except Exception as e:
        print(f"Error generating image: {e}")
        raise

def save_pet_passport(user_id: str, breed: str, postal_code: str, route_details: str, image_paths: list[str] = None) -> str:
    """Appends the generated itinerary to the user's history in GCS."""
    try:
        storage_client = storage.Client()
        bucket = storage_client.bucket(BUCKET_NAME)
        blob = bucket.blob(f"user-{user_id}.json")
        
        # Download existing or start fresh
        # ... (Implementation details hidden for brevity) ...
        return "Success"
    except Exception as e:
        print(f"Error saving path: {e}")
        raise

شرح الرمز: tools.py

  • يضبط get_maps_mcp_toolset وget_bigquery_mcp_toolset برامج MCP مع نقاط نهاية وعناوين مصادقة صحيحة.
  • يستخدم generate_pet_passport_photo Gemini لإنشاء مشهد ويحمّل النتيجة إلى Google Cloud Storage، ويعرض عنوان URL موقّعًا على الواجهة الأمامية لضمان استمرار عمل الخادم عند إعادة تشغيله.

9- إنشاء الوكيل

بعد ضبط إعدادات أدواتك، حان الوقت لإنشاء "عقل" الوكيل. ستستخدم "حزمة تطوير الوكلاء" (ADK) لإنشاء وكيل في ملف باسم petpassport/agent.py.

إكمال رمز agent.py

في ما يلي عملية التنفيذ الكاملة لـ agent.py، حيث نحدّد الوكيل وتعليماته:

import os
import dotenv
import tools
from google.adk.agents import LlmAgent

dotenv.load_dotenv()

PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-2.5-pro',
    name='root_agent',
    instruction=f"""
        You are the Pet Passport Agent. Your goal is to help users find a fun walking route for their dog in NYC.
        
        When given a breed and a postal code, follow this flow:
        1. **Strategic Discovery:** Use BigQuery to find the most popular neighborhood for that breed in NYC.
        2. **Local Execution:** Use Maps to build a walking route with specific places (parks, cafes) in that area.
        
        **NO DIRECTIONS LINKS:** You must NOT include a Google Maps directions link (e.g., `https://www.google.com/maps/dir/...`) in your final response. Only provide links to individual places.
        
        After generating the itinerary, you MUST call the `save_pet_passport` tool to save this path to the user's profile. Pass a clean summary of the itinerary as `route_details`. The summary should include details (like rating, description from maps).
    """,
    tools=[maps_toolset, bigquery_toolset, tools.generate_pet_passport_photo, tools.save_pet_passport]
)

شرح الرمز: agent.py

  • نستورد tools مباشرةً (بنية مسطّحة) لتوفير بيئة الحاوية.
  • يتم إعداد الوكيل باستخدام gemini-2.5-pro.
  • تحدّد التعليمات سلسلة صارمة ومتعددة الخطوات من التفكير (BigQuery أولاً، ثم "خرائط Google") وتحظر بشدة تقديم مسارات سير تؤدي إلى أماكن غير منظَّمة.

10. تشغيل التطبيق محليًا

قبل النشر على Cloud Run، يُنصح باختبار التطبيق محليًا.

  1. تأكَّد من أنّك في دليل المشروع:
    cd examples/petpassport
  2. بدء خادم FastAPI: نستخدم uvicorn لتشغيل التطبيق. نقطة الدخول هي main.py داخل المجلد petpassport.
    uvicorn petpassport.main:app --reload
  3. فتح واجهة المستخدم: انتقِل إلى http://127.0.0.1:8000/ui/ في المتصفّح للتفاعل مع واجهة "جواز سفر الحيوانات الأليفة".

11. النشر على Cloud Run

بعد أن يصبح وكيلك جاهزًا، حان الوقت لنشره على Cloud Run. نستخدم الأمر gcloud العادي مباشرةً للحفاظ على التحكّم الصارم في بيئة الحاوية.

من دليل المشروع، نفِّذ الأمر التالي:

gcloud run deploy petpassport \
  --source petpassport \
  --region $REGION \
  --allow-unauthenticated \
  --labels dev-tutorial=google-mcp

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

بعد النشر، انتقِل إلى خدمة Cloud Run في Google Cloud Console واضبط متغيرات البيئة التالية ضمن علامة التبويب المتغيرات والأسرار:

  • MAPS_API_KEY: مفتاح Google Maps API.
  • ‫GOOGLE_CLOUD_PROJECT: رقم تعريف مشروعك
  • PROJECT_ID: رقم تعريف مشروعك (يتم توفير التكرار للوحدات القديمة).

12. أمثلة على الطلبات

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

  1. عادي: "أريد الذهاب في نزهة مع كلبي من سلالة غولدن ريتريفر في مدينة نيويورك بالقرب من الرمز البريدي 10021. ابحث لنا عن مسار يتضمّن مقهى".
  2. سلالة مختلفة: "لديّ كلب بولدوغ فرنسي وأقيم في "أبر ويست سايد" (بالقرب من الرمز البريدي 10024). اقترح عليّ نزهة قصيرة تتضمّن التوقف في حديقة شهيرة للكلاب."
  3. مع صورة: (حمِّل صورة لكلبك) "إليك صورة لكلب كورجي. نحن بالقرب من الرمز البريدي 10013. خطِّط لنا ليوم مثالي في الخارج".

13. تَنظيم

لتجنُّب تحمّل تكاليف الموارد المستخدَمة في هذا البرنامج التعليمي، اتّبِع الخطوات التالية:

  • احذف خدمة Cloud Run: gcloud run services delete petpassport --region=$REGION
  • احذف حزمة GCS: gcloud storage rm -r gs://pet-passport-data-$PROJECT_ID