با عامل هوش مصنوعی که در سراسر Google Workspace دردسترس است، سفر برنامه‌ریزی کنید

سطح کدنویسی: پیشرفته
مدت: ۴۵ دقیقه
نوع پروژه: برافزای Google Workspace توسعه Chat، Gmail، تقویم، Drive، سندنگار، کاربرگ‌نگار، و اسلایدنگار.

این آموزش نشان می‌دهد چگونه عاملان هوش مصنوعی را به‌عنوان برافزاهای Google Workspace بااستفاده از Apps Script یا نقاط پایانی HTTP در Google Workspace منتشر کنید. پس‌از انتشار برافزا، کاربران شما می‌توانند در گردش‌های کاری خود با عوامل هوش مصنوعی تعامل داشته باشند.

نمای کلی

در این آموزش، نمونه «پشتیبانی تخصصی سفر» را از Agent Development Kit (ADK) مستقر می‌کنید. ‫Travel Concierge هوش مصنوعی چندعاملی مکالمه‌ای است که از ابزارهایی مثل Google Maps Platform Places API، «پایه جستجوی Google»، و سرور «پروتکل بافتار مدل» (MCP) استفاده می‌کند.

‫ADK به‌طور پیش‌فرض میاناهای گپ و نوشتاری را برای توسعه‌دهندگان فراهم می‌کند. در این آموزش گام‌به‌گام، به برنامه‌های Google Workspace «میانای کاربر گرافیکی» (GUI) اضافه می‌کنید که کاربران شما می‌توانند مستقیماً در Chat، ‏Gmail، «تقویم»، Drive، «سندنگار»، «کاربرگ‌نگار»، و «اسلایدنگار» به آن دسترسی داشته باشند.

  • استفاده از عامل هوش مصنوعی Chat برای طوفان فکری ایده‌های سفر.
    شکل ۱. استفاده از عامل هوشواره‌ای Chat برای طوفان فکری ایده‌های سفر.
  • استفاده از نماینده هوش مصنوعی Gmail برای برنامه‌ریزی سفر از بافت ایمیل انتخاب‌شده.
    شکل ۲. استفاده از نماینده هوش مصنوعی Gmail برای برنامه‌ریزی سفر از بافت ایمیل انتخاب‌شده.

اهداف

  • محیط را راه‌اندازی کنید.
  • عامل هوشواره‌ای را پیاده‌سازی کنید.
  • پروژه را راه‌اندازی کنید.
  • در Gmail، «تقویم»، Drive، «سندنگار»، «کاربرگ‌نگار»، «اسلایدنگار» پیاده‌سازی کنید.
  • استقرار در Chat.
  • راه‌حل را آزمایش کنید.

درباره این راهکار

این راهکار به فناوری‌های اصلی زیر متکی است: «کیت توسعه عامل» (ADK)،‏ Google Cloud و میاناهای برنامه‌سازی کاربردی Google Workspace،‏ موتور عامل هوشواره Vertex، و چارچوب کارت.

«واسط‌های گرافیکی کاربر» برای برنامه‌های Chat و غیر Chat (Gmail، «تقویم»، Drive، «سندنگار»، «کاربرگ‌نگار»، «اسلایدنگار») به‌گونه‌ای متفاوت طراحی شده‌اند تا ویژگی‌ها و محدودیت‌های خاص آن‌ها را درنظر بگیرند.

ویژگی‌ها

ویژگی‌های زیر در برنامه «کارپرداز سفر» در همه برنامه‌های Google Workspace مشترک است:

  • جلسه‌های کاربر ماندگار: جلسه‌ها برای ماندگاری توسط Vertex AI مدیریت می‌شوند. هر کاربر یک جلسه را در همه برنامه‌های Workspace هم‌رسانی می‌کند. کاربران می‌توانند جلسه خود را به‌صورت دستی بازنشانی کنند تا مکالمه جدیدی را شروع کنند.

  • پیام‌رسانی غنی: کاربران پیامک ارسال می‌کنند و پاسخ‌هایی با متن غنی و ابزارک‌های کارت دریافت می‌کنند.

  • مدیریت خطا: خطاهای غیرمنتظره بااستفاده از تلاش‌های مجدد و وضعیت‌های پیکربندی‌پذیر در پاسخ‌ها به‌خوبی مدیریت می‌شوند.

برنامه Chat ویژگی‌های اضافی زیر را دارد:

  • پیام‌رسانی چندوجهی کاربر: کاربران می‌توانند پیام‌هایی با پیوست ارسال کنند، ازجمله صدا و ویدیویی که مستقیماً از فضای Chat ضبط شده است.

  • پاسخ‌های پیشرفته‌تر ازنظر دیداری: پاسخ‌ها می‌توانند با ابزارک‌های پیشرفته‌تری مثل گردونه‌های دارای تصویر با تکیه بر ویژگی‌های فقط گپ چارچوب «کارت» و فضای پردازش بیشتر تولید شوند.

برنامه‌های دیگر این ویژگی‌های اضافی را دارند:

  • زمینه نمایه Google: کاربران می‌توانند با اطلاعات نمایه‌شان پیام ارسال کنند (در این نمونه، محدود به تاریخ تولد است).

  • زمینه Gmail: کاربران می‌توانند پیام‌هایی را با ایمیل ارسال کنند (در این نمونه به یک موضوع و بدنه محدود می‌شود).

  • دسترسی «فضای گپ» کارشناس: کاربران می‌توانند فضای پیام مستقیم (DM) برنامه Chat را با یک کلیک دکمه در برگه جدید باز کنند.

