Vertex AI Agents'ı Google Workspace ile entegre etme

1. Başlamadan önce

Vertex AI nedir?

Vertex AI, Google Cloud'un kurumsal düzeyde yapay zeka aracıları ve uygulamaları oluşturma, dağıtma ve ölçeklendirme için birleşik geliştirme platformudur. Geliştiricilere ve veri bilimcilere, küresel ölçekli altyapıyla derinlemesine entegre olan özel ajan tabanlı iş akışları tasarlamak için gereken gelişmiş araçları sağlar.

• Model Garden'a erişme: Belirli aracı görevlerine uygun olanı bulmak için 150'den fazla temel model (Gemini ailesinin tamamı, üçüncü taraf modeller ve özel açık kaynak modeller dahil) arasından seçim yapın.
• Karmaşık düzenlemeler tasarlama: Vertex AI, çok adımlı görevleri planlamak, yürütmek ve harici API'leri çağırmak için akıl yürütme kullanan özerk temsilciler tasarlamaya yönelik bir çerçeve sunar.
• Kurumsal düzeyde temellendirme: Halüsinasyonları ortadan kaldırmak ve olgusal doğruluğu sağlamak için yüksek performanslı RAG (Retrieval-Augmented Generation) dahil olmak üzere canlı işletme verilerine bağlayın.
• DevOps: Aracı performansını ve güvenliğini büyük ölçekte ölçmek için güçlü SDK'lar, API'ler ve değerlendirme araçlarıyla aracı geliştirmeyi mevcut CI/CD işlem hatlarına sorunsuz bir şekilde entegre edin.
• Endüstriyel düzeyde güvenlik: Vertex AI, eğitim veya temel oluşturma için kullanılan müşteri verilerinin gizli, şifrelenmiş ve küresel yerleşim şartlarına uygun kalmasını sağlar.
• Optimize edilmiş altyapı: Google'ın birinci sınıf TPU ve GPU kümelerinde aracı iş yüklerini zahmetsizce ölçeklendirin. En zorlu küresel uygulamalarda bile düşük gecikmeli performans elde edin.

Google Workspace nedir?

Google Workspace, bireyler, okullar ve işletmeler için tasarlanmış bulut tabanlı üretkenlik ve ortak çalışma çözümlerinden oluşan bir koleksiyondur:

• İletişim: Profesyonel e-posta hizmetleri (Gmail), video konferans (Meet) ve ekip mesajlaşması (Chat).
• İçerik Oluşturma: Doküman yazma (Dokümanlar), e-tablo oluşturma (E-Tablolar) ve sunu tasarlama (Slaytlar) araçları.
• Kuruluş: Paylaşılan takvimler (Takvimler) ve dijital not alma (Keep).
• Depolama: Dosyaları güvenli bir şekilde kaydetmek ve paylaşmak için merkezi bulut alanı (Drive).
• Yönetim: Kullanıcıları ve güvenlik ayarlarını yönetmek için yönetim denetimleri (Workspace Yönetici Konsolu).

Ne tür özel entegrasyonlar?

Google Workspace ve Vertex AI, güçlü bir geri bildirim döngüsü oluşturur. Workspace, gerçek zamanlı veriler ve ortak çalışma bağlamı sağlarken Vertex AI, akıllı iş akışlarını otomatikleştirmek için gereken modelleri, ajan tabanlı akıl yürütmeyi ve düzenlemeyi sunar.

• Akıllı bağlantı: Google tarafından yönetilen veri depoları, API'ler ve MCP sunucuları (Google tarafından yönetilen ve özel) sayesinde temsilciler, Workspace verilerine güvenli ve sorunsuz bir şekilde erişebilir ve kullanıcılar adına işlem yapabilir.
• Özel ajanlar: Ekipler, kodsuz tasarımcıları veya profesyonel kod çerçevelerini kullanarak yönetici tarafından yönetilen Workspace verilerine ve işlemlerine dayalı özel ajanlar oluşturabilir.
• Yerel entegrasyon: Workspace eklentileri, özel kullanıcı arayüzü bileşenleri veya arka plan işlemleri aracılığıyla yapay zeka sistemleri ile Chat ve Gmail gibi uygulamalar arasındaki boşluğu doldurur. Bu sayede temsilciler, anında ve bağlama uygun yardım için kullanıcılarla tam olarak bulundukları yerde buluşabilir.

