Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

ADK ve MCP ile Google Workspace yapay zeka ajanı oluşturma

1. Giriş

Bu codelab'de, doğrudan resmi Google Workspace MCP sunucularına bağlanan Agent Development Kit (ADK)'yı kullanarak profesyonel kodlama yapay zeka ajanı oluşturmayı öğreneceksiniz.

Model Context Protocol (MCP), yapay zeka modellerinin uzak sunucular tarafından sağlanan araçları güvenli bir şekilde kullanmasını sağlayan açık bir standarttır. ADK, Google'ın otonom ajanlar oluşturmak için sunduğu profesyonel kodlama çerçevesidir. Bu verileri birleştirerek Gmail, Google Drive, Google Takvim, Google Chat ve Kişiler verilerinize dayalı, son derece özelleştirilmiş temsilciler oluşturabilirsiniz.

Kullanılabilir araçlar ve yapılandırma hakkında eksiksiz doküman için Google Workspace MCP sunucularını yapılandırma başlıklı makaleyi inceleyin.

Yapacaklarınız

Google Cloud projenizde Google Workspace MCP hizmetlerini etkinleştirin.
OAuth onayını yapılandırın ve hem yerel test hem de üretim dağıtımı için kimlik bilgileri oluşturun.
Statik jetonları kullanarak 5 Workspace MCP sunucusuna bağlanan yerel bir ADK aracısı oluşturun.
Dinamik jeton yerleştirme kullanan, üretime hazır bir ADK aracısını Gemini Enterprise Agent Platform (GEAP) Agent Runtime'a oluşturup dağıtın.
Özel temsilcinizi Gemini Enterprise'da yerel olarak kaydedip test edin.

İhtiyacınız olanlar

Web tarayıcısı (ör. Chrome)
Faturalandırmanın etkin olduğu bir Google Cloud projesi.
Google Workspace hesabı (akıllı özellikler etkinleştirilmiş olmalıdır).
Yerel makinenizde Python 3.11 veya sonraki bir sürümün yüklü olması gerekir.
Google Cloud CLI (gcloud) yüklü ve başlatılmış olmalıdır.

2. Başlamadan önce

Google Cloud projesi oluşturma veya seçme

Konsol Seçeneği

Google Cloud Console'da bir Google Cloud projesi seçin veya oluşturun.

CLI Seçeneği

Yeni bir proje oluşturun ve etkin olarak ayarlayın:

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

API'leri etkinleştirme

Google Workspace MCP sunucularını kullanmak için hem standart Google Workspace API'lerini hem de özel MCP hizmetlerini etkinleştirmeniz gerekir.

Konsol Seçeneği

Web tarayıcısını kullanarak bunları etkinleştirmek için aşağıdaki düğmeleri tıklayın:

CLI seçeneği Şu terminal komutlarını çalıştırın:

# Enable standard GWS APIs
gcloud services enable chat.googleapis.com \
  drive.googleapis.com \
  calendar-json.googleapis.com \
  people.googleapis.com \
  gmail.googleapis.com

# Enable dedicated MCP services
gcloud services enable calendarmcp.googleapis.com \
  chatmcp.googleapis.com \
  drivemcp.googleapis.com \
  gmailmcp.googleapis.com

Chat uygulamasını yapılandırma

Google Chat MCP sunucusunu kullanmak için Google Cloud projenizde bir Chat uygulaması yapılandırmanız gerekir.

Google Chat API > Yönet > Yapılandırma'ya gidin.
Chat uygulamasını kurun:
- Uygulama adı: ADK Workspace Agent
- Avatar URL'si: https://developers.google.com/chat/images/quickstart-app-avatar.png
- Açıklama: MCP server connection for ADK Agent
- İşlevsellik bölümünde Etkileşimli özellikleri etkinleştir'i devre dışı bırakın.
- Günlükler bölümünde Günlük hatalarını Logging'e seçeneğini belirleyin.
Kaydet'i tıklayın.

3. OAuth iznini ve istemcilerini yapılandırma