معماری

برنامه «کارشناس سفر» رویدادهای تعامل برافزای Google Workspace را از برنامه‌های Google Workspace دریافت و پردازش می‌کند، از Vertex AI برای پیام‌واره دادن به عامل هوش مصنوعی ADK و مدیریت جلسه‌های کاربر استفاده می‌کند، و برای جمع‌آوری بافت و نمایش پاسخ‌ها به Google Cloud و «میاناهای برنامه‌سازی کاربردی Google Workspace» متکی است.

نمودارهای زیر جریان اصلی کاربر را نشان می‌دهد: ارسال پیام به هوش مصنوعی.

HTTP

  • نمودار معماری برنامه Chat.
    شکل ۳. برنامه Chat با پیوست‌های پیام کاربر زمینه‌سازی را تکمیل می‌کند و مجموعه‌ای از پیام‌ها را با سابقه تعاملات نماینده فرعی و پاسخ کلی نهایی به‌ترتیب زمانی ارسال می‌کند.
  • نمودار معماری برای برنامه‌های غیر Chat.
    شکل ۴. برنامه‌های غیر Chat با نمایه Google کاربر و انتخاب مورد، بافت را تکمیل می‌کنند و مجموعه‌ای از بخش‌ها را با سابقه تعاملات نماینده فرعی و پاسخ کلی نهایی به‌ترتیب زمانی معکوس نمایش می‌دهند.

Apps Script

  • نمودار معماری برنامه Chat.
    شکل ۳. برنامه Chat با پیوست‌های پیام کاربر زمینه‌سازی را تکمیل می‌کند و مجموعه‌ای از پیام‌ها را با سابقه تعاملات نماینده فرعی و پاسخ کلی نهایی به‌ترتیب زمانی ارسال می‌کند.
  • نمودار معماری برای برنامه‌های غیر Chat.
    شکل ۴. برنامه‌های غیر Chat با نمایه Google کاربر و انتخاب مورد، بافت را تکمیل می‌کنند و مجموعه‌ای از بخش‌ها را با سابقه تعاملات نماینده فرعی و پاسخ کلی نهایی به‌ترتیب زمانی معکوس نمایش می‌دهند.

پیش‌نیازها

آماده کردن محیط

این بخش نحوه ایجاد و پیکربندی پروژه Google Cloud را نشان می‌دهد.

ایجاد پروژه Google Cloud

Google API Console

  1. در «کنسول Google API»، به «منو» > IAM و سرپرست > ایجاد پروژه بروید.

    رفتن به «ایجاد پروژه»

  2. در فیلد نام پروژه، نامی توصیفی برای پروژه خود وارد کنید.

    اختیاری: برای ویرایش شناسه پروژه، روی ویرایش کلیک کنید. شناسه پروژه را نمی‌توان پس‌از ایجاد پروژه تغییر داد، بنابراین شناسه‌ای را انتخاب کنید که در طول عمر پروژه نیازهای شما را برآورده کند.

  3. در فیلد مکان، روی مرور کردن کلیک کنید تا مکان‌های بالقوه برای پروژه‌تان نمایش داده شود. سپس روی انتخاب کلیک کنید.
  4. روی ایجاد کردن کلیک کنید. «کنسول Google API» به صفحه «داشبورد» هدایت می‌شود و پروژه شما ظرف چند دقیقه ایجاد می‌شود.

gcloud CLI

در یکی از محیط‌های توسعه زیر، به Google Cloud CLI (gcloud) دسترسی پیدا کنید:

  • Cloud Shell: برای استفاده از ترمینال آنلاین با gcloud CLI که ازقبل راه‌اندازی شده است، Cloud Shell را فعال کنید.
    فعال کردن Cloud Shell
  • صدف محلی: برای استفاده از محیط توسعه محلی، «رابط خط فرمان gcloud» را نصب و مقداردهی اولیه کنید.
    برای ایجاد پروژه Cloud، از دستور gcloud projects create استفاده کنید: 
    gcloud projects create PROJECT_ID
     با تنظیم شناسه برای پروژه‌ای که می‌خواهید ایجاد کنید، PROJECT_ID را جایگزین کنید.

فعال کردن صورت‌حساب برای پروژه Cloud

Google API Console

  1. در «کنسول Google API»، به صورت‌حساب بروید. روی منو > صورت‌حساب > پروژه‌های من کلیک کنید.

    رفتن به «صورت‌حساب برای پروژه‌های من»

  2. در انتخاب سازمان، سازمانی را که با پروژه Google Cloud شما منسوب است انتخاب کنید.
  3. در ردیف پروژه، منو کنش‌ها () را باز کنید، روی تغییر صورت‌حساب کلیک کنید، و حساب Cloud Billing را انتخاب کنید.
  4. روی تنظیم حساب کلیک کنید.