Google Workspace'in güçlü üretkenlik ekosistemini Vertex AI'ın gelişmiş ajan gücüyle birleştiren kuruluşlar, ekiplerinin her gün kullandığı araçlarda doğrudan karmaşık iş akışlarını otomatikleştiren özel, veriye dayalı yapay zeka aracıları aracılığıyla operasyonlarını dönüştürebilir.

Ön koşullar

Tüm adımları kendi ortamınızda uygulamak istiyorsanız şunlara ihtiyacınız vardır:

• Google Cloud ve Python hakkında temel bilgi sahibi olmanız gerekir.
• Faturalandırmanın etkin olduğu ve sahibi olduğunuz 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. Proje sahipliğini değiştirmek için Proje üyelerini yönetme veya proje sahipliğini değiştirme başlıklı makaleyi inceleyin.
• Google Chat'e erişimi olan ve akıllı özelliklerin etkinleştirildiği Business veya Enterprise Google Workspace hesabı.
• Google Cloud KSA'nın Google Cloud projeniz için yüklü ve başlatılmış olması gerekir.
• Python 3.11 veya sonraki bir sürümün yüklü olması gerekir. Talimatlar için resmi Python web sitesini inceleyin.

Ne oluşturacaksınız?

Bu codelab'de, Google Workspace ile sıkı bir şekilde entegre edilmiş Vertex AI Agents ile üç çözüm oluşturacağız. Veriler, işlemler ve kullanıcı arayüzleriyle etkileşim kurmak için kullanılabilecek mimari kalıpları gösterirler.

Vertex AI Search uygulaması

Bu ajan, kullanıcıların doğal dillerinde Workspace verilerini aramasına ve Workspace'te işlem yapmasına olanak tanır. Aşağıdaki öğelerden yararlanır:

• Model: Gemini
• Veriler ve işlemler: Google Workspace (Takvim, Gmail, Drive) için Vertex AI veri depoları.
• Aracı barındırma: Vertex AI Search.
• Kullanıcı arayüzü: Vertex AI Search Web Widget'ı.

Özel aracı

Bu ajan, kullanıcıların özel araçlar ve kurallar kullanarak doğal dilde Workspace verilerini aramasına ve Workspace'te işlem yapmasına olanak tanır. Aşağıdaki öğelerden yararlanır:

• Model: Gemini
• Veriler ve işlemler: Google Workspace (Takvim, Gmail, Drive) için Vertex AI veri depoları, Google tarafından yönetilen Vertex AI Arama Model Bağlam Protokolü (MCP) sunucusu, Google Chat API'si aracılığıyla Google Chat mesajları göndermek için özel araç işlevi.
• Ajan oluşturma araçları: Agent Development Kit (ADK).
• Aracı barındırma: Vertex AI Agent Engine.
• Kullanıcı arayüzü: ADK Web.

Agent, Google Workspace eklentisi olarak

Bu aracı kullanarak kullanıcılar, Workspace uygulaması kullanıcı arayüzleri bağlamında doğal dillerini kullanarak Workspace verilerinde arama yapabilir. Aşağıdaki öğelerden yararlanır:

• Model: Gemini
• Veriler ve işlemler: Google Workspace (Takvim, Gmail, Drive) için Vertex AI veri depoları, Google tarafından yönetilen Vertex AI Arama Model Bağlam Protokolü (MCP) sunucusu, Google Chat API'si aracılığıyla Google Chat mesajları göndermek için özel araç işlevi.
• Ajan oluşturma araçları: Agent Development Kit (ADK).
• Aracı barındırma: Vertex AI Agent Engine.
• Kullanıcı arayüzü: Chat ve Gmail için Google Workspace eklentisi (Takvim, Drive, Dokümanlar, E-Tablolar ve Slaytlar'a kolayca genişletilebilir).
• Google Workspace eklentisi: Apps Komut Dosyası, Vertex AI Agent Engine API'leri, bağlamsal (seçili Gmail iletisi).

Öğrenecekleriniz

• Vertex AI Arama ile Google Workspace arasındaki, veri ve işlemleri etkinleştiren entegrasyon noktaları.
• Vertex AI'da barındırılan özel aracıları oluşturma seçenekleri.
• Kullanıcıların Vertex AI Arama Web Widget'ı ve Google Workspace uygulamaları gibi aracılara erişebileceği yöntemler.

Bu codelab'e kolay erişim

2. Kur

Çözüm oluşturmadan önce projenin Vertex AI Applications ayarlarını başlatmamız, gerekli API'leri etkinleştirmemiz ve Vertex AI Workspace veri depolarını oluşturmamız gerekir.

Kavramları inceleyin

Vertex AI uygulaması

Vertex AI uygulaması, Google Cloud'da yönetilen, uçtan uca bir çözümdür. Anlamsal arama, içerik oluşturma veya otomatik müşteri etkileşimi gibi karmaşık görevleri gerçekleştirmek için makine öğrenimi modellerini (ör. üretken yapay zeka aracıları veya arama motorları) kurumsal veriler ve özel araçlarla entegre eder.

Vertex AI veri deposu

Vertex AI veri deposu, Google Workspace gibi birinci taraf veri kaynaklarından veya Jira ya da Shopify gibi üçüncü taraf uygulamalarından alınan verileri içeren bir varlıktır. Üçüncü taraf uygulamalarından gelen verileri içeren veri depolarına veri bağlayıcılar da denir.

Vertex AI Applications ayarlarını başlatma

Aracı oluşturmayı etkinleştirmek için Vertex AI Applications ayarlarını başlatın.

Google Cloud Console'u yeni bir sekmede açın ve şu adımları uygulayın:

1. Projenizi seçin.
2. Google Cloud arama alanında AI Applications'a (Yapay Zeka Uygulamaları) gidin.

Vertex AI Uygulamaları'na gitme

3. Şartları inceleyip kabul ettikten sonra Devam et ve API'yi etkinleştir'i tıklayın.
4. Ayarlar'a gidin.
5. Authentication (Kimlik Doğrulama) sekmesinde global'i düzenleyin.

6. Google Kimliği'ni seçip Kaydet'i tıklayın.

API'leri etkinleştir

Vertex AI Workspace veri depoları için aşağıdaki API'lerin etkinleştirilmesi gerekir:

1. Google Cloud Console'da Takvim, Gmail ve People API'lerini etkinleştirin:

Takvim, Gmail ve People API'lerini etkinleştirme

2. Menü ☰ > API'ler ve Hizmetler > Etkin API'ler ve Hizmetler'i tıklayın ve Google Takvim API, Gmail API ve People API'nin listede olduğunu doğrulayın.

API'ler ve Hizmetler > Etkin API'ler ve Hizmetler'e gidin

Veri depoları oluşturma

Google Drive veri deposunu oluşturun:

1. Google Cloud Console'da AI Applications'a (Yapay Zeka Uygulamaları) gidin ve Data Stores'a (Veri Depoları) gidin.

Vertex AI Applications > Data Stores'a (Vertex AI Uygulamaları > Veri Depoları) gidin.

2. + Veri deposu oluştur'u tıklayın.
3. Kaynak bölümündeki Google Drive altında Seç'i tıklayın.

4. Veriler bölümünde Tümü'nü seçin ve Devam'ı tıklayın.

5. Yapılandırma bölümünde Veri bağlayıcı adı'nı drive olarak ayarlayın ve geçerli olabilecek ücretleri inceleyip kabul ettikten sonra Devam'ı tıklayın.

6. Fiyatlandırma bölümünde, tercih ettiğiniz fiyatlandırma modelini seçin ve Oluştur'u tıklayın. Bu codelab bağlamında genel fiyatlandırma önerilir.
7. Yeni eklenen veri deposunu görebileceğiniz Veri Depoları'na otomatik olarak yönlendirilirsiniz.

Google Takvim veri deposunu oluşturun:

1. + Veri deposu oluştur'u tıklayın.
2. Kaynak bölümünde Google Takvim'i arayın ve Seç'i tıklayın.
3. İşlemler bölümünde Atla'yı tıklayın.
4. Yapılandırma bölümünde Veri bağlayıcı adı'nı calendar olarak ayarlayın.
5. Oluştur'u tıklayın.
6. Yeni eklenen veri deposunu görebileceğiniz Veri Depoları'na otomatik olarak yönlendirilirsiniz.

Google Gmail veri deposunu oluşturun:

1. + Yeni veri deposu'nu tıklayın.
2. Kaynak bölümünde Google Gmail'i arayın ve Seç'i tıklayın.
3. İşlemler bölümünde Atla'yı tıklayın.
4. Yapılandırma bölümünde Veri bağlayıcı adı'nı gmail olarak ayarlayın.
5. Oluştur'u tıklayın.
6. Yeni eklenen veri deposunu görebileceğiniz Veri Depoları'na otomatik olarak yönlendirilirsiniz.

3. Vertex AI Search uygulaması

Bu ajan, kullanıcıların doğal dillerinde Workspace verilerini aramasına ve Workspace'te işlem yapmasına olanak tanır. Aşağıdaki öğelerden yararlanır:

• Model: Gemini
• Veriler ve işlemler: Google Workspace (Takvim, Gmail, Drive) için Vertex AI veri depoları.
• Aracı barındırma: Vertex AI Search.
• Kullanıcı arayüzü: Vertex AI Search Web Widget'ı.

Kavramları inceleme

Vertex AI Search uygulaması

Vertex AI Search uygulaması, son kullanıcılarınıza arama sonuçları, işlemler ve aracıları sunar. API'ler bağlamında uygulama terimi, motor terimiyle birbirinin yerine kullanılabilir. Bir uygulamanın, arama sonuçları, yanıtlar veya işlemler sunmak için verilerini kullanabilmesi için bir veri deposuna bağlı olması gerekir.

Vertex AI Search Web Widget'ı

Vertex AI Search Web Widget, geliştiricilerin yapay zeka destekli bir arama çubuğunu ve sonuç arayüzünü doğrudan bir web sitesine minimum kodlama ile yerleştirmesine olanak tanıyan, önceden oluşturulmuş ve özelleştirilebilir bir kullanıcı arayüzü bileşenidir.

Vertex AI Search Önizlemesi

Vertex AI Search Preview, Google Cloud Console'da yerleşik bir test ortamıdır. Bu ortam, geliştiricilerin aynı ayarları üretime hazır bir Vertex AI Search web widget'ına sorunsuz bir şekilde dağıtmadan önce arama yapılandırmalarını ve üretken yanıtları doğrulamasına olanak tanır.

Çözüm mimarisini inceleme

Uygulama oluşturma

Veri depolarınızı sabitlemek için yeni bir arama uygulaması oluşturun.

Cloud Console'da AI Applications > Apps'i (Yapay Zeka Uygulamaları > Uygulamalar) açın ve aşağıdaki adımları uygulayın:

1. + Uygulama oluştur'u tıklayın.
2. Tür bölümündeki Özel arama (genel) altında Oluştur'u tıklayın.

3. Yapılandırma bölümünde, fiyatları inceleyip kabul ettikten sonra Enterprise sürümü özellikleri ve Üretken Yanıtlar'ı işaretleyin.
4. Uygulama adını codelab olarak ayarlayın.
5. Ada göre bir kimlik oluşturulur ve alanın altında gösterilir. Bu kimliği kopyalayın.
6. Şirket adı'nı Codelab olarak ayarlayın.
7. Çok bölgeli'yi global (Global) olarak ayarlayın.
8. Devam'ı tıklayın.

9. Veriler bölümünde Drive, Gmail ve Takvim veri depolarını seçip Devam'ı tıklayın.

10. Fiyatlandırma bölümünde, tercih ettiğiniz fiyatlandırma modelini seçin ve Oluştur'u tıklayın. Bu codelab bağlamında genel fiyatlandırma önerilir.
11. Uygulama oluşturulur ve otomatik olarak AI Applications > Apps > codelab > App overview'a (Uygulama genel bakışı) yönlendirilirsiniz.
12. Bağlı veri depoları'na gidin.
13. Birkaç dakika sonra, bağlı tüm veri deposu durumları Etkin olmalıdır.

Web Widget'ını yapılandırma

Arama widget'ının görsel görünümünü ve davranışını yapılandırın.

1. Yapılandırmalar'a gidin.
2. UI (Kullanıcı Arayüzü) sekmesinde, Arama türü'nü Takip sorularıyla arama olarak ayarlayın ve Kaydet ve yayınla'yı tıklayın.

Uygulamayı dene

Arama uygulamasını doğrudan Google Cloud Console'da test edin.

1. Önizleme'ye gidin. Web Widget'ı gösterilir.
2. Sohbette Do I have any meetings today? yazıp enter tuşuna basın.
3. Sohbette Did I receive an email on March 1st 2026? yazıp enter tuşuna basın.
4. Sohbette Give me the title of the latest Drive file I created yazıp enter tuşuna basın.

4. Özel temsilci

Bu ajan, kullanıcıların özel araçlar ve kurallar kullanarak doğal dilde Workspace verilerini aramasına ve Workspace'te işlem yapmasına olanak tanır. Aşağıdaki öğelerden yararlanır:

• Model: Gemini
• Veriler ve işlemler: Google Workspace (Takvim, Gmail, Drive) için Vertex AI veri depoları, Google tarafından yönetilen Vertex AI Arama Model Bağlam Protokolü (MCP) sunucusu, Google Chat API'si aracılığıyla Google Chat mesajları göndermek için özel araç işlevi.
• Ajan oluşturma araçları: Agent Development Kit (ADK).
• Aracı barındırma: Vertex AI Agent Engine.
• Kullanıcı arayüzü: ADK Web.

Kavramları inceleyin

Agent Development Kit (ADK)

Agent Development Kit (ADK), akıl yürütme, bellek yönetimi ve araç entegrasyonu için önceden oluşturulmuş modüller sağlayarak bağımsız yapay zeka ajanlarının oluşturulmasını basitleştirmek üzere tasarlanmış özel bir araç ve çerçeve paketidir.

Model Context Protocol (MCP)

Model Bağlam Protokolü (MCP), yapay zeka uygulamaları ile çeşitli veri kaynakları veya araçlar arasında evrensel bir "tak ve çalıştır" arayüzü aracılığıyla sorunsuz ve güvenli entegrasyon sağlamak için tasarlanmış açık bir standarttır.

İşlev Aracı

İşlev aracı, yapay zeka modelinin belirli işlemleri gerçekleştirmek veya harici sistemlerden gerçek zamanlı verileri almak için tetikleyebileceği, önceden tanımlanmış bir yürütülebilir rutindir. Bu araç, yapay zeka modelinin yeteneklerini basit metin oluşturmanın ötesine taşır.

ADK Web

ADK web, daha kolay geliştirme ve hata ayıklama için ADK SDK'sı ile birlikte gelen yerleşik geliştirici kullanıcı arayüzüdür.

Çözüm mimarisini inceleme

Kaynak kodunu inceleme

agent.py

Aşağıdaki kod, Vertex AI ile kimlik doğrulaması yapar, Vertex AI Search MCP ve Chat API araçlarını başlatır ve aracının davranışını tanımlar.

1. Kimlik doğrulama: MCP ve API çağrılarının kimliğini doğrulamak için ortam değişkenlerinden ACCESS_TOKEN değerini alır.
2. Araç kurulumu: Vertex AI Arama Model Bağlam Protokolü (MCP) sunucusuna bağlanan bir araç seti olan vertexai_mcp ve send_direct_message aracını başlatır. Bu izin, temsilcinin bağlı veri depolarınızda arama yapmasına ve Google Chat mesajları göndermesine olanak tanır.
3. Agent Definition: gemini-2.5-flash modelini kullanarak root_agent tanımlar. Talimatlar, temsilciye bilgi alma için arama aracını, işlemler için ise send_direct_message aracını kullanmaya öncelik vermesini söyler. Böylece temsilci, kurumsal verilerinizle etkili bir şekilde temellendirilir.

...
MODEL = "gemini-2.5-flash"

# Access token for authentication
ACCESS_TOKEN = os.environ.get("ACCESS_TOKEN")
if not ACCESS_TOKEN:
    raise ValueError("ACCESS_TOKEN environment variable must be set")

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def send_direct_message(email: str, message: str) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=ACCESS_TOKEN)
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT,
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    ),
    tool_filter=['search']
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

