Google Workspace'te erişilebilen bir yapay zeka aracısıyla seyahat planlama

Kodlama düzeyi: İleri
Süre: 45 dakika
Proje türü: Google Workspace eklentisi Chat, Gmail, Takvim, Drive, Dokümanlar, E-Tablolar ve Slaytlar'ı genişletme.

Bu eğiticide, Apps Komut Dosyası veya HTTP uç noktalarını kullanarak yapay zeka aracılarını Google Workspace eklentisi olarak Google Workspace'te nasıl yayınlayacağınız gösterilmektedir. Eklentinizi yayınladıktan sonra kullanıcılarınız iş akışlarında yapay zeka temsilcileriyle etkileşime geçebilir.

Genel Bakış

Bu eğiticide, Agent Development Kit (ADK)'den Travel Concierge örneğini dağıtacaksınız. Seyahat Asistanı, Google Haritalar Platformu Places API, Google Arama Temellendirme ve Model Bağlam Protokolü (MCP) sunucusu gibi araçları kullanan etkileşimli bir çoklu aracı yapay zekadır.

ADK, geliştiriciler için varsayılan olarak sohbet ve metin arayüzleri sağlar. Bu eğitimde, kullanıcılarınızın Chat, Gmail, Takvim, Drive, Dokümanlar, E-Tablolar ve Slaytlar'da doğrudan erişebileceği Google Workspace uygulamalarına bir grafik kullanıcı arayüzü (GUI) ekleyeceksiniz.

  • Seyahat fikirleri için beyin fırtınası yapmak üzere Chat'teki yapay zeka temsilcisini kullanma
    Şekil 1. Seyahat fikirleri için beyin fırtınası yapmak üzere Chat'teki yapay zeka temsilcisini kullanma.
  • Seçili e-postadaki bağlamdan yola çıkarak seyahat planlamak için Gmail'deki yapay zeka aracısını kullanma.
    Şekil 2. Seçilen e-postadaki bağlamdan yola çıkarak seyahat planlamak için Gmail'deki yapay zeka aracısını kullanma.

Hedefler

  • Ortamı ayarlayın.
  • Yapay zeka aracısını dağıtın.
  • Projeyi oluşturun.
  • Gmail, Takvim, Drive, Dokümanlar, E-Tablolar ve Slaytlar'da dağıtın.
  • Chat'e dağıtın.
  • Çözümü test edin.

Bu çözüm hakkında

Bu çözüm, ADK, Google Cloud ve Google Workspace API'leri, Vertex AI Agent Engine ve Kart çerçevesi gibi temel teknolojilere dayanır.

GUI'ler, Chat ve Chat dışı (Gmail, Takvim, Drive, Dokümanlar, E-Tablolar, Slaytlar) uygulamaların kendine özgü özelliklerini ve sınırlamalarını dikkate alacak şekilde farklı tasarlanmıştır.

Özellikler

Seyahat Asistanı uygulamasının aşağıdaki özellikleri tüm Google Workspace uygulamalarında ortaktır:

  • Kalıcı kullanıcı oturumları: Oturumlar, kalıcılık için Vertex AI tarafından yönetilir. Her kullanıcı, tüm Workspace uygulamalarında tek bir oturum paylaşır. Kullanıcılar, yeni bir görüşme başlatmak için oturumlarını manuel olarak sıfırlayabilir.

  • Zengin mesajlaşma: Kullanıcılar, zengin metin ve kart widget'larıyla kısa mesaj gönderip yanıt alabilir.

  • Hata işleme: Beklenmedik hatalar, yanıtlarda yapılandırılabilir yeniden denemeler ve durumlar kullanılarak sorunsuz bir şekilde işlenir.

Chat uygulamasında aşağıdaki ek özellikler bulunur:

  • Çok formatlı kullanıcı mesajları: Kullanıcılar, doğrudan Chat alanında kaydedilen ses ve videolar da dahil olmak üzere ek içeren mesajlar gönderebilir.

  • Daha gelişmiş görsel yanıtlar: Kart çerçevesinin yalnızca sohbet özelliklerinden ve daha fazla oluşturma alanından yararlanarak, resim içeren bantlar gibi daha gelişmiş widget'larla yanıtlar oluşturulabilir.

Diğer uygulamalarda şu ek özellikler bulunur:

  • Google profili bağlamı: Kullanıcılar, profil bilgilerini (bu örnekte doğum günleriyle sınırlı) kullanarak mesaj gönderebilir.

  • Gmail bağlamı: Kullanıcılar, e-postalarla ileti gönderebilir (bu örnekte konu ve gövde ile sınırlıdır).

  • Temsilcinin Chat alanı erişimi: Kullanıcılar, tek bir düğmeyi tıklayarak Chat uygulaması doğrudan mesaj (DM) alanını yeni bir sekmede açabilir.