gcloud CLI

  1. برای فهرست کردن حساب‌های صورت‌حساب دردسترس، این دستور را اجرا کنید: 
    gcloud billing accounts list
  2. پیوند دادن حساب صورت‌حساب با پروژه Google Cloud: 
    gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

    جایگزین کردن موارد زیر:

    • ‫PROJECT_ID شناسه پروژه برای پروژه Cloud است که می‌خواهید صورت‌حساب را برای آن فعال کنید.
    • ‫BILLING_ACCOUNT_ID شناسه حساب صورت‌حساب برای پیوند دادن با پروژه Google Cloud است.

فعال کردن Google Cloud APIs

HTTP

  1. در «کنسول Google API»، میاناهای برنامه‌سازی کاربردی Vertex AI،‏ Places،‏ People،‏ Google Chat،‏ Gmail،‏ Cloud Build،‏ Cloud Functions،‏ Cloud Pub/Sub،‏ Cloud Logging،‏ Artifact Registry،‏ Cloud Run،‏ برافزاهای Google Workspace، و Cloud Resource Manager را فعال کنید.

    فعال کردن میاناهای برنامه‌سازی کاربردی

  2. تأیید کنید که میاناهای برنامه‌سازی کاربردی را در پروژه Cloud صحیح فعال می‌کنید، سپس روی بعدی کلیک کنید.

  3. تأیید کنید که درحال فعال کردن «میاناهای برنامه‌سازی کاربردی» صحیح هستید، سپس روی فعال کردن کلیک کنید.

Apps Script

  1. در «کنسول Google API»، میاناهای برنامه‌سازی کاربردی Vertex AI، «مکان‌ها»، «افراد»، Google Chat، و «مدیر منابع Cloud» را فعال کنید.

    فعال کردن میاناهای برنامه‌سازی کاربردی

  2. تأیید کنید که میاناهای برنامه‌سازی کاربردی را در پروژه Cloud صحیح فعال می‌کنید، سپس روی بعدی کلیک کنید.

  3. تأیید کنید که درحال فعال کردن «میاناهای برنامه‌سازی کاربردی» صحیح هستید، سپس روی فعال کردن کلیک کنید.

دریافت کلید «میانای برنامه‌سازی کاربردی مکان‌های پلاتفرم Google Maps»

  1. در «کنسول Google API»، به صفحه پلاتفرم Google Maps > کلیدها و اطلاعات اعتباری بروید.

    به «کلیدها و اطلاعات اعتباری» بروید

  2. در چارگوش گفتگوی شروع کار با پلاتفرم Google Maps کلید API جدیدی که ایجاد کرده‌اید، یک رشته الفبایی عددی، نمایش داده می‌شود. در بخش‌های بعدی به این رشته نیاز خواهید داشت.

ایجاد حساب خدمات در کنسول Google Cloud

با دنبال کردن این مراحل، حساب سرویس جدیدی با نقش Vertex AI User ایجاد کنید:

Google Cloud Console

  1. در «کنسول Google Cloud»، به «منو» > IAM و سرپرست > حساب‌های سرویس بروید.

    رفتن به «حساب‌های سرویس»

    مراحل باقی‌مانده در «کنسول Google Cloud» نشان داده می‌شود.

  2. پروژه Google Cloud را انتخاب کنید.
  3. روی ایجاد حساب سرویس کلیک کنید.
  4. نام حساب سرویسی را که می‌خواهید در Google Cloud Console نمایش داده شود وارد کنید.
  5. اگر نمی‌خواهید اکنون کنترل‌های دسترسی را تنظیم کنید، برای تکمیل ایجاد حساب سرویس روی تمام کلیک کنید. برای تنظیم کنترل‌های دسترسی در این لحظه، روی ایجاد و ادامه کلیک کنید و به مرحله بعد بروید.
  6. اختیاری: نقش‌هایی را به حساب خدمات خود اختصاص دهید تا علاوه‌بر منابع Google Workspace، دسترسی به منابع پروژه Google Cloud خود را نیز اعطا کنید. برای جزئیات بیشتر، به مدیریت دسترسی به پروژه‌ها، پوشه‌ها، و سازمان‌ها مراجعه کنید.
  7. روی ادامه کلیک کنید.
  8. اختیاری: کاربرها یا گروه‌هایی را که می‌توانند این حساب سرویس را مدیریت کنند و با آن کنش انجام دهند وارد کنید. برای جزئیات بیشتر، به جعل هویت حساب سرویس مراجعه کنید.
  9. برای تکمیل ایجاد حساب خدمات، روی تمام کلیک کنید.

    نشانی ایمیل حساب سرویس را یادداشت کنید.

gcloud CLI

  1. حساب سرویس را ایجاد کنید: 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. اختیاری: نقش‌هایی را به حساب خدمات خود اختصاص دهید تا علاوه‌بر منابع Google Workspace، دسترسی به منابع پروژه Google Cloud خود را نیز اعطا کنید. برای جزئیات بیشتر، به مدیریت دسترسی به پروژه‌ها، پوشه‌ها، و سازمان‌ها مراجعه کنید.

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

ایجاد کلید خصوصی

