ساخت یک عامل ADK هوش مکانی با سرورهای MCP برای BigQuery و Google Maps

۱. مقدمه

در این Codelab، شما یک عامل با ADK خواهید ساخت که توسط Gemini 3.0 Pro پشتیبانی می‌شود. این عامل به ابزارهایی از دو سرور MCP از راه دور (میزبانی شده توسط گوگل) مجهز خواهد شد تا به طور ایمن به BigQuery برای داده‌های جمعیتی، قیمت‌گذاری و فروش و به Google Maps برای تجزیه و تحلیل و اعتبارسنجی موقعیت مکانی در دنیای واقعی دسترسی داشته باشد.

این عامل، درخواست‌های بین کاربر و سرویس‌های گوگل کلود را هماهنگ می‌کند تا مشکلات تجاری مربوط به مجموعه داده‌های فرضی نانوایی را حل کند.

82dd7bd2823a821b.png

کاری که انجام خواهید داد

  • تنظیم داده‌ها: مجموعه داده‌های اولیه نانوایی را در BigQuery ایجاد کنید.
  • توسعه عامل: با استفاده از کیت توسعه عامل (ADK) یک عامل هوشمند بسازید.
  • ادغام ابزارها: از طریق سرور MCP، عامل را به قابلیت‌های BigQuery و Maps مجهز کنید.
  • تحلیل بازار: برای ارزیابی روندها و اشباع بازار با نماینده تعامل کنید.

آنچه نیاز دارید

  • یک مرورگر وب مانند کروم
  • یک پروژه گوگل کلود با قابلیت پرداخت یا یک حساب جیمیل.

این Codelab برای توسعه‌دهندگان در تمام سطوح، از جمله مبتدیان، مناسب است. شما از رابط خط فرمان در Google Cloud Shell و کد پایتون برای توسعه ADK استفاده خواهید کرد. نیازی نیست که متخصص پایتون باشید، اما درک اولیه از نحوه خواندن کد به شما در درک مفاهیم کمک می‌کند.

۲. قبل از شروع

ایجاد یک پروژه ابری گوگل

  1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .

a3dd2e6dddc8f691.png

  1. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

شروع پوسته ابری

Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا می‌شود و ابزارهای لازم از قبل روی آن بارگذاری شده‌اند.

  1. روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید:

404e4cce0f23e5c5.png

  1. پس از اتصال به Cloud Shell، این دستور را برای تأیید احراز هویت خود در Cloud Shell اجرا کنید: 
gcloud auth list
  1. برای تأیید اینکه پروژه شما برای استفاده با gcloud پیکربندی شده است، دستور زیر را اجرا کنید: 
gcloud config get project
  1. تأیید کنید که پروژه مطابق انتظار است و سپس دستور زیر را برای تنظیم شناسه پروژه خود اجرا کنید: 
export PROJECT_ID=$(gcloud config get project)

۳. کد را دریافت کنید

مخزن را کلون کنید

  1. مخزن را به محیط Cloud Shell خود کلون کنید: 
git clone https://github.com/google/mcp.git
  1. به دایرکتوری نسخه آزمایشی بروید: 
cd mcp/examples/launchmybakery

احراز هویت

برای تأیید اعتبار با حساب Google Cloud خود، دستور زیر را اجرا کنید. این برای دسترسی ADK به BigQuery لازم است.

gcloud auth application-default login

برای تکمیل فرآیند احراز هویت، دستورالعمل‌ها را دنبال کنید.

۴. پیکربندی محیط و BigQuery

اجرای اسکریپت‌های راه‌اندازی

  1. اسکریپت راه‌اندازی محیط را اجرا کنید. این اسکریپت APIهای BigQuery و Google Maps را فعال می‌کند و یک فایل .env با شناسه پروژه و کلید API نقشه‌های شما ایجاد می‌کند. 
chmod +x setup/setup_env.sh
./setup/setup_env.sh
  1. اسکریپت راه‌اندازی BigQuery را اجرا کنید. این اسکریپت ایجاد مخزن ذخیره‌سازی ابری، آپلود داده‌ها و آماده‌سازی مجموعه داده‌ها و جداول BigQuery را خودکار می‌کند. 
chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

پس از تکمیل اسکریپت، مجموعه داده mcp_bakery باید ایجاد شده و با جداول زیر پر شود:

  • جمعیت‌شناسی - داده‌های سرشماری و ویژگی‌های جمعیت بر اساس کد پستی.
  • قیمت‌های نانوایی - قیمت‌های رقبا و جزئیات محصول برای انواع شیرینی‌ها.
  • sales_history_weekly - عملکرد فروش هفتگی (مقدار و درآمد) بر اساس فروشگاه و محصول.
  • foot_traffic - امتیاز تخمینی ترافیک پیاده بر اساس کد پستی و زمان روز.
  1. با مراجعه به کنسول BigQuery در پروژه Google Cloud خود، از ایجاد مجموعه داده‌ها و جداول اطمینان حاصل کنید:

6bd0a0cd7522dd11.jpeg

۵. نصب ADK

اکنون که زیرساخت آماده است، بیایید یک محیط مجازی پایتون ایجاد کنیم و بسته‌های مورد نیاز ADK را نصب کنیم.

  1. ایجاد یک محیط مجازی: 
python3 -m venv .venv
  1. فعال کردن محیط مجازی: 
source .venv/bin/activate
  1. ADK را نصب کنید: 
pip install google-adk
  1. به دایرکتوری نماینده بروید: 
cd adk_agent/

۶. برنامه ADK را بررسی کنید

برای باز کردن ویرایشگر Cloud Shell و مشاهده مخزن کلون شده در دایرکتوری mcp/examples/launchmybakery ، روی دکمه Open Editor در Cloud Shell کلیک کنید.

a940b7eaf3c9f4b3.png

کد عامل از قبل در دایرکتوری adk_agent/ ارائه شده است. بیایید ساختار راه‌حل را بررسی کنیم: 

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

فایل‌های کلیدی در mcp_bakery_app :

  • agent.py : منطق اصلی که عامل، ابزارهای آن و مدل را تعریف می‌کند (پیش‌نمایش Gemini 3.0 Pro).
  • tools.py : شامل تعاریف ابزار سفارشی است.
  • .env : شامل پیکربندی پروژه و اطلاعات محرمانه (مانند کلیدهای API) ایجاد شده توسط اسکریپت راه‌اندازی است.

۱. مقداردهی اولیه مجموعه ابزارهای MCP:

اکنون، برای درک نحوه مقداردهی اولیه مجموعه ابزارهای MCP adk_agent/mcp_bakery_app/tools.py را در ویرایشگر باز کنید.

برای اینکه بتوانیم با BigQuery و Google Maps ارتباط برقرار کنیم، باید کلاینت‌های Model Context Protocol (MCP) را پیکربندی کنیم.

این کد با استفاده از StreamableHTTPConnectionParams اتصالات امنی را به سرورهای MCP از راه دور گوگل برقرار می‌کند. 

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
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    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
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools
  • مجموعه ابزارهای نقشه‌ها: اتصال به سرور Maps MCP را با استفاده از کلید API شما پیکربندی می‌کند.
  • مجموعه ابزارهای BigQuery: این تابع اتصال به سرور BigQuery MCP را پیکربندی می‌کند. این تابع از google.auth برای بازیابی خودکار اعتبارنامه‌های Cloud شما استفاده می‌کند، یک توکن OAuth Bearer تولید می‌کند و آن را به هدر Authorization تزریق می‌کند.

۲. تعریف عامل:

اکنون، adk_agent/mcp_bakery_app/agent.py را در ویرایشگر باز کنید تا ببینید که عامل چگونه تعریف شده است.

LlmAgent با مدل gemini-3-pro-preview مقداردهی اولیه شده است. 

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