Kaynak Kodunu İndirme

Başlamak için örnek kodu yerel ortamınıza indirin.

1. Bu GitHub deposunu indirin.

file_downloadZip dosyasını indir

2. Bir terminalde solutions/enterprise-ai-agent-local dizinini açın.

API'leri etkinleştirme

Çözümün çalışması için ek API'lerin etkinleştirilmesi gerekir:

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

Vertex AI, Cloud Resource Manager ve Google Chat API'lerini etkinleştirme

2. Menü ☰ > API'ler ve Hizmetler > Etkin API'ler ve Hizmetler'i tıklayın ve Vertex AI API, Cloud Resource Manager API ve Google Chat API'nin listede yer aldığını doğrulayın.

API'ler ve Hizmetler > Etkin API'ler ve Hizmetler'e gidin

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

Çözüm için kullanıcı rızası ekranı yapılandırması gerekir:

1. Google Cloud Console'da Menü ☰ > Google Auth platform > Markalama'yı tıklayın.

Markalama'ya gidin.

2. Başlayın'ı tıklayın.
3. Uygulama Bilgileri bölümünde Uygulama adı'nı Codelab olarak ayarlayın .
4. 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.
5. İleri'yi tıklayın.
6. Kitle bölümünde Şirket içi'ni seçin.
7. İleri'yi tıklayın.
8. İletişim bilgileri bölümünde, projenizde yapılan değişikliklerle ilgili bildirim alabileceğiniz bir e-posta adresi girin.
9. İleri'yi tıklayın.
10. 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.
11. Devam'ı, ardından Oluştur'u tıklayın.

