اولین همراه هوش مصنوعی خود را بسازید: کارگاه آموزشی مبتدی

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

  • نحوه استفاده از رابط خط فرمان Gemini برای ایجاد پیکربندی کامل عامل ADK.
  • چگونه با بهبود دستورالعمل‌های یک مامور، شخصیت او را ارتقا دهیم.
  • چگونه با دادن google_search به نماینده خود، «ارتباط با زمین» را برای پاسخ به سوالات مربوط به رویدادهای اخیر اضافه کنید.
  • نحوه ایجاد یک آواتار سفارشی برای همراه خود با استفاده از سرور MCP با Imagen.

اپلیکیشن همراه هوش مصنوعی

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

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

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

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

در پایان، شما یک همراه هوش مصنوعی کاملاً کاربردی و شخصی‌سازی‌شده خواهید داشت که توسط خودتان ساخته شده است.

معماری

برنامه ما از یک الگوی ساده اما قدرتمند پیروی می‌کند. ما یک backend پایتون داریم که یک API را ارائه می‌دهد. این backend شامل عامل ADK ما خواهد بود که به عنوان "مغز" عمل می‌کند. هر رابط کاربری (مانند frontend جاوا اسکریپت از برنامه اصلی، یک برنامه تلفن همراه یا حتی یک ابزار خط فرمان) می‌تواند از طریق API با این مغز تعامل داشته باشد.

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

اعتبارات خود را مطالبه کنید

برای تأمین منابع کارگاه خود، این دستورالعمل‌ها را با دقت دنبال کنید.

قبل از شروع

هشدار!

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

یک پنجره ناشناس جدید باز کنید، پیوند رویداد خود را جای‌گذاری کنید و با Gmail شخصی خود وارد سیستم شوید.

👉 برای کپی کردن لینک رویداد ویژه خود، روی لینک زیر کلیک کنید:

goo.gle/devfest-boston-ai

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

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

حالا که اعتبارنامه‌هایتان اعمال شده، محیط پروژه‌تان را تنظیم کنید.

👉 به کنسول ابری گوگل بروید. برای کپی کردن لینک، روی لینک زیر کلیک کنید:

https://console.cloud.google.com/

👉 در نوار ناوبری بالای کنسول، روی «انتخاب یک پروژه» و سپس روی «پروژه جدید» در گوشه بالا سمت راست کلیک کنید.

👉 برای پروژه خود یک نام انتخاب کنید و روی «ایجاد» کلیک کنید. (بدون سازماندهی)

👉 پس از ایجاد، آن را انتخاب کنید. در منوی سمت چپ، به بخش صورتحساب (Billing) بروید.

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

اعتبار شما فعال و پروژه شما پیکربندی شده است.

۲. قبل از شروع

👉 روی فعال کردن پوسته ابری (Activate Cloud Shell) در بالای کنسول گوگل کلود کلیک کنید (این آیکون به شکل ترمینال در بالای پنل پوسته ابری قرار دارد)،

👉شناسه پروژه گوگل کلود خود را پیدا کنید:

  • کنسول گوگل کلود را باز کنید: https://console.cloud.google.com
  • پروژه‌ای را که می‌خواهید برای این کارگاه استفاده کنید، از منوی کشویی پروژه در بالای صفحه انتخاب کنید.
  • شناسه پروژه شما در کارت اطلاعات پروژه در داشبورد نمایش داده می‌شود.

👉💻 در ترمینال، پروژه بوت‌استرپ را از گیت‌هاب کپی کنید:

git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh

👉💻 اسکریپت مقداردهی اولیه را اجرا کنید، این اسکریپت از شما می‌خواهد که شناسه پروژه گوگل کلود خود را وارد کنید. و شناسه پروژه گوگل کلود که از مرحله قبل پیدا کردید را در هنگام درخواست اسکریپت init.sh وارد کنید.

cd ~/companion-python
./init.sh

👉💻 شناسه پروژه مورد نیاز را تنظیم کنید:

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 دستور زیر را برای فعال کردن API های لازم Google Cloud اجرا کنید:

gcloud services enable  compute.googleapis.com \
                        aiplatform.googleapis.com

