Agent2UI aracısı içeren bir Google Chat uygulaması oluşturma

Bu sayfada, Google Chat'te çalışan ve Agent2UI (A2UI) protokolünü kullanan bir yapay zeka aracısıyla arayüz oluşturan bir Google Workspace eklentisinin nasıl oluşturulacağı açıklanmaktadır. Temsilciyi Agent Development Kit (ADK)'yi kullanarak geliştirir ve Vertex AI Agent Engine'de barındırırsınız.

Yapay zeka temsilcileri, tanımlanmış bir hedefe ulaşmak için ortamlarını bağımsız olarak algılar, akıl yürütür ve karmaşık, çok adımlı işlemleri yürütür. Bu eğitimde, bir araçtan alınan statik profil bilgilerini döndüren temel bir yapay zeka aracısı dağıtıyorsunuz.

A2UI, yapay zeka aracılarına yerel olarak oluşturulan uyarlanabilir, zengin ve etkileşimli kullanıcı arayüzleri üretme olanağı tanır. Ardından, kullanıcı arayüzlerine değil, yapay zeka aracılarının mantığına odaklanabilirsiniz.

Aşağıdaki şemada mimari ve mesajlaşma modeli gösterilmektedir:

Şemada, A2UI temsilcisiyle uygulanan bir sohbet uygulamasıyla etkileşimde bulunan kullanıcının bilgi akışı şu şekildedir:

1. Bir kullanıcı, bir Chat uygulamasına doğrudan mesaj yoluyla ya da bir Chat alanında mesaj gönderir.
2. Apps Script'te veya HTTP uç noktaları olan bir web sunucusu olarak uygulanan Chat uygulaması mantığı, mesajı alır ve işler.
3. Vertex AI Agent Engine ile barındırılan A2UI aracısı, etkileşimi alır ve işler.
4. İsteğe bağlı olarak, Chat uygulaması veya yapay zeka aracısı; Takvim ya da E-Tablolar gibi Google Workspace hizmetleriyle veya Google Haritalar ya da YouTube gibi diğer Google hizmetleriyle entegre edilebilir.
5. Chat uygulaması, yapay zeka aracısının ilerleme durumunu iletmek için Google Chat API'sini kullanarak uyarlanabilir yanıtlar oluşturur ve bunları eşzamansız olarak gönderir.
6. Yanıtlar kullanıcıya iletilir.

Hedefler

• Ortamınızı ayarlayın.
• A2UI aracısını dağıtın.
• Chat uygulamasını dağıtın.
• Chat uygulamasını yapılandırın.
• Chat uygulamasını test edin.

Ön koşullar

• Google Chat'e erişimi olan bir Business veya Enterprise Google Workspace hesabı.
• Faturalandırmanın etkin olduğu bir Google Cloud projesi. Mevcut bir projede faturalandırmanın etkinleştirilip etkinleştirilmediğini kontrol etmek için Projelerinizin faturalandırma durumunu doğrulama bölümüne bakın. Proje oluşturma ve faturalandırmayı ayarlama hakkında bilgi edinmek için Google Cloud projesi oluşturma bölümüne bakın.
• Python 3.11+: Yükleme için resmi Python web sitesindeki talimatları uygulayın.
• Python Poetry: Yükleme için resmi Poetry web sitesindeki talimatları uygulayın.
• Google Cloud KSA: Yükleme için resmi Google Cloud web sitesindeki talimatları uygulayın.

Ortamınızı ayarlama

Google Cloud API'lerini etkinleştirme

Google API'lerini kullanmadan önce bir Google Cloud projesinde etkinleştirmeniz gerekir. Tek bir Google Cloud projesinde bir veya daha fazla API'yi etkinleştirebilirsiniz.

• Google Cloud Console'da Google Chat, Vertex AI ve Cloud Resource Manager API'lerini etkinleştirin.

  API'leri etkinleştirme

OAuth izin ekranını yapılandırma

OAuth 2.0 kullanan tüm uygulamalar için izin ekranı yapılandırması gerekir. Uygulamanızın OAuth izin ekranını yapılandırmak, kullanıcılara ve uygulama inceleyicilerine nelerin gösterileceğini tanımlar ve uygulamanızı kaydeder. Böylece, uygulamanızı daha sonra yayınlayabilirsiniz.

1. Google Cloud Console'da Menü menu > 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 Ş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 iznini yapılandırma başlıklı kılavuzun tamamını inceleyin.

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ü menu > IAM ve Yönetici > Hizmet Hesapları'na gidin.

   Hizmet Hesapları'na gidin

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.

Ö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ü menu > IAM ve Yönetici > Hizmet Hesapları'na gidin.

   Hizmet Hesapları'na gidin

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.

A2UI aracısını 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ı Cloud projenizin kimliğiyle değiştirin.

2. Bu düğmeyi kullanarak googleworkspace/add-ons-samples GitHub deposunu indirin:

   Depoyu indirme

