۱. مقدمه
در این Codelab، شما یک عامل با ADK خواهید ساخت که توسط Gemini 3.1 Pro پشتیبانی میشود. این عامل به ابزارهایی از دو سرور MCP از راه دور (میزبانی شده توسط گوگل) مجهز خواهد شد تا به طور ایمن به BigQuery برای دادههای جمعیتی، قیمتگذاری و فروش و به Google Maps برای تجزیه و تحلیل و اعتبارسنجی موقعیت مکانی در دنیای واقعی دسترسی داشته باشد.
این عامل، درخواستهای بین کاربر و سرویسهای گوگل کلود را هماهنگ میکند تا مشکلات تجاری مربوط به مجموعه دادههای فرضی نانوایی را حل کند.
کاری که انجام خواهید داد
- تنظیم دادهها: مجموعه دادههای اولیه نانوایی را در BigQuery ایجاد کنید.
- توسعه عامل: با استفاده از کیت توسعه عامل (ADK) یک عامل هوشمند بسازید.
- ادغام ابزارها: از طریق سرور MCP، عامل را به قابلیتهای BigQuery و Maps مجهز کنید.
- تحلیل بازار: برای ارزیابی روندها و اشباع بازار با نماینده تعامل کنید.
آنچه نیاز دارید
- یک مرورگر وب مانند کروم
- یک پروژه گوگل کلود با قابلیت پرداخت یا یک حساب جیمیل.
این Codelab برای توسعهدهندگان در تمام سطوح، از جمله مبتدیان، مناسب است. شما از رابط خط فرمان در Google Cloud Shell و کد پایتون برای توسعه ADK استفاده خواهید کرد. نیازی نیست که متخصص پایتون باشید، اما درک اولیه از نحوه خواندن کد به شما در درک مفاهیم کمک میکند.
۲. قبل از شروع
ایجاد یک پروژه ابری گوگل
- در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
- مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
شروع پوسته ابری
Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا میشود و ابزارهای لازم از قبل روی آن بارگذاری شدهاند.
- روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید:
- پس از اتصال به Cloud Shell، این دستور را برای تأیید احراز هویت خود در Cloud Shell اجرا کنید:
gcloud auth list
- برای تأیید اینکه پروژه شما برای استفاده با gcloud پیکربندی شده است، دستور زیر را اجرا کنید:
gcloud config get project
- تأیید کنید که پروژه مطابق انتظار است و سپس دستور زیر را برای تنظیم شناسه پروژه خود اجرا کنید:
export PROJECT_ID=$(gcloud config get project)
۳. کد را دریافت کنید
مخزن را کلون کنید
- مخزن را به محیط Cloud Shell خود کلون کنید:
git clone https://github.com/google/mcp.git
- به دایرکتوری نسخه آزمایشی بروید:
cd mcp/examples/launchmybakery
احراز هویت
برای تأیید اعتبار با حساب Google Cloud خود، دستور زیر را اجرا کنید. این برای دسترسی ADK به BigQuery لازم است.
gcloud auth application-default login
برای تکمیل فرآیند احراز هویت، دستورالعملها را دنبال کنید.
۴. پیکربندی محیط و BigQuery
اجرای اسکریپتهای راهاندازی
- اسکریپت راهاندازی محیط را اجرا کنید. این اسکریپت APIهای BigQuery و Google Maps را فعال میکند و یک فایل
.envبا شناسه پروژه و کلید API نقشههای شما ایجاد میکند.
chmod +x setup/setup_env.sh
./setup/setup_env.sh
- اسکریپت راهاندازی BigQuery را اجرا کنید. این اسکریپت ایجاد مخزن ذخیرهسازی ابری، آپلود دادهها و تأمین مجموعه دادهها و جداول BigQuery را خودکار میکند.
chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh
پس از تکمیل اسکریپت، مجموعه داده mcp_bakery باید ایجاد شده و با جداول زیر پر شود:
- جمعیتشناسی - دادههای سرشماری و ویژگیهای جمعیت بر اساس کد پستی.
- قیمتهای نانوایی - قیمتهای رقبا و جزئیات محصول برای انواع شیرینیها.
- sales_history_weekly - عملکرد فروش هفتگی (مقدار و درآمد) بر اساس فروشگاه و محصول.
- foot_traffic - امتیاز تخمینی ترافیک پیاده بر اساس کد پستی و زمان روز.
- با مراجعه به کنسول BigQuery در پروژه Google Cloud خود، از ایجاد مجموعه دادهها و جداول اطمینان حاصل کنید:
۵. نصب ADK
اکنون که زیرساخت آماده است، بیایید یک محیط مجازی پایتون ایجاد کنیم و بستههای مورد نیاز ADK را نصب کنیم.
- ایجاد یک محیط مجازی:
python3 -m venv .venv
- فعال کردن محیط مجازی:
source .venv/bin/activate
- ADK را نصب کنید:
pip install google-adk==1.28.0
- به دایرکتوری نماینده بروید:
cd adk_agent/
۶. برنامه ADK را بررسی کنید
برای باز کردن ویرایشگر Cloud Shell و مشاهده مخزن کلون شده در دایرکتوری mcp/examples/launchmybakery ، روی دکمه Open Editor در Cloud Shell کلیک کنید.
کد عامل از قبل در دایرکتوری 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.1 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.1-pro-preview مقداردهی اولیه شده است.
maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()
root_agent = LlmAgent(
model='gemini-3.1-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 --allow_origins 'regex:https://.*\.cloudshell\.dev'
پس از شروع سرور، موارد زیر را در Cloud Shell مشاهده خواهید کرد:
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
شما دو گزینه برای دسترسی به رابط کاربری ADK دارید:
گزینه ۱: روی لینک محلی کلیک کنید. روی لینک http://127.0.0.1:8000 که در ترمینال Cloud Shell شما ظاهر میشود، کلیک کنید.
گزینه ۲: استفاده از پیشنمایش وب
- روی دکمه پیشنمایش وب در گوشه سمت راست بالای Cloud Shell کلیک کنید.
- تغییر پورت را انتخاب کنید.
- عدد ۸۰۰۰ را به عنوان شماره پورت وارد کنید و روی تغییر و پیشنمایش کلیک کنید.
با پرسیدن سوالات زیر در رابط کاربری وب، با عامل تعامل کنید . باید ببینید که ابزارهای مربوطه فراخوانی میشوند.
- محله را پیدا کنید (کلان): «من میخواهم یک نانوایی در لسآنجلس باز کنم. کد پستی با بالاترین امتیاز ترافیک صبحگاهی را پیدا کنید.»
عامل باید از ابزارهایی مانند get_table_info و execute_sql برای پرس و جو از جدول foot_traffic در BigQuery استفاده کند.
- اعتبارسنجی موقعیت مکانی (میکرو): «آیا میتوانید در آن کد پستی عبارت «نانواییها» را جستجو کنید تا ببینید آیا اشباع شده است؟»
عامل باید از ابزارهای search places در مجموعه ابزار Maps برای پاسخ به این سوال استفاده کند.
امتحانش کن! این نمونه سوالات را بررسی کنید تا ببینید نماینده ADK شما در عمل چگونه عمل میکند:
- «من به دنبال افتتاح چهارمین شعبه نانواییام در لسآنجلس هستم. به محله ای با فعالیت صبحگاهی نیاز دارم. کد پستی با بالاترین امتیاز ترافیک پیاده «صبحگاهی» را پیدا کنید.»
- «میتوانید در آن کد پستی «نانواییها» را جستجو کنید تا ببینید اشباع شده است یا نه؟ اگر تعدادشان زیاد است، مغازههای «قهوههای مخصوص» را بررسی کنید تا بتوانم خودم را نزدیک آنها قرار دهم تا بتوانم رفت و آمد مردم را ثبت کنم.»
- «بسیار خب، من میخواهم این را به عنوان یک برند ممتاز معرفی کنم. حداکثر قیمتی که برای یک «نان خمیر ترش» در منطقه مترو لسآنجلس دریافت میشود چقدر است؟»
- «حالا میخواهم یک پیشبینی درآمد برای دسامبر ۲۰۲۵ داشته باشم. به سابقه فروش من نگاه کنید و دادههایی از بهترین فروشگاه من برای «نان خمیر ترش» بگیرید. یک پیشبینی برای دسامبر ۲۰۲۵ انجام دهید تا مقدار فروش من را تخمین بزنید. سپس، کل درآمد پیشبینیشده را با استفاده از قیمتی کمی پایینتر از قیمت ویژهای که پیدا کردیم (بیایید از ۱۸ دلار استفاده کنیم) محاسبه کنید.»
- «این اجارهام را پوشش میدهد. در آخر، بیایید تدارکات را بررسی کنیم. نزدیکترین «رستوران دیپو» به منطقه پیشنهادی را پیدا کنید و مطمئن شوید که زمان رانندگی برای پر کردن مجدد روزانه کمتر از 30 دقیقه باشد.»
وقتی آزمایش عامل خود را تمام کردید، میتوانید با فشار دادن Ctrl+C در ترمینال Cloud Shell خود، رابط وب 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 متصل کردید.
- استدلال یکپارچه: شما یک عامل واحد ساختهاید که قادر است بینشهای دو حوزه مختلف را به صورت استراتژیک ترکیب کند تا یک مشکل تجاری را حل کند.