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.

Şekil 1. A2UI aracısı, kullanıcıya metinle ve ad, resim ve LinkedIn düğmesini içeren bir kartla yanıt verir.
Şekil 2. A2UI aracısı, profil başlığını da döndürecek şekilde güncellendi.
Şekil 3. A2UI aracısı, kartta profil adını gösteren bir mesajla kullanıcıya yanıt verir.

Aşağıdaki diyagram mimariyi ve mesajlaşma modelini göstermektedir:

A2UI yapay zeka aracısıyla uygulanan bir Chat uygulamasının mimarisi.

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

Bir kullanıcı, bir Chat uygulamasına doğrudan mesaj yoluyla ya da bir Chat alanında mesaj gönderir.
Apps Script'te veya HTTP uç noktaları olan bir web sunucusu olarak uygulanan Chat uygulaması mantığı, mesajı alır ve işler.
Vertex AI Agent Engine ile barındırılan A2UI aracısı, etkileşimi alır ve işler.
İ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.
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.
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.

Google Cloud Console'da Menü > Google Auth platform > Markalama'ya gidin.
Markalama'ya gidin.
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:

Uygulama Bilgileri bölümündeki Uygulama adı alanına uygulamanın adını girin.
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.
İleri'yi tıklayın.
Kitle bölümünde Şirket içi'ni seçin.
İleri'yi tıklayın.
İletişim bilgileri bölümünde, projenizde yapılan değişikliklerle ilgili bildirim alabileceğiniz bir e-posta adresi girin.
İleri'yi tıklayın.
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.
Devam'ı tıklayın.
Oluştur'u tıklayın.

Şimdilik kapsam eklemeyi atlayabilirsiniz. Gelecekte, Google Workspace kuruluşunuzun dışında kullanılmak üzere bir uygulama oluşturduğunuzda, Kullanıcı türü değerini Harici olarak değiştirmeniz gerekir. Ardından uygulamanızın gerektirdiği yetkilendirme kapsamlarını ekleyin. Daha fazla bilgi için, OAuth onayını yapılandırma kılavuzunun tamamına bakın.

Google Cloud konsolunda bir hizmet hesabı oluşturun.

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

Google Cloud konsolu

Google Cloud konsolunda Menü'ye gidin. > IAM ve Yönetici > Hizmet Hesapları .
Hizmet Hesaplarına Git
Hizmet hesabı oluştur'u tıklayın.
Hizmet hesabı bilgilerini doldurun, ardından Oluştur ve devam et seçeneğine tıklayın.
Not: Varsayılan olarak, Google benzersiz bir hizmet hesabı kimliği oluşturur. Kimlik numarasını değiştirmek isterseniz, hizmet hesabı kimliği alanındaki kimlik numarasını değiştirin.
İsteğe bağlı: Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha fazla ayrıntı için Kaynaklara erişim izni verme, değiştirme ve iptal etme bölümüne bakın.
Devam'ı tıklayın.
İsteğe bağlı: Bu hizmet hesabıyla işlem yapabilecek ve yönetebilecek kullanıcıları veya grupları girin. Daha fazla ayrıntı için Hizmet hesabı kimliğine bürünmeyi yönetme bölümüne bakın.
Bitti'yi tıklayın. Hizmet hesabına ait e-posta adresini not edin.

gcloud CLI

Hizmet hesabını oluşturun:

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"

İsteğe bağlı: Google Cloud projenizin kaynaklarına erişim izni vermek için hizmet hesabınıza roller atayın. Daha fazla ayrıntı için Kaynaklara erişim izni verme, değiştirme ve iptal etme bölümüne bakın.

Hizmet hesabı, hizmet hesabı sayfasında görünür.

Özel anahtar oluşturun

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

Google Cloud konsolunda Menü'ye gidin. > IAM ve Yönetici > Hizmet Hesapları .
Hizmet Hesaplarına Git
Hizmet hesabınızı seçin.
Tıklamak Anahtarlar > Anahtar ekle > Yeni anahtar oluştur.
JSON öğesini seçin, ardından Oluştur öğesine tıklayın.
Yeni genel/özel anahtar çiftiniz oluşturuldu ve yeni bir dosya olarak bilgisayarınıza indirildi. İndirdiğiniz JSON dosyasını çalışma dizininize credentials.json olarak kaydedin. Bu dosya, bu anahtarın tek kopyasıdır. Anahtarınızı güvenli bir şekilde nasıl saklayacağınız hakkında bilgi için, Hizmet hesabı anahtarlarını yönetme bölümüne bakın.
Kapat'ı tıklayın.

Hizmet hesapları hakkında daha fazla bilgi için, Google Cloud IAM belgelerindeki hizmet hesapları bölümüne bakın.

A2UI aracısını dağıtın