Google Workspace MCP sunucuları, güvenli kimlik doğrulama için OAuth 2.0'ı kullanır. OAuth kullanıcı rızası ekranını yapılandırmanız ve iki ayrı istemci kimliği oluşturmanız gerekir: biri yerel geliştirme, diğeri ise dağıtılan aracı için.

Google Cloud Console'da sol üst köşedeki gezinme menüsünü (hamburger simgesi) tıklayın. Google Auth Platform > Markalama'yı (veya Google Auth Platform görünmüyorsa API'ler ve Hizmetler > OAuth kullanıcı rızası ekranı'nı) seçin.
Uygulama Bilgileri'ni yapılandırın:
- Uygulama adı: Workspace ADK Agent
- Kullanıcı destek e-postası: E-postanızı seçin.
Kitle'yi yapılandırın: Şirket içi'ni seçin.
İletişim bilgilerini yapılandırın: E-posta adresinizi girip Oluştur'u tıklayın.

Veri Erişimi > Kapsam Ekleme veya Kaldırma'ya gidin. Kapsamları manuel olarak ekleme bölümünde, 5 hizmetin tümüne erişim izni vermek için aşağıdaki kapsamları ekleyin:

https://www.googleapis.com/auth/calendar.calendarlist.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.calendars
https://www.googleapis.com/auth/chat.spaces
https://www.googleapis.com/auth/chat.messages
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.compose
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/directory.readonly
https://www.googleapis.com/auth/userinfo.profile
https://www.googleapis.com/auth/contacts.readonly
https://www.googleapis.com/auth/cloud-platform

Tabloya Ekle'yi, ardından Güncelle'yi ve son olarak Kaydet'i tıklayın.

Yerel geliştirme için istemci kimliği oluşturma (masaüstü uygulaması)

Google Cloud Console'da Google Auth Platform > Clients'a (Müşteriler) (veya APIs & Services > Credentials'a (API'ler ve Hizmetler > Kimlik Bilgileri) gidin. Kimlik bilgileri oluştur'u (veya İstemci oluştur'u) tıklayın ve OAuth istemci kimliği'ni seçin.
Uygulama türü olarak Masaüstü uygulaması'nı seçin.
Workspace Agent Local olarak adlandırın.
Oluştur'u tıklayın ve JSON dosyasını indirin. Dosyayı yerel olarak client_secret.json şeklinde kaydedin.

4. Ajan Geliştirme ve Test Etme

Bu bölümde, aracı ortamının nasıl oluşturulacağı açıklanmaktadır. Test için statik jeton yaklaşımını kullanacağız. Bu yaklaşımda, gcloud kullanarak bir OAuth jetonu getirip ADK'nın McpToolset işlevine iletiriz. Bu adımları yerel makinenizi veya Google Cloud Shell'i kullanarak uygulayabilirsiniz.

Geliştirme ortamınızı ayarlamak için ortamınızı seçin: Yerel Makine veya Google Cloud Shell. Her iki yöntemde de platformlar arasında tutarlılık sağlamak için kimlik doğrulama amacıyla ortak bir Python komut dosyası kullanılır.

1. Ortam dizini oluşturma

Proje dizini oluşturmak ve gerekli paketleri yüklemek için terminalinizde aşağıdaki komutları çalıştırın.

Google Cloud Shell için: Öncelikle Google Cloud Console'un sağ üst araç çubuğunda Cloud Shell'i Etkinleştir simgesini (>_) tıklayın.
Yerel makine için: Standart terminalinizi açın.

mkdir -p gws-adk-agent/workspace_agent
cd gws-adk-agent
python3 -m venv .venv
source .venv/bin/activate
pip install google-adk poetry google-auth-oauthlib

2. Kimlik bilgileri dosyasını hazırlama

Önceki adımda indirdiğiniz client_secret.json dosyasını gws-adk-agent dizininizin kök dizinine yerleştirmeniz gerekir.

Yerel Makine: İndirilen client_secret.json dosyasını gws-adk-agent dizinine taşıyın veya kopyalayın.
Google Cloud Shell: Cloud Shell'de aşağıdaki komutu çalıştırarak dosyayı oluşturun ([PASTE_JSON_HERE] yerine gerçek JSON içeriğinizi girin):