3. Tercih ettiğiniz yerel geliştirme ortamında, indirilen arşiv dosyasını çıkarın ve add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui dizinini açın.

   unzip add-ons-samples-main.zip
   cd add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui

4. ADK aracısı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 yerine Cloud projenizin kimliğini yazın.
   3. PROJECT_LOCATION yerine Cloud projenizin konumunu yazın.

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

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

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

   1. CLOUD_STORAGE_BUCKET_NAME ifadesini oluşturduğunuz paketin adıyla değiştirin.
   2. PROJECT_ID yerine Cloud projenizin kimliğini yazın.
   3. PROJECT_LOCATION yerine Cloud projenizin konumunu yazın.

6. ADK aracısını sanal ortamdan yükleyip dağıtın.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. Aracı kimliğini alın. Chat uygulamasını yapılandırırken daha sonra bu bilgiye ihtiyacınız olacaktır.

   python3 deployment/deploy.py --list

Chat uygulaması projesini oluşturma ve yapılandırma

1. A2UI AI Agent Quickstart Apps Komut Dosyası projesini açmak için aşağıdaki düğmeyi tıklayın.

   Projeyi açın.

2. info_outline Genel bakış > Kopya oluştur'u tıklayın.

3. Apps Komut Dosyası projenizde, Proje Ayarları > Komut dosyası özelliklerini düzenle > Komut dosyası özelliği ekle'yi tıklayarak aşağıdaki komut dosyası özelliklerini ekleyin:

   1. REASONING_ENGINE_RESOURCE_NAME ile önceki adımlarda kopyalanan Vertex AI aracı kaynak adıyla değiştirin.
   2. SERVICE_ACCOUNT_KEY ile önceki adımlarda indirilen hizmet hesabının JSON anahtarı (ör. { ... })

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

5. Google Cloud Console'da Menü menu > IAM ve Yönetici > Ayarlar'a gidin.

   IAM ve Yönetici Ayarları'na gitme

6. Proje numarası alanındaki değeri kopyalayın.

7. Apps Komut Dosyası projenizde Proje Ayarları'nı tıklayın.

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

9. GCP proje numarası bölümüne, önceki adımlarda kopyalanan Google Cloud proje numarasını yapıştırın.

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

Test dağıtımı oluşturma

Bu Apps Komut Dosyası projesi için bir dağıtım kimliğine ihtiyacınız var. Bu kimliği sonraki adımda kullanabilirsiniz.

Ana dağıtım kimliğini almak için aşağıdakileri yapın:

1. Chat uygulaması Apps Komut Dosyası projesinde, Dağıt > Test dağıtımları'nı tıklayın.
2. Baş dağıtım kimliği bölümünde Kopyala'yı tıklayın.
3. Bitti'yi tıklayın.

Chat uygulamasını yapılandırma

Apps Komut Dosyası dağıtımınızı kullanarak Google Chat uygulamasını test için dağıtmak üzere aşağıdaki adımları uygulayın:

1. Konsolda Google Chat API ifadesini arayın ve Google Chat API'yi tıklayın.
2. Yönet'i tıklayın.

3. Yapılandırma'yı tıklayın ve Chat uygulamasını ayarlayın:

   1. Uygulama adı alanına A2UI Quickstart girin.
   2. Avatar URL'si alanına https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png girin.
   3. Açıklama alanına A2UI Quickstart girin.
   4. İşlevsellik bölümünde Alanlara ve grup görüşmelerine katılma'yı seçin.
   5. Bağlantı ayarları bölümünde Apps Komut Dosyası projesi'ni seçin.
   6. Deployment ID (Dağıtım Kimliği) alanına, daha önce kopyaladığınız Head dağıtım kimliğini yapıştırın.
   7. Görünürlük bölümünde Alanınızdaki belirli kişiler ve gruplar'ı seçip e-posta adresinizi girin.

4. Kaydet'i tıklayın.

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

Chat uygulamasını test etme

Chat uygulamanızı test etmek için Chat uygulamasıyla doğrudan mesajlaşma alanı açıp mesaj gönderin:

1. Kendinizi güvenilir test kullanıcıları arasına eklerken sağladığınız Google Workspace hesabını kullanarak Google Chat'i açın.

   Google Chat'e gidin.

2. add Yeni sohbet'i tıklayın.
3. 1 veya daha fazla kişi ekle alanına Chat uygulamanızın adını yazın.

4. Sonuçlardan Chat uygulamanızı seçin. Doğrudan mesaj açılır.

5. Uygulamayla yeni doğrudan mesajda Hello! yazıp enter tuşuna basın.

   Sohbet uygulaması, selamlama metni ve profil adı, resim ve LinkedIn düğmesini içeren bir kartla yanıt verir.