12. Yapılandırma kaydedilir ve otomatik olarak Google Auth Platform > Overview'a yönlendirilirsiniz.

Daha fazla bilgi için OAuth iznini yapılandırma kılavuzunun tamamını inceleyin.

OAuth istemci kimlik bilgileri oluşturma

Kullanıcının kimliğini yerel bir ortamda doğrulamak için yeni bir masaüstü uygulaması OAuth istemcisi oluşturun:

1. Google Cloud Console'da Menü ☰ > Google Auth platform > Clients'ı (İstemciler) tıklayın.

Müşteriler'e gidin

2. + İstemci oluştur'u tıklayın.
3. Uygulama türü için Masaüstü uygulaması'nı seçin.
4. Name'i (Ad) codelab olarak ayarlayın.
5. Oluştur'u tıklayın. Yeni oluşturulan kimlik bilgisi görünür.
6. JSON'u indir'i tıklayın ve dosyayı solutions/enterprise-ai-agent-local dizininde client_secret.json olarak kaydedin.

Vertex AI Search MCP'yi etkinleştirme

1. Terminalde şunu çalıştırın:

gcloud beta services mcp enable discoveryengine.googleapis.com \
     --project=$(gcloud config get-value project)

Chat uygulamasını yapılandırma

Google Chat uygulamasını temel bilgilendirme ayrıntılarıyla yapılandırın.

