۱. مقدمه
در این آزمایشگاه کد، شما با استفاده از کیت توسعه عامل (ADK) یک عامل خواهید ساخت که از جعبه ابزار MCP برای پایگاه‌های داده بهره می‌برد.
از طریق codelab، شما یک رویکرد گام به گام به شرح زیر را به کار خواهید گرفت:
- یک پایگاه داده Cloud SQL برای PostgreSQL تهیه کنید که شامل پایگاه داده هتل‌ها و داده‌های نمونه باشد.
- جعبه ابزار MCP را برای پایگاه‌های داده راه‌اندازی کنید، که دسترسی به داده‌ها را فراهم می‌کند.
- طراحی و توسعه یک عامل با استفاده از کیت توسعه عامل (ADK) که از جعبه ابزار MCP برای پاسخ به سؤالات کاربر استفاده می‌کند.
- گزینه‌هایی را برای آزمایش Agent و MCP Toolbox برای پایگاه‌های داده به صورت محلی و روی Google Cloud از طریق سرویس Cloud Run بررسی کنید.
کاری که انجام خواهید داد
- طراحی، ساخت و استقرار یک عامل که به سوالات کاربران در مورد هتل‌های یک مکان پاسخ می‌دهد یا هتل‌ها را بر اساس نام جستجو می‌کند.
آنچه یاد خواهید گرفت
- تهیه و پر کردن یک پایگاه داده Cloud SQL برای PostgreSQL با داده‌های نمونه.
- راه‌اندازی جعبه ابزار MCP برای پایگاه‌های داده برای Cloud SQL برای نمونه پایگاه داده PostgreSQL.
- طراحی و توسعه یک عامل با استفاده از کیت توسعه عامل (ADK) برای پاسخ به سوالات کاربران.
- جعبه ابزار Agent و MCP برای پایگاه‌های داده را در محیط محلی آزمایش کنید.
- (اختیاری) Agent و MCP Toolbox را برای پایگاه‌های داده در Google Cloud مستقر کنید.
آنچه نیاز دارید
- مرورگر وب کروم
- یک حساب جیمیل
- یک پروژه ابری با قابلیت پرداخت صورتحساب
این آزمایشگاه کد که برای توسعه‌دهندگان در تمام سطوح (از جمله مبتدیان) طراحی شده است، در برنامه نمونه خود از پایتون استفاده می‌کند. با این حال، دانش پایتون الزامی نیست و توانایی خواندن کد اولیه برای درک مفاهیم ارائه شده کافی خواهد بود.
۲. قبل از شروع
ایجاد یک پروژه
- در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
- مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
- شما از Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا می‌شود و bq از قبل روی آن بارگذاری شده است، استفاده خواهید کرد. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
- پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که آیا از قبل احراز هویت شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است یا خیر:
gcloud auth list
- دستور زیر را در Cloud Shell اجرا کنید تا تأیید شود که دستور gcloud از پروژه شما اطلاع دارد.
gcloud config list project
- اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:
gcloud config set project <YOUR_PROJECT_ID>
- 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 به مستندات مراجعه کنید.
۳. یک نمونه Cloud SQL ایجاد کنید
ما از یک نمونه Google Cloud SQL برای PostgreSQL برای ذخیره داده‌های هتل‌هایمان استفاده خواهیم کرد. Cloud SQL برای PostgreSQL یک سرویس پایگاه داده کاملاً مدیریت‌شده است که به شما در راه‌اندازی، نگهداری، مدیریت و اداره پایگاه‌های داده رابطه‌ای PostgreSQL خود در پلتفرم Google Cloud کمک می‌کند.
برای ایجاد نمونه، دستور زیر را در Cloud Shell اجرا کنید:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
اجرای این دستور حدود ۳ تا ۵ دقیقه طول می‌کشد. پس از اجرای موفقیت‌آمیز دستور، باید خروجی‌ای را مشاهده کنید که نشان می‌دهد دستور انجام شده است، به همراه اطلاعات نمونه Cloud SQL شما مانند NAME، DATABASE_VERSION، LOCATION و غیره.
۴. پایگاه داده هتل‌ها را آماده کنید
وظیفه ما اکنون ایجاد برخی داده‌های نمونه برای نماینده هتلمان خواهد بود.
به صفحه Cloud SQL در کنسول Cloud مراجعه کنید. باید hoteldb-instance آماده و ایجاد شده را ببینید. مطابق شکل زیر، روی نام نمونه ( hoteldb-instance ) کلیک کنید:
از منوی سمت چپ Cloud SQL، مطابق شکل زیر، گزینه منوی Cloud SQL Studio را انتخاب کنید:
از شما خواسته می‌شود که به Cloud SQL Studio وارد شوید، که از طریق آن چند دستور SQL ارائه خواهیم داد. برای گزینه Database، postgres انتخاب کنید و برای User و Password، مقداری که باید استفاده شود postgres است. روی AUTHENTICATE کلیک کنید.
ابتدا جدول هتل را طبق طرحواره‌ای که در زیر آورده شده است، ایجاد می‌کنیم. در یکی از پنل‌های ویرایشگر در Cloud SQL Studio، دستور SQL زیر را اجرا کنید:
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
حالا، بیایید جدول هتل‌ها را با داده‌های نمونه پر کنیم. دستور SQL زیر را اجرا کنید:
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
بیایید داده‌ها را با اجرای یک SELECT SQL مطابق شکل زیر اعتبارسنجی کنیم:
SELECT * FROM hotels;
شما باید تعدادی رکورد در جدول هتل‌ها مطابق شکل زیر مشاهده کنید:
ما فرآیند راه‌اندازی یک نمونه Cloud SQL را تکمیل کرده و داده‌های نمونه خود را ایجاد کرده‌ایم. در بخش بعدی، جعبه ابزار MCP برای پایگاه‌های داده را راه‌اندازی خواهیم کرد.
۵. راه‌اندازی جعبه ابزار MCP برای پایگاه‌های داده
جعبه ابزار MCP برای پایگاه‌های داده، یک سرور MCP متن‌باز برای پایگاه‌های داده است که با در نظر گرفتن کیفیت تولید و سطح سازمانی طراحی شده است. این جعبه ابزار به شما این امکان را می‌دهد که با مدیریت پیچیدگی‌هایی مانند ادغام اتصال، احراز هویت و موارد دیگر، ابزارها را آسان‌تر، سریع‌تر و ایمن‌تر توسعه دهید.
جعبه ابزار به شما کمک می‌کند تا ابزارهای Gen AI بسازید که به نمایندگان شما اجازه می‌دهد به داده‌های موجود در پایگاه داده شما دسترسی داشته باشند. جعبه ابزار موارد زیر را ارائه می‌دهد:
- توسعه ساده: ابزارها را در کمتر از 10 خط کد با عامل خود ادغام کنید، از ابزارها بین چندین عامل یا چارچوب استفاده مجدد کنید و نسخه‌های جدید ابزارها را آسان‌تر مستقر کنید.
- عملکرد بهتر: بهترین شیوه‌ها مانند ادغام اتصال، احراز هویت و موارد دیگر.
- امنیت پیشرفته: احراز هویت یکپارچه برای دسترسی امن‌تر به داده‌های شما
- قابلیت مشاهده از ابتدا تا انتها: معیارهای آماده و ردیابی با پشتیبانی داخلی از OpenTelemetry.
جعبه ابزار بین چارچوب هماهنگ‌سازی برنامه شما و پایگاه داده شما قرار می‌گیرد و یک صفحه کنترلی را فراهم می‌کند که برای تغییر، توزیع یا فراخوانی ابزارها استفاده می‌شود. این جعبه ابزار با فراهم کردن یک مکان متمرکز برای ذخیره و به‌روزرسانی ابزارها، مدیریت ابزارهای شما را ساده می‌کند و به شما امکان می‌دهد ابزارها را بین عامل‌ها و برنامه‌ها به اشتراک بگذارید و آن ابزارها را بدون نیاز به استقرار مجدد برنامه خود، به‌روزرسانی کنید.
می‌توانید ببینید که یکی از پایگاه‌های داده‌ای که توسط MCP Toolbox for Databases پشتیبانی می‌شود، Cloud SQL است و ما آن را در بخش قبلی ارائه کرده‌ایم.
نصب جعبه ابزار
ترمینال Cloud Shell را باز کنید و پوشه‌ای با نام mcp-toolbox ایجاد کنید.
mkdir mcp-toolbox
از طریق دستور زیر به پوشه mcp-toolbox بروید:
cd mcp-toolbox
نسخه باینری جعبه ابزار MCP برای پایگاه‌های داده را از طریق اسکریپت زیر نصب کنید. دستور زیر برای لینوکس است، اما اگر از مک یا ویندوز استفاده می‌کنید، مطمئن شوید که فایل باینری صحیح را دانلود می‌کنید. صفحه انتشارها را برای سیستم عامل و معماری خود بررسی کنید و فایل باینری صحیح را دانلود کنید.
export VERSION=0.18.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
اکنون نسخه باینری جعبه ابزار را برای استفاده آماده داریم. بیایید اعتبارسنجی کنیم که آیا باینری جعبه ابزار را به درستی تنظیم کرده‌ایم و آیا نسخه صحیح را نشان می‌دهد یا خیر.
برای تشخیص نسخه Toolbox از دستور زیر استفاده کنید:
./toolbox -v
این باید خروجی مشابه زیر را چاپ کند:
toolbox version 0.18.0+binary.linux.amd64.3ca58b1
مرحله بعدی پیکربندی جعبه ابزار با منابع داده و سایر تنظیمات ما است.
پیکربندی tools.yaml
راه اصلی برای پیکربندی Toolbox از طریق فایل tools.yaml است. فایلی با نام tools.yaml در همان پوشه mcp-toolbox ایجاد کنید که محتوای آن در زیر نشان داده شده است.
شما می‌توانید از ویرایشگر nano که در Cloud Shell موجود است استفاده کنید. دستور nano به شرح زیر است: " nano tools.yaml ".
به یاد داشته باشید که مقدار YOUR_PROJECT_ID را با شناسه پروژه Google Cloud خود جایگزین کنید.
sources:
my-cloud-sql-source:
kind: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: "postgres"
tools:
search-hotels-by-name:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
search-hotels-by-location:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
بیایید فایل را به طور خلاصه درک کنیم:
-
Sourcesمنابع داده مختلفی را نشان می‌دهند که یک ابزار می‌تواند با آنها تعامل داشته باشد. یک منبع، منبع داده‌ای را نشان می‌دهد که یک ابزار می‌تواند با آن تعامل داشته باشد. می‌توانیدSourcesبه عنوان یک نقشه در بخش منابع فایل tools.yaml خود تعریف کنید. معمولاً، پیکربندی منبع شامل هرگونه اطلاعات مورد نیاز برای اتصال و تعامل با پایگاه داده خواهد بود. در مورد ما، ما یک منبع واحد را پیکربندی کرده‌ایم که به نمونه Cloud SQL برای PostgreSQL ما با اعتبارنامه‌ها اشاره می‌کند. برای اطلاعات بیشتر، به مرجع منابع مراجعه کنید. -
Toolsاقداماتی را که یک عامل می‌تواند انجام دهد تعریف می‌کنند - مانند خواندن و نوشتن در یک منبع. یک ابزار نشان دهنده عملی است که عامل شما می‌تواند انجام دهد، مانند اجرای یک دستور SQL. می‌توانیدToolsبه عنوان یک نقشه در بخش ابزارها در فایل tools.yaml خود تعریف کنید. معمولاً یک ابزار برای اقدام به یک منبع نیاز دارد. در مورد ما، ما دو ابزار را تعریف می‌کنیم:search-hotels-by-nameوsearch-hotels-by-locationو منبعی را که روی آن عمل می‌کند، همراه با SQL و پارامترها مشخص می‌کنیم. برای اطلاعات بیشتر، به مرجع ابزارها مراجعه کنید. - در نهایت،
Toolsetرا داریم که به شما امکان می‌دهد گروه‌هایی از ابزارها را که می‌خواهید بتوانید با هم بارگذاری کنید، تعریف کنید. این می‌تواند برای تعریف گروه‌های مختلف بر اساس عامل یا برنامه مفید باشد. در مورد ما، یک مجموعه ابزار واحد به نامmy_first_toolsetداریم که شامل دو ابزاری است که تعریف کرده‌ایم.
فایل tools.yaml را در ویرایشگر nano از طریق مراحل زیر ذخیره کنید:
-
Ctrl + O(دستور "Write Out") را فشار دهید. - از شما خواسته می‌شود که «نام فایل برای نوشتن» را تأیید کنید. فقط
Enterفشار دهید. - حالا برای خروج
Ctrl + Xفشار دهید.
جعبه ابزار MCP را برای سرور پایگاه داده اجرا کنید
برای شروع سرور، دستور زیر را (از پوشه mcp-toolbox ) اجرا کنید:
./toolbox --tools-file "tools.yaml"
در حالت ایده‌آل، باید خروجی‌ای ببینید که نشان می‌دهد سرور توانسته به منابع داده ما متصل شود و مجموعه ابزارها و ابزارها را بارگذاری کرده است. یک نمونه خروجی در زیر آورده شده است:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z 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.15.0+binary.linux.amd64.c934d7adfd4d012dab3f1707dc0adbdc7cb328cb",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location. Result is sorted by price from least to most expensive.",
"parameters": [
{
"name": "location",
"type": "string",
"required": true,
"description": "The location of the hotel.",
"authSources": []
}
],
"authRequired": []
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"required": true,
"description": "The name of the hotel.",
"authSources": []
}
],
"authRequired": []
}
}
}
ابزارها را از طریق جعبه ابزار MCP برای رابط کاربری پایگاه‌های داده آزمایش کنید
جعبه ابزار یک رابط بصری ( Toolbox UI ) فراهم می‌کند تا با تغییر پارامترها، مدیریت هدرها و اجرای فراخوانی‌ها، همه در یک رابط کاربری وب ساده، مستقیماً با ابزارها تعامل داشته باشید.
اگر می‌خواهید این را امتحان کنید، می‌توانید دستور قبلی که برای راه‌اندازی Toolbox Server با گزینه --ui استفاده کردیم را اجرا کنید.
برای انجام این کار، نسخه قبلی MCP Toolbox for Databases Server را که ممکن است در حال اجرا داشته باشید، خاموش کنید و دستور زیر را اجرا کنید:
./toolbox --tools-file "tools.yaml" --ui
در حالت ایده‌آل، باید خروجی‌ای ببینید که نشان می‌دهد سرور توانسته به منابع داده ما متصل شود و مجموعه ابزارها و برنامه‌ها را بارگذاری کند. یک خروجی نمونه در زیر آورده شده است و متوجه خواهید شد که به فعال بودن رابط کاربری جعبه ابزار اشاره می‌کند.
2025-09-08T02:44:11.561572538Z INFO "Initialized 1 sources."
2025-09-08T02:44:11.561966395Z INFO "Initialized 0 authServices."
2025-09-08T02:44:11.562060934Z INFO "Initialized 2 tools."
2025-09-08T02:44:11.562105678Z INFO "Initialized 2 toolsets."
2025-09-08T02:44:11.568209923Z INFO "Server ready to serve!"
2025-09-08T02:44:11.568259411Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui"
روی آدرس رابط کاربری کلیک کنید و مطمئن شوید که ...
/ui
در انتهای URL (اگر این را در Cloud Shell اجرا می‌کنید، تغییر مسیر مرورگر منجر به عدم وجود /ui در انتها می‌شود). این یک رابط کاربری مانند تصویر زیر نمایش می‌دهد:
برای مشاهده ابزارهای پیکربندی‌شده، روی گزینه ابزارها در سمت چپ کلیک کنید و در مورد ما، باید دو مورد از آنها یعنی search-hotels-by-name و search-hotels-by-location ، مطابق شکل زیر باشد:
کافیست روی یکی از ابزارها ( search-hotels-by-location ) کلیک کنید تا صفحه‌ای برای شما باز شود و بتوانید با وارد کردن مقادیر پارامترهای مورد نیاز، ابزار را امتحان کنید و سپس برای مشاهده نتیجه، روی اجرای ابزار کلیک کنید. نمونه‌ای از اجرای ابزار در زیر نشان داده شده است:
جعبه ابزار MCP برای پایگاه‌های داده همچنین روشی پایتونی را برای اعتبارسنجی و آزمایش ابزارها شرح می‌دهد که در اینجا مستند شده است.
اگر نمودار قبلی را دوباره بررسی کنیم (مطابق شکل زیر)، اکنون راه‌اندازی پایگاه داده و سرور MCP را تکمیل کرده‌ایم و دو مسیر پیش روی خود داریم:
- برای درک نحوه پیکربندی سرور MCP در یک ترمینال / IDE مجهز به هوش مصنوعی، به مرحله 6 بروید. این مرحله نحوه ادغام سرور جعبه ابزار MCP خود را در Gemini CLI پوشش می‌دهد.
- برای درک نحوه استفاده از کیت توسعه عامل (ADK) با استفاده از پایتون، برای نوشتن عامل‌های خودتان که می‌توانند از جعبه ابزار سرور MCP به عنوان یک ابزار استفاده کنند، برای پاسخ به سوالات مربوط به مجموعه داده‌ها، به مراحل 7 و 8 بروید.
۶. ادغام جعبه ابزار MCP در رابط خط فرمان Gemini
رابط خط فرمان Gemini یک عامل هوش مصنوعی متن‌باز است که قدرت Gemini را مستقیماً به ترمینال شما می‌آورد. می‌توانید از آن برای کارهای کدنویسی و غیرکدنویسی استفاده کنید. این رابط با ابزارهای مختلف و همچنین پشتیبانی از سرورهای MCP یکپارچه شده است.
از آنجایی که ما یک سرور MCP فعال داریم، هدف ما در این بخش پیکربندی جعبه ابزار MCP برای سرور پایگاه داده در Gemini CLI و سپس استفاده از Gemini CLI برای ارتباط با داده‌هایمان خواهد بود.
اولین قدم ما این است که مطمئن شویم آیا Toolbox را در یکی از ترمینال‌های Cloud Shell فعال و در حال اجرا دارید یا خیر. با فرض اینکه آن را روی پورت پیش‌فرض 5000 اجرا می‌کنید، رابط MCP Server در نقطه پایانی زیر در دسترس است: http://localhost:5000/mcp .
یک ترمینال جدید باز کنید و پوشه‌ای به نام my-gemini-cli-project به صورت زیر ایجاد کنید. به پوشه my-gemini-cli-project نیز بروید.
mkdir my-gemini-cli-project
cd my-gemini-cli-project
دستور زیر را برای اضافه کردن سرور MCP به لیست سرورهای MCP پیکربندی شده در Gemini CLI اجرا کنید.
gemini mcp add --scope="project" --transport="http" "MCPToolbox" "http://localhost:5000/mcp"
شما می‌توانید لیست فعلی سرورهای MCP پیکربندی‌شده در Gemini CLI را از طریق دستور زیر بررسی کنید:
gemini mcp list
در حالت ایده‌آل، باید MCPToolbox که پیکربندی کردیم را با یک تیک سبز در کنارش ببینید، که نشان می‌دهد Gemini CLI توانسته به MCP Server متصل شود.
Configured MCP servers:
✓ MCPToolbox: http://localhost:5000/mcp (http) - Connected
از همان ترمینال، مطمئن شوید که در پوشه my-gemini-cli-project هستید. Gemini CLI را از طریق دستور gemini اجرا کنید.
این کار رابط خط فرمان Gemini را نمایش می‌دهد و خواهید دید که اکنون یک سرور MCP پیکربندی شده است. می‌توانید از دستور /mcp list برای مشاهده لیست سرورهای MCP و ابزارها استفاده کنید. برای مثال، در اینجا یک خروجی نمونه آمده است:
اکنون می‌توانید هر یک از درخواست‌ها را ارائه دهید:
-
Which hotels are there in Basel? -
Tell me more about the Hyatt Regency?
متوجه خواهید شد که کوئری‌های بالا منجر به انتخاب ابزار مناسب از MCPToolbox توسط Gemini CLI می‌شوند. از شما اجازه اجرای ابزار را می‌خواهد. اجازه لازم را به آن بدهید و متوجه خواهید شد که نتایج از پایگاه داده برگردانده می‌شوند.
۷. نوشتن عامل ما با کیت توسعه عامل (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.
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 برای ایجاد یک چارچوب برای برنامه Hotel Agent خود از طریق دستور adk create با نام برنامه ** (hotel-agent-app) ** مطابق شکل زیر استفاده کنیم.
adk create hotel-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_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel-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 به اینجا مراجعه کنید.
بیایید کد مربوط به agent.py را به صورت زیر تغییر دهیم:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='hotel_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
برنامه عامل را به صورت محلی آزمایش کنید
از پنجره ترمینال موجود دستور زیر را اجرا کنید. مطمئن شوید که در پوشه والد (my-agents) هستید که پوشه hotel-agent-app در آن قرار دارد.
adk web
نمونه‌ای از اجرا در زیر نشان داده شده است:
INFO: Started server process [1478]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| 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)
روی آخرین لینک کلیک کنید تا یک کنسول وب برای آزمایش Agent باز شود. باید موارد زیر را در مرورگر مشاهده کنید:
توجه کنید که در بالا سمت چپ، hotel-agent-app شناسایی شده است. اکنون می‌توانید با نماینده صحبت کنید. چند سوال در مورد شهرها مطرح کنید. یک نمونه مکالمه در زیر نشان داده شده است:
شما می‌توانید فرآیند در حال اجرا را در ترمینال Cloud Shell (Ctrl-C) خاموش کنید.
یک روش جایگزین برای آزمایش Agent از طریق دستور adk run است که در زیر از پوشه my-agents آورده شده است.
adk run hotel-agent-app
دستور را امتحان کنید و می‌توانید از طریق خط فرمان (ترمینال) با عامل گفتگو کنید. برای بستن گفتگو، exit تایپ کنید.
۸. اتصال عامل ما به ابزارها
حالا که می‌دانیم چگونه یک عامل بنویسیم و آن را به صورت محلی آزمایش کنیم، قصد داریم این عامل را به ابزارها متصل کنیم. در زمینه 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 single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-2.5-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
اکنون می‌توانیم عاملی را که داده‌های واقعی را از پایگاه داده PostgreSQL ما که با جعبه ابزار MCP برای پایگاه‌های داده پیکربندی شده است، واکشی می‌کند، آزمایش کنیم.
برای انجام این کار، دنباله زیر را دنبال کنید:
در یکی از ترمینال‌های Cloud Shell، جعبه ابزار MCP برای پایگاه‌های داده را اجرا کنید. همانطور که قبلاً آزمایش کردیم، ممکن است از قبل آن را به صورت محلی روی پورت ۵۰۰۰ اجرا کرده باشید. در غیر این صورت، دستور زیر را (از پوشه mcp-toolbox ) برای شروع سرور اجرا کنید:
./toolbox --tools_file "tools.yaml"
در حالت ایده‌آل، باید خروجی‌ای ببینید که نشان می‌دهد سرور توانسته به منابع داده ما متصل شود و مجموعه ابزارها و ابزارها را بارگذاری کرده است. یک نمونه خروجی در زیر آورده شده است:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
پس از شروع موفقیت‌آمیز سرور MCP، در یک ترمینال دیگر، همانطور که قبلاً از طریق دستور adk run (از پوشه my-agents ) که در زیر نشان داده شده است، Agent را اجرا کنید. در صورت تمایل می‌توانید از دستور adk web نیز استفاده کنید.
$ adk run hotel-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 hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
توجه داشته باشید که اکنون عامل از دو ابزاری که ما در جعبه ابزار MCP برای پایگاه‌های داده پیکربندی کرده‌ایم ( search-hotels-by-name و search-hotels-by-location ) استفاده می‌کند و گزینه‌های صحیح را در اختیار ما قرار می‌دهد. سپس می‌تواند داده‌ها را به طور یکپارچه از پایگاه داده نمونه PostgreSQL بازیابی کرده و پاسخ را بر اساس آن قالب‌بندی کند.
این، توسعه و آزمایش محلیِ نماینده هتل ما را که با استفاده از کیت توسعه نماینده (ADK) ساخته‌ایم و توسط ابزارهایی که در جعبه ابزار MCP برای پایگاه‌های داده پیکربندی کرده‌ایم، پشتیبانی می‌شود، تکمیل می‌کند.
۹. (اختیاری) استقرار جعبه ابزار MCP برای پایگاه‌های داده و عامل در Cloud Run
در بخش قبلی، ما از ترمینال Cloud Shell برای راه‌اندازی سرور MCP Toolbox استفاده کردیم و ابزارها را با Agent آزمایش کردیم. این کار به صورت محلی در محیط Cloud Shell اجرا می‌شد.
شما می‌توانید هم سرور MCP Toolbox و هم Agent را در سرویس‌های Google Cloud که می‌توانند این برنامه‌ها را برای ما میزبانی کنند، مستقر کنید.
میزبانی سرور MCP Toolbox در Cloud Run
اول از همه، می‌توانیم با سرور MCP Toolbox شروع کنیم و آن را روی Cloud Run میزبانی کنیم. این کار به ما یک نقطه پایانی عمومی می‌دهد که می‌توانیم آن را با هر برنامه دیگری و/یا برنامه‌های Agent نیز ادغام کنیم. دستورالعمل‌های میزبانی این مورد روی Cloud Run در اینجا آورده شده است. اکنون مراحل کلیدی را بررسی خواهیم کرد.
یک ترمینال Cloud Shell جدید راه‌اندازی کنید یا از یک ترمینال Cloud Shell موجود استفاده کنید. به پوشه mcp-toolbox بروید، جایی که فایل باینری toolbox و tools.yaml وجود دارند.
دستورات زیر را اجرا کنید (برای هر دستور توضیحی ارائه شده است):
متغیر PROJECT_ID طوری تنظیم کنید که به شناسه پروژه گوگل کلود شما اشاره کند.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
در مرحله بعد، تأیید کنید که سرویس‌های Google Cloud زیر در پروژه فعال هستند.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
بیایید یک حساب سرویس جداگانه ایجاد کنیم که به عنوان هویت سرویس Toolbox که در Google Cloud Run مستقر خواهیم کرد، عمل کند. همچنین اطمینان حاصل می‌کنیم که این حساب سرویس نقش‌های صحیحی مانند توانایی دسترسی به Secret Manager و ارتباط با Cloud SQL را دارد.
gcloud iam service-accounts create toolbox-identity
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/cloudsql.client
ما فایل tools.yaml را به عنوان یک فایل مخفی آپلود خواهیم کرد و از آنجایی که باید Toolbox را در Cloud Run نصب کنیم، قصد داریم از جدیدترین تصویر Container برای toolbox استفاده کنیم و آن را در متغیر IMAGE تنظیم کنیم.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
آخرین مرحله در دستور استقرار آشنا برای Cloud Run:
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
این باید فرآیند استقرار Toolbox Server را با tools.yaml پیکربندی شده ما در Cloud Run آغاز کند. در صورت استقرار موفقیت‌آمیز، باید پیامی مشابه پیام زیر مشاهده کنید:
Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app
اکنون می‌توانید Service URL ذکر شده در بالا را در مرورگر مشاهده کنید. باید پیام "سلام دنیا" که قبلاً دیدیم را نمایش دهد. علاوه بر این، می‌توانید از آدرس اینترنتی زیر نیز برای مشاهده ابزارهای موجود استفاده کنید:
SERVICE URL/api/toolset
همچنین می‌توانید از کنسول Google Cloud به Cloud Run مراجعه کنید و سرویس Toolbox را در لیست سرویس‌های Cloud Run مشاهده خواهید کرد.
توجه: اگر می‌خواهید همچنان Hotel Agent خود را به صورت محلی اجرا کنید و در عین حال به سرویس Cloud Run که به تازگی مستقر شده است متصل شوید، فقط باید یک تغییر در فایل my-agents/hotel-agent-app/agent.py ایجاد کنید.
به جای موارد زیر:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
آن را به آدرس سرویس مربوط به سرویس Cloud Run مطابق شکل زیر تغییر دهید:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
همانطور که قبلاً دیدیم، برنامه‌ی عامل را با استفاده از adk run یا adk web آزمایش کنید.
استقرار اپلیکیشن آژانس هتل روی Cloud Run
اولین قدم این است که مطمئن شوید طبق دستورالعمل بالا، تغییری را در my-agents/hotel-agent-app/agent.py ایجاد کرده‌اید تا به URL سرویس Toolbox که روی Cloud Run اجرا می‌شود و نه میزبان محلی، اشاره کند.
در یک ترمینال Cloud Shell جدید یا یک جلسه ترمینال موجود، مطمئن شوید که در محیط مجازی پایتون صحیحی که قبلاً راه‌اندازی کردیم، قرار دارید.
ابتدا، بیایید یک فایل requirements.txt در پوشه my-agents/hotel-agent-app مطابق شکل زیر ایجاد کنیم:
google-adk
toolbox-core
به پوشه my-agents بروید و ابتدا متغیرهای محیطی زیر را تنظیم کنید:
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel-agent-app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
export GOOGLE_GENAI_USE_VERTEXAI=True
در نهایت، بیایید برنامه Agent را از طریق دستور adk deploy cloud_run مطابق شکل زیر در Cloud Run مستقر کنیم. اگر از شما خواسته شد که امکان فراخوانی‌های احراز هویت نشده به سرویس را فراهم کنید، لطفاً فعلاً مقدار "y" را وارد کنید.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
این کار فرآیند استقرار برنامه Hotel Agent در Cloud Run را آغاز می‌کند. منابع را آپلود می‌کند، آن را در یک Docker Container بسته‌بندی می‌کند، آن را به Artifact Registry ارسال می‌کند و سپس سرویس را در Cloud Run مستقر می‌کند. این کار ممکن است چند دقیقه طول بکشد، بنابراین لطفاً صبور باشید.
باید پیامی مشابه پیام زیر را ببینید:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250905_132636
Copying agent source code...
Copying agent source code completed.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250905_132636/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_PROJECT_ID] region [us-central1]
- Building and deploying... Uploading sources.
- Uploading sources...
. Building Container...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/d1f7e76b-0587-4bb6-b9c0-bb4360c07aa0?project=415
458962931]. f
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00003-hrl] has been deployed and is serving 100 percent of traffic.
Service URL: <YOUR_CLOUDRUN_APP_URL>
INFO: Display format: "none"
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250905_132636
پس از استقرار موفقیت‌آمیز، مقداری برای URL سرویس به شما ارائه می‌شود که می‌توانید در مرورگر به آن دسترسی پیدا کنید تا همان برنامه وب را که به شما امکان چت با نماینده هتل را می‌داد، مشاهده کنید، همانطور که قبلاً در تنظیمات محلی دیدیم.
۱۰. پاکسازی
برای جلوگیری از هزینه‌های مداوم برای حساب Google Cloud شما، حذف منابعی که در طول این کارگاه ایجاد کرده‌ایم، مهم است. ما نمونه Cloud SQL را حذف خواهیم کرد و در صورت تمایل، اگر Toolbox و Hotels App را در Cloud Run مستقر کرده‌اید، آن سرویس‌ها را نیز حذف خواهیم کرد.
مطمئن شوید که متغیرهای محیطی زیر، مطابق با پروژه و منطقه شما، به درستی تنظیم شده‌اند:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
دو دستور زیر سرویس‌های Cloud Run که ما مستقر کرده‌ایم را حذف می‌کند:
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
دستور زیر نمونه Cloud SQL را حذف می‌کند:
gcloud sql instances delete hoteldb-instance
۱۱. تبریک
تبریک می‌گویم، شما با موفقیت یک عامل با استفاده از کیت توسعه عامل (ADK) ساختید که از جعبه ابزار MCP برای پایگاه‌های داده استفاده می‌کند.