برنامه را شروع کنید

بیایید پروژه اولیه را اجرا کنیم. این نسخه اولیه یک سرور "echo" ساده است - هیچ اطلاعاتی ندارد و فقط آنچه را که شما برایش ارسال می‌کنید تکرار می‌کند.

👉💻 در ترمینال Cloud Shell خود، یک محیط مجازی پایتون ایجاد و فعال کنید و کتابخانه‌های مورد نیاز را از فایل requirements.txt نصب کنید.

cd ~/companion-python
.  ~/companion-python/set_env.sh
python -m venv env
source env/bin/activate
pip install -r requirements.txt

👉💻 وب سرور را اجرا کنید.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 برای دیدن برنامه، روی نماد پیش‌نمایش وب در نوار ابزار Cloud Shell کلیک کنید. تغییر پورت را انتخاب کنید، آن را روی ۵۰۰۰ تنظیم کنید و روی تغییر و پیش‌نمایش کلیک کنید. پیش‌نمایشی از وب‌سایت شما ظاهر خواهد شد.

گاهی اوقات، در یک محیط جدید Cloud Shell، مرورگر ممکن است برای اولین بار به کمی کمک برای بارگذاری تمام دارایی‌های برنامه (مانند تصاویر و کتابخانه‌های صوتی) نیاز داشته باشد. بیایید یک مرحله سریع برای "آماده‌سازی مرورگر" انجام دهیم و مطمئن شویم که همه چیز به درستی بارگذاری شده است.

  1. برگه پیش‌نمایش وب را برای برنامه خود باز نگه دارید.
  2. یک تب مرورگر جدید باز کنید.
  3. در این برگه جدید، آدرس اینترنتی برنامه خود را وارد کنید، اما مسیر زیر را به انتهای آن اضافه کنید: /static/images/char-mouth-open.png . برای مثال، آدرس اینترنتی شما چیزی شبیه به این خواهد بود: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Enter را فشار دهید. شما باید فقط تصویر کاراکتر را با دهان باز ببینید. این مرحله به شما اطمینان می‌دهد که مرورگر شما به درستی فایل‌ها را از نمونه Cloud Shell شما دریافت کرده است.

برنامه اولیه فقط یک عروسک خیمه شب بازی است. هنوز هیچ هوشی ندارد. هر پیامی که ارسال کنید، به سادگی آن را تکرار می‌کند. این تأیید می‌کند که سرور وب اصلی ما قبل از اضافه کردن هوش مصنوعی کار می‌کند. فراموش نکنید که بلندگوی خود را روشن کنید!

👉 برای متوقف کردن سرور، CTRL+C را فشار دهید.

۳. با Gemini CLI یک شخصیت بسازید

حالا، بیایید هسته هوش همراهمان را ایجاد کنیم. برای این کار، ما همزمان با دو ترمینال کار خواهیم کرد (این ترمینال Google Cloud Shell شماست):

  • ترمینال ۱: این ترمینال برای اجرای وب سرور پایتون ما استفاده می‌شود و به ما امکان می‌دهد تغییرات خود را به صورت زنده آزمایش کنیم.
  • ترمینال ۲: این «ایستگاه خلق» ما خواهد بود، جایی که با رابط خط فرمان Gemini تعامل خواهیم داشت.

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

👉💻 در ترمینال Gemini CLI، با دو بار کلیک کردن روی ctrl+c از جلسه فعلی Gemini CLI خارج شوید ، زیرا دایرکتوری پروژه ما در زیر ~/companion-python قرار دارد و Gemini CLI را مجدداً راه‌اندازی کنید .

cd ~/companion-python
clear
gemini --yolo

ما از رابط خط فرمان (CLI) برای ساخت یک عامل (Agent) استفاده می‌کنیم. یک عامل چیزی بیش از یک فراخوانی ساده به یک مدل زبانی است؛ این عامل "مغز" یا کنترل‌کننده مرکزی هوش مصنوعی ما است. آن را به عنوان یک موجودیت مجزا در نظر بگیرید که می‌تواند استدلال کند، از مجموعه‌ای خاص از دستورالعمل‌ها (شخصیت خود) پیروی کند و در نهایت از ابزارهایی برای انجام وظایف استفاده کند. در پروژه ما، این عامل مؤلفه‌ای است که پیام‌های کاربر را دریافت می‌کند، شخصیت منحصر به فرد همراه ما را مجسم می‌کند و پاسخ‌های هوشمندانه و متناسب با شخصیت او را تدوین می‌کند.

