جعبه ابزار MCP برای پایگاه های داده: در دسترس قرار دادن مجموعه داده های BigQuery برای مشتریان MCP

۱. مقدمه

در این آزمایشگاه کد، شما از جعبه ابزار MCP برای پایگاه‌های داده استفاده خواهید کرد تا مجموعه داده‌های BigQuery خود را در دسترس قرار دهید.

از طریق codelab، شما یک رویکرد گام به گام به شرح زیر را به کار خواهید گرفت:

1. یک مجموعه داده خاص BigQuery ("یادداشت‌های انتشار Google Cloud") را از برنامه مجموعه داده‌های عمومی BigQuery شناسایی کنید.
2. راه‌اندازی جعبه ابزار MCP برای پایگاه‌های داده، که به مجموعه داده BigQuery متصل می‌شود.
3. با استفاده از کیت توسعه عامل (ADK) یک عامل توسعه دهید که از جعبه ابزار MCP برای پاسخ به سؤالات کاربر در مورد یادداشت‌های انتشار Google Cloud استفاده کند.

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

• جعبه ابزار MCP را برای پایگاه‌های داده راه‌اندازی کنید تا یادداشت‌های انتشار Google Cloud، یک مجموعه داده عمومی BigQuery، به عنوان یک رابط MCP برای سایر کلاینت‌های MCP (IDEها، ابزارها و غیره) در دسترس قرار گیرد.

آنچه یاد خواهید گرفت

• مجموعه داده‌های عمومی BigQuery را بررسی کنید و یک مجموعه داده خاص را انتخاب کنید.
• جعبه ابزار MCP برای پایگاه‌های داده را برای مجموعه داده عمومی BigQuery که می‌خواهیم در دسترس مشتریان MCP قرار دهیم، راه‌اندازی کنید.
• طراحی و توسعه یک عامل با استفاده از کیت توسعه عامل (ADK) برای پاسخ به سوالات کاربران.
• جعبه ابزار Agent و MCP برای پایگاه‌های داده را در محیط محلی آزمایش کنید.

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

• مرورگر وب کروم.
• یک محیط توسعه محلی پایتون.

۲. قبل از شروع

ایجاد یک پروژه

1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
3. شما از Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا می‌شود و bq از قبل روی آن بارگذاری شده است، استفاده خواهید کرد. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.

4. پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که آیا از قبل احراز هویت شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است یا خیر:

gcloud auth list

5. دستور زیر را در Cloud Shell اجرا کنید تا تأیید شود که دستور gcloud از پروژه شما اطلاع دارد.

gcloud config list project

6. اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:

gcloud config set project <YOUR_PROJECT_ID>

7. API های مورد نیاز را از طریق دستور زیر فعال کنید. این کار ممکن است چند دقیقه طول بکشد، پس لطفاً صبور باشید.

gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudfunctions.googleapis.com \
                       aiplatform.googleapis.com \
                       sqladmin.googleapis.com \
                       compute.googleapis.com 

در صورت اجرای موفقیت‌آمیز دستور، باید پیامی مشابه آنچه در زیر نشان داده شده است را مشاهده کنید:

Operation "operations/..." finished successfully.

جایگزین دستور gcloud از طریق کنسول با جستجوی هر محصول یا استفاده از این لینک است.

اگر هر API از قلم افتاده باشد، می‌توانید همیشه آن را در طول پیاده‌سازی فعال کنید.

برای دستورات و نحوه‌ی استفاده از gcloud به مستندات مراجعه کنید.

۳. مجموعه داده‌های یادداشت‌های انتشار گوگل و کلاینت‌های MCP

اول از همه، بیایید نگاهی به یادداشت‌های انتشار گوگل کلود بیندازیم که مرتباً در صفحه وب رسمی یادداشت‌های انتشار گوگل کلود به‌روزرسانی می‌شوند، تصویری از آن در زیر نشان داده شده است:

شما می‌توانید در آدرس فید مشترک شوید، اما چه می‌شود اگر بتوانیم به سادگی در چت با نمایندگان خود در مورد این یادداشت‌های انتشار سوال کنیم. شاید یک سوال ساده مانند «یادداشت‌های انتشار Google Cloud من را به‌روزرسانی کنید».

۴. جعبه ابزار MCP برای پایگاه‌های داده

جعبه ابزار MCP برای پایگاه‌های داده، یک سرور MCP متن‌باز برای پایگاه‌های داده است که با در نظر گرفتن کیفیت تولید و سطح سازمانی طراحی شده است. این جعبه ابزار به شما این امکان را می‌دهد که با مدیریت پیچیدگی‌هایی مانند ادغام اتصال، احراز هویت و موارد دیگر، ابزارها را آسان‌تر، سریع‌تر و ایمن‌تر توسعه دهید.

جعبه ابزار به شما کمک می‌کند تا ابزارهای Gen AI بسازید که به نمایندگان شما اجازه می‌دهد به داده‌های موجود در پایگاه داده شما دسترسی داشته باشند. جعبه ابزار موارد زیر را ارائه می‌دهد:

• توسعه ساده: ابزارها را در کمتر از 10 خط کد با عامل خود ادغام کنید، از ابزارها بین چندین عامل یا چارچوب استفاده مجدد کنید و نسخه‌های جدید ابزارها را آسان‌تر مستقر کنید.
• عملکرد بهتر: بهترین شیوه‌ها مانند ادغام اتصال، احراز هویت و موارد دیگر.
• امنیت پیشرفته: احراز هویت یکپارچه برای دسترسی امن‌تر به داده‌های شما
• قابلیت مشاهده از ابتدا تا انتها: معیارهای آماده و ردیابی با پشتیبانی داخلی از OpenTelemetry.
• جعبه ابزار، اتصال پایگاه‌های داده به هر دستیار هوش مصنوعی سازگار با MCP، حتی آن‌هایی که در IDE شما هستند را آسان می‌کند.

جعبه ابزار بین چارچوب هماهنگ‌سازی برنامه شما و پایگاه داده شما قرار می‌گیرد و یک صفحه کنترلی را فراهم می‌کند که برای تغییر، توزیع یا فراخوانی ابزارها استفاده می‌شود. این جعبه ابزار با فراهم کردن یک مکان متمرکز برای ذخیره و به‌روزرسانی ابزارها، مدیریت ابزارهای شما را ساده می‌کند و به شما امکان می‌دهد ابزارها را بین عامل‌ها و برنامه‌ها به اشتراک بگذارید و آن ابزارها را بدون نیاز به استقرار مجدد برنامه خود، به‌روزرسانی کنید.

خلاصه به زبان ساده:

1. جعبه ابزار MCP به صورت یک تصویر باینری و کانتینری در دسترس است یا می‌توانید آن را از منبع بسازید.
2. این مجموعه ابزارهایی را که شما از طریق فایل tools.yaml پیکربندی می‌کنید، در معرض نمایش قرار می‌دهد. می‌توان تصور کرد که این ابزارها به منابع داده شما متصل می‌شوند. می‌توانید منابع داده مختلفی را که پشتیبانی می‌کند، مشاهده کنید: AlloyDB، BigQuery و غیره.
3. از آنجایی که این جعبه ابزار اکنون از MCP پشتیبانی می‌کند، شما به طور خودکار یک نقطه پایانی سرور MCP دارید که می‌تواند توسط Agentها (IDEها) مورد استفاده قرار گیرد یا می‌توانید از آنها هنگام توسعه برنامه‌های Agent خود با استفاده از چارچوب‌های مختلف مانند Agent Development Kit (ADK) استفاده کنید.

تمرکز ما در این پست وبلاگ بر روی حوزه‌های برجسته زیر خواهد بود:

به طور خلاصه، ما قصد داریم پیکربندی را در جعبه ابزار MCP برای پایگاه‌های داده ایجاد کنیم که بداند چگونه به مجموعه داده‌های BigQuery ما متصل شود. سپس با استفاده از کیت توسعه عامل (ADK) یک عامل ایجاد خواهیم کرد که با نقطه پایانی جعبه ابزار MCP ادغام می‌شود و به ما امکان می‌دهد پرس‌وجوهای طبیعی را برای پرسیدن در مورد مجموعه داده‌های خود ارسال کنیم. آن را به عنوان یک برنامه عامل در نظر بگیرید که در حال توسعه آن هستید و می‌داند چگونه با مجموعه داده‌های BigQuery شما صحبت کند و برخی از پرس‌وجوها را اجرا می‌کند.

۵. مجموعه داده BigQuery برای یادداشت‌های انتشار Google Cloud

برنامه مجموعه داده‌های عمومی گوگل کلود (Google Cloud Public Dataset Program) برنامه‌ای است که طیف وسیعی از مجموعه داده‌ها را برای برنامه‌های شما در دسترس قرار می‌دهد. یکی از این مجموعه داده‌ها، پایگاه داده یادداشت‌های انتشار گوگل کلود (Google Cloud Release Notes) است. این مجموعه داده همان اطلاعات صفحه وب رسمی یادداشت‌های انتشار گوگل کلود را در اختیار شما قرار می‌دهد و به عنوان یک مجموعه داده قابل پرس‌وجو برای عموم در دسترس است.

به عنوان یک آزمایش، من به سادگی با اجرای یک پرس و جوی ساده که در زیر نشان داده شده است، مجموعه داده‌ها را اعتبارسنجی می‌کنم:

SELECT
       product_name,description,published_at
     FROM
       `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
     WHERE
       DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
     GROUP BY product_name,description,published_at
     ORDER BY published_at DESC

این دستور لیستی از رکوردهای مجموعه داده‌های Release Notes که در ۷ روز گذشته منتشر شده‌اند را به من نشان می‌دهد.

این را با هر مجموعه داده دلخواه و پرس‌وجوها و پارامترهای مربوطه که می‌خواهید جایگزین کنید. تنها کاری که اکنون باید انجام دهیم این است که این را به عنوان یک منبع داده و ابزار در جعبه ابزار MCP برای پایگاه‌های داده تنظیم کنیم. بیایید ببینیم چگونه این کار را انجام دهیم.

۶. نصب جعبه ابزار MCP برای پایگاه‌های داده

یک ترمینال در دستگاه محلی خود باز کنید و پوشه‌ای با نام mcp-toolbox ایجاد کنید.

mkdir mcp-toolbox

از طریق دستور زیر به پوشه mcp-toolbox بروید:

cd mcp-toolbox

نسخه باینری جعبه ابزار MCP برای پایگاه‌های داده را از طریق اسکریپت زیر نصب کنید. دستور زیر برای لینوکس است، اما اگر از مک یا ویندوز استفاده می‌کنید، مطمئن شوید که فایل باینری صحیح را دانلود می‌کنید. صفحه انتشارها را برای سیستم عامل و معماری خود بررسی کنید و فایل باینری صحیح را دانلود کنید.

export VERSION=1.13.1
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

اکنون نسخه باینری جعبه ابزار آماده استفاده است. مرحله بعدی پیکربندی جعبه ابزار با منابع داده و سایر تنظیمات است.

۷. پیکربندی جعبه ابزار MCP برای پایگاه‌های داده

حالا باید مجموعه داده و ابزارهای BigQuery خود را در فایل tools.yaml که برای جعبه ابزار MCP برای پایگاه داده مورد نیاز است، تعریف کنیم. فایل tools.yaml روش اصلی برای پیکربندی جعبه ابزار است.

فایلی با نام tools.yaml در همان پوشه یعنی mcp-toolbox ایجاد کنید که محتوای آن در زیر نشان داده شده است.

شما می‌توانید از ویرایشگر nano که در Cloud Shell موجود است استفاده کنید. دستور nano به شرح زیر است: " nano tools.yaml ".

به یاد داشته باشید که مقدار YOUR_PROJECT_ID را با شناسه پروژه Google Cloud خود جایگزین کنید.

kind: source
name: my-bq-source
type: bigquery
project: YOUR_PROJECT_ID
---
kind: tool
name: search_release_notes_bq
type: bigquery-sql
source: my-bq-source
description: Use this tool to get information on Google Cloud Release Notes.
statement: |
    SELECT
     product_name,description,published_at
    FROM
      `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
    WHERE
     DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
    GROUP BY product_name,description,published_at
    ORDER BY published_at DESC;
