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

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

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

Genel Bakış

Bu eğitimde, Agent Development Kit (ADK)'den Seyahat Concierge örneğini dağıtacaksınız. Seyahat Asistanı, Google Haritalar Platformu Places API, Google Arama Temellendirme ve Model Context Protocol (MCP) sunucusu gibi araçları kullanan, çoklu ajan içeren bir yapay zeka uygulamasıdı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 doğrudan Chat, Gmail, Takvim, Drive, Dokümanlar, E-Tablolar ve Slaytlar'da 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 Chat'teki yapay zeka ajanını kullanma.
  • Seçili e-postadaki bağlamdan yola çıkarak seyahat planlamak için Gmail'deki yapay zeka aracını kullanma.
    Şekil 2. Gmail'deki yapay zeka aracısını kullanarak seçili e-postadaki bağlamdan seyahat planlama

Hedefler

  • Ortamı ayarlayın.
  • Yapay zeka ajanını dağıtın.
  • Projeyi ayarlayın.
  • 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 & Google Workspace API'leri, Vertex AI Agent Engine, ve Card framework olmak üzere aşağıdaki 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ı içeren kısa mesajlar gönderip yanıtlar alır.

  • Hata işleme: Beklenmeyen 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 Sohbet alanında kaydedilen ses ve videolar da dahil olmak üzere ek içeren mesajlar gönderebilir.

  • Görsel açıdan daha gelişmiş 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 bilgileriyle (bu örnekte doğum günleriyle sınırlı) 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, Chat uygulaması doğrudan mesaj (DM) alanını tek bir düğmeyi tıklayarak yeni sekmede açabilir.

Mimari

Travel Concierge uygulaması, Google Workspace uygulamalarından Google Workspace eklenti etkileşim 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ı işlemleri 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 API Konsolu

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

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

  2. 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 kimliği, proje oluşturulduktan sonra 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 API Konsolu, 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 CLI'nın önceden ayarlandığı bir online terminal kullanmak için Cloud Shell'i etkinleştirin.
    Cloud Shell'i etkinleştirme
  • Yerel kabuk: Yerel geliştirme ortamı kullanmak için gcloud CLI'yı yükleyin ve ilk kullanıma hazırlayı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 yazın.

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

Google API Konsolu

  1. Google API Konsolu'nda Faturalandırma'ya gidin. Şunu tıklayın: Menü > Faturalandırma > Projelerim.

    Projelerim için Faturalandırma'ya git

  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. 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 API Konsolu'nda Vertex AI, Places, People, Google Chat, Gmail, Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry, Cloud Run, Google Workspace eklentileri ve Cloud Resource Manager 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ğinizi onaylayın ve Etkinleştir'i tıklayın.

Apps Komut Dosyası

  1. Google API Konsolu'nda Vertex AI, Places, People, Google Chat ve Cloud Resource Manager 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ğinizi onaylayın ve Etkinleştir'i tıklayın.