Mimari

Seyahat Asistanı uygulaması, Google Workspace uygulamalarından Google Workspace eklenti etkileşimi etkinliklerini alır ve işler, ADK yapay zeka aracısına istem göndermek ve kullanıcı oturumlarını yönetmek için Vertex AI'ı kullanır, bağlam toplamak ve yanıtları görüntülemek için Google Cloud ve Google Workspace API'lerini kullanır.

Aşağıdaki şemada ana kullanıcı akışı (yapay zeka temsilcisine mesaj gönderme) gösterilmektedir.

HTTP

  • Chat uygulamasının mimari şeması.
    Şekil 3. Chat uygulaması, kullanıcının mesajındaki eklerle bağlamı tamamlar ve alt aracı etkileşimlerinin geçmişini içeren bir mesaj dizisiyle kronolojik sırayla nihai genel yanıtı gönderir.
  • Chat dışı uygulamaların mimari şeması.
    Şekil 4. Chat dışı uygulamalar, kullanıcının Google profili ve öğe seçimiyle bağlamı tamamlar. Ayrıca, alt aracı etkileşimlerinin geçmişini ve nihai genel yanıtı ters kronolojik sırayla içeren bir dizi bölüm gösterir.

Apps Komut Dosyası

  • Chat uygulamasının mimari şeması.
    Şekil 3. Chat uygulaması, kullanıcının mesajındaki eklerle bağlamı tamamlar ve alt aracı etkileşimlerinin geçmişini içeren bir mesaj dizisiyle kronolojik sırayla nihai genel yanıtı gönderir.
  • Chat dışı uygulamaların mimari şeması.
    Şekil 4. Chat dışı uygulamalar, kullanıcının Google profili ve öğe seçimiyle bağlamı tamamlar. Ayrıca, alt aracı etkileşimlerinin geçmişini ve nihai genel yanıtı ters kronolojik sırayla içeren bir dizi bölüm gösterir.

Ön koşullar

Ortamı hazırlama

Bu bölümde, Google Cloud projesinin nasıl oluşturulacağı ve yapılandırılacağı gösterilmektedir.

Google Cloud projesi oluşturma

Google Cloud konsolu

  1. Google Cloud Console'da Menü > IAM & Admin > Proje Oluştur'a gidin.

    Proje oluşturma bölümüne gitme

  2. Project Name (Proje Adı) alanına projeniz için açıklayıcı bir ad girin.

    İsteğe bağlı: Proje kimliğini düzenlemek için Düzenle'yi tıklayın. Proje oluşturulduktan sonra proje kimliği değiştirilemez. Bu nedenle, projenin kullanım ömrü boyunca ihtiyaçlarınızı karşılayacak bir kimlik seçin.

  3. Konum alanında, projeniz için olası konumları görüntülemek üzere Göz at'ı tıklayın. Ardından Seç'i tıklayın.
  4. Oluştur'u tıklayın. Google Cloud Console, Kontrol Paneli sayfasına gider ve projeniz birkaç dakika içinde oluşturulur.

gcloud CLI

Aşağıdaki geliştirme ortamlarından birinde Google Cloud KSA'ya (gcloud) erişin:

  • Cloud Shell: gcloud KSA'nın önceden ayarlandığı bir online terminal kullanmak için Cloud Shell'i etkinleştirin.
    Cloud Shell'i etkinleştirin.
  • Yerel kabuk: Yerel geliştirme ortamı kullanmak için gcloud CLI'yı yükleyin ve başlatın.
    Cloud projesi oluşturmak için gcloud projects create komutunu kullanın: 
    gcloud projects create PROJECT_ID
     Oluşturmak istediğiniz projenin kimliğini ayarlayarak PROJECT_ID yerine kendi proje kimliğinizi girin.

Cloud projesi için faturalandırmayı etkinleştirme

Google Cloud konsolu

  1. Google Cloud Console'da Faturalandırma'ya gidin. Şunu tıklayın: Menü > Faturalandırma > Projelerim.

    Projelerim için Faturalandırma'ya gitme

  2. Bir kuruluş seçin bölümünde, Google Cloud projenizle ilişkili kuruluşu seçin.
  3. Proje satırında İşlemler menüsünü () açın, Faturalandırmayı değiştir'i tıklayın ve Cloud Faturalandırma hesabını seçin.
  4. Hesap belirle'yi tıklayın.

