Agent2Agent temsilcisiyle Google Chat uygulaması oluşturma

Bu sayfa, Google Chat'te çalışan ve Agent2Agent (A2A) protokolünü kullanan bir yapay zeka temsilcisiyle arayüz oluşturan bir Google Workspace eklentisinin nasıl oluşturulacağını açıklamaktadır. Ajanı Ajan Geliştirme Kiti (ADK) kullanarak geliştirir ve Vertex Yapay Zeka Ajan Motoru içinde barındırırsınız.

Yapay zekâ ajanları, tanımlanmış bir hedefe ulaşmak için çevrelerini otonom olarak algılar, akıl yürütür ve karmaşık, çok adımlı eylemler gerçekleştirir. Bu eğitimde, Gemini ve Google Arama temellerini kullanarak gerçekleri eleştiren ve düzelten LLM Auditor çoklu ajan örneğini dağıtacaksınız.

LLM Auditor çoklu ajan örneği, sohbet uygulaması olarak.

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

A2A yapay zeka ajanı ile entegre edilmiş bir sohbet uygulamasının mimarisi.

Şemada, A2A ajanı ile entegre edilmiş bir sohbet uygulamasıyla etkileşim kuran bir kullanıcının bilgi akışı şu şekildedir:

  1. Kullanıcı, doğrudan mesaj yoluyla veya sohbet alanında bir sohbet uygulamasına mesaj gönderir.
  2. Apps Script'te veya HTTP uç noktalarına sahip bir web sunucusu olarak uygulanan sohbet uygulaması mantığı, mesajı alır ve işler.
  3. Vertex AI Agent Engine'de barındırılan A2A ajanı, etkileşimi alır ve işler.
  4. İsteğe bağlı olarak, sohbet uygulaması veya yapay zeka temsilcisi, Google Workspace hizmetleriyle (örneğin Takvim veya E-Tablolar) veya diğer Google hizmetleriyle (örneğin Google Haritalar veya YouTube) entegre olabilir.
  5. Sohbet uygulaması, yapay zeka aracısının ilerlemesini iletmek için Google Chat API'sini kullanarak yanıtları eşzamansız olarak gönderir.
  6. Yanıtlar kullanıcıya iletilir.

Hedefler

  • Ortamınızı ayarlayın.
  • A2A aracısını devreye alın.
  • Sohbet uygulamasını dağıtın.
  • Sohbet uygulamasını yapılandırın.
  • Sohbet uygulamasını test edin.

Ön koşullar

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

    Hizmet Hesaplarına Git

  2. Hizmet hesabı oluştur'u tıklayın.
  3. Hizmet hesabı bilgilerini doldurun, ardından Oluştur ve devam et seçeneğine 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 fazla ayrıntı için Kaynaklara erişim izni verme, değiştirme ve iptal etme bölümüne bakın.
  5. Devam'ı tıklayın.
  6. İ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.
  7. Bitti'yi tıklayın. Hizmet hesabına ait 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 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 üzere aşağıdaki adımları uygulayın:

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

    Hizmet Hesapları'na 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.

A2A 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 ADK örnekleri GitHub deposunu indirin:

    adk-samples'ı indirin

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

    unzip adk-samples-main.zip
cd adk-samples-main/python/agents/llm-auditor

  4. ADK aracısını A2A uzak aracısı olarak dağıtmak için uygulamayı güncelleyin:

    1. pyproject.toml: Dağıtım grubuna ADK ve A2A SDK bağımlılıklarını ekleyin.

      apps-script/chat/a2a-ai-agent/llm-auditor/pyproject.toml
      [project]
name = "llm-auditor"
version = "0.1.0"
description = "The LLM Auditor evaluates LLM-generated answers, verifies actual accuracy using the web, and refines the response to ensure alignment with real-world knowledge."
authors = [
    { name = "Chun-Sung Ferng", email = "csferng@google.com" },
    { name = "Cyrus Rashtchian", email = "cyroid@google.com" },
    { name = "Da-Cheng Juan", email = "dacheng@google.com" },
    { name = "Ivan Kuznetsov", email = "ivanku@google.com" },
]
license = "Apache License 2.0"
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.10"
google-adk = "^1.0.0"
google-cloud-aiplatform = { extras = [
    "adk",
    "agent-engines",
], version = "^1.93.0" }
google-genai = "^1.9.0"
pydantic = "^2.10.6"
python-dotenv = "^1.0.1"

[tool.poetry.group.dev]
optional = true

[tool.poetry.group.dev.dependencies]
google-adk = { version = "^1.0.0", extras = ["eval"] }
pytest = "^8.3.5"
pytest-asyncio = "^0.26.0"

[tool.poetry.group.deployment]
optional = true

[tool.poetry.group.deployment.dependencies]
absl-py = "^2.2.1"
google-adk = "^1.0.0"
a2a-sdk = "^0.3.0"

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

    2. deployment/deploy.py: ADK uygulama dağıtımını bir A2A aracısı ve kartıyla değiştirin.

      apps-script/chat/a2a-ai-agent/llm-auditor/deployment/deploy.py
      # Copyright 2025 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.

"""Deployment script for LLM Auditor."""

import os

from absl import app
from absl import flags
from dotenv import load_dotenv
from llm_auditor.agent import root_agent
import vertexai
from vertexai import agent_engines

# A2A wrapping
from a2a.types import AgentSkill
from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
from google.adk.runners import InMemoryRunner
from vertexai.preview.reasoning_engines.templates.a2a import create_agent_card
from vertexai.preview.reasoning_engines import A2aAgent

FLAGS = flags.FLAGS
flags.DEFINE_string("project_id", None, "GCP project ID.")
flags.DEFINE_string("location", None, "GCP location.")
flags.DEFINE_string("bucket", None, "GCP bucket.")
flags.DEFINE_string("resource_id", None, "ReasoningEngine resource ID.")