1. Google Cloud Console'da Google Cloud arama alanında Google Chat API ifadesini arayın, Google Chat API'yi, Yönet'i ve Yapılandırma'yı tıklayın.

Google Chat API yapılandırmasına gitme

2. Uygulama adı ve Açıklama'yı Vertex AI olarak ayarlayın.
3. Avatar URL'sini https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png olarak ayarlayın.
4. Etkileşimli özellikleri etkinleştir'in seçimini kaldırın ve açılan modal iletişim kutusunda Devre dışı bırak'ı tıklayın.
5. Günlük hatalarını Logging'e seçeneğini belirleyin.
6. Kaydet'i tıklayın.

ADK Web'de aracıyı çalıştırma

ADK web arayüzünü kullanarak aracıyı yerel olarak başlatın.

1. Bir terminalde solutions/enterprise-ai-agent-local dizinini açın ve şu komutu çalıştırın:

# 1. Authenticate with all the required scopes
gcloud auth application-default login \
  --client-id-file=client_secret.json \
   --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.messages

# 2. Configure environment
export ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export GOOGLE_CLOUD_LOCATION=us-central1

# 3. Create and activate a new virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 4. Install poetry and project dependencies
pip install poetry
poetry install

# 5. Start ADK Web
adk web

Temsilciyi deneyin

Özel temsilcinizle sohbet ederek akışı doğrulayın.