gcloud CLI

  1. Kullanılabilir faturalandırma hesaplarını listelemek için şu komutu çalıştırın: 
    gcloud billing accounts list
  2. Bir faturalandırma hesabını Google Cloud projesiyle bağlama: 
    gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

    Aşağıdakini değiştirin:

    • PROJECT_ID, faturalandırmayı etkinleştirmek istediğiniz Cloud projesinin proje kimliğidir.
    • BILLING_ACCOUNT_ID, Google Cloud projesiyle ilişkilendirilecek faturalandırma hesabı kimliğidir.

Google Cloud API'lerini etkinleştirme

HTTP

  1. Google Cloud Console'da Vertex AI, Places, People, Google Chat, Gmail, Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry, Cloud Run ve Google Workspace eklentileri API'lerini etkinleştirin.

    API'leri etkinleştirme

  2. API'leri doğru Cloud projesinde etkinleştirdiğinizi onaylayın ve İleri'yi tıklayın.

  3. Doğru API'leri etkinleştirdiğinizden emin olun ve Etkinleştir'i tıklayın.

Apps Komut Dosyası

  1. Google Cloud Console'da Vertex AI, Places, People ve Google Chat API'lerini etkinleştirin.

    API'leri etkinleştirme

  2. API'leri doğru Cloud projesinde etkinleştirdiğinizi onaylayın ve İleri'yi tıklayın.

  3. Doğru API'leri etkinleştirdiğinizden emin olun ve Etkinleştir'i tıklayın.

Google Haritalar Platformu Places API anahtarı edinme

  1. Google Cloud Console'da Google Haritalar Platformu > Anahtarlar ve Kimlik Bilgileri sayfasına gidin.

    Anahtarlar ve Kimlik Bilgileri'ne gidin.

  2. Google Haritalar Platformu'nu kullanmaya başlama iletişim kutusunda yeni oluşturduğunuz API anahtarı (alfanümerik bir dize) gösterilir. Bu dizeye sonraki bölümlerde ihtiyacınız olacak.

Google Cloud Console'da hizmet hesabı oluşturma

Aşağıdaki adımları uygulayarak Vertex AI User rolüne sahip yeni bir hizmet hesabı oluşturun:

Google Cloud konsolu

  1. Google Cloud Console'da Menü > IAM ve Yönetici > Hizmet Hesapları'na gidin.

    Hizmet Hesapları'na gitme

  2. Hizmet hesabı oluştur'u tıklayın.
  3. Hizmet hesabı ayrıntılarını girip Oluştur ve devam et'i tıklayın.
  4. İsteğe bağlı: Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha ayrıntılı bilgi için Kaynaklara erişim verme, erişimi değiştirme ve iptal etme başlıklı makaleyi inceleyin.
  5. Devam'ı tıklayın.
  6. İsteğe bağlı: Bu hizmet hesabıyla işlem yapabilecek ve hesabı yönetebilecek kullanıcıları veya grupları girin. Daha fazla bilgi için Hizmet hesabı kimliğine bürünmeyi yönetme başlıklı makaleyi inceleyin.
  7. Bitti'yi tıklayın. Hizmet hesabının e-posta adresini not edin.

gcloud CLI

  1. Hizmet hesabını oluşturun: 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. İsteğe bağlı: Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha ayrıntılı bilgi için Kaynaklara erişim verme, erişimi değiştirme ve iptal etme başlıklı makaleyi inceleyin.

Hizmet hesabı, hizmet hesabı sayfasında görünür. Ardından, hizmet hesabı için özel anahtar oluşturun.

Özel anahtar oluşturma

Hizmet hesabı için özel anahtar oluşturmak ve indirmek üzere aşağıdaki adımları uygulayın:

  1. Google Cloud Console'da Menü > IAM ve Yönetici > Hizmet Hesapları'na gidin.

    Hizmet Hesapları'na gitme

  2. Hizmet hesabınızı seçin.
  3. Anahtarlar > Anahtar ekle > Yeni anahtar oluştur'u tıklayın.
  4. JSON'ı seçip Oluştur'u tıklayın.

    Yeni herkese açık/özel anahtar çiftiniz oluşturulur ve makinenize yeni bir dosya olarak indirilir. İndirilen JSON dosyasını çalışma dizininize credentials.json olarak kaydedin. Bu dosya, anahtarın tek kopyasıdır. Anahtarınızı güvenli bir şekilde depolama hakkında bilgi edinmek için Hizmet hesabı anahtarlarını yönetme başlıklı makaleyi inceleyin.

  5. Kapat'ı tıklayın.

Hizmet hesapları hakkında daha fazla bilgi için Google Cloud IAM belgelerindeki hizmet hesapları başlıklı makaleyi inceleyin.