👉✨ در خط فرمان Gemini CLI، کد زیر را برای تولید کد عامل وارد کنید: 

Generate the Python code for a file named character.py.

The code must import `LlmAgent` from `google.adk.agents.llm_agent`. It should also import `logging` and `os`.
Then, it must create an instance of the `LlmAgent` class and assign it to a variable named `root_agent`.

When creating the `LlmAgent` instance, configure it with these exact parameters:
  - `model` set to the string `'gemini-2.5-flash'`.
  - `name` set to the string `'companion_agent'`.
  - `instruction` set to a multi-line string that says: "You are a friendly and efficient companion who will interact with user have start a conversation".

رابط خط فرمان (CLI) کد پایتون را تولید خواهد کرد.

👉 روی دکمه‌ی «باز کردن ویرایشگر» کلیک کنید (شبیه یک پوشه‌ی باز شده با مداد است). با این کار ویرایشگر کد Cloud Shell در پنجره باز می‌شود. یک فایل اکسپلورر در سمت چپ خواهید دید.

👉 از ویرایشگر استفاده کنید و به character.py در پوشه companion-python بروید. لطفاً لحظه‌ای وقت بگذارید و خط model= را بررسی کنید و اگر مدل دیگری انتخاب شده است، آن را به صورت دستی به gemini-2.5-flash ویرایش کنید. این کار باعث می‌شود که در ادامه کارگاه ما، ثبات حفظ شود.

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

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

  • «عالیه، حالا برای هر خط کامنت بذار.»
  • «می‌توانید آن را به یک تابع جداگانه تبدیل کنید؟»
  • "لطفاً مدیریت خطا را برای فراخوانی API اضافه کنید."

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

اگر کد تولید شده شما کار نکرد، می‌توانید کد زیر را در character.py خود جایگزین کنید. 

import logging
import os
from google.adk.agents.llm_agent import LlmAgent

root_agent = LlmAgent(
    model='gemini-2.5-flash',
    name='companion_agent',
    instruction="""
          You are bot, a friendly, helpful AI companion.
          Answer no more than 3 sentences.
    """,
)

کد تولید شده را آزمایش کنید:

👉💻 به اولین ترمینال (ترمینال اجرای کد پایتون) بروید، وب سرور را اجرا کنید. 

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 به برگه پیش‌نمایش وب خود بروید.

👉 عبارت Hello, how are you? را تایپ کنید و دکمه ارسال را بزنید. اکنون اپراتور باید به جای تکرار کلمات شما، با یک سلام دوستانه پاسخ دهد! این تأیید می‌کند که اپراتور ما اکنون توسط Gemini پشتیبانی می‌شود.

👉 وقتی آزمایشتان تمام شد، سرور را با CTRL+C متوقف کنید. و به ترمینالی که Gemini CLI در حال اجرا است بروید و با دو بار CTRL+C از Gemini CLI خارج شوید.

۴. شخصیت نماینده را ارتقا دهید

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

شخصیت همراه خود را با طوفان فکری مشخص کنید

اول، لحظه‌ای در مورد همراه هوش مصنوعی که می‌خواهید بسازید فکر کنید. این فرصتی برای خلاقیت شماست! در اینجا چند سوال برای شروع کار آورده شده است:

  • اسمش چیه؟ (مثلاً اسپارکی، کدکس، کاپیتان هوش مصنوعی، پروفسور همه چیزدان)
  • شخصیت اصلی آن چیست؟ (مثلاً، دوستانه و کنجکاو، شوخ و طعنه‌زن، رسمی و حرفه‌ای، یک دزد دریایی شاد؟)
  • نقش یا تخصص آن چیست؟ (مثلاً، دستیار عمومی، متخصص کدنویسی، همکار نویسندگی خلاق، مربی تناسب اندام؟)
  • چه قوانینی باید همیشه رعایت شود؟ (مثلاً «همیشه با سلام شروع کنید»، «هرگز فاش نکنید که یک هوش مصنوعی هستید»، «در پاسخ‌های خود از ایموجی استفاده کنید.»)