Henüz yapmadıysanız, Google Cloud hesabınızla kimlik doğrulaması yapı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 yerine bulut projenizin kimliğini yazın.
Bu düğmeyi kullanarak googleworkspace/add-ons-samples GitHub deposunu indirin:

Depoyu indir
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
```
ADK aracısı için özel olarak ayrılmış 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. CLOUD_STORAGE_BUCKET_NAME kullanmak istediğiniz benzersiz bir kova adıyla.
2. Bulut projenizin kimliğiyle PROJECT_ID.
3. Bulut projenizin konumunu PROJECT_LOCATION ile belirtin.
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 ile oluşturduğunuz kovanın adını yazın.
2. Bulut projenizin kimliğiyle PROJECT_ID.
3. Bulut projenizin konumunu PROJECT_LOCATION ile belirtin.

ADK aracısını sanal ortamdan kurun ve devreye alın.

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

Temsilci kimliğini alın. Bunu daha sonra, sohbet uygulamasını yapılandırırken ihtiyacınız olacak.
```
python3 deployment/deploy.py --list
```

Sohbet uygulaması projesini oluşturun ve yapılandırın.

Aşağıdaki düğmeye tıklayarak A2UI AI Agent Quickstart Apps Script projesini açın.

Projeyi aç
Tıklamak Genel Bakış > Bir kopyasını oluşturun.
Apps Script projenizde tıklayın. Proje Ayarları > Komut dosyası özelliklerini düzenle > Komut dosyası özelliğini ekle Aşağıdaki komut dosyası özelliklerini eklemek için:
1. REASONING_ENGINE_RESOURCE_NAME önceki adımlarda kopyalanan Vertex AI ajanı kaynak adıyla.
2. SERVICE_ACCOUNT_KEY önceki adımlarda indirilen hizmet hesabından alınan JSON anahtarıyla, örneğin { ... }.
Komut dosyası özelliklerini kaydet'i tıklayın.
Google Cloud konsolunda Menü'ye gidin. > IAM ve Yönetici > Ayarlar .

IAM ve Yönetici Ayarlarına Git
Proje numarası alanındaki değeri kopyalayın.
Apps Script projenizde, Proje Ayarları seçeneğine tıklayın.
Google Cloud Platform (GCP) Projesi altında, Projeyi değiştir seçeneğine tıklayın.
GCP proje numarası alanına, önceki adımlarda kopyaladığınız Google Cloud proje numarasını yapıştırın.
Projeyi ayarla seçeneğine tıklayın. Bulut projesi ve Apps Script projesi artık birbirine bağlı.

Bir test dağıtımı oluşturun

Sonraki adımda kullanabilmeniz için bu Apps Script projesi için bir dağıtım kimliğine ihtiyacınız var.

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

Sohbet uygulaması Apps Script projesinde, tıklayın. Dağıt > Test dağıtımları .
Baş dağıtım kimliği altında, Kopyala seçeneğine tıklayın.
Bitti'yi tıklayın.

Sohbet uygulamasını yapılandırın

Apps Script dağıtımınızı kullanarak, Google Chat uygulamasını test için dağıtmak üzere şu adımları izleyin:

konsol'de Google Chat API'yi arayın ve Google Chat API'ye tıklayın.
Yönet'i tıklayın.
Yapılandırma seçeneğine tıklayın ve Sohbet uygulamasını kurun:
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 altında, Alanlara ve grup konuşmalarına katıl seçeneğini belirleyin.
5. Bağlantı ayarları altında, Apps Script projesi öğesini seçin.
6. Dağıtım Kimliği alanına, daha önce kopyaladığınız Ana dağıtım kimliğini yapıştırın.
7. Görünürlük altında, Alan adınızdaki belirli kişiler ve gruplar seçeneğini belirleyin ve e-posta adresinizi girin.
Kaydet'i tıklayın.

Sohbet uygulaması mesajlara yanıt vermeye hazır.

Sohbet uygulamasını test edin

Sohbet uygulamanızı test etmek için, sohbet uygulamasıyla bir doğrudan mesaj alanı açın ve bir mesaj gönderin:

Güvenilir test kullanıcısı olarak kendinizi eklerken verdiğiniz Google Workspace hesabını kullanarak Google Chat'i açın.

Google Chat'e gidin.
Yeni sohbet'ye tıklayın.
1 veya daha fazla kişi ekle alanına Sohbet uygulamanızın adını yazın.
Sonuçlardan sohbet uygulamanızı seçin. Doğrudan mesaj açılıyor.

Not: Sohbet uygulamanızı sonuç listesinde görmüyorsanız, Google Cloud konsolundaki Sohbet API Yapılandırması sayfasının Görünürlük ayarlarında Google Workspace hesabınızın yer aldığından emin olun.
Uygulamayla açılan yeni doğrudan mesajda Hello! yazın ve enter tuşuna basın.

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

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]
)

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

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
Proje listesinde, silmek istediğiniz projeyi seçin ve Sil'i tıklayın.
İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.