flags.DEFINE_bool("list", False, "List all agents.")
flags.DEFINE_bool("create", False, "Creates a new agent.")
flags.DEFINE_bool("delete", False, "Deletes an existing agent.")
flags.mark_bool_flags_as_mutual_exclusive(["create", "delete"])


def create() -> None:
    """Creates an agent engine for LLM Auditor."""
    agent_card = create_agent_card(
        agent_name=root_agent.name,
        description=root_agent.description,
        skills=[AgentSkill(
            id='audit_llm_output',
            name='Audit LLM Output',
            description='Critiques and revises outputs from large language models.',
            tags=['LLM', 'Audit', 'Revision'],
            examples=[
                'The earth is flat.',
                'The capital of France is Berlin.',
                'The last winner of the Super Bowl was the New England Patriots in 2020.',
            ],
        )]
    )
    a2a_agent = A2aAgent(
        agent_card=agent_card,
        agent_executor_builder=lambda: A2aAgentExecutor(
            runner=InMemoryRunner(
                app_name=root_agent.name,
                agent=root_agent,
            )
        )
    )
    a2a_agent.set_up()

    remote_agent = agent_engines.create(
        a2a_agent,
        display_name=root_agent.name,
        requirements=[
                "google-adk (>=0.0.2)",
                "google-cloud-aiplatform[agent_engines] (>=1.88.0,<2.0.0)",
                "google-genai (>=1.5.0,<2.0.0)",
                "pydantic (>=2.10.6,<3.0.0)",
                "absl-py (>=2.2.1,<3.0.0)",
                "a2a-sdk>=0.3.22",
                "uvicorn",
        ],
        # In-memory runner
        max_instances=1,
        env_vars ={
            "NUM_WORKERS": "1"
        },
        extra_packages=["./llm_auditor"],
    )
    print(f"Created remote agent: {remote_agent.resource_name}")


def delete(resource_id: str) -> None:
    remote_agent = agent_engines.get(resource_id)
    remote_agent.delete(force=True)
    print(f"Deleted remote agent: {resource_id}")


def list_agents() -> None:
    remote_agents = agent_engines.list()
    TEMPLATE = '''
{agent.name} ("{agent.display_name}")
- Create time: {agent.create_time}
- Update time: {agent.update_time}
'''
    remote_agents_string = '\n'.join(TEMPLATE.format(agent=agent) for agent in remote_agents)
    print(f"All remote agents:\n{remote_agents_string}")

def main(argv: list[str]) -> None:
    del argv  # unused
    load_dotenv()

    project_id = (
        FLAGS.project_id
        if FLAGS.project_id
        else os.getenv("GOOGLE_CLOUD_PROJECT")
    )
    location = (
        FLAGS.location if FLAGS.location else os.getenv("GOOGLE_CLOUD_LOCATION")
    )
    bucket = (
        FLAGS.bucket if FLAGS.bucket
        else os.getenv("GOOGLE_CLOUD_STORAGE_BUCKET")
    )

    print(f"PROJECT: {project_id}")
    print(f"LOCATION: {location}")
    print(f"BUCKET: {bucket}")

    if not project_id:
        print("Missing required environment variable: GOOGLE_CLOUD_PROJECT")
        return
    elif not location:
        print("Missing required environment variable: GOOGLE_CLOUD_LOCATION")
        return
    elif not bucket:
        print(
            "Missing required environment variable: GOOGLE_CLOUD_STORAGE_BUCKET"
        )
        return

    vertexai.init(
        project=project_id,
        location=location,
        staging_bucket=f"gs://{bucket}",
    )

    if FLAGS.list:
        list_agents()
    elif FLAGS.create:
        create()
    elif FLAGS.delete:
        if not FLAGS.resource_id:
            print("resource_id is required for delete")
            return
        delete(FLAGS.resource_id)
    else:
        print("Unknown command")


if __name__ == "__main__":
    app.run(main)

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

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

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

  8. 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. A2A AI Agent Quickstart Apps Komut Dosyası projesini açmak için aşağıdaki düğmeyi tıklayın.

    Projeyi açın.

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

  3. Apps Script projenizde tıklayın.Proje ayarları simgesi 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 { ... }.

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

  5. Google Cloud konsolunda Menü'ye gidin. > IAM ve Yönetici > Ayarlar .

    IAM ve Yönetici Ayarlarına Git

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

  7. Apps Script projenizde, Proje ayarları simgesi Proje Ayarları seçeneğine tıklayın.

  8. Google Cloud Platform (GCP) Projesi altında, Projeyi değiştir seçeneğine tıklayın.

  9. GCP proje numarası alanına, önceki adımlarda kopyaladığınız Google Cloud proje numarasını yapıştırın.

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

  1. Sohbet uygulaması Apps Script projesinde, tıklayın. Dağıt > Test dağıtımları .
  2. Baş dağıtım kimliği altında, Kopyalama simgesi Kopyala seçeneğine tıklayın.
  3. 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:

  1. konsolda, Google Chat API ifadesini arayın ve Google Chat API'ye tıklayın.
  2. Yönet'i tıklayın.

  3. Yapılandırma seçeneğine tıklayın ve Sohbet uygulamasını kurun:

    1. Uygulama adı alanına A2A 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 A2A 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. 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 The Eiffel Tower was completed in 1900 yazıp enter tuşuna basın.

    Sohbet uygulaması, Eleştirmen ve Düzenleyici alt aracılarının yanıtlarıyla karşılık 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ü > IAM ve Yönetici > Kaynakları Yönetin.

    Resource Manager'a gidin

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