---
kind: toolset
name: my_bq_toolset
tools:
  - search_release_notes_bq

بیایید فایل را به طور خلاصه درک کنیم:

1. منابع، منابع داده مختلف شما را نشان می‌دهند که یک ابزار می‌تواند با آنها تعامل داشته باشد. یک منبع، منبع داده‌ای را نشان می‌دهد که یک ابزار می‌تواند با آن تعامل داشته باشد. می‌توانید منابع را به عنوان یک نقشه در بخش منابع فایل tools.yaml خود تعریف کنید. معمولاً، پیکربندی منبع شامل هرگونه اطلاعات مورد نیاز برای اتصال و تعامل با پایگاه داده خواهد بود. در مورد ما، ما یک منبع BigQuery به my-bq-source تعریف کرده‌ایم و شما باید شناسه پروژه Google Cloud خود را ارائه دهید. برای اطلاعات بیشتر، به مرجع منابع مراجعه کنید.
2. ابزارها اقداماتی را که یک عامل می‌تواند انجام دهد تعریف می‌کنند - مانند خواندن و نوشتن در یک منبع. یک ابزار نشان دهنده عملی است که عامل شما می‌تواند انجام دهد، مانند اجرای یک دستور SQL. می‌توانید ابزارها را به عنوان یک نقشه در بخش ابزارهای فایل tools.yaml خود تعریف کنید. معمولاً یک ابزار برای اقدام به یک منبع نیاز دارد. در مورد ما، ما یک ابزار واحد به نام search_release_notes_bq تعریف می‌کنیم. این به منبع BigQuery my-bq-source که در مرحله اول تعریف کردیم، اشاره دارد. همچنین شامل عبارت و دستورالعملی است که توسط کلاینت‌های عامل هوش مصنوعی استفاده خواهد شد. برای اطلاعات بیشتر، به مرجع ابزارها مراجعه کنید.
3. در نهایت، Toolset را داریم که به شما امکان می‌دهد گروه‌هایی از ابزارها را که می‌خواهید بتوانید با هم بارگذاری کنید، تعریف کنید. این می‌تواند برای تعریف گروه‌های مختلف بر اساس عامل یا برنامه مفید باشد. در مورد ما، یک تعریف toolset داریم که در حال حاضر فقط یک ابزار موجود search_release_notes_bq را که خودمان تعریف کرده‌ایم، تعریف کرده‌ایم. می‌توانید بیش از یک toolset داشته باشید که ترکیبی از ابزارهای مختلف باشد.

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

جزئیات پیکربندی بیشتر را در پیکربندی منبع داده BigQuery در جعبه ابزار MCP برای پایگاه‌های داده بررسی کنید.

۸. آزمایش جعبه ابزار MCP برای پایگاه‌های داده

ما Toolbox را به همراه فایل tools.yaml در پوشه mcp-toolbox دانلود و پیکربندی کرده‌ایم. ابتدا آن را به صورت محلی اجرا می‌کنیم.

دستور زیر را اجرا کنید:

./toolbox --config "tools.yaml"

در صورت اجرای موفقیت‌آمیز، باید شاهد راه‌اندازی سرور با خروجی نمونه‌ای مشابه نمونه زیر باشید:

2026-09-26T12:58:14.590825+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6" 
2026-09-26T12:58:14.59319+05:30 INFO "Initialized 1 sources: my-bq-source" 
2026-09-26T12:58:14.593198+05:30 INFO "Initialized 0 authServices: " 
2026-09-26T12:58:14.593201+05:30 INFO "Initialized 0 embeddingModels: " 
2026-09-26T12:58:14.59323+05:30 INFO "Initialized 1 tools: search_release_notes_bq" 
2026-09-26T12:58:14.593235+05:30 INFO "Initialized 0 prompts: " 
2026-09-26T12:58:14.593236+05:30 INFO "Initialized 0 resources: " 
2026-09-26T12:58:14.593238+05:30 INFO "Initialized 0 resource templates: " 
2026-09-26T12:58:14.593244+05:30 INFO "Initialized 2 groups: my_bq_toolset, default" 
2026-09-26T12:58:14.593259+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses." 
2026-09-26T12:58:14.593266+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains." 
2026-09-26T12:58:14.593365+05:30 INFO "Server ready to serve!"  

سرور جعبه ابزار MCP به طور پیش‌فرض روی پورت 5000 اجرا می‌شود. اگر متوجه شدید که پورت 5000 از قبل در حال استفاده است، می‌توانید طبق دستور زیر از پورت دیگری (مثلاً 7000 ) استفاده کنید. لطفاً در دستورات بعدی به جای پورت 5000 از 7000 استفاده کنید.

./toolbox --config "tools.yaml" --port 7000

بیایید از Cloud Shell برای آزمایش این موضوع استفاده کنیم.

مطابق شکل زیر، روی پیش‌نمایش وب در Cloud Shell کلیک کنید:

روی Change port کلیک کنید و پورت را مانند تصویر زیر روی ۵۰۰۰ تنظیم کنید و روی Change and Preview کلیک کنید.

این باید خروجی زیر را به همراه داشته باشد:

ابزارها را از طریق جعبه ابزار MCP برای رابط کاربری پایگاه‌های داده آزمایش کنید

جعبه ابزار یک رابط بصری ( Toolbox UI ) فراهم می‌کند تا با تغییر پارامترها، مدیریت هدرها و اجرای فراخوانی‌ها، همه در یک رابط کاربری وب ساده، مستقیماً با ابزارها تعامل داشته باشید.

اگر می‌خواهید این را امتحان کنید، می‌توانید دستور قبلی که برای راه‌اندازی Toolbox Server با گزینه --ui استفاده کردیم را اجرا کنید.

برای انجام این کار، نسخه قبلی MCP Toolbox for Databases Server را که ممکن است در حال اجرا داشته باشید، خاموش کنید و دستور زیر را اجرا کنید:

./toolbox --tools-file "tools.yaml" --ui

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

Flag --tools-file has been deprecated, please use --config instead
2026-09-26T12:59:21.662102+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6" 
2026-09-26T12:59:21.663076+05:30 INFO "Initialized 1 sources: my-bq-source" 
2026-09-26T12:59:21.663084+05:30 INFO "Initialized 0 authServices: " 
2026-09-26T12:59:21.663087+05:30 INFO "Initialized 0 embeddingModels: " 
2026-09-26T12:59:21.663101+05:30 INFO "Initialized 1 tools: search_release_notes_bq" 
2026-09-26T12:59:21.663104+05:30 INFO "Initialized 0 prompts: " 
2026-09-26T12:59:21.663107+05:30 INFO "Initialized 0 resources: " 
2026-09-26T12:59:21.663109+05:30 INFO "Initialized 0 resource templates: " 
2026-09-26T12:59:21.663116+05:30 INFO "Initialized 2 groups: default, my_bq_toolset" 
2026-09-26T12:59:21.663124+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses." 
2026-09-26T12:59:21.663132+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains." 
2026-09-26T12:59:21.663242+05:30 INFO "Server ready to serve!" 
2026-09-26T12:59:21.663249+05:30 INFO "Toolbox UI is up and running at: http://127.0.0.1:5000/ui" 