Google Workspace eklentileri için izin ekranı yapılandırması gerekir. Eklentinizin OAuth kullanıcı rızası ekranını yapılandırmak, Google'ın kullanıcılara ne göstereceğini tanımlar.

  1. Google Cloud Console'da Menü > Google Auth platform > Markalama'ya gidin.

    Markalama'ya gidin

  2. Google Auth platformyapılandırdıysanız Markalama, Kitle ve Veri Erişimi'nde aşağıdaki OAuth kullanıcı rızası ekranı ayarlarını yapılandırabilirsiniz. Google Auth platform henüz yapılandırılmadı mesajını görürseniz Başlayın'ı tıklayın:
    1. Uygulama Bilgileri bölümündeki Uygulama adı alanına uygulamanın adını girin.
    2. Kullanıcı destek e-postası bölümünde, kullanıcıların rızalarıyla ilgili soruları olduğunda sizinle iletişime geçebileceği bir destek e-posta adresi seçin.
    3. İleri'yi tıklayın.
    4. Kitle bölümünde Dahili'yi seçin.
    5. İleri'yi tıklayın.
    6. İletişim bilgileri bölümünde, projenizde yapılan değişikliklerle ilgili bildirim alabileceğiniz bir e-posta adresi girin.
    7. İleri'yi tıklayın.
    8. Bitir bölümünde Google API Hizmetleri Kullanıcı Verileri Politikası'nı inceleyin ve kabul ediyorsanız Google API Hizmetleri: Kullanıcı Verileri Politikası'nı kabul ediyorum'u seçin.
    9. Devam'ı tıklayın.
    10. Oluştur'u tıklayın.
  3. Şimdilik kapsam eklemeyi atlayabilirsiniz. Gelecekte Google Workspace kuruluşunuzun dışında kullanılacak bir uygulama oluşturduğunuzda Kullanıcı türü'nü Harici olarak değiştirmeniz gerekir. Ardından, uygulamanızın gerektirdiği yetkilendirme kapsamlarını ekleyin. Daha fazla bilgi edinmek için OAuth iznini yapılandırma başlıklı kılavuzun tamamını inceleyin.

Seyahat Concierge ADK Yapay Zeka Temsilcisini dağıtma

  1. Henüz yapmadıysanız Google Cloud hesabınızla kimliğinizi doğrulayın ve Google Cloud CLI'yı Google Cloud projenizi kullanacak şekilde yapılandırın.

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

    PROJECT_ID kısmını, oluşturduğunuz Cloud projesinin kimliğiyle değiştirin.

  2. Bu GitHub deposunu indirin

    İndir

  3. Tercih ettiğiniz yerel geliştirme ortamında, indirilen arşiv dosyasını çıkarın ve adk-samples/python/agents/travel-concierge dizinini açın.

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

  4. ADK yapay zeka aracına özel yeni bir Cloud Storage paketi oluşturun.

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

    Aşağıdakini değiştirin:

    1. CLOUD_STORAGE_BUCKET_NAME ile kullanmak istediğiniz benzersiz bir paket adı.
    2. PROJECT_ID kısmını, oluşturduğunuz Cloud projesinin kimliğiyle değiştirin.
    3. PROJECT_LOCATION kısmını, oluşturduğunuz Cloud projesinin konumuyla değiştirin.

  5. Aşağıdaki ortam değişkenlerini ayarlayın:

    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

    Aşağıdakini değiştirin:

    1. PROJECT_ID kısmını, oluşturduğunuz Cloud projesinin kimliğiyle değiştirin.
    2. PROJECT_LOCATION kısmını, oluşturduğunuz Cloud projesinin konumuyla değiştirin.
    3. PLACES_API_KEY kısmını, oluşturduğunuz API anahtarının dizesiyle değiştirin.
    4. CLOUD_STORAGE_BUCKET_NAME ifadesini oluşturduğunuz paketin adıyla değiştirin.

  6. ADK yapay zeka aracısını yükleyin ve dağıtın.

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

  7. Proje numarasını ve motor kimliğini, son yazdırılan günlükten sırasıyla PROJECT_NUMBER ve ENGINE_ID olarak alın. Projenizi yapılandırmak için daha sonra her ikisine de ihtiyacınız olacak.

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

Örnek kodu inceleme

İsteğe bağlı olarak, projeyi ayarlamadan önce GitHub'da barındırılan örnek kodu inceleyip tanıyabilirsiniz.

Python

GitHub'da göster

Apps Komut Dosyası

GitHub'da göster

Projeyi oluşturma ve yapılandırma