برای ایجاد و بارگیری کلید خصوصی برای حساب سرویس، این مراحل را دنبال کنید:

  1. در «کنسول Google Cloud»، به «منو» > IAM و سرپرست > حساب‌های سرویس بروید.

    رفتن به «حساب‌های سرویس»

    مراحل باقی‌مانده در «کنسول Google Cloud» نشان داده می‌شود.

  2. پروژه Google Cloud را انتخاب کنید.
  3. روی نشانی ایمیل حساب سرویسی که می‌خواهید کلید برای آن ایجاد کنید کلیک کنید.
  4. روی برگه کلیدها کلیک کنید.
  5. روی منوِ کرکره‌ای افزودن کلید کلیک کنید، سپس ایجاد کلید جدید را انتخاب کنید.
  6. JSON را به‌عنوان نوع کلید انتخاب کنید و روی ایجاد کلیک کنید.

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

برای کسب اطلاعات بیشتر درباره حساب‌های خدمات، به حساب‌های خدمات در اسناد Google Cloud IAM مراجعه کنید.

برافزاهای Google Workspace به پیکربندی صفحه موافقت نیاز دارند. پیکربندی صفحه موافقت OAuth برافزایتان مشخص می‌کند که Google چه چیزی را به کاربران نمایش دهد.

  1. در «کنسول Google API»، به «منو» > پلاتفرم «احراز هویت Google» > نمانام‌سازی بروید.

    رفتن به نمانام‌سازی

  2. اگر قبلاً پلاتفرم «احراز هویت Google» را پیکربندی کرده‌اید، می‌توانید تنظیمات «صفحه موافقت OAuth» زیر را در نمانام‌سازی، مخاطب، و دسترسی به داده‌ها پیکربندی کنید. اگر پیامی با این مضمون دیدید: پلاتفرم «احراز هویت Google» هنوز پیکربندی نشده است، روی شروع به کار کلیک کنید:
    1. در بخش اطلاعات برنامه، در نام برنامه، نامی برای برنامه وارد کنید.
    2. در ایمیل پشتیبانی کاربر، نشانی ایمیل پشتیبانی را انتخاب کنید که کاربران بتوانند درصورت داشتن سؤال درباره رضایتشان با شما تماس بگیرند.
    3. روی بعدی کلیک کنید.
    4. در بخش مخاطبان، داخلی را انتخاب کنید.
    5. روی بعدی کلیک کنید.
    6. در بخش اطلاعات تماس، نشانی ایمیلی وارد کنید که ازطریق آن بتوانید از هرگونه تغییر در پروژه خود مطلع شوید.
    7. روی بعدی کلیک کنید.
    8. در بخش تکمیل، خط‌مشی داده‌های کاربر سرویس‌های Google API را مرور کنید و درصورت موافقت، با «خط‌مشی داده‌های کاربر سرویس‌های Google API» موافقم را انتخاب کنید.
    9. روی ادامه کلیک کنید.
    10. روی ایجاد کردن کلیک کنید.
  3. درحال‌حاضر می‌توانید از افزودن محدوده‌ها رد شوید. در آینده، وقتی برنامه‌ای برای استفاده در خارج از سازمان Google Workspace خودتان ایجاد می‌کنید، باید نوع کاربر را به خارجی تغییر دهید. سپس محدوده‌های مجوز موردنیاز برنامه‌تان را اضافه کنید. برای کسب اطلاعات بیشتر، راهنمای کامل پیکربندی موافقت OAuth را ببینید.

مستقر کردن «عامل هوش مصنوعی ADK دربان سفر»

  1. اگر قبلاً این کار را نکرده‌اید، با حساب Google Cloud خود اصالت‌سنجی کنید و «میانای خط فرمان Google Cloud» را برای استفاده از پروژه Google Cloud خود پیکربندی کنید.

    gcloud auth application-default login
gcloud config set project PROJECT_ID
gcloud auth application-default set-quota-project PROJECT_ID

    PROJECT_ID را با شناسه پروژه Cloud که ایجاد کرده‌اید جایگزین کنید.

  2. بارگیری این مخزن GitHub

    بارگیری

  3. در محیط توسعه محلی دلخواهتان، فایل بایگانی بارگیری‌شده را استخراج کنید و فهرست راهنمای adk-samples/python/agents/travel-concierge را باز کنید.

    unzip adk-samples-main.zip
cd adk-samples-main/python/agents/travel-concierge

  4. باکت جدیدی در Cloud Storage ایجاد کنید که به عامل هوش مصنوعی ADK اختصاص داده شده باشد.

    gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

    جایگزین کردن موارد زیر:

    1. CLOUD_STORAGE_BUCKET_NAME با نام باکت یکتایی که می‌خواهید استفاده کنید.
    2. PROJECT_ID با شناسه پروژه Cloud که ایجاد کرده‌اید.
    3. PROJECT_LOCATION را با مکان پروژه Cloud که ایجاد کرده‌اید جایگزین کنید.

  5. متغیرهای محیطی زیر را تنظیم کنید:

    export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
export GOOGLE_PLACES_API_KEY=PLACES_API_KEY
export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
export TRAVEL_CONCIERGE_SCENARIO=travel_concierge/profiles/itinerary_empty_default.json

    جایگزین کردن موارد زیر:

    1. PROJECT_ID با شناسه پروژه Cloud که ایجاد کرده‌اید.
    2. PROJECT_LOCATION را با مکان پروژه Cloud که ایجاد کرده‌اید جایگزین کنید.
    3. PLACES_API_KEY با رشته کلید میانای برنامه‌سازی کاربردی که ایجاد کرده‌اید.
    4. CLOUD_STORAGE_BUCKET_NAME با نام سطلی که ایجاد کرده‌اید.

  6. عامل هوش مصنوعی ADK را نصب و مستقر کنید.

    uv sync --group deployment