روی آدرس رابط کاربری کلیک کنید و مطمئن شوید که /ui در انتهای آدرس وجود دارد. این کار رابط کاربری را مانند تصویر زیر نمایش می‌دهد:

برای مشاهده ابزارهای پیکربندی‌شده، روی گزینه Tools در سمت چپ کلیک کنید و در مورد ما، فقط باید یکی از آنها یعنی search_release_notes_bq باشد، همانطور که در زیر نشان داده شده است:

به سادگی روی ابزارها ( search_release_notes_bq ) کلیک کنید و باید صفحه‌ای برای آزمایش ابزار برای شما باز شود. از آنجایی که هیچ پارامتری برای ارائه وجود ندارد، می‌توانید به سادگی روی Run Tool کلیک کنید تا نتیجه را ببینید. یک نمونه اجرا در زیر نشان داده شده است:

۹. نوشتن عامل ما با کیت توسعه عامل (ADK)

کیت توسعه عامل (ADK) را نصب کنید

یک تب ترمینال جدید در Cloud Shell باز کنید و پوشه‌ای به نام my-agents به صورت زیر ایجاد کنید. به پوشه my-agents نیز بروید.

mkdir my-agents
cd my-agents

حالا، بیایید یک محیط مجازی پایتون با استفاده از venv به صورت زیر ایجاد کنیم:

python -m venv .venv

محیط مجازی را به صورت زیر فعال کنید:

source .venv/bin/activate

بسته‌های ADK و MCP Toolbox for Databases را به همراه وابستگی langchain به شرح زیر نصب کنید:

pip install google-adk toolbox-core

اکنون می‌توانید ابزار adk را به صورت زیر فراخوانی کنید.

adk

لیستی از دستورات را به شما نشان می‌دهد.

$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
  Agent Development Kit CLI tools.
Options:
  --version  Show the version and exit.
  --help     Show this message and exit.
Commands:
  api_server   Starts a FastAPI server for agents.
  conformance  Conformance testing tools for ADK.
  create       Creates a new app in the current folder with prepopulated...
  deploy       Deploys agent to hosted environments.
  eval         Evaluates an agent given the eval sets.
  eval_set     Manage Eval Sets.
  migrate      ADK migration commands.
  optimize     Optimizes the root agent instructions using the GEPA...
  run          Runs an agent.
  telemetry    Manage telemetry settings.
  test         Runs pytest on agent test JSON files under the specified...
  web          Starts a FastAPI server with Web UI for agents.

ایجاد اولین برنامه عامل ما

اکنون می‌خواهیم از adk برای ایجاد یک چارچوب برای برنامه Google Cloud Release Notes Agent از طریق دستور adk create با نام برنامه ** (gcp_releasenotes_agent_app) ** مطابق شکل زیر استفاده کنیم.

adk create gcp_releasenotes_agent_app

مراحل زیر را دنبال کنید و موارد زیر را انتخاب کنید:

• برای انتخاب مدل عامل ریشه، مدل gemini-3.8-flash را انتخاب کنید.
• برای بک‌اند، Vertex AI را انتخاب کنید.
• شناسه پیش‌فرض پروژه گوگل شما نمایش داده خواهد شد. آن را انتخاب کنید.
• منطقه فعلی پروژه ابری گوگل نمایش داده خواهد شد. مطمئن شوید که global را تایپ می‌کنید.

Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2

1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [YOUR_PROJECT_ID]: 
Enter Google Cloud region [us-central1]: global
Agent created in /Users/romin/my-agents/gcp_releasenotes_agent_app:
- .env
- .gitignore
- __init__.py
- agent.py

پوشه‌ای را که در آن یک الگوی پیش‌فرض و فایل‌های مورد نیاز برای Agent ایجاد شده‌اند، مشاهده کنید.

اولین مورد، فایل .env است که محتوای آن در زیر نشان داده شده است:

GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

این مقادیر نشان می‌دهند که ما از Gemini از طریق Gemini Enterprise به همراه مقادیر مربوط به شناسه پروژه Google Cloud و مکان استفاده خواهیم کرد.