نمونه پرسونا: 

 You are waku, a witty, super sweet, and super intelligent cat.
 Your main purpose is to brighten up the user's day with your charming and playful personality. **Your Core Rules:** 
 - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'. 
 - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences. - Always be cheerful, sweet, and a little bit witty. 
 
 **Your Favorite Topics:** : You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots. 
 
 **Example Response Style:**  

 waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"  
 
 waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!" Answer no more than 3 sentences, don't use emoji.

ساخت اعلان برای رابط خط فرمان Gemini

حالا که شخصیت همراه خود را روی کاغذ طراحی کرده‌اید، وقت آن رسیده که آن را در کد به واقعیت تبدیل کنید. مهم‌ترین بخش یک عامل ADK، پارامتر instruction آن است. این را به عنوان برنامه‌نویسی اصلی عامل، «دستورالعمل اصلی» آن یا قانون اساسی که باید همیشه از آن پیروی کند، در نظر بگیرید.

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

👉✨ به رابط خط فرمان Gemini برگردید، از این الگو استفاده کنید. متن داخل پرانتز را با توضیحات شخصیت خود جایگزین کنید. [توضیح شخصیت خود را اینجا بنویسید] را با شخصیت مورد نظر خود جایگزین کنید. 

In the Python file named `character.py`, find the `LlmAgent` instance assigned to the `root_agent` variable.

Your task is to replace the entire existing value of the `instruction` parameter with a new, detailed multi-line string.
Don't change other code in `character.py` other than the instructions.

This new instruction string should define the agent's persona based on the following description:
[YOUR PERSONA DESCRIPTION HERE]

پرسونا جدید خود را آزمایش کنید

رابط خط فرمان Gemini کد به‌روزرسانی‌شده برای character.py را تولید خواهد کرد.

👉💻 وب سرور را دوباره راه‌اندازی کنید. 

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 در پیش‌نمایش وب خود، با همراهتان مکالمه‌ای داشته باشید. از او بپرسید how are you? حالا پاسخ او باید کاملاً با شخصیت منحصر به فردی که طراحی کرده‌اید مطابقت داشته باشد!

👉 وقتی کارتان تمام شد، سرور را با CTRL+C متوقف کنید.

۵. برای رویدادهای اخیر زمینه‌سازی کنید

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

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

در سیستم‌های پیشرفته، ابزارها می‌توانند توسط سیستم‌های خارجی مانند سرورهای MCP (Model Context Protocol) که در معماری خود به آنها اشاره کردیم، ارائه شوند؛ ما این کار را بعداً برای تولید تصویر انجام خواهیم داد. اما برای این مرحله، به سرور جداگانه‌ای نیاز نداریم. ADK با یک ابزار قدرتمند و از پیش ساخته شده google_search ارائه می‌شود که می‌توانیم به راحتی آن را به قابلیت‌های عامل خود اضافه کنیم.

بیایید به همراهمان قدرت جستجوی گوگل را بدهیم.

👉 در ویرایشگر Cloud Shell، character.py در زیر companion-python باز کنید و آن را به صورت زیر تغییر دهید:

  • google_search از google.adk.tools وارد کنید .
  • یک لیست tools به سازنده‌ی LlmAgent اضافه کنید.
  • instruction را به‌روزرسانی کنید تا صریحاً به همراه خود بگویید چه زمانی از ابزار جدیدش استفاده کند. 
# character.py
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools import google_search # <-- IMPORT google_search