uv run python deployment/deploy.py --create

  7. شماره پروژه و شناسه موتور را از آخرین گزارش چاپ‌شده به‌ترتیب به‌عنوان PROJECT_NUMBER و ENGINE_ID بازیابی کنید، بعداً برای پیکربندی پروژه به هر دو مورد نیاز خواهید داشت.

    Created remote agent: projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENGINE_ID

بررسی کد نمونه

به‌صورت اختیاری، قبل‌از راه‌اندازی پروژه، چند لحظه وقت بگذارید و کد نمونه میزبانی‌شده در GitHub را مرور کنید و با آن آشنا شوید.

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

Python

  1. بارگیری این مخزن GitHub

    بارگیری

  2. در محیط توسعه محلی دلخواهتان، فایل بایگانی بارگیری‌شده را استخراج کنید و فهرست راهنمای add-ons-samples/python/travel-adk-ai-agent را باز کنید.

    unzip add-ons-samples-main.zip
cd add-ons-samples-main/python/travel-adk-ai-agent

  3. فایل کلید JSON credentials.json را از حساب سرویس بارگیری‌شده در مراحل قبلی به فهرست راهنمای پروژه منتقل کنید.

  4. در «کنسول Google API»، به Cloud Run بروید:

    رفتن به Cloud Run

  5. روی نوشتن تابع کلیک کنید.

  6. در صفحه ایجاد سرویس، تابع خود را راه‌اندازی کنید:

    1. در فیلد نام سرویس، travel-concierge-app را وارد کنید.
    2. در فهرست منطقه، مکان پروژه Cloud را که ایجاد کرده‌اید، PROJECT_LOCATION، انتخاب کنید.
    3. در بخش نشانی وب نقطه پایان، روی نماد تهیه کپی کلیک کنید.
    4. در فهرست زمان اجرا، جدیدترین نسخه Python را انتخاب کنید.
    5. در بخش اصالت‌سنجی، اجازه دسترسی عمومی را انتخاب کنید.
    6. در بخش ظروف، حجم‌ها، شبکه‌سازی، امنیت، در زیر منابع:
      1. در فیلد حافظه، ۱ گیگابایت را انتخاب کنید.
      2. در فیلد CPU، 2 را انتخاب کنید.
    7. روی ایجاد کردن کلیک کنید و منتظر بمانید تا Cloud Run سرویس را ایجاد کند. کنسول شما را به برگه منبع هدایت می‌کند.

  7. در محیط توسعه محلی ترجیحی‌تان، منبع پروژه را مستقر کنید:

    gcloud run deploy travel-concierge-app --quiet --source . \
    --region PROJECT_LOCATION  \
    --function adk_ai_agent  \
    --set-env-vars LOCATION=LOCATION,PROJECT_NUMBER=PROJECT_NUMBER,ENGINE_ID=ENGINE_ID,BASE_URL=BASE_URL

    جایگزین کردن موارد زیر:

    1. PROJECT_LOCATION با مکان تابع Cloud Run که قبلاً ایجاد کرده‌اید.
    2. ‫LOCATION با مکان پروژه Google Cloud ایجادشده در مراحل قبلی، PROJECT_LOCATION.
    3. ‫PROJECT_NUMBER با شماره پروژه «عامل هوش مصنوعی Travel Concierge ADK» که در مراحل قبلی مستقر شده است.
    4. ENGINE_ID با شناسه موتور Travel Concierge ADK عامل هوش مصنوعی که در مراحل قبلی مستقر شده است.
    5. ‫BASE_URL با نشانی وب نقطه پایان که قبلاً کپی کرده‌اید.

Apps Script

برای ایجاد پروژه Apps Script و پیکربندی آن برای استفاده از عامل هوش مصنوعی ADK «کارپرداز سفر» مستقرشده:

  1. برای باز کردن پروژه عامل هوش مصنوعی «کیت توسعه تبلیغات» «دروازبان سفر» Apps Script، روی دکمه زیر کلیک کنید.
    باز کردن پروژه

  2. روی نمای کلی و سپس نماد تهیه کپی تهیه رونوشت کلیک کنید.

  3. نام کپی پروژه Apps Script خود را وارد کنید:

    1. روی کپی «نماینده هوش مصنوعی ADK مشاور سفر» کلیک کنید.
    2. در عنوان پروژه، Travel Concierge ADK AI Agent را تایپ کنید.
    3. روی تغییر نام کلیک کنید.

  4. در پروژه Apps Script، روی نماد تنظیمات پروژه تدوین‌گر کلیک کنید و فایل VertexAi.gs را بااستفاده از کنش فایل انتقال فایل به بالا به‌بالا ببرید تا بالای فایل AgentHandler.gs قرار بگیرد.

  5. در پروژه Apps Script، روی نماد تنظیمات پروژه تنظیمات پروژه کلیک کنید، روی ویرایش دارایی‌های نوشتار کلیک کنید، سپس روی افزودن دارایی نوشتار کلیک کنید تا دارایی‌های نوشتار زیر را اضافه کنید:

  6. ENGINE_ID با شناسه موتور «عامل هوش مصنوعی ADK سرپرست سفر» مستقرشده در مراحل قبلی، ENGINE_ID.

  7. LOCATION با مکان پروژه Google Cloud که در مراحل قبلی ایجاد شده است، PROJECT_LOCATION.

  8. PROJECT_NUMBER با شماره پروژه «عامل هوش مصنوعی Travel Concierge ADK» که در مراحل قبلی مستقر شده است، PROJECT_NUMBER.

  9. ‫SERVICE_ACCOUNT_KEY با کلید JSON از حساب سرویس بارگیری‌شده در مراحل قبلی مثل { ... }.

  10. روی ذخیره کردن دارایی‌های نوشتار کلیک کنید

  11. در پروژه Apps Script خود، روی نماد تنظیمات پروژه تنظیمات پروژه کلیک کنید.

  12. در بخش پروژه Google Cloud Platform (GCP)، روی تغییر پروژه کلیک کنید.

  13. در شماره پروژه GCP، شماره پروژه «عامل هوش مصنوعی Travel Concierge ADK» را که در مراحل قبلی مستقر شده است جای‌گذاری کنید، PROJECT_NUMBER.

  14. روی تنظیم پروژه کلیک کنید. پروژه Cloud و پروژه Apps Script اکنون متصل هستند.

