۱. مقدمه
پشته عامل مدرن
ساخت یک عامل هوش مصنوعی در سطح تولید، به چیزی بیش از یک مدل زبان بزرگ (LLM) نیاز دارد. در حالی که یک LLM قابلیتهای استدلال را فراهم میکند، یک عامل قوی باید با دنیای خارج تعامل داشته باشد، وضعیت مکالمه را مدیریت کند و ترجیحات کاربر را در طول زمان به خاطر بسپارد.
در این کارگاه، شما یاد خواهید گرفت که چگونه با استفاده از سه فناوری بنیادی، یک سیستم جامع عاملگرا را معماری و بسازید:
- اتصال (MCP) : برای دسترسی نماینده شما به ابزارها و دادههای محلی.
- هماهنگسازی (ADK) : برای مدیریت حلقه استدلال و وضعیت عامل.
- حافظه (بانک حافظه) : برای فراهم کردن زمینه شخصیسازیشده و بلندمدت.
مفاهیم اصلی
کامپوننت | عملکرد |
پروتکل زمینه مدل (MCP) | یک استاندارد جهانی که مدلهای هوش مصنوعی را بدون ادغامهای سفارشی به سیستمهای خارجی (پایگاههای داده، سیستم فایلها، APIها) متصل میکند. |
کیت توسعه عامل (ADK) | چارچوبی که محیط زمان اجرا را برای عاملها فراهم میکند، حلقه رویداد، انتقال حالتها و اجرای ابزار را مدیریت میکند. |
سرویس جلسه | حافظه کوتاهمدت را مدیریت میکند. این حافظه، زمینه مکالمه فوری را حفظ میکند (مثلاً «کاربر همین الان چه پرسید؟») اما با پایان جلسه پاک میشود. |
بانک حافظه هوش مصنوعی ورتکس | حافظه بلندمدت را مدیریت میکند. این حافظه، حقایق و ترجیحات خاص کاربر (مثلاً «کاربر پایتون را ترجیح میدهد») را به طور نامحدود ذخیره میکند و به عامل اجازه میدهد تعاملات آینده را شخصیسازی کند. |
موتور عامل هوش مصنوعی ورتکس | سرویس زیرساخت مدیریتشدهای که منطق عامل و اجزای حافظه شما را در مقیاس بزرگ میزبانی میکند. |
آنچه خواهید ساخت
برای نشان دادن این مفاهیم، شما یک دستیار طراحی تعطیلات خواهید ساخت. این عامل قادر به دریافت درخواستهای سطح بالای کاربر و هماهنگسازی خودکار ابزارهای محلی پایتون برای تولید کد و تصاویر شخصیسازیشده خواهد بود.
شما در سه مرحله پیشرفت خواهید کرد:
- لایه ابزارسازی : یک سرور MCP ایجاد کنید تا توابع محلی پایتون را در اختیار هوش مصنوعی قرار دهد.
- لایه عامل : از ADK برای ساخت عاملی استفاده کنید که گردشهای کاری چند مرحلهای را برنامهریزی و اجرا میکند.
- لایه حافظه : یکپارچهسازی بانک حافظه برای فعال کردن عامل در یادگیری و به خاطر سپردن ترجیحات سبک کاربر.
۲. راهاندازی
برای توانمندسازی عوامل هوش مصنوعی خود، به دو چیز نیاز داریم: یک پروژه ابری گوگل برای فراهم کردن پایه و اساس.
بخش اول: فعال کردن حساب صورتحساب
- برای فعال کردن حساب صورتحساب خود با اعتبار ۵ دلاری، به آن برای استقرار خود نیاز خواهید داشت. حتماً به حساب جیمیل خود وارد شوید.
بخش دوم: محیط باز
- 👉 برای دسترسی مستقیم به ویرایشگر Cloud Shell ، روی این لینک کلیک کنید
- 👉 اگر امروز در هر مرحلهای از شما خواسته شد که مجوز دهید، برای ادامه روی «مجوز دادن» کلیک کنید.
- 👉 اگر ترمینال در پایین صفحه نمایش داده نشد، آن را باز کنید:
- روی مشاهده کلیک کنید
- روی ترمینال کلیک کنید
- 👉💻 در ترمینال، با استفاده از دستور زیر تأیید کنید که از قبل احراز هویت شدهاید و پروژه روی شناسه پروژه شما تنظیم شده است:
gcloud auth list - 👉💻 پروژه بوتاسترپ را از گیتهاب کپی کنید:
git clone https://github.com/cuppibla/holiday_workshop - 👉💻 اسکریپت راهاندازی را از دایرکتوری پروژه اجرا کنید.
cd ~/holiday_workshop ./init.sh - 👉💻 شناسه پروژه مورد نیاز را تنظیم کنید:
gcloud config set project $(cat ~/project_id.txt) --quiet
بخش سوم: تنظیم مجوز
- 👉💻 با استفاده از دستور زیر، APIهای مورد نیاز را فعال کنید. این کار ممکن است چند دقیقه طول بکشد.
gcloud services enable \ cloudresourcemanager.googleapis.com \ servicenetworking.googleapis.com \ run.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com - 👉💻 با اجرای دستورات زیر در ترمینال، مجوزهای لازم را اعطا کنید:
. ~/holiday_workshop/set_env.sh
توجه داشته باشید که یک فایل .env برای شما ایجاد شده است که اطلاعات پروژه شما را نشان میدهد.
۳. تقویت با MCP
لحظه «USB-C» برای هوش مصنوعی
تصور کنید هر بار که یک ماوس جدید میخریدید، مجبور بودید آن را به مادربرد خود لحیم کنید. وضعیت ابزارهای هوش مصنوعی تا همین اواخر همین بود. توسعهدهندگان مجبور بودند برای اتصال LLMها به پایگاههای داده، سیستم فایلها یا APIها، «کد چسب» سفارشی بنویسند.
پروتکل زمینه مدل (MCP) را وارد کنید. MCP را به عنوان پورت USB-C برای برنامههای هوش مصنوعی در نظر بگیرید. این پروتکل یک روش استاندارد برای اتصال مدلهای هوش مصنوعی به منابع داده و ابزارها فراهم میکند.
اگر یک بار یک سرور MCP برای ابزارهای خود بسازید، میتوانید آن را بدون تغییر حتی یک خط کد به Gemini CLI، یک IDE یا هر کلاینت سازگار با MCP دیگر متصل کنید.
آنچه خواهید ساخت
در این آزمایشگاه کد، شما یک دستیار طراحی تعطیلات خواهید ساخت که:
- با استفاده از MCP به محیط محلی شما (ابزارهای استودیویی) متصل میشود .
- با استفاده از کیت توسعه عامل (ADK)، زمینه مکالمه را به طور قابل اعتمادی مدیریت میکند .
- تنظیمات برگزیده شما (مثلاً «من کد پایتون را ترجیح میدهم») را در جلسات مختلف با استفاده از بانک حافظه هوش مصنوعی Vertex به خاطر میسپارد.
ساخت منطق سرور
ما محیط را آماده کردهایم، اما منطق سرور ناقص است. ما باید چهار ابزار خاص را که نماینده ما در نهایت برای ساخت کارت تعطیلات ما استفاده خواهد کرد، پیادهسازی کنیم.
بخش اول: باز کردن اسکلت سرور
ما در دایرکتوری 01-MCP-Files-Testing/01-starter کار خواهیم کرد.
- در ترمینال Cloud Shell خود، مطمئن شوید که در دایرکتوری صحیح هستید:
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/ - با اجرای دستور زیر، فایل را در ویرایشگر Cloud Shell باز کنید:
cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
متوجه خواهید شد که کد اصلی (تنظیم سرور MCP، مدیریت اتصالات و مقداردهی اولیه کلاینت Vertex AI) از قبل انجام شده است. با این حال، چهار تابع اصلی در حال حاضر جای خالی دارند.
بخش دوم: پیادهسازی مولد صحنه تعطیلات
اول، ما به ابزاری نیاز داریم که علاقه کاربر (مثلاً «پرندگان») را جلب کند و آن را به یک پیام غنی و دقیق تبدیل کند که برای تولید تصویر بهینه شده باشد.
عبارت #REPLACE_GENERATE_HOLIDAY_SCENE درون تابع generate_holiday_scene پیدا کنید.
کل این خط را با کد زیر جایگزین کنید :
prompt = (
f"""
Create a cozy, high-fidelity 3D render of a winter holiday scene.
The scene should be warm and inviting with soft cinematic lighting.
Seamlessly integrate the following specific theme/interest into the
holiday decor or landscape: {interest}.
The style should be whimsical but detailed.
Aspect Ratio: 16:9 Landscape.
"""
)
generate_image(prompt, "16:9", "static/generated_scene.png")
return "Done! Saved at generated_scene.png"
بخش سوم: پیادهسازی نتیجه نهایی عکس
در نهایت، میخواهیم مطمئن شویم که نورپردازی و سبک، واقعگرایانه و جشنگونه به نظر میرسند.
کامنت #REPLACE_GENERATE_FINAL_PHOTO را پیدا کنید.
برای انجام انتقال و رندر نهایی استایل، کل این خط را با کد زیر جایگزین کنید :
prompt = (
"""
Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
Lighting: Warm, glowing ambient light from a fire below (out of frame).
Background: Softly blurred (bokeh) pine garland and twinkling lights.
Foreground Composition:
1. A wooden picture frame containing the [attached selfie image].
The face in the photo must be clearly visible.
2. A folded holiday greeting card standing upright next to the frame.
The front of the card displays the [attached holiday scene image] as a print.
Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
"""
)
generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
return "Done! Saved at generated_final_photo.png"
تنظیمات محیط
حالا که کد آماده است، باید مطمئن شویم که وابستگیهایمان نصب شدهاند. ما uv ، یک بسته سریع پایتون و یک مدیر پروژه، استفاده خواهیم کرد.
👉💻 در ترمینال خود، دستور زیر را اجرا کنید تا FastMCP به عنوان یک وابستگی به پروژه ما اضافه شود:
cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp
خواهید دید که یک وابستگی جدید fastmcp>=2.13.3 به ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml شما اضافه شده است.
۴. تست با Gemini CLI برای سرور MCP
حالا که کد سرور ما کامل شده است، چگونه آن را آزمایش کنیم؟
معمولاً، آزمایش یک سرور backend نیاز به ساخت یک رابط کاربری frontend یا نوشتن درخواستهای پیچیده curl دارد. با این حال، در اینجا میتوانیم از Gemini CLI استفاده کنیم.
این برای توسعه فوقالعاده مفید است زیرا منطق را ایزوله میکند. میتوانید قبل از اینکه نگران ساخت رابط وب یا چارچوب عامل باشید، تأیید کنید که مدل ابزارهای شما را درک میکند و آنها را به درستی فراخوانی میکند.
اتصال و اجرا
ما با استفاده از دستور mcp add به Gemini CLI میگوییم که سرور ما را مدیریت کند.
در ترمینال خود، دستور زیر را اجرا کنید:
gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
add holidays: ما به سرور خود یک لقب ("تعطیلات") دادیم.-
uv run ...: ما دستور صریحی برای شروع سرور پایتون که اخیراً تغییر دادهایم، ارائه دادیم.
بیایید جادو کنیم!
حالا، جلسه چت را شروع کنید:
gemini
برای بررسی اینکه آیا Gemini میتواند ابزارهای جدید شما را "ببیند"، از دستور زیر استفاده کنید. توجه داشته باشید که ممکن است لازم باشد به Gemini CLI اجازه دهید از ابزار تعطیلات ما استفاده کند.
- 👉 کاربر:
"I want to create a festive holiday photo. I like birds a lot." - جوزا:
*Thinking...* *Calling tool: generate_holiday_scene(interest='birds')* Done! Saved at generated_scene.png - 👉 کاربر:
"Great! Now generate a knitting pattern for a sweater with reindeer on it." - جوزا:
*Thinking...* *Calling tool: generate_sweater_pattern(motif='reindeer')* Done! Saved at generated_pattern.png
تصویر را بررسی کنید
- با فشردن
Control+Cرابط خط فرمان Gemini را خاتمه دهید. - تصویر تولید شده را در پوشهی
~/holiday_workshop/01-MCP-Files-Testing/01-starter/staticبررسی کنید.
عکس خود را اینجا بررسی کنید: 
نتیجهگیری و مراحل بعدی
تبریک! شما با موفقیت یک سرور MCP کارآمد ساختید. اکنون مجموعهای کاربردی از «ابزارهای هوش مصنوعی» دارید که میتوانند الگوها، تصاویر ترکیبی و صحنهها را تولید کنند.
با این حال، آیا در آزمون بالا متوجه چیزی شدید؟ شما باید فرآیند را پیش میبردید. باید صحنه را درخواست میکردید، سپس الگو را درخواست میکردید، و در نهایت درخواست ترکیب آنها را میکردید.
اگرچه Gemini هوشمند است، اما برای یک گردش کار پیچیده تولید - که در آن باید قبل از اینکه بتوانیم آن را روی ژاکت قرار دهیم، الگویی ایجاد کنیم و در صورت عدم موفقیت در تولید تصویر، خطاها را مدیریت کنیم - ما کنترل بیشتری میخواهیم. ما یک سیستم اختصاصی میخواهیم که بتواند برنامهریزی کند، کار خود را نقد کند و وضعیت کارت تبریک ما را بدون اینکه ما در هر مرحله از آن دخالت کنیم، مدیریت کند.
در بخش بعدی، به این هرج و مرج خلاقانه نظم خواهیم بخشید. ما قصد داریم کیت توسعه عامل (ADK) را برای ساخت یک عامل ساختاریافته پیادهسازی کنیم که این ابزارهای MCP را در یک خط تولید بینقص هماهنگ میکند.
۵. کدنویسی Vibe برای یک عامل ADK
ما یک مجموعه ابزار کاربردی (سرور MCP) داریم، اما در حال حاضر، ما کسانی هستیم که تمام کارهای سنگین را انجام میدهیم - به Gemini میگوییم دقیقاً کدام ابزار را و چه زمانی فراخوانی کند.
در این بخش، ما یک عامل هوش مصنوعی خواهیم ساخت: سیستمی که میتواند به صورت خودکار استدلال، برنامهریزی و وظایف چند مرحلهای را اجرا کند. برای انجام این کار، از کیت توسعه عامل (ADK) استفاده خواهیم کرد.
نماینده چیست؟
اگر ابزارهای MCP «دستها» (که کار را انجام میدهند) باشند، عامل «مغز» است. یک عامل از یک LLM برای درک قصد کاربر («برای من یک کارت تبریک درست کن») استفاده میکند، آن را به مراحلی تقسیم میکند («اول به یک صحنه نیاز دارم، سپس یک الگو...») و تصمیم میگیرد که از کدام ابزارها برای رسیدن به هدف استفاده کند.
ADK چیست؟
کیت توسعه عامل (ADK) چارچوبی از گوگل است که ساخت این عاملها را آسان میکند. این کیت، «لولهکشی» پیچیده، مانند مدیریت تاریخچه چت، اتصال به ابزارها و جابجایی بین مدلهای مختلف را مدیریت میکند - بنابراین میتوانید روی شخصیت و منطق برنامه خود تمرکز کنید.
کدگذاری ارتعاشی مبتنی بر متن
استفاده از یک اعلان واحد و عظیم برای تولید کد، الگوی رایجی است. با این حال، هنگام ساخت برنامههای پیچیده، اغلب بهتر است با هوش مصنوعی به عنوان شریکی رفتار کنید که در طول زمان، زمینه را حفظ میکند.
ما قبل از نوشتن حتی یک خط کد، از ویژگیهای حافظهی Gemini CLI برای آمادهسازی مقدمات استفاده خواهیم کرد.
۱. محیط را آماده کنید
ترمینال خود را باز کنید و به دایرکتوری starter بروید:
cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter
اجرای رابط خط فرمان Gemini:
gemini
۲. مدیریت زمینه و حافظه
هنگام کدنویسی ارتعاشی، هوش مصنوعی باید بداند که کیست و چه میداند. رابط خط فرمان Gemini به ما اجازه میدهد تا این را به صراحت مدیریت کنیم.
-
/memory show: این را تایپ کنید تا ببینید هوش مصنوعی در حال حاضر درباره پروژه و جلسه شما چه میداند. -
/memory add: از این برای تزریق دانش بنیادی که هوش مصنوعی باید در طول مکالمه به خاطر بسپارد، استفاده کنید.
بیایید با تعریف شخصیت همکار کدنویسی خود شروع کنیم. دستور زیر را در Gemini CLI اجرا کنید:
/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."
جمینی اکنون نقش خود را درک میکند. این زمینه بر هر پاسخ بعدی تأثیر خواهد گذاشت و کد سازگار با ADK با کیفیت بالا را تضمین میکند.
۳. مرحله ۱: کدگذاری ارتعاشی عامل پایه
به جای تلاش برای ایجاد کل سیستم به طور همزمان، بیایید با اسکلت شروع کنیم. ما میخواهیم ساختار فایل و شخصیت اولیه عامل را ایجاد کنیم.
دستور زیر را در Gemini CLI وارد کنید:
Let's start by building the basic agent structure.
Please create a file structure for a `root_agent`.
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant".
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.
Gemini ساختار فایل و کد اولیه پایتون را تولید میکند. آن را بررسی کنید تا مطمئن شوید که درست به نظر میرسد، سپس تغییرات را اعمال/پذیرش کنید.
۴. مرحله ۲: اضافه کردن سرور MCP (ابزارها)
حالا که یک عامل پایه داریم، باید به آن «دست» بدهیم. باید عامل را به سرور MCP که در تمرین قبلی ساختیم متصل کنیم.
دستور زیر را در Gemini CLI وارد کنید:
Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.
Gemini اکنون agent.py موجود شما را برای گنجاندن تعاریف ابزار و منطق اتصال، بازسازی میکند.
توجه: اگر میخواهید کار خود را بررسی کنید یا اگر کد تولید شده مطابق انتظار کار نمیکند، میتوانید فایلهای خود را با راهحل مرجع واقع در: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution مقایسه کنید.
۶. رابط وب عامل را اجرا کنید
ADK با یک رابط آزمایشی داخلی به نام adk web ارائه میشود. این رابط کاربری، یک رابط کاربری چت سبک را ایجاد میکند تا بتوانیم فوراً با اپراتور خود صحبت کنیم.
- اگر هنوز GeminiCLI باز است، برای بستن آن،
control+Cرا فشار دهید. اکنون در ترمینال خود (این در پوشهsolutionاست، میتوانید با اجرایuv run adk webدر پوشهstarter، بهstarterبروید تا کد خود را آزمایش کنید)، دستور زیر را اجرا کنید:cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution uv run adk web --port 8000 - Cloud Shell به شما هشدار میدهد که یک سرویس روی پورت ۸۰۰۰ در حال اجرا است. روی «پیشنمایش وب» -> «پیشنمایش روی پورت ۸۰۰۰» کلیک کنید.
عامل را آزمایش کنید
اکنون باید یک رابط چت ببینید. بیایید ببینیم که آیا نماینده ما دستورالعملهای جدید خود را دنبال میکند و به درستی به ابزارهای MCP دسترسی پیدا میکند یا خیر.
این دستورالعملها را امتحان کنید:
- «سلام! شما کی هستید؟»
- (منتظر یک واکنش پرشور و شاد باشید.)
- «برای کارت تبریک تعطیلاتم به یک پسزمینه نیاز دارم. یک روستای برفی برایش بساز.»
- (عامل باید تابع
generate_holiday_sceneفراخوانی کند . توجه کنید که چگونه به طور خودکار سبک "cute/cartoon" تعریف شده در دستورالعملهای سیستم را اعمال میکند.)
- (عامل باید تابع
- «یک الگوی ژاکت با برشهای کوچک پیتزا روی آن درست کن.»
- (عامل باید
generate_sweater_patternفراخوانی کند ).
- (عامل باید
میتوانید تصویر ایجاد شده را اینجا مشاهده کنید:
اگر تست را تمام کردید، برای خروج Control+C را فشار دهید.
نتیجهگیری و مراحل بعدی
شما اکنون با موفقیت یک عامل Google ADK را با استفاده از رویکرد آگاه از متن، "Vibe-Coded" کردهاید!
- ما Context را ایجاد کردیم: ما از
/memory addبرای تعریف یک شخصیت متخصص استفاده کردیم. - ما به صورت تکراری ساختیم: ابتدا اسکلت را ایجاد کردیم، سپس اتصالات ابزار را اضافه کردیم.
پیشنمایش وب ADK داخلی برای آزمایش عالی است، اما برای محصول نهایی خود، یک تجربه سفارشی و برندسازی شده میخواهیم. در بخش بعدی، این Agent را در یک رابط کاربری وب سفارشی ادغام خواهیم کرد.
۷. اتصال ADK با رابط کاربری
حالا که تعریف Agent را داریم، باید آن را اجرا کنیم. اینجاست که Runner و Session Service وارد عمل میشوند.
پیادهسازی
- 👉 دستور زیر را در دستور خود تایپ کنید:
cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.pyرا در ویرایشگر شما باز میکند. - عبارت
# TODO: Create Session Serviceبا کد زیر جایگزین کنید:from google.adk.sessions import InMemorySessionService from google.adk.memory import InMemoryMemoryService session_service = InMemorySessionService() memory_service = InMemoryMemoryService() - دستور
# TODO: Initialize Runnerبا دستور زیر جایگزین کنید:runner = Runner( app_name="agents", agent=christmas_agent, session_service=session_service, memory_service=memory_service, )
- خط ۱۵۸ را در
~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py( نیازی به اقدام خاصی نیست ): اگر کنجکاو هستید که برنامه چگونه پاسخ نهایی را دریافت میکند، در زیر حلقه رویدادی را مشاهده میکنید که توسط runner اجرا میشود:async for event in runner.run_async( user_id=user_id, session_id=session_id, new_message=content )
بررسی عمیق: معماری و استقرار
ما از FastAPI برای سرویسدهی به این عامل استفاده میکنیم.
- چرا FastAPI؟ : عاملها اغلب مقید به ورودی/خروجی هستند (منتظر LLMها میمانند). ماهیت ناهمگام FastAPI این مشکل را به خوبی برطرف میکند.
- بیحالتی : توجه داشته باشید که نقطه پایانی API ما بیحالت است. ما متغیرها را در محدوده سراسری ذخیره نمیکنیم. ما برای بازسازی حالت برای هر درخواست واحد، به
session_idوSessionServiceمتکی هستیم. این بدان معناست که میتوانید این را در Cloud Run (بدون سرور) مستقر کنید و مقیاس آن را به صفر برسانید!
۸. برنامه را با جادوی عامل امتحان کنید
- 👉💻 دستور زیر را در دستور خود تایپ کنید:
cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter ./start_app.sh~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.pyرا در ویرایشگر شما باز میکند. - نتیجه را مانند زیر خواهید دید:
👉👉 مطمئن شوید که روی http://localhost:5173/کلیک میکنید، یا یک پنجره جدید باز میکنید وhttp://localhost:5173/را تایپ میکنید. - سپس وبسایت با رابط چت را مشاهده خواهید کرد:
- با آپلود یک تصویر (میتواند تصویر خودتان یا حیوان خانگیتان باشد) تست کنید
- 👉 سپس بپرسید
Can you generate a picture my cat wearing snowflake pattern sweater?
- 👉💻 پس از اتمام آزمایش، برای پایان دادن به فرآیند،
control+Cرا در ترمینال فشار دهید.
اگر میبینید که همه چیز طبق انتظار کار نمیکند، میتوانید به ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution بروید و ./start_app.sh را اجرا کنید، سپس همان مراحل بالا را انجام دهید.
۹. بانک حافظه هوش مصنوعی ورتکس
حافظه کوتاه مدت در مقابل حافظه بلند مدت
- زمینه کوتاهمدت : «من الان چی گفتم؟» (تاریخچه جلسه). این با بسته شدن پنجره چت از بین میرود.
- حافظه بلندمدت : «زبان برنامهنویسی مورد علاقه من چیست؟» (ترجیحات کاربر). این باید برای همیشه باقی بماند.
بانک حافظه هوش مصنوعی ورتکس این ذخیرهسازی بلندمدت را فراهم میکند. این بانک به عامل اجازه میدهد تا اطلاعات شخصیسازیشده در مورد کاربر را ذخیره و بازیابی کند.
جلسات در مقابل بانک حافظه
- جلسات (
VertexAiSessionService): این گزارش است. این گزارش، توالی خام و زمانی هر پیام، فراخوانی ابزار و رویداد (AppendEvent،ListEvents) را ذخیره میکند. این گزارش، حقیقتِ آنچه اتفاق افتاده است را ارائه میدهد. - بانک حافظه (
VertexAiMemoryBankService): این دانش است. این دانش، حقایق بلندمدت و ترکیبی (GenerateMemories،RetrieveMemories) را ذخیره میکند. این بانک به یکuser_idخاص محدود شده است و حریم خصوصی و انزوا را تضمین میکند.
- 👉💻 دستور زیر را در دستور خود تایپ کنید:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.pyرا در ویرایشگر شما باز میکند. -
# TODO: Create Vertex AI Session Service & Memory Bank Serviceپیدا کنید، کل خط را با موارد زیر جایگزین کنید:session_service = VertexAiSessionService( project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID ) memory_service = VertexAiMemoryBankService( project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID )
- 👉💻 دستور زیر را در دستور خود تایپ کنید:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.pyرا در ویرایشگر شما باز میکند. - عبارت
# TODO: Set Up Configurationبا کد زیر جایگزین کنید:# Basic configuration types MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig SimilaritySearchConfig = ( types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig ) GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig # Advanced configuration types CustomizationConfig = types.MemoryBankCustomizationConfig MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample ConversationSource = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource ) ConversationSourceEvent = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent ) ExampleGeneratedMemory = ( types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory )
- 👉 در همان فایل:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. به دنبال# TODO: Set up topicبگردید، کل خط را با کد زیر جایگزین کنید:custom_topics = [ # Topic 1: Sweater Preference MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="sweater_preference", description="""Extract the user's preferences for sweater styles, patterns, and designs. Include: - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.) - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted) - Color preferences (red, green, navy, pastel, etc.) - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft) - Themes (retro, modern, ugly christmas sweater, elegant) Example: "User wants a retro style sweater with a pixelated reindeer pattern." Example: "User prefers dark blue colors and hates itchy wool." """, ) ), # Topic 2: Personal Context MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="personal_context", description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include: - Hobbies and activities (skiing, reading, gaming, cooking, etc.) - Pets (type, breed, name, color) - Job or profession if relevant to their style - General interests (sci-fi, nature, vintage, tech) - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach) Example: "User has a golden retriever named Max." Example: "User loves skiing and wants a snowy mountain background." Example: "User is a software engineer who likes cyberpunk aesthetics." """, ) ) ] - 👉 در همان فایل:
04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. به دنبال# TODO: Create Agent Engineبگردید، کل خط را با کد زیر جایگزین کنید:agent_engine = client.agent_engines.create( config={ "display_name": AGENT_DISPLAY_NAME, "context_spec": { "memory_bank_config": { "generation_config": { "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash" }, "customization_configs": [customization_config] } }, } )
چرا فقط از Prompt استفاده نمیکنیم؟
ممکن است بپرسید، «چرا فقط تاریخچه کاربر را در اعلان وارد نمیکنیم؟»
- محدودیتهای اندازه : پنجرههای Context بزرگ هستند، اما بینهایت نیستند. شما نمیتوانید ۵ سال سابقه را در آنها جای دهید.
- هزینه : پردازش ۱ میلیون توکن برای هر «سلام» فوقالعاده گران است.
- تمرکز : بانک حافظه به عنوان یک موتور جستجو برای نماینده شما عمل میکند. این بانک فقط حقایق مرتبط را بازیابی میکند.
- 👉💻 دستور زیر را در دستور خود تایپ کنید:
cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pyرا در ویرایشگر شما باز میکند. - در فایل:
~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.pyعبارت# TODO: Add PreloadMemoryToolبا عبارت زیر جایگزین کنید:if USE_MEMORY_BANK: agent_tools.append(PreloadMemoryTool())
PreloadMemoryTool و add_session_to_memory
در agent.py ، دو جزء کلیدی را مشاهده خواهید کرد:
-
PreloadMemoryTool): این ابزاری است که به عامل اجازه میدهد تا «خودش را در گوگل جستجو کند.» اگر کاربر سوال مبهمی مانند «قهوه همیشگیام را برایم بیاور» بپرسد، عامل میتواند قبل از پاسخ دادن، از این ابزار برای پرسوجو از بانک حافظه در مورد «ترجیحات قهوه» استفاده کند. -
add_session_to_memory: این یک فراخوانی پسزمینه است.- چرا ناهمگام؟ ذخیره حافظه زمان میبرد (خلاصه کردن چت، استخراج حقایق). ما نمیخواهیم کاربر منتظر این بماند. ما آن را در پسزمینه (
add_session_to_memory) با استفادهafter_agent_callbackاجرا میکنیم.
- چرا ناهمگام؟ ذخیره حافظه زمان میبرد (خلاصه کردن چت، استخراج حقایق). ما نمیخواهیم کاربر منتظر این بماند. ما آن را در پسزمینه (
۱۰. بانک حافظه در عمل
- 👉💻 دستور زیر را در دستور خود تایپ کنید:
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./use_memory_bank.sh
فایل ~/holiday_workshop/.envرا بررسی کنید، خواهید دید ( نیازی به انجام کاری نیست )USE_MEMORY_BANK=TRUE AGENT_ENGINE_ID={agent_engine_id} - 👉💻 حافظه را با رابط کاربری برنامه آزمایش کنید. دستور زیر را در دستور خود تایپ کنید:
cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter ./start_app.shhttp://localhost:5173/کلیک میکنید، یا یک پنجره جدید باز کنید وhttp://localhost:5173/را تایپ کنید. توجه داشته باشید کهUvicorn running on http://0.0.0.0:8000، فقط سرور backend است، نه لینک واقعی که میخواهیم روی آن کلیک کنیم. اکنون رابط چت در وبسایت به عامل شخصیسازیشده شما تبدیل شده است! - 👉 تست حافظه. اگر در رابط کاربری تایپ کنید:
I want a sweater that matches my dog. He's a golden retriever.I'm a programmer, so I want something geeky. Maybe a matrix style?I like snowflake sweater pattern
عامل این را به عنوان یک ترجیح شناسایی کرده و آن را در بانک حافظه ذخیره میکند.
هفتهی بعد (یا هر زمان که برنامه را با Control+C و ./start_app.sh مجدداً راهاندازی کنید)، اگر بپرسید:
what is my preference on sweater pattern?
عامل، بانک حافظه را بررسی میکند، ترجیح شما را میبیند و بدون اینکه از او خواسته شود، الگوی ژاکت را تولید میکند. 
- با مراجعه به Google Cloud Console Agent Engine ، در Vertex AI Agent Engine تأیید کنید
- مطمئن شوید که پروژه را از انتخابگر پروژه در بالا سمت چپ انتخاب میکنید:
- و موتور عاملی که از دستور قبلی
use_memory_bank.shمستقر کردهاید را تأیید کنید.
روی موتور عاملی که تازه ایجاد کردهاید کلیک کنید.
- مطمئن شوید که پروژه را از انتخابگر پروژه در بالا سمت چپ انتخاب میکنید:
- روی برگه
Memoriesدر این عامل مستقر کلیک کنید، میتوانید تمام حافظه را در اینجا مشاهده کنید.
تبریک میگویم! شما همین الان بانک حافظه را به دستگاه خود متصل کردید!
۱۱. نتیجهگیری
خلاصه
شما با موفقیت یک سیستم عامل کامل را معماری و ساختهاید.
- اتصال : شما از MCP برای استانداردسازی نحوه دسترسی عامل خود به ابزارهای محلی استفاده کردید.
- ارکستراسیون : شما از ADK برای مدیریت حلقه استدلال پیچیده مورد نیاز برای وظایف چند مرحلهای استفاده کردید.
- شخصیسازی : شما از بانک حافظه برای ایجاد یک لایه پایدار و یادگیرنده که زمینه کاربر را به خاطر میسپارد، استفاده کردید.
مراحل بعدی
- سرور MCP خودتان را بسازید : یک سرور برای API یا پایگاه داده داخلی خود ایجاد کنید.
- الگوهای ADK را بررسی کنید : در مستندات ADK درباره «حلقههای استدلال» و «ارکستراسیون» اطلاعات کسب کنید.
- استقرار : عامل خود را از یک اسکریپت محلی به یک سرویس تولید در Cloud Run ببرید.