6. Profil başlığını da döndürmeye başlamak için A2UI aracısının uygulamasını güncelleyin.

   Yerel geliştirme ortamınızda a2ui/agent.py dosyasını açın ve döndürülen verilere başlığı ekleyen satırın yorum işaretini kaldırın.

   apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py

   GitHub'da göster
   # Copyright 2026 Google LLC
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #     http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   
   """A2UI agent."""
   
   from google.adk.agents import LlmAgent
   from google.adk.tools.tool_context import ToolContext
   import json
   
   # The schema for any A2UI message. This never changes.
   from .a2ui_schema import A2UI_SCHEMA
   
   def get_user_profile(tool_context: ToolContext) -> str:
       """Call this tool to get the current user profile."""
       return json.dumps({
           "name": "Pierrick Voulet",
           # "title": "DevRel Engineer @ Google Workspace | Gen AI & AI Agents & Agentic AI | Automation & Digital Transformation",
           "imageUrl": "https://io.google/2024/speakers/3ea87822-3160-4d54-89dd-57e185085f79_240.webp",
           "linkedin": "https://www.linkedin.com/in/pierrick-voulet/"
       })
   
   AGENT_INSTRUCTION="""
   You are a user profile assistant. Your goal is to help users get their profile information using a rich UI.
   
   To achieve this, you MUST follow these steps to answer user requests:
   
   1.  You MUST call the `get_user_profile` tool and extract all the user profile information from the result.
   2.  You MUST generate a final a2ui UI JSON based on the user profile information extracted in the previous step."""
   
   A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f"""
   
   To generate a valid a2ui UI JSON, you MUST follow these rules:
   1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
   2.  The first part is your conversational text response.
   3.  The second part is a single, raw JSON object which is a list of A2UI messages.
   4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.
   
   To represent the user profile, you MUST use the following A2UI message types:
   1.  Buttons MUST be used to represent links (e.g., LinkedIn profile link).
   2.  Image MUST be used to represent the user's profile picture.
   
   ---BEGIN A2UI JSON SCHEMA---
   {A2UI_SCHEMA}
   ---END A2UI JSON SCHEMA---
   """
   
   root_agent = LlmAgent(
       name="user_profile",
       model="gemini-2.5-flash",
       instruction=A2UI_AND_AGENT_INSTRUCTION,
       description="An agent that returns the current user profile.",
       tools=[get_user_profile]
   )

7. Daha önce dağıtılan ADK'yı uygulamanın yeni sürümüyle güncelleyin.

   python3 deployment/deploy.py --update --resource_id=RESOURCE_ID

   RESOURCE_ID kısmını önceki adımlarda kopyalanan Vertex AI aracısı kaynak adıyla değiştirin.

8. Uygulamayla olan doğrudan mesajda Hello again! yazıp enter tuşuna basın.

   Chat uygulaması, bir mesaja metin ve profil başlığını içeren bir kartla yanıt verir.

Güvenilir test kullanıcıları ekleme ve etkileşimli özellikleri test etme hakkında daha fazla bilgi edinmek için Google Chat uygulamaları için etkileşimli özellikleri test etme başlıklı makaleyi inceleyin.

Sorun giderme

Bir Google Chat uygulaması veya kartı hata döndürdüğünde Chat arayüzünde "Bir hata oluştu" veya "İsteğiniz işlenemiyor" mesajı gösterilir. Bazen Chat kullanıcı arayüzünde hata mesajı gösterilmez ancak Chat uygulaması veya kartı beklenmedik bir sonuç üretir. Örneğin, kart mesajı görünmeyebilir.

Chat kullanıcı arayüzünde hata mesajı gösterilmese de Chat uygulamaları için hata günlüğü kaydı etkinleştirildiğinde hataları düzeltmenize yardımcı olacak açıklayıcı hata mesajları ve günlük verileri kullanılabilir. Hataları görüntüleme, hataları ayıklama ve düzeltme konusunda yardım için Google Chat hatalarını giderme ve düzeltme başlıklı makaleyi inceleyin.

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ü menu > IAM ve Yönetici > Kaynakları Yönetin.

   Resource Manager'a gidin

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

İlgili konular

• Kullanıcı işlemlerini içeren bir A2UI tarafından sunulan ADK yapay zeka aracına sahip bir Google Chat uygulaması oluşturma
• ADK yapay zeka temsilcisiyle Google Chat uygulaması oluşturma
• A2A temsilcisi içeren bir Google Chat uygulaması oluşturma
• ADK yapay zeka aracısı ve Gemini modeliyle ifadelerin doğruluğunu kontrol etme
• Google Workspace'te erişilebilen bir yapay zeka aracısıyla seyahat planlama
• Temel yapay zeka kavramlarını Chat uygulamalarına entegre etme
• Gemini Yapay Zeka Chat uygulamasıyla yapılan Chat görüşmelerine dayalı olarak soruları yanıtlama
• Google Chat, Vertex AI, Apps Komut Dosyası ve kullanıcı kimlik doğrulaması ile olaylara yanıt verme
• Google Chat, Vertex AI ve Firestore ile projeleri yönetme