Google Haritalar Platformu Places API anahtarı alma

  1. Google API Konsolu'nda 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 Console

  1. Google Cloud Console'da Menü > IAM & Admin > Service Accounts'a (Hizmet Hesapları) gidin.

    Hizmet hesaplarına gidin

    Geri kalan adımlar Google Cloud Console'da gösterilir.

  2. Bir Google Cloud projesi seçin.
  3. Hizmet hesabı oluştur'u tıklayın.
  4. Google Cloud Console'da gösterilecek bir hizmet hesabı adı girin.
  5. Erişim denetimlerini şimdi ayarlamak istemiyorsanız hizmet hesabını oluşturmayı tamamlamak için Bitti'yi tıklayın. Erişim denetimlerini hemen ayarlamak için Oluştur ve devam et'i tıklayın ve sonraki adıma geçin.
  6. İsteğe bağlı: Google Workspace kaynaklarının yanı sıra Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha fazla bilgi için Projelere, klasörlere ve kuruluşlara erişimi yönetme başlıklı makaleyi inceleyin.
  7. Devam'ı tıklayın.
  8. İ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ünme başlıklı makaleyi inceleyin.
  9. Hizmet hesabı oluşturma işlemini tamamlamak için 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 Workspace kaynaklarının yanı sıra Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha fazla bilgi için Projelere, klasörlere ve kuruluşlara erişimi yönetme 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 & Admin > Service Accounts'a (Hizmet Hesapları) gidin.

    Hizmet hesaplarına gidin

    Geri kalan adımlar Google Cloud Console'da gösterilir.

  2. Bir Google Cloud projesi seçin.
  3. Anahtar oluşturmak istediğiniz hizmet hesabının e-posta adresini tıklayın.
  4. Anahtarlar sekmesini tıklayın.
  5. Anahtar ekle açılır menüsünü tıklayıp Yeni anahtar oluştur'u seçin.
  6. Anahtar türü olarak JSON'u seçin ve Oluştur'u tıklayın.

    Herkese açık/özel yeni anahtar çiftiniz oluşturulur ve makinenize hizmet hesabı anahtarı dosyası olarak indirilir. İndirilen JSON dosyasını çalışma dizininize credentials.json olarak kaydedin. Bu dosya, anahtarın tek kopyasıdır. Anahtar dosyasını indirdikten sonra tekrar indiremezsiniz. Anahtarınızı güvenli bir şekilde nasıl depolayacağınız hakkında bilgi edinmek için Hizmet hesabı anahtarlarını yönetmeyle ilgili en iyi uygulamalar başlıklı makaleyi inceleyin.

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 kullanıcı rızası 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 API Konsolu'nda Menü > Google Auth platform > Markalama'ya gidin.

    Markalama'ya gidin.

  2. Google Auth platformunu zaten yapı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 platformu 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 izinleriyle 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 Şirket içi'ni 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 kullanıcı rızası ekranını yapılandırma başlıklı makalenin tamamını inceleyin.

Seyahat Concierge ADK Yapay Zeka Ajanı'nı dağıtma

  1. Henüz yapmadıysanız Google Cloud hesabınızla kimliğinizi doğrulayın ve Google Cloud KSA'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 yerine oluşturduğunuz Cloud projesinin kimliğini girin.

  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ısına ayrılmış 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 paket adını girin.
    2. PROJECT_ID ile oluşturduğunuz Cloud projesinin kimliği.
    3. PROJECT_LOCATION ile oluşturduğunuz Cloud projesinin konumu.

  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 ile oluşturduğunuz Cloud projesinin kimliği.
    2. PROJECT_LOCATION ile oluşturduğunuz Cloud projesinin konumu.
    3. PLACES_API_KEY kısmını, oluşturduğunuz API anahtarının dizesiyle değiştirin.
    4. CLOUD_STORAGE_BUCKET_NAME ile oluşturduğunuz paketin adıyla değiştirin.

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

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

  7. Proje numarasını ve motor kimliğini, sırasıyla PROJECT_NUMBER ve ENGINE_ID olarak son yazdırılan günlükten 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ımak için biraz zaman ayırın.

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 JSON anahtar dosyasını credentials.json proje dizinine taşıyın.

  4. Google API Konsolu'nda Cloud Run'a gidin:

    Cloud Run'a gitme

  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. Runtime (Çalışma zamanı) listesinde en yeni Python 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. Kapsayıcılar, Birimler, Ağ, Güvenlik bölümündeki 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 konumunu girin.
    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 yapay zeka ajanı'nın proje numarası.
    4. ENGINE_ID ile önceki adımlarda dağıtılan Travel Concierge ADK yapay zeka ajanının motor kimliği.
    5. BASE_URL kısmını daha önce kopyaladığınız Uç Nokta URL'si ile değiştirin.