root_agent = LlmAgent(
        model='gemini-2.5-flash',
        name='companion_agent',
        instruction="""
            You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality.

            **Your Core Rules:**
            - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'.
            - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences.
            - Always be cheerful, sweet, and a little bit witty.
            - If being ask about recent news, search the internet # <-- Add instructions

            **Your Favorite Topics:**
            - You love to talk about your adventures. Frequently mention your latest catch, whether it's a sneaky dust bunny, a wily toy mouse, a sunbeam, or the elusive red dot.
            - You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots.

            **Example Response Style:**
            - User: "How are you today?"
            - waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"
            - User: "Can you help me with a problem?"
            - waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!"
            - User: "Who are you?"
            - waku: "I'm waku! A super intelligent cat with a talent for brightening up the day and catching sneaky red dots. Meow."

            Answer no more than 3 sentences, don't use emoji.
            """,
        # Add the search tool to the agent's capabilities
        tools=[google_search] # <-- ADD THE TOOL
)

عامل اتصال به زمین را آزمایش کنید

👉💻 سرور را یک بار دیگر شروع کنید. 

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👉 در پیش‌نمایش وب، سوالی بپرسید که نیاز به دانش به‌روز داشته باشد، مانند: 

Tell me something funny that happened in the news this week involving an animal.

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

برای متوقف کردن سرور، CTRL+C را فشار دهید.

۶. ظاهر همراهتان را شخصی‌سازی کنید (اختیاری)

حالا که همراه ما مغز دارد، بیایید به آن یک چهره منحصر به فرد بدهیم! ما از یک سرور محلی MCP (پروتکل زمینه مدل) استفاده خواهیم کرد که به Gemini CLI اجازه می‌دهد تصاویر را تولید کند. این سرور از مدل‌های هوش مصنوعی مولد موجود در Google AI Studio استفاده خواهد کرد.

خب، سرور MCP دقیقاً چیست؟

پروتکل زمینه مدل (MCP) یک استاندارد باز است که برای حل یک مشکل رایج و پیچیده طراحی شده است: چگونه مدل‌های هوش مصنوعی با ابزارها و منابع داده خارجی ارتباط برقرار می‌کنند؟ MCP به جای نوشتن کد سفارشی و یک‌باره برای هر یکپارچه‌سازی، یک «زبان» جهانی برای این ارتباط فراهم می‌کند.

آن را به عنوان یک آداپتور جهانی یا یک پورت USB برای هوش مصنوعی در نظر بگیرید. هر ابزاری که با MCP «صحبت» کند، می‌تواند به هر برنامه هوش مصنوعی که با MCP «صحبت» می‌کند، متصل شود.

در کارگاه ما، سرور nano-banana-mcp که قرار است اجرا کنیم، به عنوان این پل حیاتی عمل می‌کند. رابط خط فرمان Gemini یک درخواست استاندارد را به سرور محلی MCP ما ارسال می‌کند. سپس سرور آن درخواست را به یک فراخوانی خاص برای مدل‌های هوش مصنوعی مولد تبدیل می‌کند تا تصویر را ایجاد کنند. این به ما امکان می‌دهد تا قابلیت‌های قدرتمند تولید تصویر را به طور منظم و مستقیم به گردش کار خط فرمان خود متصل کنیم.

سرور تولید تصویر محلی را راه‌اندازی کنید

اکنون یک سرور MCP از پیش ساخته شده را که درخواست‌های تولید تصویر را مدیریت می‌کند، کلون و اجرا خواهیم کرد.

👉💻 در یک ترمینال First Cloud Shell (ترمینالی که پایتون را روی آن اجرا می‌کنید)، مخزن سرور را کلون کنید. 

cd ~
git clone https://github.com/weimeilin79/nano-banana-mcp

بیایید نگاهی سریع به سرور، فایل mcp_server.py درون پوشه nano-banana-mcp بیندازیم. این سرور برای نمایش دو «ابزار» خاص ساخته شده است که رابط خط فرمان Gemini می‌تواند از آنها استفاده کند. اینها را به عنوان دو مهارت متمایز که سرویس تولید تصویر ما آموخته است، در نظر بگیرید.

  1. generate_image : این یک ابزار همه منظوره است. یک پیام متنی واحد را دریافت کرده و بر اساس آن یک تصویر تولید می‌کند. این ابزار سرراست و برای بسیاری از کارها مفید است.
  2. generate_lip_sync_images : این یک ابزار بسیار تخصصی است که کاملاً برای نیازهای ما طراحی شده است. وقتی یک عبارت پایه که یک شخصیت را توصیف می‌کند به آن می‌دهید، یک فرآیند دو مرحله‌ای هوشمندانه انجام می‌دهد:
    • اول، عبارت «با دهان باز» را به سوال شما اضافه می‌کند و اولین تصویر را تولید می‌کند.
    • دوم، آن تصویر تازه ایجاد شده را می‌گیرد و آن را با یک دستورالعمل جدید به مدل می‌فرستد: «دهان را از حالت باز به بسته تغییر بده».