cat << 'EOF' > client_secret.json
[PASTE_JSON_HERE]
EOF

3. Kimlik doğrulama ve .env oluşturma (`auth.py`)

Kimlik doğrulama işlemlerini tutarlı bir şekilde yönetmek ve ortama özgü CLI yönlendirme sorunlarını önlemek için resmi Google kimlik doğrulama kitaplıkları tarafından desteklenen özel bir Python komut dosyası kullanırız. Bu komut dosyası, OAuth akışını yönetir, Uygulama Varsayılan Kimlik Bilgilerini (ADC) yerel olarak kaydeder ve gerekli .env dosyasını oluşturur.

gws-adk-agent dizininde auth.py adlı bir dosya oluşturun ve aşağıdaki kodu ekleyin:

import json
import os
from urllib.parse import urlparse, parse_qs
import google.auth
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRET_FILE = 'client_secret.json'

SCOPES = [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/chat.spaces.readonly",
    "https://www.googleapis.com/auth/chat.messages",
    "https://www.googleapis.com/auth/drive.readonly",
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.compose",
    "https://www.googleapis.com/auth/directory.readonly",
    "https://www.googleapis.com/auth/contacts.readonly"
]

# Initialize the flow from the client secrets JSON
flow = InstalledAppFlow.from_client_secrets_file(
    CLIENT_SECRET_FILE,
    scopes=SCOPES,
    redirect_uri='http://localhost:8085/'
)

# Generate the Auth URL
auth_url, expected_state = flow.authorization_url(prompt='consent', access_type='offline')

print("\n=== GOOGLE OAUTH OFFICIAL LIBRARY FLOW ===")
print("1. Copy the following link and paste it into your browser (or click it if supported):\n")
print(auth_url)
print("\n2. Authorize the application.")
print("3. Your browser will redirect to a 'localhost' page (it will show a 'Site can't be reached' error, which is EXPECTED and normal).")
print("4. Copy the ENTIRE URL from your browser's address bar (including the http://localhost:8085/ part).\n")

# Get the redirected URL from the user
redirected_url = input("Paste the full localhost URL here: ").strip()

# Exchange the redirect URL for tokens
print("\nExchanging code for tokens...")
try:
    parsed_url = urlparse(redirected_url)
    query_params = parse_qs(parsed_url.query)
    
    returned_state = query_params.get('state', [None])[0]
    code = query_params.get('code', [None])[0]
    
    if not code:
        raise ValueError("No 'code' parameter found in the URL.")
    if returned_state != expected_state:
        raise ValueError("CSRF Warning! State mismatch.")
        
    flow.fetch_token(code=code)
    creds = flow.credentials
except Exception as e:
    print(f"Authentication failed: {e}")
    exit(1)

if not creds.refresh_token:
    print("\nError: No refresh token returned. You may need to revoke access and try again.")
    exit(1)

# Save Application Default Credentials
adc_data = {
    "client_id": creds.client_id,
    "client_secret": creds.client_secret,
    "refresh_token": creds.refresh_token,
    "type": "authorized_user"
}

adc_dir = os.path.expanduser("~/.config/gcloud")
os.makedirs(adc_dir, exist_ok=True)
adc_path = os.path.join(adc_dir, "application_default_credentials.json")

with open(adc_path, "w") as f:
    json.dump(adc_data, f, indent=2)

# Detect Project ID
try:
    _, project_id = google.auth.default()
except Exception:
    project_id = None

project_id = project_id or os.environ.get("GOOGLE_CLOUD_PROJECT", "YOUR_PROJECT_ID")

# Save to .env for local development (relative to project root)
env_dir = "workspace_agent"
os.makedirs(env_dir, exist_ok=True)
env_path = os.path.join(env_dir, ".env")

with open(env_path, "w") as f:
    f.write("GOOGLE_GENAI_USE_VERTEXAI=1\n")
    f.write(f"GOOGLE_CLOUD_PROJECT={project_id}\n")
    f.write("GOOGLE_CLOUD_LOCATION=us-central1\n")