استقرار در Gmail، «تقویم»، Drive، «سندنگار»، «کاربرگ‌نگار»، «اسلایدنگار»

Python

از استقرار برافزای Google Workspace برای نصب پروژه نمونه در همه برنامه‌های Google Workspace (به‌جز Google Chat) استفاده کنید تا آزمایش فعال شود.

  1. در محیط توسعه محلی ترجیحی‌تان، فایل deployment.json را از منبع کد پروژه باز کنید و همه موارد $BASE_URL را با مقدار BASE_URL، نشانی وب نقطه پایانی که در مراحل قبلی کپی کردید جایگزین کنید.

  2. استقرار برافزای Google Workspace با نام travel-concierge-addon ایجاد کنید:

    gcloud workspace-add-ons deployments create travel-concierge-addon \
    --deployment-file=deployment.json

  3. نصب استقرار برافزای Google Workspace:

    gcloud workspace-add-ons deployments install travel-concierge-addon

Apps Script

پروژه Apps Script را در همه برنامه‌های Google Workspace (به‌جز Google Chat) نصب کنید تا آزمایش فعال شود.

  1. در پروژه Apps Script، روی پیاده‌سازی > پیاده‌سازی‌های آزمایشی کلیک کنید، سپس نصب را انتخاب کنید.

اکنون برافزا از نوارهای کناری برنامه Google Workspace قابل‌دسترسی است.

استقرار در Chat

Python

برای فعال کردن آزمایش، پروژه نمونه را بااستفاده از نشانی وب نقطه پایان در Chat نصب کنید.

  1. در کنسول API، Google Chat API را جستجو کنید، روی Google Chat API، سپس مدیریت، و پیکربندی کلیک کنید.

    رفتن به صفحه «پیکربندی Google Chat API»

  2. راه‌اندازی برنامه Chat:

    1. در فیلد نام برنامه، Travel ADK AI Agent را وارد کنید.
    2. در فیلد نشانی وب چهرک، https://goo.gle/3SfMkjb را وارد کنید.
    3. در فیلد شرح، Travel ADK AI Agent را وارد کنید.
    4. در بخش تنظیمات اتصال، نشانی وب نقطه پایان HTTP را انتخاب کنید.
    5. در بخش محرک‌ها، استفاده از نشانی وب نقطه پایان HTTP مشترک برای همه محرک‌ها را انتخاب کنید.
    6. در فیلد نشانی وب نقطه پایان HTTP، نشانی وب نقطه پایان را که قبلاً کپی کرده‌اید جای‌گذاری کنید، BASE_URL.
    7. فرمان سریعی را ثبت کنید که برنامه Chat کاملاً پیاده‌سازی‌شده از آن استفاده می‌کند:
      1. در بخش فرمان‌ها، روی افزودن فرمان کلیک کنید.
      2. در شناسه فرمان، 1 را تایپ کنید.
      3. در شرح، Reset session را تایپ کنید.
      4. در بخش نوع فرمان، فرمان سریع را انتخاب کنید.
      5. در نام، Reset session را تایپ کنید.
      6. روی تمام کلیک کنید. فرمان سریع ثبت و فهرست می‌شود.
    8. در بخش رؤیت‌پذیری، گزینه دسترسی این برنامه Chat را برای افراد و گروه‌های خاص در «دامنه Workspace شما» فراهم کنید را انتخاب کنید و نشانی ایمیلتان را وارد کنید.
    9. در بخش گزارش‌ها، خطاهای گزارش به «گزارش‌گیری» را انتخاب کنید.
    10. روی ذخیره کلیک کنید.

Apps Script

