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

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

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ştiricilere 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 Grafiksel Kullanıcı Arayüzü (GUI) ekleyeceksiniz.

• 

  Şekil 1. Chat'teki yapay zeka aracısını kullanarak seyahat fikirleri üretiyoruz.

• 

  Şekil 2. Gmail'deki yapay zeka aracısını kullanarak seçili e-postadaki bağlamdan yola çıkarak seyahat planlamak.

Hedefler

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

Bu çözüm hakkında

Bu çözüm şu temel teknolojilere dayanmaktadır: ADK, Google Cloud ve Google Workspace API'leri, Vertex AI Agent Engine ve Card çerçevesi.

GUI'ler, Sohbet ve Sohbet dışı (Gmail, Takvim, Drive, Dokümanlar, E-Tablolar, Slaytlar) uygulamaların özel özelliklerini ve sınırlamalarını dikkate almak amacıyla farklı şekilde tasarlanmıştır.

Özellikler

Travel Concierge 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 bir oturumu paylaşır. Kullanıcılar yeni bir görüşme başlatmak için oturumlarını manuel olarak sıfırlayabilirler.

• Zengin mesajlaşma: Kullanıcılar zengin metin ve kart widget'larıyla kısa mesaj gönderir ve yanıtlar alır.

• 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:

• Çoklu modlu kullanıcı mesajlaşması: Kullanıcılar, doğrudan Sohbet alanından kaydedilen ses ve video da dahil olmak üzere ekli mesajlar gönderebilir.

• Görsel olarak daha gelişmiş yanıtlar: Kart çerçevesinin yalnızca Sohbet özelliklerine ve daha fazla görüntüleme alanına güvenerek, resimli karusel gibi daha gelişmiş araçlarla yanıtlar oluşturulabilir.

Diğer uygulamalarda şu ek özellikler bulunur:

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