سپس فایل __init__.py را داریم که پوشه را به عنوان یک ماژول علامت‌گذاری می‌کند و یک دستور واحد دارد که عامل را از فایل agent.py وارد می‌کند.

from . import agent

در نهایت، بیایید نگاهی به فایل agent.py بیندازیم. محتویات آن در زیر نشان داده شده است:

from google.adk.agents.llm_agent import Agent
root_agent = Agent(
    model='gemini-3.8-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

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

به طور خاص، یک LLMAgent که معمولاً با نام مستعار Agent شناخته می‌شود، از مدل‌های زبان بزرگ (LLM) به عنوان موتور اصلی خود برای درک زبان طبیعی، استدلال، برنامه‌ریزی، تولید پاسخ‌ها و تصمیم‌گیری پویا در مورد نحوه ادامه یا استفاده از ابزارها استفاده می‌کند و آنها را برای وظایف انعطاف‌پذیر و زبان‌محور ایده‌آل می‌سازد. برای کسب اطلاعات بیشتر در مورد LLM Agents به اینجا مراجعه کنید.

این کار، چارچوب ما برای تولید یک عامل اولیه با استفاده از کیت توسعه عامل (ADK) را تکمیل می‌کند. اکنون می‌خواهیم عامل خود را به جعبه ابزار MCP متصل کنیم تا بتواند از آن ابزار برای پاسخ به سؤالات کاربر استفاده کند (در این مورد، یادداشت‌های انتشار Google Cloud خواهد بود).

۱۰. اتصال عامل ما به ابزارها

اکنون قصد داریم این عامل را به ابزارها متصل کنیم. در زمینه ADK، یک ابزار نشان‌دهنده یک قابلیت خاص ارائه شده به یک عامل هوش مصنوعی است که آن را قادر می‌سازد فراتر از توانایی‌های اصلی تولید متن و استدلال، اقداماتی را انجام دهد و با جهان تعامل داشته باشد.

در مورد ما، اکنون قصد داریم Agent خود را به ابزارهایی که در جعبه ابزار MCP برای پایگاه‌های داده پیکربندی کرده‌ایم، مجهز کنیم.

فایل agent.py را با کد زیر تغییر دهید. توجه داشته باشید که ما در کد از پورت پیش‌فرض ۵۰۰۰ استفاده می‌کنیم، اما اگر از شماره پورت دیگری استفاده می‌کنید، لطفاً از آن استفاده کنید.

from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load all the tools
tools = toolbox.load_toolset('my_bq_toolset')
root_agent = Agent(
    name="gcp_releasenotes_agent",
    model="gemini-3.8-flash",
    description=(
        "Agent to answer questions about Google Cloud Release notes."
    ),
    instruction=(
        "You are a helpful agent who can answer user questions about the Google Cloud Release notes. Use the tools to answer the question"
    ),
    tools=tools,
)

اکنون می‌توانیم عاملی را که داده‌های واقعی را از مجموعه داده‌های BigQuery ما که با جعبه ابزار MCP برای پایگاه‌های داده پیکربندی شده است، واکشی می‌کند، آزمایش کنیم.

برای انجام این کار، دنباله زیر را دنبال کنید:

در یکی از ترمینال‌های Cloud Shell، جعبه ابزار MCP برای پایگاه‌های داده را اجرا کنید. همانطور که قبلاً آزمایش کردیم، ممکن است از قبل آن را به صورت محلی روی پورت ۵۰۰۰ اجرا کرده باشید. در غیر این صورت، دستور زیر را (از پوشه mcp-toolbox ) برای شروع سرور اجرا کنید:

./toolbox --config "tools.yaml"

در حالت ایده‌آل، باید خروجی‌ای ببینید که نشان می‌دهد سرور توانسته به منابع داده ما متصل شود و مجموعه ابزارها و ابزارها را بارگذاری کرده است.

پس از شروع موفقیت‌آمیز سرور MCP، در یک ترمینال دیگر، Agent را از طریق دستور adk run (از پوشه my-agents ) که در زیر نشان داده شده است، اجرا کنید. در صورت تمایل می‌توانید از دستور adk web نیز استفاده کنید.

$ adk run gcp_releasenotes_agent_app/
Running agent gcp_releasenotes_agent, type exit to exit.
[user]: Hello
[gcp_releasenotes_agent]: Hello! I am your Google Cloud Release Notes assistant. How can I help you today? Feel free to ask about recent updates, feature releases, deprecations, or announcements across Google Cloud products.
[user]: get me the google cloud release notes
[gcp_releasenotes_agent]: Here are the latest highlights from the Google Cloud Release Notes:
---

### **AI & Machine Learning**
* **Gemini Enterprise**: 
  * **Gemini 3.8 Flash** is now Generally Available (GA) and enabled by default in `global`, `us`, and `eu` regions.
* **Gemini Enterprise Agent Platform**: 
  * **Gemini 3.8 Live** is now GA, bringing improved voice quality, model reliability, and agent orchestration.
  * **Meta's Muse Spark 1.3** is in Preview (reasoning model with tool calling, MCP support, and 1M context window).
* **CX Agent Studio**: 
  * **Agent as a tool** is now GA.
  * Added **Composite models** for enterprise voice agents.
  * Introduced **Supervisor agents** to monitor active agent performance.
  * Added **Agent-to-agent (A2A) protocol tools** and integrations for WhatsApp, Instagram, and SecureCo.
* **Model Armor**: Prompt injection, jailbreak detection, and Responsible AI filters are now supported in Melbourne (`australia-southeast2`).
---

### **Compute & Infrastructure**
* **Compute Engine**: Standard snapshots deleted accidentally or maliciously are now retained in the **Recycle Bin for 3 days** before permanent erasure (Preview).
* **Confidential VM**: Support for **Intel TDX on `c4-standard-*`** machine types is now GA.
* **SAP on Google Cloud**: Certified the **X5 series** of memory-optimized bare metal machine types (Intel Granite Rapids CPU platform) for SAP HANA and SAP NetWeaver.
* **Cloud Workstations**: Cloud Workstations is now a covered product under the Google Cloud HIPAA BAA.
---

### **Containers & Networking**
* **Google Kubernetes Engine (GKE)**: **GKE ambient networking** is now in Preview (allowlist), providing a sidecarless, Layer 4 service mesh using Gateway API on GKE Dataplane V2.
* **Cloud Service Mesh**: Maintenance and security patch releases available for in-cluster versions `1.30.4-asm.14`, `1.29.7-asm.18`, and `1.28.10-asm.40`.
---

### **Data Analytics & Databases**
* **BigQuery**: In BigQuery Studio, the query editor results table now freezes row numbers on the left during horizontal scrolling (GA).
* **Memorystore for Valkey**: Valkey version 9.1 is now GA.
* **Looker**: Deployment of version 26.16; includes a long-polling concurrency guard, tile-level filter controls (Preview), and an OAuth authorization warning dialog.
* **Data Studio / Looker Studio**: 
  * Added private IP connectivity for Cloud SQL PostgreSQL databases.
..
..
..

توجه داشته باشید که عامل از ابزاری که ما در جعبه ابزار MCP برای پایگاه‌های داده ( search_release_notes_bq ) پیکربندی کرده‌ایم استفاده می‌کند و داده‌ها را از مجموعه داده BigQuery بازیابی کرده و پاسخ را بر اساس آن قالب‌بندی می‌کند.

۱۱. تبریک

تبریک می‌گوییم، شما با موفقیت جعبه ابزار MCP را برای پایگاه‌های داده پیکربندی کردید و یک مجموعه داده BigQuery را برای دسترسی در کلاینت‌های MCP پیکربندی نمودید.

اسناد مرجع

• جعبه ابزار MCP برای پایگاه‌های داده
• مجموعه داده‌های عمومی BigQuery