print(f"\nSuccess! Application Default Credentials saved to: {adc_path}")
print(f"Environment variables saved to: {env_path}")
if project_id == "YOUR_PROJECT_ID":
    print("NOTE: Could not automatically detect Project ID. Please update it manually in .env")

Komut dosyasını terminalinizde çalıştırın:

python3 auth.py

Aracı kodunu oluşturma

Önceki adımda seçtiğiniz ortamdan bağımsız olarak temsilci kodu tamamen aynı kalır. Önceden oluşturduğunuz workspace_agent alt dizininizde agent.py adlı bir dosya oluşturun ve aşağıdaki kodu ekleyin. Bu komut dosyası, yetkilendirme sağlamak için Uygulama Varsayılan Kimlik Bilgileri'ni (ADC) kullanır. Kimlik bilgilerini dinamik bir üstbilgi sağlayıcı aracılığıyla tamamen bellekte otomatik olarak doğrular ve yeniler.

import datetime
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

MODEL = "gemini-2.5-flash"

# Load credentials from Application Default Credentials (ADC) saved by auth.py
creds, _ = google.auth.default()

# 1. STARTUP SAFETY: Ensure valid token at import time for static tool discovery (e.g. adk web UI load)
if not creds.valid:
    creds.refresh(Request())
    print("\n[Agent Startup] Access token refreshed from ADC.")

def auth_header_provider(tool_context=None) -> dict[str, str]:
    """2. RUNTIME SAFETY: Dynamically provides auth headers, refreshing if expired during the session."""
    if not creds.valid:
        creds.refresh(Request())
        print("\n[Agent Runtime] Access token refreshed from ADC.")
    return {"Authorization": f"Bearer {creds.token}"}

# Initialize the 5 GWS MCP servers with combined startup headers and dynamic runtime provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://calendarmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://chatmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://drivemcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://gmailmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://people.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)

current_date = datetime.datetime.now().strftime("%Y-%m-%d")