• Gmail bağlamı: Kullanıcılar e-postalarla mesaj gönderebilir (bu örnekte tek konu ve gövdeyle 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

Travel Concierge uygulaması, Google Workspace uygulamalarından Google Workspace eklenti etkileşim olaylarını alır ve işler, ADK AI aracısını uyarmak ve kullanıcı oturumlarını yönetmek için Vertex AI'yı kullanır ve bağlamı toplamak ve yanıtları görüntülemek için Google Cloud ve Google Workspace API'lerine güvenir.

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

HTTP

• 

  Ş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.

• 

  Ş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ı

• 

  Şekil 3. Sohbet uygulaması, kullanıcı mesajından gelen eklerle bağlamı tamamlar ve alt aracı etkileşimlerinin geçmişini ve son genel yanıtı kronolojik sırayla içeren bir dizi mesaj gönderir.

• 

  Ş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

• Google Chat'e erişimi olan bir Business veya Enterprise Google Workspace hesabı.

• İnternete erişimi olan bir web tarayıcısı.

• Travel Concierge ADK AI temsilcisine özgü ön koşullar

  • Python 3.10+: Kurulum için resmi Python web sitesindeki talimatları izleyin.
  • uv: Yükleme için resmi uv web sitesindeki talimatları uygulayın.
  • Google Cloud KSA: Yükleme için resmi Google Cloud web sitesindeki talimatları uygulayın.

Ortamı hazırlayın

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 konsolunda Menü > IAM ve Yönetici > 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 oluşturulduktan sonra proje kimliği değiştirilemez, bu nedenle projenin ö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özat'a tıklayın. Ardından Seç'e tıklayın.
   Dikkat: Google Workspace kuruluşunuzu bulamıyor musunuz?
   Bu, bir Google Workspace hesabında oturum açmadığınız anlamına gelir. Google Workspace geliştirici belgelerinde açıklanan özelliklerin bazıları yalnızca bir kuruluşla ilişkili projelerde kullanılabilir.
4. Oluştur'u tıklayın. Google Cloud konsolu Pano sayfasına yönlendirilir ve projeniz birkaç dakika içinde oluşturulur.

gcloud CLI

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

• Cloud Shell: gcloud CLI'si önceden kurulmuş bir çevrimiçi terminali kullanmak için Cloud Shell'i etkinleştirin.
  Cloud Shell'i Etkinleştirin
• Yerel Kabuk: Yerel bir geliştirme ortamı kullanmak için gcloud CLI'yi yükleyin ve başlatın.
  Bir Bulut 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 öğesini değiştirin.

Bulut projesi için faturalandırmayı etkinleştirin

Bir faturalandırma hesabını bağlayamıyorsanız, bu değişikliği yapmak için gereken izinlere sahip değilsiniz demektir. Daha fazla bilgi için Faturalandırmayı etkinleştirmek için gereken izinler bölümüne bakın.

Google Cloud konsolu

1. Google Cloud konsolunda Faturalandırma'ya gidin. Menü > Faturalandırma > Projelerim'e tıklayın.

   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 Eylemler menüsünü () açın, Faturalandırmayı değiştir'e tıklayın ve Cloud Billing 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ı bir Google Cloud projesine bağlayın:

   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 Bulut projesinin Proje Kimliğidir.
   • BILLING_ACCOUNT_ID, Google Cloud projesiyle bağlantı kurmak için kullanılacak faturalandırma hesabı kimliğidir.

Google Cloud API'lerini etkinleştirin

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 Bulut projesinde etkinleştirdiğinizi onaylayın ve ardından İleri'ye tıklayın.

3. Doğru API'leri etkinleştirdiğinizi onaylayın ve ardından Etkinleştir'e tıklayın.

Apps Komut Dosyası

1. Google Cloud konsolunda Vertex AI, Yerler, Kişiler, 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 Yerler API anahtarını edinin

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'nda Başlayın iletişim kutusu, yeni oluşturduğunuz API anahtarını (alfanümerik bir dize) görüntüler. Bu dizeye sonraki bölümlerde ihtiyacınız olacak.

Not: Zaten uygun bir API anahtarınız varsa, Google Haritalar Platformu'nda Başlayın iletişim kutusu değil, API anahtarlarının listesi görüntülenir. Anahtarı görüntülemek için Anahtarı göster'i seçin.

Google Cloud konsolunda bir hizmet hesabı oluşturun

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

Google Cloud konsolu

1. Google Cloud konsolunda 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ı girin ve ardından Oluştur ve devam et'e tıklayın.
   Not: Varsayılan olarak Google, benzersiz bir hizmet hesabı kimliği oluşturur. Kimliği değiştirmek isterseniz, hizmet hesabı kimliği alanındaki kimliği değiştirin.
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şlemleri yönetebilecek ve gerçekleştirebilecek 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 bir anahtar oluşturun

Uyarı: Bu örnekte basitlik adına dışa aktarılmış bir hizmet hesabı anahtarı kullanılmıştır. Özel anahtarın dışa aktarılması, kaynak kontrolü gibi güvenli olmayan bir konumda depolanmaması gerektiğinden üretimde önerilmez.

Güvenli hizmet hesabı uygulamaları ve en iyi uygulamalar hakkında daha fazla bilgi edinmek için Hizmet hesaplarını ne zaman kullanacağınızı seçme başlıklı makaleyi inceleyin.

Hizmet hesabı için özel bir anahtar oluşturmak ve indirmek için şu adımları izleyin:

1. Google Cloud konsolunda 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'u seçin ve ardından Oluştur'a 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.

OAuth kullanıcı rızası ekranını yapılandırma

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 için OAuth iznini yapılandırma başlıklı kılavuzun tamamını inceleyin.

Seyahat Danışmanı ADK AI Aracısını Dağıtın

1. Henüz yapmadıysanız, Google Cloud hesabınızla kimlik doğrulaması yapın ve Google Cloud projenizi kullanmak için Google Cloud CLI'yi 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 değerini oluşturduğunuz Bulut 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 AI aracısına özel yeni bir Bulut Depolama kovası oluşturun.

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

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

   1. Kullanmak istediğiniz benzersiz bir kova adı olan CLOUD_STORAGE_BUCKET_NAME.
   2. PROJECT_ID kısmını, oluşturduğunuz Cloud projesinin kimliğiyle değiştirin.
   3. Oluşturduğunuz Bulut projesinin konumuyla PROJECT_LOCATION.

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. Oluşturduğunuz Bulut projesinin konumuyla PROJECT_LOCATION.
   3. Oluşturduğunuz API anahtarının dizesiyle PLACES_API_KEY.
   4. Oluşturduğunuz kovanın adı ile CLOUD_STORAGE_BUCKET_NAME.

6. ADK AI aracısını kurun ve dağıtın.

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

7. Son yazdırılan günlükten proje numarasını ve motor kimliğini 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 kurmadan önce GitHub'da barındırılan örnek kodu inceleyip kendinizi buna alıştırmak için bir dakikanızı ayırın.

Python

GitHub'da göster

Apps Komut Dosyası

GitHub'da göster

Projeyi oluşturun ve yapılandırın

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

4. Google Cloud konsolunda Cloud Run'a gidin:

   Cloud Run'a git

5. Bir fonksiyon yaz'a 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 Bulut projesinin konumunu (PROJECT_LOCATION) seçin.
   3. Uç nokta URL'si bölümünde 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 Genel 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'ı 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. Daha önce oluşturduğunuz Cloud Run işlevinin konumuyla PROJECT_LOCATION.
   2. Önceki adımlarda oluşturulan Google Cloud projesinin konumu olan LOCATION, PROJECT_LOCATION.
   3. Önceki adımlarda konuşlandırılan Travel Concierge ADK AI Agent'ın proje numarasıyla PROJECT_NUMBER.
   4. ENGINE_ID ile önceki adımlarda dağıtılan Seyahat Asistanı ADK'sı AI Agent'ın motor kimliği.
   5. Daha önce kopyaladığınız Uç Nokta URL'si ile BASE_URL.

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 Uygulama Komut Dosyası projesini açmak için aşağıdaki düğmeye tıklayın.
   Projeyi açın.

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

3. Apps Script projenizin kopyasına şu 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 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 Script projenizde Proje Ayarları'na tıklayın, Komut dosyası özelliklerini düzenle'ye tıklayın ve ardından aşağıdaki komut dosyası özelliklerini eklemek için Komut dosyası özelliği ekle'ye tıklayın:

6. Önceki adımlarda dağıtılan Travel Concierge ADK AI Agent'ın motor kimliğiyle ENGINE_ID, ENGINE_ID.

7. Önceki adımlarda oluşturulan Google Cloud projesinin konumu olan LOCATION, PROJECT_LOCATION.

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

9. Önceki adımlarda indirilen hizmet hesabından JSON anahtarıyla SERVICE_ACCOUNT_KEY (örneğin { ... }).

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

11. Apps Komut Dosyası projenizde, 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ıdır.

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

Python

Test etmeyi etkinleştirmek için örnek projeyi tüm Google Workspace uygulamalarına (Google Chat hariç) yüklemek üzere bir Google Workspace eklentisi 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 Uç Nokta URL'si 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 Script projenizde Dağıt > Dağıtımları test et'e ve ardından Yükle'ye tıklayın.

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

Sohbete Dağıt

Python

Test etmeyi etkinleştirmek için Uç Nokta URL'sini kullanarak örnek projeyi Sohbet'e yükleyin.

1. Konsolda Google Chat API öğesini arayın, Google Chat API'ye, ardından Yönet'e ve Yapılandırma'ya 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 altında 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, BASE_URL, yapıştırın.
   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. Ad alanına Reset session yazın.
      6. Bitti'yi tıklayın. Hızlı komut kayıt altına alınır ve listelenir.
   8. Görünürlük altında Bu Sohbet uygulamasını Çalışma Alanı Alanınızdaki belirli kişiler ve gruplar için kullanılabilir hale getirin seçeneğini belirleyin ve e-posta adresinizi girin.
   9. Günlükler altında Günlük Kaydına Hataları Kaydet'i seçin.
   10. Kaydet'i tıklayın.

Apps Komut Dosyası

Test etmeyi etkinleştirmek için Baş Dağıtım Kimliğini kullanarak Uygulama Komut Dosyası projesini Sohbet'e yükleyin.

1. Apps Script projenizde Dağıt > Dağıtımları test et'e tıklayın, ardından Baş Dağıtım Kimliği altında Kopyala'ya tıklayın.

2. 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

3. Sohbet uygulamasını kurun:

   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ı altında Uygulama Komut Dosyası'nı seçin.
   5. Dağıtım Kimliği alanına, daha önce kopyaladığınız Başlık dağıtım kimliğini yapıştırın.
   6. Tam olarak uygulanan Sohbet 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. Ad alanına Reset session yazın.
      6. Bitti'yi tıklayın. Hızlı komut kayıt altına alınır ve listelenir.
   7. Görünürlük altında Bu Sohbet uygulamasını Çalışma Alanı Alanınızdaki belirli kişiler ve gruplar için kullanılabilir hale getirin seçeneğini belirleyin ve e-posta adresinizi girin.
   8. Günlükler altında Günlük Kaydına Hataları Kaydet'i 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ını 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'ye 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. Aşağıdaki e-postayı kendinize 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 AI Agent eklentisini açın.

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

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

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

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

   

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. Give me ideas mesajını gönder.

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

   

9. Eyfel Kulesi gibi herhangi bir konumun resmini yükledikten sonra I want to go there! mesajını gönderin.

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

   

Not: Seyahat ADK Yapay Zeka Aracısı eklentisi, Gmail'de olduğu gibi Takvim, Drive, Dokümanlar, E-Tablolar ve Slaytlar'daki kenar çubuğundan da açılabilir.

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:

• Eşzamanlıdır: Kenar çubukları yalnızca kullanıcı etkileşimlerine yanıt olarak güncellenebilir, bu nedenle yapay zeka aracısının yanıtları yalnızca tam tamamlandıktan sonra görüntülenir (akış yok).

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

Chat'te bu sınırlamalar mevcut değil.

Apps Komut Dosyası

Tüm Google Workspace uygulamalarında, AI aracısı UrlFetchApp kullanarak Vertex AI REST API'lerini çağırır ve bu da aşağıdaki sınırlamalara neden olur:

• Eşzamanlıdır: Yapay zeka aracısının yanıtları yalnızca tam tamamlanmadan 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 aracıları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 olay işleyicileri) tanımlar. Tipik bir eklenti, Drive uygulaması için Drive belgelerini bağlam özelliği olarak etkinleştirmek olurdu; bu, Gmail uygulaması için Gmail iletilerinde yapılanlara benzer.