برای استفاده از Chat، پروژه Apps Script را بااستفاده از شناسه استقرار سر نصب کنید تا آزمایش فعال شود.

  1. در پروژه Apps Script، روی پیاده‌سازی > پیاده‌سازی‌های آزمایشی کلیک کنید، سپس نماد کپی کردن «شناسه استقرار سر» کپی کردن را در زیر شناسه پیاده‌سازی سر انتخاب کنید.

  2. در کنسول API، Google Chat API را جستجو کنید، روی Google Chat API، سپس مدیریت، و پیکربندی کلیک کنید.

    رفتن به صفحه «پیکربندی Google Chat API»

  3. راه‌اندازی برنامه Chat:

    1. در فیلد نام برنامه، Travel ADK AI Agent را وارد کنید.
    2. در فیلد نشانی وب چهرک، https://goo.gle/3SfMkjb را وارد کنید.
    3. در فیلد شرح، Travel ADK AI Agent را وارد کنید.
    4. در بخش تنظیمات اتصال، Apps Script را انتخاب کنید.
    5. در فیلد شناسه استقرار، شناسه استقرار سر را که قبلاً کپی کرده‌اید جای‌گذاری کنید.
    6. فرمان سریعی را ثبت کنید که برنامه Chat کاملاً پیاده‌سازی‌شده از آن استفاده می‌کند:
      1. در بخش فرمان‌ها، روی افزودن فرمان کلیک کنید.
      2. در شناسه فرمان، 1 را تایپ کنید.
      3. در شرح، Reset session را تایپ کنید.
      4. در بخش نوع فرمان، فرمان سریع را انتخاب کنید.
      5. در نام، Reset session را تایپ کنید.
      6. روی تمام کلیک کنید. فرمان سریع ثبت و فهرست می‌شود.
    7. در بخش رؤیت‌پذیری، گزینه دسترسی این برنامه Chat را برای افراد و گروه‌های خاص در «دامنه Workspace شما» فراهم کنید را انتخاب کنید و نشانی ایمیلتان را وارد کنید.
    8. در بخش گزارش‌ها، خطاهای گزارش به «گزارش‌گیری» را انتخاب کنید.
    9. روی ذخیره کلیک کنید.

اکنون این برنامه از Google Chat دردسترس است.

  1. ‫Google Chat را باز کنید.

    رفتن به Google Chat

  2. ایجاد فضای پیام مستقیم Chat:

    1. روی گپ جدید کلیک کنید.
    2. برنامه Travel ADK AI Agent را در جستجو تایپ و انتخاب کنید.
    3. در کادر گفتگوی Install app، روی نصب برنامه کلیک کنید.
    4. کادر گفتگوی Install app بسته می‌شود و فضای «پیام مستقیم گپ» تازه‌ساخته‌شده انتخاب می‌شود.

برنامه Chat آماده پاسخ دادن به پیام‌ها است.

آزمایش عامل

  1. Gmail را باز کنید.

    رفتن به Gmail

  2. ایمیل زیر را برای خودتان ارسال کنید:

    • موضوع: You need to travel to Paris
    • متن اصلی: Please be there between 11/25/2025 and 11/30/2025!

  3. برافزای عامل هوش مصنوعی Travel ADK را از نوار کناری باز کنید.

  4. برای تکمیل راه‌اندازی برافزا، روی اعطای اجازه‌ها کلیک کنید.

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

    • پیام: Please help me plan this travel!
    • زمینه: ایمیل فعلی را انتخاب کنید

    نوار کناری با پاسخ عامل به‌روز می‌شود.

    برنامه‌ریزی سفر از Gmail

  6. روی باز کردن Chat کلیک کنید تا به فضای پیام مستقیم Chat هدایت شوید.

  7. روی + > بازنشانی جلسه کلیک کنید.

    پیام جدیدی دریافت می‌کنید که انجام شدن آن را تأیید می‌کند: OK, let's start from the beginning, what can I help you with?

  8. پیام Give me ideas را ارسال کنید.

    پیام‌های جدیدی با پاسخ کارشناس دریافت می‌کنید.

    بارش فکری از Chat

  9. پیام I want to go there! را پس‌از بارگذاری کردن تصویری از هر مکانی مثل برج ایفل ارسال کن.

    پیام‌های جدیدی با پاسخ کارشناس دریافت می‌کنید.

    دریافت جزئیات مکان از پیوست Chat

محدودیت‌ها

HTTP

در برنامه‌های Google Workspace به‌جز Chat، کارگزار هوش مصنوعی محدودیت‌های زیر را دارد:

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

  • ممکن است زمان آن تمام شود: اگر به‌روزرسانی‌های نوار کناری بیشتر از چند دقیقه طول بکشد، زمان آن‌ها تمام می‌شود.

این محدودیت‌ها در Chat وجود ندارد.

Apps Script

در همه برنامه‌های Google Workspace، عامل هوش مصنوعی بااستفاده از UrlFetchApp، میاناهای برنامه‌سازی کاربردی REST مربوط به Vertex AI را فراخوانی می‌کند که باعث محدودیت‌های زیر می‌شود:

  • هم‌زمان است: پاسخ‌های عامل هوشواره‌ای فقط پس‌از تکمیل کامل برگردانده می‌شود (بدون جاری‌سازی).

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

سفارشی‌سازی

این راهکار از عوامل هوش مصنوعی «کیت توسعه عامل» میزبانی‌شده در «موتور عامل Vertex AI»، زیرمجموعه‌ای از میاناهای کاربر برنامه Google Workspace، و پردازش پاسخ‌های خاص برای پاسخ‌های نمونه «مشاور سفر» پشتیبانی می‌کند. این راه‌حل از چارچوب توسعه‌پذیر استفاده می‌کند، بنابراین می‌توانید با اصلاح فایل‌های زیر آن را سفارشی‌سازی کنید:

Python

  • main.py: منطق اصلی میاناهای کاربر و تعامل‌های کاربر را تعریف می‌کند (مدیران رویداد Google Workspace). افزونه معمولی این است که اسناد Drive را به‌عنوان ویژگی زمینه‌ای برای برنامه Drive فعال کنیم، مشابه آنچه برای پیام‌های Gmail در برنامه Gmail انجام می‌شود.

  • vertex_ai.py: جلسات، پاسخ‌ها، و خطاهای نماینده هوش مصنوعی را مدیریت می‌کند و واسط‌های ویژه Vertex AI را برای پیاده‌سازی به‌منظور پشتیبانی از تعاملات نماینده و پردازش پاسخ‌ها تعریف می‌کند. افزونه‌های معمول شامل افزودن پشتیبانی از چند جلسه برای مکالمه‌های جداگانه کاربر، و دیگر پلاتفرم‌های مدیریت عامل هوش مصنوعی می‌شود.

  • agent_handler.py: رابط‌های ویژه Vertex AI تعریف‌شده در vertex_ai.py را در موارد خاص برنامه‌های Chat و غیر Chat پیاده‌سازی می‌کند. افزونه معمولی این است که دکمه‌هایی برای کاربران اضافه شود تا درباره پاسخ‌های عامل هوشواره بازخورد ارسال کنند.

  • google_workspace.py: تعاملات پلاتفرم مدیریت کارگزار غیرهوش مصنوعی را بااستفاده از تماس‌های API پیاده‌سازی می‌کند. فقط از «میاناهای برنامه‌سازی کاربردی Google Workspace» در این نمونه برای جمع‌آوری جزئیات زمینه‌ای و انجام کنش‌ها استفاده می‌شود. افزونه معمولاً برای افزودن کارکردهایی است که داده‌های کسب‌وکار را از «تقویم Google» یا «مدیریت ارتباط با مشتری» (CRM) بازیابی می‌کند.

  • travel_agent_ui_render.gs: پیاده‌سازی پاسخ‌های ویژه «دستیار سفر» برای عامل‌های فرعی و برنامه‌های Workspace. افزونه‌های معمول شامل افزودن پشتیبانی برای پردازه‌های پاسخ جدید برای نمایش گرافیکی گزینه‌های پرواز و دیگر کارگزاران هوش مصنوعی می‌شود.

Apps Script

  • Code.gs: منطق اصلی میاناهای کاربر و تعامل‌های کاربر (مدیران رویداد Google Workspace) را تعریف می‌کند. افزونه معمولی این است که اسناد Drive را به‌عنوان ویژگی زمینه‌ای برای برنامه Drive فعال کند، مشابه آنچه برای پیام‌های Gmail در برنامه Gmail انجام می‌شود.

  • VertexAi.gs: جلسات، پاسخ‌ها، خطاها، و واسط‌های ویژه Vertex AI را برای پیاده‌سازی به‌منظور پشتیبانی از تعاملات نماینده و پرداز پاسخ‌ها مدیریت می‌کند. افزونه‌های معمول شامل افزودن پشتیبانی از چند جلسه برای مکالمه‌های جداگانه کاربر، و دیگر پلاتفرم‌های مدیریت عامل هوش مصنوعی می‌شود.

  • AgentHandler.gs: رابط‌های ویژه Vertex AI را که در VertexAi.gs تعریف شده است در موارد خاص برنامه‌های Chat و غیر Chat پیاده‌سازی می‌کند. افزونه معمولی این است که دکمه‌هایی برای کاربران اضافه شود تا درباره پاسخ‌های عامل هوشواره بازخورد ارسال کنند.

  • GoogleWorkspace.gs: تعاملات پلاتفرم مدیریت نماینده غیر هوش مصنوعی را بااستفاده از فراخوانی‌های API پیاده‌سازی می‌کند. فقط از «میاناهای برنامه‌سازی کاربردی Google Workspace» در این نمونه برای جمع‌آوری جزئیات زمینه‌ای و انجام کنش‌ها استفاده می‌شود. افزونه معمولاً برای افزودن کارکردهایی است که داده‌های کسب‌وکار را از «تقویم Google» یا «مدیریت ارتباط با مشتری» (CRM) بازیابی می‌کند.

  • TravelAgentUiRender.gs: پیاده‌سازی رندرینگ‌های پاسخ ویژه «دستیار سفر» برای برنامه‌های Workspace و نمایندگان فرعی. افزونه‌های معمول شامل افزودن پشتیبانی برای پردازه‌های پاسخ جدید برای نمایش گرافیکی گزینه‌های پرواز و دیگر کارگزاران هوش مصنوعی می‌شود.

مرتب‌سازی

برای اینکه هزینه منابع استفاده‌شده در این آموزش به حساب Google Cloud شما اضافه نشود، توصیه می‌کنیم پروژه Cloud را حذف کنید.

  1. در «کنسول Google API»، به صفحه مدیریت منابع بروید. روی منو > IAM و سرپرست > مدیریت منابع کلیک کنید.

    به «مدیر منابع» بروید

  2. در فهرست پروژه، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی حذف کلیک کنید.
  3. در چارگوش گفتگو، شناسه پروژه را تایپ کنید و سپس روی خاموش کردن کلیک کنید تا پروژه حذف شود.