root_agent = LlmAgent(
    model='gemini-3-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)
  • دستورالعمل‌های سیستم: به اپراتور دستورالعمل‌های خاصی برای ترکیب بینش‌های BigQuery (برای داده‌ها) و Maps (برای تحلیل موقعیت مکانی) داده می‌شود.
  • ابزارها: هر دو maps_toolset و bigquery_toolset به عامل اختصاص داده شده‌اند و به آن امکان دسترسی به قابلیت‌های هر دو سرویس را می‌دهند.

عامل با دستورالعمل‌ها و ابزارهای تعریف‌شده در مخزن مطابقت دارد. می‌توانید در دستورالعمل‌ها تغییراتی ایجاد کنید تا ببینید چگونه بر رفتار عامل تأثیر می‌گذارد.

۷. با نماینده خود چت کنید!

به ترمینال در Cloud Shell برگردید و این دستور را اجرا کنید تا به دایرکتوری adk_agent بروید: 

cd adk_agent

دستور زیر را برای شروع رابط وب ADK اجرا کنید. این دستور یک وب سرور سبک را برای میزبانی برنامه چت راه‌اندازی می‌کند: 

adk web

پس از شروع سرور، می‌توانید با کلیک بر روی URL ارائه شده برای راه‌اندازی رابط وب ADK با نماینده خود چت کنید .

با پرسیدن سوالات زیر با نماینده تعامل کنید . باید ببینید که ابزارهای مربوطه فراخوانی می‌شوند.

  1. محله را پیدا کنید (کلان): «من می‌خواهم یک نانوایی در لس‌آنجلس باز کنم. کد پستی با بالاترین امتیاز ترافیک صبحگاهی را پیدا کنید.»

5f2a48bebfc49709.png

عامل باید از ابزارهایی مانند get_table_info و execute_sql برای پرس و جو از جدول foot_traffic در BigQuery استفاده کند.

  1. اعتبارسنجی موقعیت مکانی (میکرو): «آیا می‌توانید در آن کد پستی عبارت «نانوایی‌ها» را جستجو کنید تا ببینید آیا اشباع شده است؟»

۳۲۷۹۶c9a8cefca7.png

عامل باید از ابزارهای search places در مجموعه ابزارهای Maps برای پاسخ به این سوال استفاده کند.

امتحانش کن! این نمونه سوالات را بررسی کنید تا ببینید نماینده ADK شما در عمل چگونه عمل می‌کند:

  • «من به دنبال افتتاح چهارمین شعبه نانوایی‌ام در لس‌آنجلس هستم. به محله ای با فعالیت صبحگاهی نیاز دارم. کد پستی با بالاترین امتیاز ترافیک پیاده «صبحگاهی» را پیدا کنید.»
  • «می‌توانید در آن کد پستی «نانوایی‌ها» را جستجو کنید تا ببینید اشباع شده است یا نه؟ اگر تعدادشان زیاد است، مغازه‌های «قهوه‌های مخصوص» را بررسی کنید تا بتوانم خودم را نزدیک آنها قرار دهم تا ترافیک عابر پیاده را ثبت کنم.»
  • «بسیار خب، من می‌خواهم این را به عنوان یک برند ممتاز معرفی کنم. حداکثر قیمتی که برای یک «نان خمیر ترش» در منطقه مترو لس‌آنجلس دریافت می‌شود چقدر است؟»
  • «حالا می‌خواهم یک پیش‌بینی درآمد برای دسامبر ۲۰۲۵ داشته باشم. به سابقه فروش من نگاه کنید و داده‌هایی از بهترین فروشگاه من برای «نان خمیر ترش» بگیرید. یک پیش‌بینی برای دسامبر ۲۰۲۵ انجام دهید تا مقدار فروش من را تخمین بزنید. سپس، کل درآمد پیش‌بینی‌شده را با استفاده از قیمتی کمی پایین‌تر از قیمت ویژه‌ای که پیدا کردیم (بیایید از ۱۸ دلار استفاده کنیم) محاسبه کنید.»
  • «این اجاره‌ام را پوشش می‌دهد. در آخر، بیایید تدارکات را بررسی کنیم. نزدیک‌ترین «رستوران دیپو» به منطقه پیشنهادی را پیدا کنید و مطمئن شوید که زمان رانندگی برای پر کردن مجدد روزانه کمتر از ۳۰ دقیقه باشد.»

۸. تمیز کردن

برای جلوگیری از هزینه‌های مداوم برای حساب Google Cloud خود، منابع ایجاد شده در طول این Codelab را حذف کنید.

اسکریپت پاکسازی را اجرا کنید. این اسکریپت مجموعه داده BigQuery، مخزن ذخیره‌سازی ابری و کلیدهای API ایجاد شده در طول راه‌اندازی را حذف می‌کند. 

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

۹. تبریک

ماموریت تمام شد! شما با موفقیت یک عامل اطلاعات مکانی با استفاده از کیت توسعه عامل (ADK) ساختید.

با پر کردن شکاف بین داده‌های «سازمانی» خود در BigQuery و داده‌های مکانی واقعی از Google Maps ، شما ابزاری قدرتمند ایجاد کرده‌اید که قادر به استدلال پیچیده تجاری است - همه اینها با استفاده از پروتکل Model Context (MCP) و Gemini انجام می‌شود.

کاری که شما انجام دادید:

  • زیرساخت به عنوان کد: شما با استفاده از ابزارهای Google Cloud CLI یک پشته داده تهیه کردید.
  • ادغام MCP: شما یک عامل هوش مصنوعی را به دو سرور MCP از راه دور مجزا (BigQuery و Maps) بدون نوشتن بسته‌های پیچیده API متصل کردید.
  • استدلال یکپارچه: شما یک عامل واحد ساخته‌اید که قادر است بینش‌های دو حوزه مختلف را به صورت استراتژیک ترکیب کند تا یک مشکل تجاری را حل کند.

اسناد مرجع