ساخت یک آژانس مسافرتی با استفاده از جعبه ابزار MCP برای پایگاه‌های داده و کیت توسعه نماینده (ADK)
درباره این codelab
1. مقدمه
در این کد لبه، شما یک عامل با استفاده از کیت توسعه عامل (ADK) می سازید که از جعبه ابزار MCP برای پایگاه های داده استفاده می کند.
از طریق کد لبه، شما یک رویکرد گام به گام را به شرح زیر به کار خواهید گرفت:
- ارائه یک Cloud SQL برای پایگاه داده PostgreSQL که دارای پایگاه داده هتل ها و داده های نمونه باشد.
- جعبه ابزار MCP را برای پایگاه های داده راه اندازی کنید، که دسترسی به داده ها را فراهم می کند.
- با استفاده از کیت توسعه عامل (ADK) یک عامل را طراحی و توسعه دهید که از جعبه ابزار MCP برای پاسخ به سؤالات کاربر استفاده می کند.
- گزینه‌های آزمایش Agent و جعبه ابزار MCP برای پایگاه‌های داده را به صورت محلی و در Google Cloud از طریق سرویس Cloud Run کاوش کنید.
کاری که خواهی کرد
- عاملی را طراحی، بسازید و استقرار دهید که به سؤالات کاربر در مورد هتل های یک مکان پاسخ دهد یا هتل ها را با نام جستجو کند.
چیزی که یاد خواهید گرفت
- تهیه و پر کردن یک Cloud SQL برای پایگاه داده PostgreSQL با داده های نمونه.
- جعبه ابزار MCP را برای پایگاه های داده برای Cloud SQL برای نمونه پایگاه داده PostgreSQL تنظیم کنید.
- طراحی و توسعه یک عامل با استفاده از کیت توسعه عامل (ADK) برای پاسخ به سؤالات کاربر.
- Agent و MCP Toolbox را برای پایگاه‌های داده در محیط محلی آزمایش کنید.
- (اختیاری) Agent و MCP Toolbox را برای پایگاه‌های داده در Google Cloud مستقر کنید.
آنچه شما نیاز دارید
- مرورگر وب کروم
- یک اکانت جیمیل
- یک پروژه Cloud با فعال کردن صورتحساب
این کد لبه که برای توسعه دهندگان همه سطوح (از جمله مبتدیان) طراحی شده است، از پایتون در برنامه نمونه خود استفاده می کند. با این حال، دانش پایتون برای درک مفاهیم ارائه شده مورد نیاز نیست.
2. قبل از شروع
یک پروژه ایجاد کنید
- در Google Cloud Console ، در صفحه انتخاب پروژه، یک پروژه Google Cloud را انتخاب یا ایجاد کنید.
- مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورتحساب در پروژه آشنا شوید.
- شما از Cloud Shell استفاده خواهید کرد، یک محیط خط فرمان در حال اجرا در Google Cloud که با bq از قبل بارگذاری شده است. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
- پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که قبلاً احراز هویت شده‌اید و پروژه به ID پروژه شما تنظیم شده است:
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 به اسناد مراجعه کنید.
3. یک نمونه Cloud SQL ایجاد کنید
ما از Google Cloud SQL برای نمونه PostgreSQL برای ذخیره داده های هتل هایمان استفاده خواهیم کرد. Cloud SQL for PostgreSQL یک سرویس پایگاه داده کاملاً مدیریت شده است که به شما کمک می کند پایگاه داده های ارتباطی PostgreSQL خود را در Google Cloud Platform راه اندازی، نگهداری، مدیریت و مدیریت کنید.
برای ایجاد نمونه، دستور زیر را در Cloud Shell اجرا کنید:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--cpu=2 \
--memory=8GiB \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
اجرای این دستور حدود 3-5 دقیقه طول می کشد. هنگامی که دستور با موفقیت اجرا شد، باید خروجی را مشاهده کنید که نشان می دهد دستور انجام شده است، همراه با اطلاعات نمونه Cloud SQL مانند NAME، DATABASE_VERSION، LOCATION و غیره.
4. پایگاه داده هتل ها را آماده کنید
وظیفه ما در حال حاضر ایجاد برخی داده های نمونه برای نماینده هتل ما خواهد بود.
از صفحه Cloud SQL در کنسول Cloud دیدن کنید. باید hoteldb-instance آماده و ساخته شده ببینید. مطابق شکل زیر روی نام نمونه ( hoteldb-instance ) کلیک کنید:
از منوی سمت چپ Cloud SQL، مطابق شکل زیر به گزینه منوی Cloud SQL Studio مراجعه کنید:
این از شما می خواهد که وارد Cloud SQL Studio شوید که از طریق آن ما چند دستور SQL را می دهیم. postgres برای گزینه Database انتخاب کنید و برای 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-22', '2024-04-20', 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-24', '2024-04-05', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', 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 را برای پایگاه‌های داده راه‌اندازی می‌کنیم.
5. جعبه ابزار MCP را برای پایگاه داده راه اندازی کنید
MCP Toolbox for Databases یک سرور MCP منبع باز برای پایگاه های داده است که با در نظر گرفتن درجه سازمانی و کیفیت تولید طراحی شده است. این به شما امکان می دهد تا با مدیریت پیچیدگی هایی مانند ادغام اتصال، احراز هویت و موارد دیگر، ابزارها را آسان تر، سریع تر و ایمن تر توسعه دهید.
Toolbox به شما کمک می کند ابزارهای Gen AI بسازید که به عوامل شما اجازه می دهد به داده های موجود در پایگاه داده شما دسترسی داشته باشند. جعبه ابزار فراهم می کند:
- توسعه ساده: ابزارها را در کمتر از 10 خط کد با عامل خود ادغام کنید، از ابزارها بین چندین عامل یا فریمورک استفاده مجدد کنید و نسخه های جدید ابزارها را راحت تر اجرا کنید.
- عملکرد بهتر: بهترین روش‌ها مانند ادغام اتصال، احراز هویت و موارد دیگر.
- امنیت پیشرفته: احراز هویت یکپارچه برای دسترسی ایمن تر به داده های شما
- قابلیت مشاهده سرتاسر: معیارهای خارج از جعبه و ردیابی با پشتیبانی داخلی برای OpenTelemetry.
جعبه ابزار بین چارچوب سازماندهی برنامه شما و پایگاه داده شما قرار می گیرد و یک صفحه کنترل را ارائه می دهد که برای اصلاح، توزیع یا فراخوانی ابزارها استفاده می شود. با ارائه یک مکان متمرکز برای ذخیره و به‌روزرسانی ابزارها، مدیریت ابزارهای شما را ساده می‌کند و به شما این امکان را می‌دهد که ابزارها را بین عوامل و برنامه‌ها به اشتراک بگذارید و آن ابزارها را بدون نیاز به استقرار مجدد برنامه خود به‌روزرسانی کنید.
می بینید که یکی از پایگاه های داده ای که توسط MCP Toolbox for Databases پشتیبانی می شود، Cloud SQL است و ما آن را در قسمت قبل ارائه کرده ایم.
نصب جعبه ابزار
Cloud Shell Terminal را باز کنید و یک پوشه به نام mcp-toolbox ایجاد کنید.
mkdir mcp-toolbox
با دستور زیر به پوشه mcp-toolbox بروید:
cd mcp-toolbox
نسخه باینری جعبه ابزار MCP برای پایگاه‌های داده را از طریق اسکریپت زیر نصب کنید:
export VERSION=0.6.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
اکنون نسخه باینری جعبه ابزار را برای استفاده آماده کرده ایم. مرحله بعدی پیکربندی جعبه ابزار با منابع داده و سایر تنظیمات است.
پیکربندی tools.yaml
راه اصلی برای پیکربندی جعبه ابزار از طریق فایل tools.yaml است. یک فایل با نام tools.yaml در همان پوشه یعنی mcp-toolbox ایجاد کنید که محتویات آن در زیر نشان داده شده است.
می توانید از ویرایشگر نانویی که در 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.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
اجازه دهید فایل را به طور خلاصه درک کنیم:
-
Sourcesنشان دهنده منابع داده های مختلف شما هستند که یک ابزار می تواند با آنها تعامل داشته باشد. منبع یک منبع داده را نشان می دهد که یک ابزار می تواند با آن تعامل داشته باشد. می توانیدSourcesبه عنوان نقشه در قسمت sources فایل tools.yaml خود تعریف کنید. به طور معمول، یک پیکربندی منبع حاوی اطلاعات مورد نیاز برای اتصال و تعامل با پایگاه داده است. در مورد ما، ما یک منبع واحد را پیکربندی کرده‌ایم که به Cloud SQL ما برای نمونه PostgreSQL با اعتبارنامه اشاره می‌کند. برای اطلاعات بیشتر به مرجع منابع مراجعه کنید. -
Toolsاقداماتی را که یک عامل می تواند انجام دهد را تعریف می کند - مانند خواندن و نوشتن برای یک منبع. یک ابزار عملکردی را نشان می دهد که نماینده شما می تواند انجام دهد، مانند اجرای یک دستور SQL. می توانیدToolsبه عنوان نقشه در قسمت tools فایل tools.yaml خود تعریف کنید. به طور معمول، یک ابزار برای عمل کردن به یک منبع نیاز دارد. در مورد ما، ما دو ابزار را تعریف می‌کنیم:search-hotels-by-nameوsearch-hotels-by-locationو مشخص کردن منبعی که روی آن عمل می‌کند، همراه با SQL و پارامترها. برای اطلاعات بیشتر به مرجع ابزار مراجعه کنید. - در نهایت،
Toolsetداریم که به شما امکان می‌دهد گروه‌هایی از ابزارها را تعریف کنید که می‌خواهید با هم بارگذاری شوند. این می تواند برای تعریف گروه های مختلف بر اساس عامل یا برنامه مفید باشد. در مورد ما، ما یک مجموعه ابزار به نامmy_first_toolsetداریم که شامل دو ابزاری است که ما تعریف کرده ایم.
جعبه ابزار MCP را برای سرور پایگاه داده اجرا کنید
دستور زیر را (از پوشه mcp-toolbox ) برای راه اندازی سرور اجرا کنید:
./toolbox --tools-file "tools.yaml"
در حالت ایده‌آل باید خروجی‌ای ببینید که سرور توانسته است به منابع داده ما متصل شود و مجموعه ابزار و ابزارها را بارگیری کرده باشد. یک نمونه خروجی در زیر آورده شده است:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
سرور جعبه ابزار MCP به طور پیش فرض روی پورت 5000 اجرا می شود. اگر متوجه شدید که پورت 5000 از قبل در حال استفاده است، طبق دستور زیر از پورت دیگری (مثلاً 7000 ) استفاده کنید. لطفاً به جای پورت 5000 در دستورات بعدی 7000 استفاده کنید.
./toolbox --tools-file "tools.yaml" --port 7000
اجازه دهید از Cloud Shell برای آزمایش این موضوع استفاده کنیم.
مطابق شکل زیر روی Web Preview در Cloud Shell کلیک کنید:
بر روی Change port کلیک کنید و مطابق شکل زیر پورت را روی 5000 قرار دهید و روی Change and Preview کلیک کنید.
این باید خروجی زیر را به همراه داشته باشد:
در URL مرورگر، موارد زیر را به انتهای URL اضافه کنید:
/api/toolset
این باید ابزارهایی را که در حال حاضر پیکربندی شده اند را نشان دهد. یک نمونه خروجی در زیر نشان داده شده است:
{
"serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location.",
"parameters": [
{
"name": "location",
"type": "string",
"description": "The location of the hotel.",
"authSources": []
}
]
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"description": "The name of the hotel.",
"authSources": []
}
]
}
}
}
MCP Toolkit برای پایگاه‌های داده یک روش پایتونیک را برای اعتبارسنجی و آزمایش ابزارها توصیف می‌کند که در اینجا مستند شده است. ما آن را نادیده می گیریم و در بخش بعدی که از این ابزارها استفاده می کند، مستقیماً به کیت توسعه عامل (ADK) می پریم.
6. نوشتن نماینده ما با کیت توسعه عامل (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 برای ایجاد داربست برای Agent Hotel خود از طریق دستور adk create با نام برنامه ** (hotel-agent-app) ** همانطور که در زیر آورده شده است استفاده کنیم.
adk create hotel-agent-app
مراحل را دنبال کنید و موارد زیر را انتخاب کنید:
- مدل جمینی برای انتخاب مدل برای عامل ریشه.
- Vertex AI را برای backend انتخاب کنید.
- شناسه و منطقه پیش فرض پروژه Google شما نمایش داده می شود. خود پیش فرض را انتخاب کنید.
Choose a model for the root agent:
1. gemini-2.0-flash-001
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 [gcp-experiments-349209]:
Enter Google Cloud region [us-central1]:
Agent created in /home/romin/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.0-flash-001',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
این ساده ترین عاملی است که می توانید با ADK بنویسید. از صفحه مستندات ADK، یک Agent یک واحد اجرایی مستقل است که برای عمل مستقل برای دستیابی به اهداف خاص طراحی شده است. عامل ها می توانند وظایف را انجام دهند، با کاربران تعامل داشته باشند، از ابزارهای خارجی استفاده کنند و با عوامل دیگر هماهنگ شوند.
به طور خاص، یک LLMAgent، که معمولاً به عنوان عامل نامیده می‌شود، از مدل‌های زبان بزرگ (LLM) به عنوان موتور اصلی خود برای درک زبان طبیعی، دلیل، برنامه‌ریزی، تولید پاسخ‌ها و تصمیم‌گیری پویا در مورد چگونگی ادامه یا استفاده از ابزارها استفاده می‌کند و آنها را برای کارهای انعطاف‌پذیر و زبان محور ایده‌آل می‌کند. در اینجا درباره نمایندگان LLM بیشتر بیاموزید.
بیایید کد agent.py را به صورت زیر تغییر دهیم:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
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.',
)
برنامه Agent را به صورت محلی تست کنید
از پنجره ترمینال موجود و دستور زیر را بدهید. مطمئن شوید که در پوشه والد (my-agents) حاوی پوشه hotel-agent-app هستید.
adk web
یک نمونه اجرای در زیر نشان داده شده است:
INFO: Started server process [5015]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
روی آخرین لینک کلیک کنید و باید یک کنسول وب برای آزمایش Agent ظاهر شود. مانند تصویر زیر باید موارد زیر را در مرورگر اجرا کنید:
توجه داشته باشید که در بالا سمت چپ، هتل-عامل-اپلیکیشن شناسایی شده است. اکنون می توانید مکالمه با نماینده را شروع کنید. چند دستور برای پرس و جو در مورد شهرها ارائه دهید. یک نمونه گفتگو در زیر نشان داده شده است:
می توانید فرآیند در حال اجرا در ترمینال Cloud Shell (Ctrl-C) را خاموش کنید.
یک راه جایگزین برای آزمایش Agent از طریق دستور adk run است که در زیر از پوشه my-agents ارائه شده است.
adk run hotel-agent-app
دستور را امتحان کنید و می توانید از طریق خط فرمان (ترمینال) با Agent مکالمه کنید. برای بستن مکالمه exit تایپ کنید.
7. اتصال نماینده ما به ابزار
اکنون که می دانیم چگونه یک Agent بنویسیم و آن را به صورت محلی آزمایش کنیم. ما قصد داریم این Agent را به Tools متصل کنیم. در زمینه ADK، یک ابزار قابلیت خاصی را نشان می‌دهد که به یک عامل هوش مصنوعی ارائه می‌شود و آن را قادر می‌سازد تا اقداماتی را انجام دهد و با جهان فراتر از تولید متن اصلی و توانایی‌های استدلال خود تعامل داشته باشد.
در مورد ما، اکنون می‌خواهیم نماینده خود را با ابزارهایی که در جعبه ابزار MCP برای پایگاه‌های داده پیکربندی کرده‌ایم، مجهز کنیم.
فایل agent.py را با کد زیر تغییر دهید. توجه داشته باشید که ما از پورت پیش فرض 5000 در کد استفاده می کنیم، اما اگر از یک شماره پورت جایگزین استفاده می کنید، لطفاً از آن استفاده کنید.
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.0-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 را برای پایگاه های داده راه اندازی کنید. همانطور که قبلاً آزمایش کردیم، ممکن است آن را به صورت محلی روی پورت 5000 اجرا کنید. اگر نه، دستور زیر را (از پوشه mcp-toolbox ) برای راه اندازی سرور اجرا کنید:
./toolbox --tools_file "tools.yaml"
در حالت ایده‌آل باید خروجی‌ای ببینید که سرور توانسته است به منابع داده ما متصل شود و مجموعه ابزار و ابزارها را بارگیری کرده باشد. یک نمونه خروجی در زیر آورده شده است:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
هنگامی که سرور MCP با موفقیت راه اندازی شد، در ترمینال دیگر، Agent را همانطور که قبلاً از طریق دستور adk run (از پوشه my-agents ) نشان داده شده در زیر انجام دادیم، راه اندازی کنید. در صورت تمایل می توانید از دستور 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.
توجه داشته باشید که Agent اکنون از دو ابزاری که ما در جعبه ابزار MCP برای پایگاه‌های داده پیکربندی کرده‌ایم ( search-hotels-by-name و search-hotels-by-location ) استفاده می‌کند و گزینه‌های صحیح را در اختیار ما قرار می‌دهد. سپس می تواند به طور یکپارچه داده ها را از پایگاه داده نمونه PostgreSQL بازیابی کند و پاسخ را بر اساس آن قالب بندی کند.
این برنامه توسعه محلی و آزمایش نماینده هتل ما را که با استفاده از کیت توسعه عامل (ADK) ساخته بودیم و با ابزارهایی که در جعبه ابزار MCP برای پایگاه‌های داده پیکربندی کرده بودیم، تکمیل می‌شود.
8. (اختیاری) استقرار جعبه ابزار MCP برای پایگاه های داده و عامل در اجرای ابری
در قسمت قبل از ترمینال 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 را طوری تنظیم کنید که به شناسه پروژه Google Cloud شما اشاره کند.
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 را به صورت مخفی آپلود می کنیم و از آنجایی که باید جعبه ابزار را در Cloud Run نصب کنیم، از آخرین تصویر Container برای جعبه ابزار استفاده می کنیم و آن را در متغیر 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 فهرست شده در بالا در مرورگر دیدن کنید. باید پیام "Hello World" را که قبلاً دیدیم نمایش دهد. علاوه بر این، می‌توانید برای مشاهده ابزارهای موجود، به آدرس اینترنتی زیر نیز مراجعه کنید:
SERVICE URL/api/toolset
همچنین می توانید از طریق کنسول Google Cloud به Cloud Run مراجعه کنید و سرویس Toolbox را در لیست خدمات موجود در Cloud Run مشاهده خواهید کرد.
توجه: اگر می‌خواهید باز هم آژانس هتل خود را به صورت محلی اجرا کنید و با این حال به سرویس Cloud Run تازه مستقر شده متصل شوید، فقط باید یک تغییر در فایل my-agents/hotel-agent-app/agent.py انجام دهید.
به جای موارد زیر:
toolbox = ToolboxTool("http://127.0.0.1:5000")
مطابق زیر آن را به URL Service سرویس Cloud Run تغییر دهید:
toolbox = ToolboxTool("CLOUD_RUN_SERVICE_URL")
همانطور که قبلا دیدیم، Agent Application را با استفاده از adk run یا adk web آزمایش کنید.
استقرار برنامه Hotel Agent در Cloud Run
اولین قدم این است که اطمینان حاصل کنید که مطابق دستورالعمل بالا، تغییر را در my-agents/hotel-agent-app/agent.py انجام داده اید تا به URL سرویس جعبه ابزار اشاره کنید که در Cloud Run اجرا می شود و نه میزبان محلی.
در یک ترمینال جدید Cloud Shell یا جلسه ترمینال موجود، اطمینان حاصل کنید که در محیط مجازی پایتون درستی هستید که قبلاً تنظیم کردیم.
ابتدا، اجازه دهید مانند شکل زیر یک فایل requires.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 Application را از طریق دستور adk deploy 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 فشار می‌دهد و سپس سرویس را در Cloud Run اجرا می‌کند. این ممکن است چند دقیقه طول بکشد، پس لطفا صبور باشید.
شما باید پیامی مشابه پیام زیر ببینید:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
| Building and deploying... Uploading sources.
| Uploading sources...
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/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623
در صورت استقرار موفقیت آمیز، مقداری برای URL Service به شما ارائه می شود، که سپس می توانید در مرورگر به آن دسترسی داشته باشید تا همان برنامه وب را مشاهده کنید که به شما امکان می داد با نماینده هتل چت کنید، همانطور که قبلاً در تنظیمات محلی دیدیم.
9. پاکسازی
برای جلوگیری از هزینه‌های مداوم برای حساب Google Cloud خود، مهم است که منابعی را که در طول این کارگاه ایجاد کرده‌ایم حذف کنید. ما نمونه Cloud SQL را حذف خواهیم کرد و به صورت اختیاری، اگر برنامه Toolbox و Hotels را در 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
10. تبریک میگم
تبریک می‌گوییم، شما با استفاده از کیت توسعه عامل (ADK) که از جعبه ابزار MCP برای پایگاه‌های داده استفاده می‌کند، با موفقیت یک عامل ایجاد کردید.