Python

  1. Bu GitHub deposunu indirin

    İndir

  2. Tercih ettiğiniz yerel geliştirme ortamında, indirilen arşiv dosyasını çıkarın ve add-ons-samples/python/travel-adk-ai-agent dizinini açın.

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

  3. Önceki adımlarda indirilen hizmet hesabından credentials.json JSON anahtar dosyasını proje dizinine taşıyın.

  4. Google Cloud Console'da Cloud Run'a gidin:

    Cloud Run'a git

  5. Write a function'ı (İşlev yaz) tıklayın.

  6. Hizmet oluştur sayfasında işlevinizi ayarlayın:

    1. Hizmet adı alanına travel-concierge-app girin.
    2. Bölge listesinde, oluşturduğunuz Cloud projesinin konumunu seçin PROJECT_LOCATION.
    3. Uç nokta URL'si bölümünde Kopya oluşturma simgesi simgesini tıklayın.
    4. Çalışma zamanı listesinde Python'ın en son sürümünü seçin.
    5. Kimlik Doğrulama bölümünde Herkese açık erişime izin ver'i seçin.
    6. Containers, Volumes, Networking, Security (Kapsayıcılar, Birimler, Ağ, Güvenlik) bölümündeki Resources (Kaynaklar) altında:
      1. Bellek alanında 1 GiB'i seçin.
      2. CPU alanında 2'yi seçin.
    7. Oluştur'u tıklayın ve Cloud Run'ın hizmeti oluşturmasını bekleyin. Konsol sizi Kaynak sekmesine yönlendirir.

  7. Tercih ettiğiniz yerel geliştirme ortamında projenin kaynağını dağıtın:

    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

    Aşağıdakini değiştirin:

    1. PROJECT_LOCATION ile daha önce oluşturduğunuz Cloud Run işlevinin konumu.
    2. LOCATION ile önceki adımlarda oluşturulan Google Cloud projesinin konumu PROJECT_LOCATION.
    3. PROJECT_NUMBER ile önceki adımlarda dağıtılan Travel Concierge ADK AI Agent'ın proje numarası.
    4. ENGINE_ID ile önceki adımlarda dağıtılan Seyahat Asistanı ADK'sı AI Agent'ın motor kimliği.
    5. BASE_URL ile daha önce kopyaladığınız uç nokta URL'sini değiştirin.

Apps Komut Dosyası

Apps Komut Dosyası projesi oluşturmak ve bunu dağıtılmış Travel Concierge ADK yapay zeka aracınızı kullanacak şekilde yapılandırmak için:

  1. Travel Concierge ADK AI Agent Apps Komut Dosyası projesini açmak için aşağıdaki düğmeyi tıklayın.
    Projeyi açın

  2. Genel bakış'ı, ardından Kopya oluşturma simgesi Kopya oluştur'u tıklayın.

  3. Apps Komut Dosyası projesinin kopyanıza ad verin:

    1. Copy of Travel Concierge ADK AI Agent'ı (Seyahat Concierge ADK Yapay Zeka Aracısı Kopyası) tıklayın.
    2. Proje başlığı'na Travel Concierge ADK AI Agent yazın.
    3. Yeniden adlandır'ı tıklayın.

  4. Apps Script projenizde Proje ayarları simgesi Düzenleyici'ye tıklayın ve Dosyayı yukarı taşı dosya eylemini kullanarak VertexAi.gs dosyasını AgentHandler.gs dosyasının üzerine gelene kadar yukarı taşıyın.

  5. Apps Komut Dosyası projenizde Proje ayarları simgesi Proje Ayarları'nı tıklayın, Komut dosyası özelliklerini düzenle'yi tıklayın, ardından Komut dosyası özelliği ekle'yi tıklayarak aşağıdaki komut dosyası özelliklerini ekleyin:

  6. ENGINE_ID ile önceki adımlarda dağıtılan Travel Concierge ADK Yapay Zeka Temsilcisi'nin arama motoru kimliği ENGINE_ID.

  7. LOCATION ile önceki adımlarda oluşturulan Google Cloud projesinin konumu PROJECT_LOCATION.

  8. PROJECT_NUMBER ile önceki adımlarda dağıtılan Travel Concierge ADK AI Agent'ın proje numarası PROJECT_NUMBER.

  9. SERVICE_ACCOUNT_KEY ile önceki adımlarda indirilen hizmet hesabının JSON anahtarı (ör. { ... })

  10. Komut dosyası özelliklerini kaydet'i tıklayın.

  11. Apps Komut Dosyası projenizde Proje ayarları simgesi Proje Ayarları'nı tıklayın.

  12. Google Cloud Platform (GCP) Projesi bölümünde Projeyi değiştir'i tıklayın.

  13. GCP proje numarası bölümüne, önceki adımlarda dağıtılan Travel Concierge ADK AI Agent'ın proje numarasını yapıştırın, PROJECT_NUMBER.

  14. Projeyi ayarla'yı tıklayın. Cloud projesi ve Apps Komut Dosyası projesi artık bağlı.