• vertex_ai.py: AI aracı oturumlarını, yanıtları, hataları yönetir ve aracı etkileşimlerini ve yanıt oluşturmalarını desteklemek için uygulanacak Vertex AI'ya özgü arayüzleri tanımlar. Tipik uzantılar, ayrı kullanıcı görüşmeleri için çoklu oturum desteği ve diğer AI aracı yönetim platformlarını eklemek olacaktır.

• agent_handler.py: vertex_ai.py'de tanımlanan Vertex AI'ya özgü arayüzleri, Sohbet ve Sohbet dışı uygulamaların belirli durumlarında 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 olay işleyicileri) tanımlar. Tipik bir eklenti, Drive uygulaması için Drive belgelerini bağlam özelliği olarak etkinleştirmek olurdu; bu, Gmail uygulaması için Gmail iletilerinde yapılanlara benzer.

• 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: VertexAi.gs'de tanımlanan Vertex AI'ya özgü arayüzleri, Sohbet ve Sohbet dışı uygulamaların belirli durumlarında uygular. Tipik bir uzantı, kullanıcıların AI aracılarının yanıtları hakkında geri bildirim göndermelerine olanak tanıyan düğmeler eklemek olacaktır.

• 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ıza ücret yansıtılmasını önlemek için Cloud projesini silmenizi öneririz.

Dikkat: Bir projeyi silmenin aşağıdaki etkileri vardır:

• Projedeki her şey silinir. Bu eğitim için mevcut bir projeyi kullandıysanız projeyi sildiğinizde projede yaptığınız diğer tüm çalışmalar da silinir.
• Özel proje kimlikleri kaybolur. Bu projeyi oluştururken gelecekte kullanmak istediğiniz özel bir proje kimliği oluşturmuş olabilirsiniz. Proje kimliğini kullanan URL'leri (ör. appspot.com'daki bir URL) korumak için projenin tamamını silmek yerine proje içindeki seçili kaynakları silin.

Birden fazla eğitici ve hızlı başlangıç kılavuzunu incelemeyi planlıyorsanız projeleri yeniden kullanmak proje kotası sınırlarını aşmanızı önleyebilir.

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

   Kaynak Yöneticisine Git

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

İlgili konular

• ADK yapay zeka aracısı ve Gemini modeliyle ifadelerin doğruluğunu kontrol etme
• Temel yapay zeka kavramlarını Sohbet uygulamalarına entegre edin
• Apps Komut Dosyası ile Google Workspace eklentisi olarak Chat uygulaması oluşturma