1. İnternet tarayıcınızda ADK web sitesini açın.
2. Sohbette Please find my meetings for today, I need their titles and links yazıp enter tuşuna basın.
3. Ajan, kullanıcının hesabına bağlı olarak bir Takvim etkinlikleri listesiyle yanıt verir.
4. Sohbette Please send a Chat message to someone@example.com with the following text: Hello! yazıp enter tuşuna basın.
5. Temsilci, onay mesajıyla yanıt verir.

5. Google Workspace eklentisi olarak ajan

Bu aracı kullanarak kullanıcılar, Workspace uygulaması kullanıcı arayüzleri bağlamında doğal dillerini kullanarak Workspace verilerinde arama yapabilir. Aşağıdaki öğelerden yararlanır:

• Model: Gemini
• Veriler ve işlemler: Google Workspace (Takvim, Gmail, Drive) için Vertex AI veri depoları, Google tarafından yönetilen Vertex AI Arama Model Bağlam Protokolü (MCP) sunucusu, Google Chat API'si aracılığıyla Google Chat mesajları göndermek için özel araç işlevi.
• Ajan oluşturma araçları: Agent Development Kit (ADK).
• Aracı barındırma: Vertex AI Agent Engine.
• Kullanıcı arayüzü: Chat ve Gmail için Google Workspace eklentisi (Takvim, Drive, Dokümanlar, E-Tablolar ve Slaytlar'a kolayca genişletilebilir).
• Google Workspace eklentisi: Apps Komut Dosyası, Vertex AI Agent Engine API'leri, bağlamsal (seçili Gmail iletisi).

Kavramları inceleme

Google Workspace eklentisi

Google Workspace eklentisi, bir veya daha fazla Google Workspace uygulamasını (Gmail, Chat, Takvim, Dokümanlar, Drive, Meet, E-Tablolar ve Slaytlar) genişleten özelleştirilmiş bir uygulamadır.

Apps Komut Dosyası

Apps Komut Dosyası, Google Drive tarafından desteklenen bulut tabanlı bir JavaScript platformudur. Bu platform, Google ürünlerinde görevleri entegre etmenize ve otomatikleştirmenize olanak tanır.

Google Workspace Kart çerçevesi

Google Workspace'teki Kart çerçevesi, geliştiricilerin zengin ve etkileşimli kullanıcı arayüzleri oluşturmasına olanak tanır. Metin, resim, düğme ve diğer widget'ları içeren düzenli ve görsel açıdan çekici kartlar oluşturulmasına olanak tanır. Bu kartlar, yapılandırılmış bilgiler sağlayarak ve doğrudan Workspace uygulamalarında hızlı işlemler yapılmasına olanak tanıyarak kullanıcı deneyimini iyileştirir.

Çözüm mimarisini inceleme

Kaynak kodunu inceleme

Ajan

agent.py

Aşağıdaki kod, Vertex AI ile kimlik doğrulaması yapar, Vertex AI Search MCP ve Chat API araçlarını başlatır ve aracının davranışını tanımlar.

1. Kimlik doğrulama: İstemcinin yerleştirdiği kimlik doğrulama jetonunu (CLIENT_AUTH_NAME) almak için yardımcı bir işlev (_get_access_token_from_context) kullanır. Bu jeton, Vertex AI Search MCP ve Google Chat araçları gibi aşağı akış hizmetlerinin güvenli bir şekilde çağrılması için çok önemlidir.
2. Araç kurulumu: Vertex AI Arama Model Bağlam Protokolü (MCP) sunucusuna bağlanan bir araç seti olan vertexai_mcp ve send_direct_message aracını başlatır. Bu izin, temsilcinin bağlı veri depolarınızda arama yapmasına ve Google Chat mesajları göndermesine olanak tanır.
3. Agent Definition: gemini-2.5-flash modelini kullanarak root_agent tanımlar. Talimatlar, temsilciye bilgi alma için arama aracını, işlemler için ise send_direct_message aracını kullanmaya öncelik vermesini söyler. Böylece temsilci, kurumsal verilerinizle etkili bir şekilde temellendirilir.

...
MODEL = "gemini-2.5-flash"

# Client injects a bearer token into the ToolContext state.
# The key pattern is "CLIENT_AUTH_NAME_<random_digits>".
# We dynamically parse this token to authenticate our MCP and API calls.
CLIENT_AUTH_NAME = "enterprise-ai"

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id