Gmail, Takvim, Drive, Dokümanlar, E-Tablolar ve Slaytlar'da dağıtma

Python

Testi etkinleştirmek için örnek projeyi tüm Google Workspace uygulamalarına (Google Chat hariç) yüklemek üzere Google Workspace eklenti dağıtımı kullanın.

  1. Tercih ettiğiniz yerel geliştirme ortamında, projenin kod kaynağındaki deployment.json dosyasını açın ve $BASE_URL ifadesinin tüm örneklerini, önceki adımlarda kopyaladığınız Endpoint URL olan BASE_URL değeriyle değiştirin.

  2. travel-concierge-addon adlı bir Google Workspace eklenti dağıtımı oluşturun:

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

  3. Google Workspace eklenti dağıtımını yükleyin:

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

Apps Komut Dosyası

Testi etkinleştirmek için Apps Komut Dosyası projesini Google Chat hariç tüm Google Workspace uygulamalarına yükleyin.

  1. Apps Komut Dosyası projenizde Dağıt > Test dağıtımları'nı ve ardından Yükle'yi tıklayın.

Eklentiye artık Google Workspace uygulamasının kenar çubuklarından erişebilirsiniz.

Chat'e dağıtma

Python

Testi etkinleştirmek için uç nokta URL'sini kullanarak örnek projeyi Chat'e yükleyin.

  1. Konsolda arama yapın Google Chat API, Google Chat API'yi, ardından Yönet'i ve Yapılandırma'yı tıklayın.

    Google Chat API Yapılandırma sayfasına gidin

  2. Chat uygulamasını ayarlayın:

    1. Uygulama adı alanına Travel ADK AI Agent girin.
    2. Avatar URL'si alanına https://goo.gle/3SfMkjb girin.
    3. Açıklama alanına Travel ADK AI Agent girin.
    4. Bağlantı ayarları bölümünde HTTP uç nokta URL'si'ni seçin.
    5. Tetikleyiciler bölümünde Tüm tetikleyiciler için ortak bir HTTP uç noktası URL'si kullan'ı seçin.
    6. HTTP uç nokta URL'si alanına daha önce kopyaladığınız Uç Nokta URL'sini yapıştırın BASE_URL.
    7. Tam olarak uygulanmış Chat uygulamasının kullandığı bir hızlı komut kaydedin:
      1. Komutlar bölümünde Komut ekle'yi tıklayın.
      2. Komut kimliği alanına 1 yazın.
      3. Açıklama bölümüne Reset session yazın.
      4. Komut türü bölümünde Hızlı komut'u seçin.
      5. Ad alanına Reset session yazın.
      6. Bitti'yi tıklayın. Hızlı komut kaydedilir ve listelenir.
    8. Görünürlük bölümünde Bu Chat uygulamasını, Workspace alanınızdaki belirli kişiler ve gruplar için kullanılabilir hale getir'i seçin ve e-posta adresinizi girin.
    9. Günlükler bölümünde Günlük hatalarını Logging'e seçeneğini belirleyin.
    10. Kaydet'i tıklayın.

Apps Komut Dosyası

Testi etkinleştirmek için Head Deployment ID'yi kullanarak Apps Komut Dosyası projesini Chat'e yükleyin.

  1. Apps Komut Dosyası projenizde Dağıt > Dağıtımları test et'i, ardından Ana dağıtım kimliğini kopyalama simgesi Baş Dağıtım Kimliği bölümünde Kopyala'yı tıklayın.

  2. Konsolda Google Chat API simgesini arayın, Google Chat API'yi, ardından Yönet'i ve Yapılandırma'yı tıklayın.

    Google Chat API Yapılandırma sayfasına gidin

  3. Chat uygulamasını ayarlayın:

    1. Uygulama adı alanına Travel ADK AI Agent girin.
    2. Avatar URL'si alanına https://goo.gle/3SfMkjb girin.
    3. Açıklama alanına Travel ADK AI Agent girin.
    4. Bağlantı ayarları bölümünde Apps Komut Dosyası'nı seçin.
    5. Deployment ID (Dağıtım Kimliği) alanına, daha önce kopyaladığınız Head deployment ID'yi (Ana dağıtım kimliği) yapıştırın.
    6. Tam olarak uygulanmış Chat uygulamasının kullandığı bir hızlı komut kaydedin:
      1. Komutlar bölümünde Komut ekle'yi tıklayın.
      2. Komut kimliği alanına 1 yazın.
      3. Açıklama bölümüne Reset session yazın.
      4. Komut türü bölümünde Hızlı komut'u seçin.
      5. Ad alanına Reset session yazın.
      6. Bitti'yi tıklayın. Hızlı komut kaydedilir ve listelenir.
    7. Görünürlük bölümünde Bu Chat uygulamasını, Workspace alanınızdaki belirli kişiler ve gruplar için kullanılabilir hale getir'i seçin ve e-posta adresinizi girin.
    8. Günlükler bölümünde Günlük hatalarını Logging'e seçeneğini belirleyin.
    9. Kaydet'i tıklayın.