Apps Komut Dosyası

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

  1. Travel Concierge ADK yapay zeka ajanı 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 Asistanı ADK Yapay Zeka Ajanı 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 Komut Dosyası projenizde Proje ayarları simgesi Düzenleyici'yi tıklayın ve VertexAi.gs dosyasını AgentHandler.gs dosyasının üzerine gelene kadar Dosyayı yukarı taşı dosya işlemini kullanarak yukarı taşıyın.

  5. Apps Komut Dosyası projenizde, Proje ayarları simgesi Proje Ayarları'nı, Komut dosyası özelliklerini düzenle'yi ve 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 Ajanı'nın motor 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 yapay zeka ajanı'nın proje numarasını yapıştırın: PROJECT_NUMBER.

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

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 öğesinin 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 eklentisi 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. API Konsolu'nda Google Chat API 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

  2. Chat uygulamasını ayarlama:

    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'si'ni 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. Command ID (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. Name (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 yap'ı seçin ve e-posta adresinizi girin.
    9. Günlükler bölümünde Günlük hatalarını günlüğe kaydetme'yi seçin.
    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 Deploy > Test deployments'ı (Dağıt > Test dağıtımları) ve ardından Head Deployment ID (Baş Dağıtım Kimliği) bölümünde Ana Dağıtım Kimliği kopyalama simgesi Copy'yi (Kopyala) tıklayın.

  2. API Konsolu'nda Google Chat API 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ı ayarlama:

    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. Command ID (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. Name (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 yap'ı seçin ve e-posta adresinizi girin.
    8. Günlükler bölümünde Günlük hatalarını günlüğe kaydetme'yi seçin.
    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şturma:

    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 Sohbet DM alanı seçilir.

Chat uygulaması, mesajları yanıtlamaya hazırdır.

Ajanı 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
    • Gövde: Please be there between 11/25/2025 and 11/30/2025!

  3. Kenar çubuğundan Travel ADK yapay zeka ajanı 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, ajanın 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.

    Aracının yanıtını içeren yeni mesajlar alırsınız.

    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.

    Aracının yanıtını içeren yeni mesajlar alırsınız.

    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 çalışır: 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ış şeklinde gösterilmez).

  • 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 aracısı UrlFetchApp kullanarak Vertex AI REST API'lerini çağırır. Bu durum aşağıdaki sınırlamalara neden olur:

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

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

Özelleştirme

Bu çözüm, Vertex AI Agent Engine'de barındırılan ADK yapay zeka ajanlarını, 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 iletileriyle 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 ajanı oturumlarını, yanıtlarını ve hatalarını yönetir. Ayrıca, ajanı etkileşimlerini ve yanıt oluşturmayı desteklemek için uygulanacak Vertex AI'a ö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. Tipik bir uzantı, Google Takvim veya bir müşteri ilişkileri yönetiminden (CRM) işletme verilerini almak için işlevler eklemek olabilir.

  • travel_agent_ui_render.gs: Alt aracılar ve Workspace uygulamaları için Travel Concierge'e özel yanıt oluşturma işlemlerini uygular. Tipik uzantılar, uçuş seçeneklerini grafiksel olarak görüntülemek için yeni yanıt oluşturma biçimlerine ve diğer yapay zeka aracılarına destek 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 iletileriyle 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 ajanı oturumlarını, yanıtlarını ve hatalarını yönetir. Ayrıca, ajanı 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ışı uygulamaların belirli durumlarında VertexAi.gs içinde tanımlanan Vertex AI'a özgü arayüzleri uygular. Tipik bir uzantı, kullanıcıların yapay zeka aracısı yanıtları hakkında geri bildirim göndermesi 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. Tipik bir uzantı, Google Takvim veya bir müşteri ilişkileri yönetiminden (CRM) işletme verilerini almak için işlevler eklemek olabilir.

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

Temizleme

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

  1. Google API Konsolu'nda Kaynakları yönet sayfasına gidin. Şunu tıklayın: Menü > IAM & Admin > Kaynakları Yönetin.

    Kaynak Yöneticisi'ne 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.