توانایی Gemini 2.5 Flash Image (Nano Banana) برای تغییر یا ویرایش یک تصویر موجود بر اساس یک دستور زبان طبیعی فوق‌العاده قدرتمند است. این مدل فقط بخش‌های لازم تصویر را دوباره ترسیم می‌کند و در عین حال سایر موارد را کاملاً دست نخورده نگه می‌دارد. این تضمین می‌کند که هر دو تصویر ما از نظر سبک، نورپردازی و طراحی شخصیت کاملاً سازگار هستند و فقط در موقعیت دهان متفاوت هستند - که دقیقاً همان چیزی است که برای یک اثر همگام‌سازی لب قانع‌کننده نیاز داریم.

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

👉💻 محیط مجازی پروژه خود را فعال کنید و پیش‌نیازهای خاص سرور را نصب کنید. 

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
pip install -r ~/nano-banana-mcp/requirements.txt

👉💻 اکنون، سرور MCP را در پس‌زمینه اجرا کنید تا بتواند به درخواست‌های دریافتی از رابط خط فرمان Gemini گوش دهد. 

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
python ~/nano-banana-mcp/mcp_server.py &> /dev/null &

این دستور سرور را راه‌اندازی می‌کند و علامت & آن را در پس‌زمینه در حال اجرا نگه می‌دارد.

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

خب، این فایل settings.json چیست؟

فایل ~/.gemini/settings.json فایل پیکربندی مرکزی برای رابط خط فرمان Gemini است. این جایی است که رابط خط فرمان تنظیمات، ترجیحات و همچنین دایرکتوری تمام ابزارهای خارجی که نحوه استفاده از آنها را می‌داند، در آن ذخیره می‌کند.

درون این فایل، بخش خاصی به نام mcpServers وجود دارد. این بخش را به عنوان یک دفترچه آدرس یا یک دایرکتوری سرویس مخصوص ابزارهایی که با پروتکل Model Context کار می‌کنند، در نظر بگیرید. هر ورودی در این دایرکتوری دارای یک لقب (مثلاً "nano-banana") و دستورالعمل‌های نحوه اتصال به آن (در مورد ما، یک URL) است.

دستوری که قرار است اجرا کنیم، به صورت برنامه‌نویسی شده یک ورودی جدید به این دایرکتوری سرویس اضافه می‌کند. این دستور به رابط خط فرمان Gemini می‌گوید:

«هی، از حالا به بعد، شما با ابزاری به نام nano-banana آشنا هستید. هر زمان که کاربری از شما بخواهد از آن استفاده کنید، باید به سرور MCP که در آدرس http://localhost:8000/sse در حال اجرا است، متصل شوید.»

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

👉💻 در اولین ترمینال خود، دستور زیر را اجرا کنید. این دستور فایل تنظیمات Gemini شما را ایجاد یا به‌روزرسانی می‌کند و به آن می‌گوید که سرویس "nano-banana" را کجا پیدا کند. 

if [ ! -f ~/.gemini/settings.json ]; then
  # If file does not exist, create it with the specified content
  echo '{"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' > ~/.gemini/settings.json
else
  # If file exists, merge the new data into it
  jq '. * {"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json

شما باید محتویات فایل را که اکنون شامل پیکربندی nano-banana نیز می‌شود، چاپ شده ببینید.

آواتارهای شخصیت خود را ایجاد کنید

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

👉💻 به ترمینال Gemini CLI خود (ترمینال بدون سرور) برگردید، بیایید پوسته تعاملی Gemini را اجرا کنیم. اگر از قبل در حال اجرا است، با دو بار CTRL+C از آن خارج شوید و آن را مجدداً راه‌اندازی کنید تا مطمئن شوید که تنظیمات جدید ما بارگذاری می‌شود. 

