جعبه ابزار 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. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

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

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>

برای دستورات و نحوه‌ی استفاده از 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=0.22.0
curl -O https://storage.googleapis.com/genai-toolbox/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 خود جایگزین کنید.

sources:
 my-bq-source:
   kind: bigquery
   project: YOUR_PROJECT_ID

tools:
 search_release_notes_bq:
   kind: bigquery-sql
   source: my-bq-source
   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
   description: |
    Use this tool to get information on Google Cloud Release Notes.

toolsets:
 my_bq_toolset:
   - 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 داشته باشید که ترکیبی از ابزارهای مختلف باشد.

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

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

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

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

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

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

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

2025-12-09T08:27:02.777619+05:30 INFO "Initialized 1 sources: my-bq-source" 
2025-12-09T08:27:02.777695+05:30 INFO "Initialized 0 authServices: " 
2025-12-09T08:27:02.777707+05:30 INFO "Initialized 1 tools: search_release_notes_bq" 
2025-12-09T08:27:02.777716+05:30 INFO "Initialized 2 toolsets: my_bq_toolset, default" 
2025-12-09T08:27:02.777719+05:30 INFO "Initialized 0 prompts: " 
2025-12-09T08:27:02.777723+05:30 INFO "Initialized 1 promptsets: default" 
2025-12-09T08:27:02.77773+05:30 WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag to prevent DNS rebinding attacks" 
2025-12-09T08:27:02.777839+05:30 INFO "Server ready to serve!"

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

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

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

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

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

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

در آدرس اینترنتی مرورگر، عبارت زیر را به انتهای آدرس اینترنتی اضافه کنید:

/api/toolset

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

{
  "serverVersion": "0.22.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
  "tools": {
    "search_release_notes_bq": {
      "description": "Use this tool to get information on Google Cloud Release Notes.\n",
      "parameters": [],
      "authRequired": []
    }
  }
}

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

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

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

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

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

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

2025-12-09T08:28:07.479989+05:30 INFO "Initialized 1 sources: my-bq-source" 
2025-12-09T08:28:07.480065+05:30 INFO "Initialized 0 authServices: " 
2025-12-09T08:28:07.480079+05:30 INFO "Initialized 1 tools: search_release_notes_bq" 
2025-12-09T08:28:07.480087+05:30 INFO "Initialized 2 toolsets: my_bq_toolset, default" 
2025-12-09T08:28:07.48009+05:30 INFO "Initialized 0 prompts: " 
2025-12-09T08:28:07.480094+05:30 INFO "Initialized 1 promptsets: default" 
2025-12-09T08:28:07.4801+05:30 WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag to prevent DNS rebinding attacks" 
2025-12-09T08:28:07.480214+05:30 INFO "Server ready to serve!" 
2025-12-09T08:28:07.480218+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 کلیک کنید تا نتیجه را ببینید. یک نمونه اجرا در زیر نشان داده شده است:

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

۹. نوشتن عامل ما با کیت توسعه عامل (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:
  --help  Show this message and exit.

Commands:
  api_server  Starts a FastAPI server for agents.
  create      Creates a new app in the current folder with prepopulated agent template.
  deploy      Deploys agent to hosted environments.
  eval        Evaluates an agent given the eval sets.
  run         Runs an interactive CLI for a certain agent.
  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

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

• مدل جمینی برای انتخاب مدل برای عامل ریشه.
• برای بک‌اند، Vertex AI را انتخاب کنید.
• شناسه و منطقه پیش‌فرض پروژه گوگل شما نمایش داده خواهد شد. گزینه پیش‌فرض را انتخاب کنید.

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

Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 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_GOOGLE_PROJECT_ID]: 
Enter Google Cloud region [us-central1]: 

Agent created in ../my-agents/gcp-releasenotes-agent-app:
- .env
- __init__.py
- agent.py

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

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

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

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

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

from . import agent

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

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-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-2.0-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 --tools_file "tools.yaml"

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

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

$ adk run gcp-releasenotes-agent-app/

Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent gcp_releasenotes_agent, type exit to exit.

[user]: get me the google cloud release notes


[gcp_releasenotes_agent]: Here are the Google Cloud Release Notes.

Google SecOps SOAR: Release 6.3.49 is being rolled out to the first phase of regions. This release contains internal and customer bug fixes. Published: 2025-06-14

Compute Engine: Dynamic NICs let you add or remove network interfaces to or from an instance without having to restart or recreate the instance. You can also use Dynamic NICs when you need more network interfaces. The maximum number of vNICs for most machine types in Google Cloud is 10; however, you can configure up to 16 total interfaces by using Dynamic NICs. Published: 2025-06-13

Compute Engine: General purpose C4D machine types, powered by the fifth generation AMD EPYC processors (Turin) and Google Titanium, are generally available. Published: 2025-06-13

Google Agentspace: Google Agentspace Enterprise: App-level feature management. As an Agentspace administrator, you can choose to turn the following features on or off for your end users in the web app: Agents gallery, Prompt gallery, No-code agent, NotebookLM Enterprise. Published: 2025-06-13

Cloud Load Balancing: Cloud Load Balancing supports load balancing to multi-NIC instances that use Dynamic NICs. This capability is in Preview. Published: 2025-06-13

Virtual Private Cloud: Dynamic Network Interfaces (NICs) are available in Preview. Dynamic NICs let you update an instance to add or remove network interfaces without having to restart or recreate the instance. Published: 2025-06-13

Security Command Center: The following Event Threat Detection detectors for Vertex AI have been released to Preview:
- `Persistence: New Geography for AI Service`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Admin Activity`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Data Access`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Admin Activity`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Data Access`
- `Privilege Escalation: Anomalous Impersonation of Service Account for AI Admin Activity`
- `Persistence: New AI API Method`
......
......

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

۱۱. تبریک

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

اسناد مرجع

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