# Define the agent and attach all 5 toolsets
root_agent = LlmAgent(
    model=MODEL,
    name='gws_adk_agent',
    instruction=f"""You are a helpful assistant grounded in the user's Google Workspace data.
    Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
    Use the provided MCP tools to answer questions about their Calendar, Chat, Drive, Gmail, and Contacts.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

Temsilcinizi Çalıştırma ve Test Etme

Etkileşimli web kullanıcı arayüzünü kullanarak veya doğrudan Terminal/Shell'inizde aracınızla etkileşime geçebilirsiniz.

1. seçenek: Etkileşimli web kullanıcı arayüzü

Yerel makine kullanıyorsanız:

gws-adk-agent proje kök dizininizden ADK web arayüzünü başlatın:
```
adk web
```
Temsilcinizle sohbet etmek için tarayıcınızda http://localhost:8000 simgesini açın.

Google Cloud Shell'deyseniz:

gws-adk-agent proje kök dizininizden, 8080 bağlantı noktasını açıkça zorunlu kılan ADK web arayüzünü başlatın:
```
adk web --port 8080 --allow_origins=*
```
Arayüzü yeni bir sekmede açmak için Cloud Shell araç çubuğunun sağ üst kısmındaki Web Önizlemesi düğmesini tıklayın ve 8080 bağlantı noktasında önizle'yi seçin.

2. seçenek: Terminal CLI modu (alternatif)

Terminalde kalmayı tercih ediyorsanız veya web tarayıcısı önizlemelerini ayarlamaktan kaçınmak istiyorsanız ADK, yerel bir etkileşimli REPL sohbet modu sunar.

gws-adk-agent proje kök dizininizden aşağıdaki komutu çalıştırın (bu komut hem yerel makinede hem de Google Cloud Shell'de aynı şekilde çalışır):

adk run workspace_agent

Doğrudan kabuğunuzda etkileşimli bir sohbet oturumuna gireceksiniz:

Running agent gws_adk_agent, type exit to exit.
[user]:

Temsilcinize istem girmeyi deneyin

Seçtiğiniz arayüzden bağımsız olarak, Workspace MCP araçlarından yararlanan sorgularla aracıyı test etmeyi deneyin:

What are my upcoming meetings this week?

Summarize the last 3 unread emails in my Gmail.

5. Üretim Dağıtımı

Aracı üretime dağıtmak için sabit kodlanmış yerel jeton kullanamayız. Bunun yerine, bir kullanıcı temsilciyle etkileşimde bulunduğunda Gemini Enterprise platformu tarafından yerleştirilen OAuth erişim jetonunu dinamik olarak çıkarmak için ADK'yı header_provider kullanırız.

Üretim temsilcisi kodunu oluşturma

enterprise_ai adlı bir dizin paketi oluşturun ve içinde bir agent.py dosyası oluşturun:

mkdir -p enterprise_ai

enterprise_ai/agent.py için aşağıdaki içeriği yaz:

import datetime
import os
import re
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext

MODEL = "gemini-2.5-flash"
# This name MUST match the Authorization Name used during Gemini Enterprise registration
CLIENT_AUTH_NAME = "workspace-adk-auth"

def _get_access_token_from_context(tool_context: ToolContext) -> str:
    """Dynamically parses the user bearer token injected into the ToolContext state."""
    escaped_name = re.escape(CLIENT_AUTH_NAME)
    pattern = re.compile(fr"^{escaped_name}_\d+$")
    state_dict = tool_context.state.to_dict() if hasattr(tool_context.state, 'to_dict') else tool_context.state
    matching_keys = [k for k in state_dict.keys() if pattern.match(k)]
    if matching_keys:
        return state_dict.get(matching_keys[0])
    raise Exception(f"No bearer token found in ToolContext state matching pattern {pattern.pattern}")

def auth_header_provider(tool_context: ToolContext) -> dict[str, str]:
    """Provides the dynamic Authorization header for MCP requests."""
    token = _get_access_token_from_context(tool_context)
    return {"Authorization": f"Bearer {token}"}

# Initialize toolsets using the dynamic header_provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://calendarmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://chatmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://drivemcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://gmailmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://people.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)

current_date = datetime.datetime.now().strftime("%Y-%m-%d")

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""You are an enterprise assistant grounded securely in the user's Workspace data.
    Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
    Always use the provided MCP tools to fetch context from Calendar, Chat, Drive, Gmail, and People.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

GEAP Agent Runtime'a dağıtma

ADK KSA'yı kullanarak profesyonel kod temsilcinizi dağıtın:

adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Workspace ADK Agent" \
  enterprise_ai

Dağıtımın tamamlanmasını bekleyin ve oluşturulan Reasoning Engine kaynak adını terminal çıkışından kopyalayın (ör. projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID).

6. Gemini Enterprise'a kaydolma

Artık özel ADK aracısını Gemini Enterprise'a getiriyoruz. Böylece kullanıcılar, bu aracıyla doğrudan sohbet edebilir.

Üretim için istemci kimliği oluşturma (web uygulaması)

Aracınızı üretime dağıtmak için Web uygulaması istemci kimliği oluşturmanız gerekir. Yerel test için kullanılan masaüstü istemcisinin aksine, web uygulaması istemcisi güvenli bir sunucu tarafı OAuth akışı sağlar. Bu, GEAP Agent Runtime'daki barındırılan aracının, belirtilen yönlendirme URI'sini kullanarak Gemini Enterprise tarafından iletilen kullanıcının kimlik doğrulama jetonlarını güvenli bir şekilde almasına olanak tanır. Bu kurulum, temsilcinin üretim ortamında kullanıcı adına Google Workspace verilerine güvenli bir şekilde erişmesi için gereklidir.

Google Cloud Console'da sol üst köşedeki gezinme menüsünü (hamburger simgesi) tıklayın. Google Auth Platform > Clients'ı (Google Auth Platform görünmüyorsa API'ler ve Hizmetler > Kimlik Bilgileri'ni) seçin. Kimlik bilgileri oluştur'u (veya İstemci oluştur'u) tıklayın ve OAuth istemci kimliği'ni seçin.
Uygulama türü olarak Web uygulaması'nı seçin.
Workspace Agent Production olarak adlandırın.
Yetkilendirilmiş yönlendirme URI'leri bölümüne aşağıdaki URI'leri ekleyin:
- URI ekle'yi tıklayın ve https://vertexaisearch.cloud.google.com/oauth-redirect girin.
- URI ekle'yi tekrar tıklayın ve https://vertexaisearch.cloud.google.com/static/oauth/oauth.html girin.
Oluştur'u tıklayın. "OAuth istemcisi oluşturuldu" pop-up penceresinde (veya İstemciler listesinden) İstemci Kimliği ve İstemci Gizli Anahtarı'nı kopyalayın. Gemini Enterprise'da aracı kaydederken bu bilgilere ihtiyacınız olacak.

Gemini Enterprise uygulaması oluşturma

Google Cloud Console'da Gemini Enterprise sayfasına gidin:

Gemini Enterprise kartında Yönet'i tıklayın.
Uygulama oluştur'u tıklayın.
Gemini Enterprise bölümünde Oluştur'u tıklayın.
Uygulama adınız alanına uygulamanız için bir ad girin. Uygulama kimliğiniz, uygulama adının altında görünür.
Şirketinizin veya kuruluşunuzun harici adı alanına şirket ya da kuruluş adını girin. Bu eğitimde Cymbal Bank kullanabilirsiniz.
Uygulamanızın konumu olarak global (Küresel)'i seçin.
Devam'ı tıklayın.

Özel temsilciyi kaydetme

Gemini Enterprise konsolunu açın:

Etkin uygulamanızı seçin, Aracıları'na gidin ve + Aracı ekle > Aracı Çalışma Zamanı aracılığıyla Özel Aracı Ekle'yi tıklayın.

Yetkilendirmeler bölümünde Yetkilendirme ekle'yi tıklayın:

Yetkilendirme adı: workspace-adk-auth (Python kodunuzdaki CLIENT_AUTH_NAME ile tam olarak eşleşmelidir)
İstemci kimliği: Yukarıda oluşturulan üretim web uygulaması istemci kimliğini yapıştırın.
İstemci gizli anahtarı: Yukarıda oluşturulan Üretim Web Uygulaması istemci gizli anahtarını yapıştırın.
Token URI: https://oauth2.googleapis.com/token

Yetkilendirme URI'si: Yukarıdaki 5. adımda kopyaladığınız istemci kimliği ile YOUR_CLIENT_ID yerine koyarak URI'yi oluşturun:

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.calendars%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.events%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.send%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.spaces%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.messages%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.file%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdirectory.readonly&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

Bitti'yi, ardından Sonraki'yi tıklayın.

Yapılandırma bölümünde:

Ajan adı: Workspace Pro Agent

Açıklama:

Use this agent to answer questions about your Google Workspace data, including Gmail, Google Drive, Google Calendar, Google Chat, and Contacts. It can find files, summarize emails, check your schedule, and look up contact information.

Agent Runtime akıl yürütme motoru: adk deploy çıkışından kopyaladığınız motor kaynağı adını yapıştırın.

Oluştur'u tıklayın.

Gemini Enterprise'da temsilciyi deneyin

Aracınızla Google Cloud Console Önizlemesi (geliştiriciler için en hızlı yöntem) veya Gemini Enterprise Web Uygulaması'nı (son kullanıcı deneyimi) kullanarak etkileşimde bulunabilirsiniz.

1. seçenek: Google Cloud Console Önizlemesi

Google Cloud Console'da Gemini Enterprise sayfasına gidin:

Gezinme menüsünde Uygulamalar'ı tıklayın ve yeni oluşturduğunuz uygulamayı seçin.
Sağ üstte Önizleme'yi veya Önizlemeyi aç'ı tıklayın.

Arama çubuğuna aşağıdaki sorguyu girin:

Search for files in Drive related to 'Project Milestone', summarize them, and tell me if I have any meetings with the project owner today.

Sorguyu göndermek ve sonuçları doğrudan konsolda görüntülemek için Enter tuşuna basın.

2. seçenek: Gemini Enterprise web uygulaması

Gemini Enterprise web uygulaması arayüzünüzü açın.
Menü ☰ > Aracıları'na gidin ve Kuruluşunuzdan bölümünde Workspace Pro Aracı'yı seçin.
Google Cloud Console Önizleme seçeneğindeki sorgunun aynısını yazın.
OAuth kullanıcı izni akışını tamamlamanız istendiğinde Yetkilendir'i tıklayın.
Ajan, MCP protokolünü kullanarak görevleri birden fazla hizmette sorunsuz bir şekilde yürütecek.

7. Temizleme

Gereksiz ücretleri önlemek için kaynaklarınızı temizleyin:

Konsol Seçeneği

API ve Hizmetler Kontrol Paneli'ne gidin, etkinleştirdiğiniz MCP hizmetlerini (ör. Calendar MCP, Gmail MCP) seçin ve API'yi devre dışı bırak'ı tıklayın. Google Auth Platform > Clients (İstemciler) bölümündeki OAuth istemci kimliklerini ve Gemini Enterprise Console'dan Reasoning Engine dağıtımını silin.

CLI Seçeneği

MCP hizmetlerini devre dışı bırakmak için aşağıdaki terminal komutlarını yürütün:

# Disable Workspace MCP services
gcloud services disable calendarmcp.googleapis.com \
  chatmcp.googleapis.com \
  drivemcp.googleapis.com \
  gmailmcp.googleapis.com

8. Tebrikler

Tebrikler! Doğrudan resmi Google Workspace MCP sunucularına bağlı bir profesyonel kod ADK yapay zeka aracını başarıyla oluşturup test ettiniz ve dağıttınız.

Öğrendikleriniz

Google Cloud'da Google Workspace MCP hizmetlerini etkinleştirme
Statik başlıklar kullanarak yerel ADK testi için OAuth kimlik bilgilerini işleme
Üretim aracıları için header_provider kullanarak dinamik jeton yerleştirme nasıl uygulanır?
GEAP Agent Runtime'a ADK aracısı dağıtma ve Gemini Enterprise'a kaydetme

Referans belgeleri

Model Context Protocol (MCP) Spesifikasyonu
ADK Documentation (Pro-code framework) [ADK Belgeleri (Profesyonel kod çerçevesi)]
Google Workspace MCP sunucularını yapılandırma

ADK ve MCP ile Google Workspace yapay zeka ajanı oluşturma

1. Giriş

Yapacaklarınız

İhtiyacınız olanlar

2. Başlamadan önce

Google Cloud projesi oluşturma veya seçme

Konsol Seçeneği

CLI Seçeneği

API'leri etkinleştirme

Konsol Seçeneği

CLI seçeneği Şu terminal komutlarını çalıştırın:

Chat uygulamasını yapılandırma

3. OAuth iznini ve istemcilerini yapılandırma

OAuth kullanıcı rızası ekranını ayarlama

Yerel geliştirme için istemci kimliği oluşturma (masaüstü uygulaması)

4. Ajan Geliştirme ve Test Etme

1. Ortam dizini oluşturma

2. Kimlik bilgileri dosyasını hazırlama

3. Kimlik doğrulama ve .env oluşturma (auth.py)

Aracı kodunu oluşturma

Temsilcinizi Çalıştırma ve Test Etme

1. seçenek: Etkileşimli web kullanıcı arayüzü

Yerel makine kullanıyorsanız:

Google Cloud Shell'deyseniz:

2. seçenek: Terminal CLI modu (alternatif)

Temsilcinize istem girmeyi deneyin

5. Üretim Dağıtımı

Üretim temsilcisi kodunu oluşturma

GEAP Agent Runtime'a dağıtma

6. Gemini Enterprise'a kaydolma

Üretim için istemci kimliği oluşturma (web uygulaması)

Gemini Enterprise uygulaması oluşturma

Özel temsilciyi kaydetme

Gemini Enterprise'da temsilciyi deneyin

1. seçenek: Google Cloud Console Önizlemesi

2. seçenek: Gemini Enterprise web uygulaması

7. Temizleme

Konsol Seçeneği

CLI Seçeneği

8. Tebrikler

Öğrendikleriniz

Referans belgeleri

3. Kimlik doğrulama ve .env oluşturma (`auth.py`)