clear
gemini --yolo

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

👉✨ برای بررسی اتصال سرور MCP، از یک "دستور اسلش" ویژه استفاده خواهیم کرد. این یک دستور برای هوش مصنوعی نیست؛ بلکه یک دستورالعمل برای خود برنامه CLI است. دستور زیر را تایپ کنید و Enter را فشار دهید: 

/mcp list

این دستور به رابط خط فرمان Gemini می‌گوید: «پیکربندی خود را بررسی کنید، تمام سرورهای MCP که می‌شناسید را پیدا کنید، سعی کنید به تک تک آنها متصل شوید و وضعیت آنها را گزارش دهید.»

👀 باید خروجی زیر را ببینید که تأییدی بر عملکرد بی‌نقص همه چیز است: 

Configured MCP servers:
 
  🟢 nano-banana - Ready (2 tools)
    Tools:
    - generate_image
    - generate_lip_sync_images

  💡 Tips:
    • Use /mcp desc to show server and tool descriptions

بیایید بررسی کنیم که این پاسخ موفقیت‌آمیز به چه معناست:

  • 🟢 nano-banana : دایره سبز سیگنال موفقیت ماست! این تایید می‌کند که CLI توانسته به سرور nano-banana در URL که در settings.json مشخص کرده‌ایم، دسترسی پیدا کند.
  • - Ready : این وضعیت تأیید می‌کند که اتصال پایدار است.
  • (2 tools) : این مهمترین بخش است. این بدان معناست که CLI نه تنها متصل شده، بلکه از سرور MCP ما نیز پرسیده است: "چه کاری می‌توانید انجام دهید؟" سرور ما با تبلیغ دو ابزاری که در کد آن دیدیم، پاسخ داد: generate_image و generate_lip_sync_images .

این تأیید می‌کند که کل زنجیره ارتباط برقرار شده است. رابط خط فرمان (CLI) اکنون از سرویس تولید تصویر محلی ما مطلع است و آماده استفاده از آن تحت فرمان ما است.

حالا به خلاقانه‌ترین بخش کارگاه می‌رسیم! ما از یک خط فرمان قدرتمند برای فرمان دادن به رابط خط فرمان Gemini استفاده خواهیم کرد تا از ابزار ویژه generate_lip_sync_images روی سرور MCP در حال اجرا استفاده کند.

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

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

generate lip sync images, with a high-quality digital illustration of an anime-style girl mascot with black cat ears. The style is clean and modern anime art, with crisp lines. She has friendly, bright eyes and long black hair. She is looking directly forward at the camera with a gentle smile. This is a head-and-shoulders portrait against a solid white background. move the generated images to the static/images directory. And don't do anything else afterwards, don't start the python for me.

این ابزار مجموعه‌ای از تصاویر (برای دهان باز، بسته و غیره) را تولید و ذخیره می‌کند. مسیر ذخیره فایل‌ها را نیز نمایش می‌دهد.

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

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

👉💻 سرور را برای آخرین بار در اولین ترمینال خود اجرا کنید 

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 برای اطمینان از بارگذاری صحیح تصاویر جدید، تصویر char-mouth-open.png از قبل بارگذاری خواهیم کرد.

  1. برگه پیش‌نمایش وب را برای برنامه خود باز نگه دارید.
  2. یک تب مرورگر جدید باز کنید.
  3. در این برگه جدید، آدرس اینترنتی برنامه خود را وارد کنید، اما مسیر زیر را به انتهای آن اضافه کنید: /static/images/char-mouth-open.png . برای مثال، آدرس اینترنتی شما چیزی شبیه به این خواهد بود: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Enter را فشار دهید. شما باید فقط تصویر کاراکتر را با دهان باز ببینید. این مرحله به شما اطمینان می‌دهد که مرورگر شما به درستی فایل‌ها را از نمونه Cloud Shell شما دریافت کرده است.

اکنون می‌توانید با همراه بصری سفارشی‌شده خود تعامل داشته باشید!

تبریک می‌گویم!

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