Uygulamaya artık Google Chat'ten erişebilirsiniz.

  1. Google Chat'i açın.

    Google Chat'e gidin.

  2. Chat DM alanı oluşturun:

    1. Yeni Sohbet'i tıklayın.
    2. Aramada uygulamayı yazıp seçin Travel ADK AI Agent.
    3. Install app iletişim kutusunda Uygulamayı yükle'yi tıklayın.
    4. Install app iletişim kutusu kapanır ve yeni oluşturulan Chat DM alanı seçilir.

Chat uygulaması, mesajlara yanıt vermeye hazırdır.

Aracıyı test etme

  1. Gmail'i açın.

    Gmail'e gidin

  2. Kendinize aşağıdaki e-postayı gönderin:

    • Konu: You need to travel to Paris
    • Body: Please be there between 11/25/2025 and 11/30/2025!

  3. Kenar çubuğundan Travel ADK AI Agent eklentisini açın.

  4. Eklentinin kurulumunu tamamlamak için İzin ver'i tıklayın.

  5. Aşağıdaki isteği yapılandırdıktan sonra Gönder'i tıklayın:

    • Mesaj: Please help me plan this travel!
    • Bağlam: Mevcut e-posta'yı seçin.

    Kenar çubuğu, temsilcinin yanıtıyla güncellenir.

    Gmail'den seyahat planlama

  6. Chat DM alanına yönlendirilmek için Chat'i aç'ı tıklayın.

  7. + > Oturumu sıfırla'yı tıklayın.

    İşlemin tamamlandığını onaylayan yeni bir mesaj alırsınız: OK, let's start from the beginning, what can I help you with?

  8. Mesajı gönderin Give me ideas.

    Yeni mesajlar, temsilcinin yanıtıyla birlikte gönderilir.

    Chat'ten beyin fırtınası yapma

  9. Eyfel Kulesi gibi herhangi bir yerin fotoğrafını yükledikten sonra I want to go there! mesajını gönder.

    Yeni mesajlar, temsilcinin yanıtıyla birlikte gönderilir.

    Chat ekinden konum ayrıntılarını alma

Sınırlamalar

HTTP

Chat dışındaki Google Workspace uygulamalarında yapay zeka aracısının aşağıdaki sınırlamaları vardır:

  • Senkronize: Yan çubuklar yalnızca kullanıcı etkileşimlerine yanıt olarak güncellenebilir. Bu nedenle, yapay zeka aracısı yanıtları yalnızca tam olarak tamamlandıktan sonra gösterilir (akış yok).

  • Zaman aşımına uğrayabilir: Kenar çubuğu güncellemelerinin tamamlanması birkaç dakikadan uzun sürdüğünde zaman aşımına uğrarlar.

Bu sınırlamalar Chat'te geçerli değildir.

Apps Komut Dosyası

Tüm Google Workspace uygulamalarında yapay zeka temsilcisi, UrlFetchApp kullanarak Vertex AI REST API'lerini çağırır. Bu durum aşağıdaki sınırlamalara neden olur:

  • Senkronize: Yapay zeka aracısı yanıtları yalnızca tamamlama işlemi bittikten sonra döndürülür (akış yok).

  • Zaman aşımına uğrayabilir: Yapay zeka aracısı isteklerinin tamamlanması yaklaşık bir dakikadan uzun sürdüğünde zaman aşımına uğrarlar.

Özelleştirme

Bu çözüm, Vertex AI Agent Engine'de barındırılan ADK yapay zeka temsilcilerini, Google Workspace uygulama kullanıcı arayüzlerinin bir alt kümesini ve Travel Concierge örneğinin yanıtlarına özgü yanıt oluşturma işlemlerini destekler. Çözümde genişletilebilir bir çerçeve kullanıldığından aşağıdaki dosyaları değiştirerek çözümü özelleştirebilirsiniz:

Python

  • main.py: Ana kullanıcı arayüzlerini ve kullanıcı etkileşimleri mantığını (Google Workspace etkinlik işleyicileri) tanımlar. Tipik bir uzantı, Gmail uygulamasında Gmail mesajlarıyla yapılan işleme benzer şekilde, Drive uygulamasında Drive dokümanlarını bağlam özelliği olarak etkinleştirmek olacaktır.

  • vertex_ai.py: Yapay zeka temsilcisi oturumlarını, yanıtlarını ve hatalarını yönetir. Ayrıca, temsilci etkileşimlerini ve yanıt oluşturmayı desteklemek için uygulanacak Vertex AI'e özgü arayüzleri tanımlar. Tipik uzantılar, ayrı kullanıcı sohbetleri için çoklu oturum desteği ve diğer yapay zeka aracısı yönetim platformları eklemeyi içerir.

  • agent_handler.py: Chat ve Chat dışı uygulamaların belirli durumlarında vertex_ai.py içinde tanımlanan Vertex AI'a özgü arayüzleri uygular. Tipik bir uzantı, kullanıcılara yapay zeka aracısı yanıtları hakkında geri bildirim göndermeleri için düğmeler eklemek olabilir.

  • google_workspace.py: API çağrılarını kullanarak yapay zeka dışı aracı yönetim platformu etkileşimlerini uygular. Bu örnekte, bağlam ayrıntılarını toplamak ve işlem yapmak için yalnızca Google Workspace API'leri kullanılır. Google Takvim veya bir müşteri ilişkileri yönetiminden (CRM) işletme verilerini almak için işlevler eklemek tipik bir uzantı olur.

  • travel_agent_ui_render.gs: Alt aracılar ve Workspace uygulamaları için Seyahat Asistanı'na özel yanıt oluşturma işlemlerini uygular. Tipik uzantılar, uçuş seçeneklerini grafik olarak görüntülemek için yeni yanıt oluşturma desteği ve diğer yapay zeka aracılarını eklemeyi içerir.

Apps Komut Dosyası

  • Code.gs: Ana kullanıcı arayüzlerini ve kullanıcı etkileşimleri mantığını (Google Workspace etkinlik işleyicileri) tanımlar. Tipik bir uzantı, Gmail uygulamasında Gmail mesajlarıyla yapılan işleme benzer şekilde, Drive uygulamasında Drive dokümanlarını bağlam özelliği olarak etkinleştirmek olacaktır.

  • VertexAi.gs: Yapay zeka temsilcisi oturumlarını, yanıtlarını ve hatalarını yönetir. Ayrıca, temsilci etkileşimlerini ve yanıt oluşturmayı desteklemek için uygulanacak Vertex AI'e özgü arayüzleri tanımlar. Tipik uzantılar, ayrı kullanıcı sohbetleri için çoklu oturum desteği ve diğer yapay zeka aracısı yönetim platformları eklemeyi içerir.

  • AgentHandler.gs: Chat ve Chat dışı uygulamalarda, VertexAi.gs içinde tanımlanan Vertex AI'a özgü arayüzleri uygular. Tipik bir uzantı, kullanıcılara yapay zeka aracısı yanıtları hakkında geri bildirim göndermeleri için düğmeler eklemek olabilir.

  • GoogleWorkspace.gs: API çağrılarını kullanarak yapay zeka dışı aracı yönetim platformu etkileşimlerini uygular. Bu örnekte, bağlam ayrıntılarını toplamak ve işlem yapmak için yalnızca Google Workspace API'leri kullanılır. Google Takvim veya bir müşteri ilişkileri yönetiminden (CRM) işletme verilerini almak için işlevler eklemek tipik bir uzantı olur.

  • TravelAgentUiRender.gs: Alt aracılar ve Workspace uygulamaları için Travel Concierge'a özel yanıt oluşturma işlemlerini uygular. Tipik uzantılar, uçuş seçeneklerini grafik olarak görüntülemek için yeni yanıt oluşturma desteği ve diğer yapay zeka aracılarını eklemeyi içerir.

Temizleme

Bu eğitimde kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini önlemek istiyorsanız Cloud projesini silmenizi öneririz.

  1. Google Cloud Console'da Kaynakları yönetin sayfasına gidin. Şunu tıklayın: Menü > IAM ve Yönetici > Kaynakları Yönetin.

    Resource Manager'a gidin

  2. Proje listesinde, silmek istediğiniz projeyi seçin ve Sil'i tıklayın.
  3. İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.