Google Workspace'te Agentic Workflows: ADK ile Google Dokümanlar aracısı oluşturma

1. Giriş

Google Workspace, işlerin yapıldığı yerdir. Dokümanlar'da rapor taslağı oluşturmaktan E-Tablolar'da verileri analiz etmeye, Gmail ve Meet'te ortak çalışmaya kadar birçok işlem yapabilirsiniz.

Şimdi de Dokümanlar, E-Tablolar ve Gmail'in sadece araç değil, iş arkadaşı olduğunu düşünün.

Google'ın Agent Development Kit'i (ADK) ve Gemini Enterprise Agent Platform'un yardımıyla bu artık sadece bir fikir değil. Bu çerçeveleri kullanarak akıllı bir ajan oluşturacak, ajanı büyük ölçekte dağıtacak ve Google Workspace araçlarımıza sorunsuz bir şekilde entegre edeceğiz. Böylece, ajan destekli üretkenliğin yeni bir dönemini başlatacağız.

Bu codelab'de aşağıdaki gibi adım adım bir yaklaşım kullanacaksınız:

1. Agent Development Kit'i kullanarak Yapay Zeka Doğruluk Denetleyicisi aracını geliştirin.
2. Temsilciyi, geniş ölçekte temsilciler çalıştırmak için tümüyle yönetilen bir ortam olan Gemini Enterprise Agent Platform'da dağıtın.
3. Bu Aracı'yı Google Dokümanlar'a entegre ederek dokümandaki metin için doğruluk kontrolü yapın.

Nihai çözümün nasıl çalıştığını açıklayan kavramsal bir şema aşağıda gösterilmektedir:

Doğruluk Kontrolü Temsilcisi'nin Google Dokümanı'nda nasıl çalıştığına dair nihai çıktıyı aşağıda bulabilirsiniz. Bu örnekte, bazı ifadeler içeren orijinal bir metin var ve belgedeki her ifade için doğruluk kontrolü yapılıyor. Kırmızı köşeli kutudaki çıkış, Aracının çıkışıdır.

Yapacaklarınız

• Google Dokümanı içinde doğruluk kontrolü yapacak bir ajan tasarlayın, oluşturun ve dağıtın.

Neler öğreneceksiniz?

• Agent Development Kit (AK) kullanarak bir temsilci geliştirin.
• Ajanı yerel olarak test edin ve Gemini Enterprise Ajan Platformu'nda dağıtın.
• Ajana bir Google Workspace dokümanı (Google Dokümanı) entegre edin.

Gerekenler

• Chrome web tarayıcısı
• Gmail hesabı
• Faturalandırmanın etkin olduğu bir Cloud projesi

Her seviyeden geliştirici (yeni başlayanlar dahil) için tasarlanan bu codelab'in örnek kodunda Python ve Apps Komut Dosyası kullanılmaktadır. Ancak bu programlama dillerini bilmek ön koşul değildir ve sunulan kavramları anlamak için temel düzeyde kod okuma becerisi yeterli olacaktır.

2. Başlamadan önce

Google Cloud kredileri için: Başlamanıza yardımcı olmak için bu bağlantıyı kullanarak ücretsiz Google Cloud kredilerinizi kullanın. Krediyi etkinleştirmek ve yeni bir proje oluşturmak için buradaki talimatları uygulayabilirsiniz.

Proje oluşturma

1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin .
3. bq'nun önceden yüklendiği, Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmında Cloud Shell'i Etkinleştir'i tıklayın.

4. Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulandığını ve projenin proje kimliğinize ayarlandığını kontrol edin:

gcloud auth list

5. gcloud komutunun projeniz hakkında bilgi sahibi olduğunu onaylamak için Cloud Shell'de aşağıdaki komutu çalıştırın.

gcloud config list project

6. Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:

gcloud config set project <YOUR_PROJECT_ID>

7. Aşağıda gösterilen komutu kullanarak gerekli API'leri etkinleştirin. Bu işlem birkaç dakika sürebilir. Lütfen bekleyin.

gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       discoveryengine.googleapis.com

Komut başarıyla yürütüldüğünde aşağıda gösterilene benzer bir mesaj görürsünüz:

Operation "operations/..." finished successfully.

Herhangi bir API atlanırsa uygulama sırasında istediğiniz zaman etkinleştirebilirsiniz.

gcloud komutları ve kullanımı için belgelere bakın.

3. ADK aracısını oluşturma

Google'ın doğruluk kontrolü özel işlevinden örnek alınarak metinlerin doğruluğunu kontrol eden, yapay zeka tabanlı bir denetçi olan ADK aracısını (Document Fact Checker Agent) oluşturalım. Örnekteki tek adımlı yaklaşımın aksine, aracımız iddiaları ayıklamak, bunları google_search ile doğrulamak ve yapılandırılmış JSON çıktısı oluşturmak için çok adımlı akıl yürütme kullanır.

1. adım : Agent Development Kit'i yükleyin

Cloud Shell'de yeni bir terminal sekmesi açın ve aşağıdaki gibi my-agents adlı bir klasör oluşturun. my-agents klasörüne de gidin.

mkdir workspace-agents
cd workspace-agents

Şimdi de venv kullanarak aşağıdaki şekilde sanal bir Python ortamı oluşturalım:

python -m venv .venv

Sanal ortamı aşağıdaki şekilde etkinleştirin:

source .venv/bin/activate

ADK'yı aşağıdaki gibi yükleyin:

pip install google-adk

Artık adk yardımcı programını aşağıdaki şekilde çağırabilirsiniz.

adk

Komutların listesi gösterilir.

$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...

  Agent Development Kit CLI tools.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  api_server   Starts a FastAPI server for agents.
  conformance  Conformance testing tools for ADK.
  create       Creates a new app in the current folder with prepopulated agent template.
  deploy       Deploys agent to hosted environments.
  eval         Evaluates an agent given the eval sets.
  eval_set     Manage Eval Sets.
  run          Runs an interactive CLI for a certain agent.
  web          Starts a FastAPI server with Web UI for agents.

2. adım : ADK'yı kullanarak Belge Doğruluk Denetleyicisi Aracısı'nı geliştirin

Şimdi, aşağıdaki gibi bir uygulama adı **(docfactcheckeragent)**ile adk create komutunu kullanarak aracımız için bir iskele oluşturmak üzere adk'ı kullanacağız.

adk create docfactcheckeragent

Adımları uygulayın ve aşağıdakileri seçin:

• Kök ajan için model seçmeye yönelik Gemini modeli.
• Arka uç için Vertex AI'ı seçin.
• Varsayılan Google proje kimliğiniz ve bölgeniz gösterilir. Varsayılanı seçin.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)

Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [YOUR_PROJECT_ID]: 
Enter Google Cloud region [us-central1]: 

Agent created in <YOUR_HOME_FOLDER>/workspace-agents/docfactcheckeragent:
- .env
- __init__.py
- agent.py

Varsayılan şablonun ve Agent için gerekli dosyaların oluşturulduğu klasörü inceleyin.

İlk olarak .env dosyası. İçeriği aşağıda gösterilmiştir:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

Değerler, Google Cloud projesi kimliği ve konumuna ilişkin ilgili değerlerle birlikte Vertex AI üzerinden Gemini'ı kullanacağımızı gösterir.

Ardından, klasörü modül olarak işaretleyen ve aracıyı agent.py dosyasından içe aktaran tek bir ifadeye sahip olan __init__.py dosyası gelir.

from . import agent

Son olarak, agent.py dosyası vardır. Bu agent.py dosyasındaki içeriği aşağıdaki kodla değiştirmeniz gerekir:

from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name='ai_auditor',
    model='gemini-2.5-flash',
    description="Fact-checks statements from a document and provides citations.",
    instruction="""
You are an AI Auditor specialized in factual verification and evidence-based reasoning.
Your goal is to analyze text from a Google Doc, identify verifiable factual claims, and produce a concise, source-backed audit report.

### 🔍 TASK FLOW

1. **Extract Claims**
   - Analyze the input text and identify factual claims that can be objectively verified.
   - A factual claim is any statement that can be proven true or false with external evidence.
   - Skip opinions, vague generalizations, or speculative language.
   - List each claim as a string in a JSON array.

2. **Verify Claims**
   - For each extracted claim:
     - Use the `google_search` tool to find relevant, credible results.
     - Evaluate at least the top 3 relevant URLs to determine the claim's accuracy.
     - Cross-check multiple sources when possible to ensure confidence.

3. **Classify Findings**
   - For each claim, determine one of the following verdicts:
     - ✅ **True:** Supported by multiple reputable sources.
     - ⚠️ **Misleading / Partially True:** Contains partially correct or context-dependent information.
     - ❌ **False:** Contradicted by credible evidence.
     - ❓ **Unverifiable:** Insufficient information to confirm or deny.
   - Provide a **confidence score (0–100)** reflecting the strength of evidence.

4. **Record Evidence**
   - For each claim, include:
     - The **verdict**
     - **Reasoning summary** (1–2 sentences)
     - **List of citation URLs** used for verification

5. **Summarize Results**
   - Compile a final report including:
     - Total number of claims analyzed
     - Distribution of verdicts (True / False / Misleading / Unverifiable)
     - Brief overall conclusion (e.g., "Most claims are accurate but some lack supporting evidence.")

### 🧾 OUTPUT FORMAT

Return your final response in structured JSON format as follows:

{
  "claims": [
    {
      "claim": "...",
      "verdict": "True | False | Misleading | Unverifiable",
      "confidence": 0-100,
      "reasoning": "...",
      "sources": ["https://...", "https://..."]
    }
  ],
  "summary": {
    "total_claims": X,
    "verdict_breakdown": {
      "True": X,
      "False": X,
      "Misleading": X,
      "Unverifiable": X
    },
    "overall_summary": "..."
  }
}

### 🧠 ADDITIONAL INSTRUCTIONS
- Always prefer authoritative domains (.gov, .edu, .org, or major media).
- Avoid low-quality or user-generated content as primary sources.
- Be concise, accurate, and transparent about uncertainty.
    """,
    tools=[google_search],  # Only use the search tool
)

Yukarıdaki kaynak kodun önemli noktaları şunlardır:

• Yapay zeka ajanını adını, modelini, açıklamasını ve çok ayrıntılı bir talimat grubunu vererek tanımlarız.
• Talimat grubu, ajanın tam olarak nasıl düşünmesi ve çalışması gerektiğini tanımlayan en önemli kısımdır. Bu yapı, profesyonel doğruluk kontrolü uzmanlarının çalışma şeklini yansıtır ve yapay zekayı bağımsız bir denetim hattına dönüştürür.
• Bu temsilci beyanı tamamlandıktan sonra, Google Search tool aracılığıyla temsilciye gerçek dünya bilgilerine erişim izni verilir. Önceden eğitilmiş verilere güvenmek yerine, canlı aramalar yapabilir, sonuçları değerlendirebilir ve güncel alıntılar sağlayabilir.

Bu, sistemi etkili kılar . Model yalnızca yanıt oluşturmaz, bilgileri doğrulamak için işlem de yapar (araçları kullanarak).

3. adım : Aracıyı yerel olarak test edin

Mevcut terminal penceresinden aşağıdaki komutu verin. docfactcheckeragent klasörünü içeren üst klasör (workspace-agents) içinde olduğunuzdan emin olun.

adk web

Yukarıdaki komutu Cloud Shell'de çalıştırıyorsanız aşağıdakileri kullanmanızı öneririz:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Aşağıda örnek bir yürütme gösterilmektedir:

INFO:     Started server process [1478]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Son bağlantıyı tıkladığınızda, aracı test etmek için bir web konsolu açılır. İlk etkileşimimiz temeldir: Temsilcinin gerçekten neler yapabileceğini anlamak. Bu, temsilcinin description ve instruction text özetleme yeteneğini test eder.

Aracı, açıklamasından ve talimat grubundan yararlanarak yeteneklerinin kısa bir özetini sunuyor.

Ardından, iki ifade (The sky is blue due to Rayleigh scattering. The Earth is flat.) sağlıyoruz. Bu ifade, içeriği başarıyla denetliyor ve iyi yapılandırılmış bir JSON yanıtı veriyor.

Perde arkası:

• google_search aracı, web'den alakalı sayfaları getirir.
• Gemini 2.5 Flash modeli, bu snippet'leri ayrıştırır ve doğruluklarını sınıflandırır.
• ADK, akıl yürütme düzenlemesini yönetir ve adım adım mantığın izlenmesini sağlar.

Bu yerel test aşaması, aracımızı Dokümanlar veya E-Tablolar gibi Google Workspace araçlarına bağlanabileceği Gemini Enterprise Agent Platform'da dağıtmadan önce iş akışını doğrulamaya yardımcı olur.

Özetle, Google'ın Agent Development Kit'ini (ADK) kullanarak güçlü bir yapay zeka denetçisi ajanı oluşturduk. Ajanımız metin okuyabilir, gerçeklere dayalı iddiaları belirleyebilir, güvenilir kaynakları (google_search aracını kullanarak) arayabilir ve net bir karar verebilir.

Her şeyi ADK web arayüzü üzerinden yerel olarak oluşturup test ettik ve temsilcinin şu gibi ifadeleri nasıl analiz ettiğini gördük:

The sky is blue due to Rayleigh scattering. The Earth is flat.

Temsilci, bir talebi true olarak doğruladı ve diğerini false olarak işaretledi. Bu, yerel kurulumumuzun mükemmel şekilde çalıştığını gösteren küçük ama uygun bir kanıt.

Şimdi bir sonraki büyük adımı atma, yani yerelden buluta geçme zamanı. Şimdi bu işlemi yapalım.

4. Ajanı Gemini Enterprise Ajan Platformu'na dağıtma

Gerçek bir aracı yalnızca dizüstü bilgisayarınızda test etmezsiniz. Bu aracı ölçekli olarak çalıştırabilir, diğer sistemlerle entegre edebilir ve uygulamalarınızda üretim için dağıtabilirsiniz.

Neden dağıtmalısınız?

Aracılarınızı buluta dağıtmak için bazı iyi nedenler:

• Ölçeklenebilirlik: Yerel çalışma zamanı sınırları olmadan yüksek hacimli istekleri işleyin.
• Güvenilirlik: Yerleşik izleme ve otomatik ölçeklendirme, 18 Ekim 2025'teki ADK araç yapılandırması güncellemesi gibi düzeltmelerle birlikte.
• Entegrasyona Hazır: Sorunsuz Workspace görüşmeleri için bir API uç noktası kullanıma sunun.

Neden Gemini Enterprise Ajan Platformu?

Gemini Enterprise Agent Platform'u, dağıtılan ADK temsilcilerinizin bulunduğu yer olarak düşünebilirsiniz. Bu platform, güvenilirlik, ölçeklenebilirlik ve entegrasyon için oluşturulmuş yönetilen bir ortamdır.

Bu sayede temsilciniz:

• Kalıcı durum ve bellek
• Entegre araç yürütme (ör. Google Arama, Vertex AI modelleri)
• Harici çağrılar için güvenli API uç noktaları
• Cloud Logging aracılığıyla günlük kaydı ve gözlemlenebilirlik
• Çoklu aracı düzenlemesi için yerel destek

Kısacası, ADK ile bir kez yazdıktan sonra Gemini Enterprise Agent Platformu'nu kullanarak ölçeklendirebilirsiniz.

1. adım : Dağıtım için ayarlama

Ajanı Gemini Enterprise Agent Platform'a dağıtmadan önce yapmamız gereken birkaç şey var. Aracı kodunu çalıştırmak için gereken tüm bağımlılıkların Gemini Enterprise Agent Platform çalışma zamanı ortamında kullanılabilmesi için bir requirements.txt dosyası sağlıyoruz.

Kök klasörde (docfactcheckeragent/) aşağıdaki içeriklere sahip requirements.txt dosyasını oluşturun:

google-cloud-aiplatform
google-adk
requests

2. adım : Aracıyı dağıtın

Bir sonraki adım, adk deploy komutunu kullanarak aracınızı Gemini Enterprise Agent Platform'a dağıtmaktır.

adk deploy agent_engine \
    --project=YOUR_PROJECT_ID \
    --region=YOUR_PROJECT_REGION \
    --display_name "Doc Fact Checker" \
    docfactcheckeragent/

Bu işlem, aracımızı Gemini Enterprise Ajan Platformu'na dağıtma sürecini başlatır. Bu işlem zaman alır ve yaklaşık 5-8 dakika sürebilir. Genel olarak şu işlemler gerçekleşir:

1. Aracı oluşturma işlemi başlar ve ADK CLI, kodunuzu paketler, Cloud Storage paketine yükler ve Gemini Enterprise Agent Platform'u yeni bir Gemini Enterprise Agent Platform örneği oluşturması için tetikler.
2. Tamamlama mesajı : Dağıtım tamamlandığında terminalde, Reasoning Engine kimliğinizin yer aldığı bir onay mesajı gösterilir. Örnek aşağıda gösterilmiştir:

Files and dependencies resolved

Deploying to agent engine...

✅ Created agent engine: projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

3. adım : Cloud Console'da aracıyı doğrulayın (Gemini Enterprise Ajan Platformu)

Dağıtım tamamlandıktan sonra Google Cloud Console'unuzun Agent Platform → Agents → Deployment (Aracı Platformu → Aracıları → Dağıtım) bölümüne gidin. Dağıtılan aracınızın konsolda aşağıdaki gibi listelendiğini görmeniz gerekir:

🎉 Hepsi bu kadar. Ajanınız artık Gemini Enterprise Ajan Platformu'nda yayında ve Google Workspace'e entegre edilmeye veya doğrudan test edilmeye hazır.

4. adım : Dağıtım aracınızı test etme

Tebrikler . Ajanınız artık Gemini Enterprise Ajan Platformu'nda yayında. Sonraki adım, uygulamanın doğru şekilde dağıtıldığını ve isteklere yanıt verdiğini test etmektir.

Çalışma şeklinize bağlı olarak bunu yapmanın birkaç farklı yolu vardır:

1. Google Cloud Console aracılığıyla: Dağıtılan aracılarınızı doğrudan görüntülemek, yönetmek ve test etmek için kullanılan görsel arayüz.
2. REST API'yi (cURL) kullanma: İstekleri manuel olarak göndermek ve yanıtları incelemek isteyen geliştiriciler için idealdir.
3. Python için Vertex AI SDK ile: Testi geliştirme iş akışınıza entegre etmek için daha programatik bir seçenek.

Her yaklaşım, temsilcinizin dağıtıldıktan sonra nasıl davrandığına dair bilgi verir. Örneğin, sorguları işleyip işlemediği, oturumları yönetip yönetmediği veya yanıt döndürüp döndürmediği gibi.

Yapay Zeka Denetçiniz artık Gemini Enterprise Ajan Platformu'na dağıtılan, bulut destekli bir ajan ve google_search ile geniş ölçekte doğruluk kontrolü yapmaya hazır. Bu araç, güvenilir ve API destekli bir dijital iş arkadaşına dönüştürülerek aşağıdaki gibi JSON'lar oluşturur:

{ "claims": [{"claim": "The sky is blue...", "verdict": "True", "confidence": 95}] }

Bunu doğrudan bir sonraki bölümde test edeceğiz. Bu bölümde, aracı Google Dokümanı'na entegre edip dokümanda belirtilen bilgileri doğrulayacağız.

5. Doğruluk Kontrolü Aracısı'nı Google Dokümanlar'a entegre etme

Bu bölümde, her şeyi birbirine bağlayarak dağıtılan aracınızı Google Dokümanlar'a getireceğiz. Birkaç satırlık Apps Komut Dosyası ile standart bir Google Dokümanı'nı, dağıtılan aracınızı kullanarak içeriği otomatik olarak analiz edip doğrulayabilen, yapay zeka destekli bir düzenleyiciye dönüştürebilirsiniz.

1. adım: Google Dokümanlar ortamınızı ayarlayın

Yeni veya mevcut bir Google Dokümanı (docs.new) açarak başlayın.

Bu eğitim için kullandığımız Google Dokümanı aşağıdaki içerikleri barındırıyor (bu içerikleri veya doğruluğunu kontrol etmeyi planladığınız kendi içeriklerinizi kullanabilirsiniz):

Climate change is mainly caused by solar activity cycles, not human activities. The Earth's temperature has not increased significantly in the last 100 years. Wind energy now produces more electricity than coal in every country in Europe. In 2015, nearly all world nations signed the Paris Agreement to limit global warming.

2. adım: Apps Komut Dosyası projenizi ve dosyalarınızı ayarlayın

Bu kurulum için Apps Komut Dosyası projenizde iki dosya olması gerekir:

1. AIVertex.gs: Vertex AI ve ADK Agent ile tüm iletişimi yönetir.
2. Code.gs: Google Dokümanlar arayüzünü, menülerini ve doküman işlemlerini kontrol eder.

Menüden Extensions -> Apps Script simgesine giderek düzenleyiciyi açın. Bu alanı, dağıtılan ADK aracısına bağlanmak için kullanırız. Halihazırda oluşturulmuş bir Code.gs dosyası göreceksiniz. Bu dosyanın içeriğini, sonraki bölümde verilen Code.gs koduyla değiştirmeniz gerekir.

Her birini inceleyelim.

AIVertex.gs

Soldaki Dosyalar bölümünün yanındaki + işaretini kullanarak yeni bir dosya oluşturun, bunu Script olarak seçin ve aşağıdaki içeriği dosyaya kopyalayın.

const LOCATION = PropertiesService.getScriptProperties().getProperty('LOCATION');
const GEMINI_MODEL_ID = PropertiesService.getScriptProperties().getProperty('GEMINI_MODEL_ID');
const REASONING_ENGINE_ID = PropertiesService.getScriptProperties().getProperty('REASONING_ENGINE_ID');
const SERVICE_ACCOUNT_KEY = PropertiesService.getScriptProperties().getProperty('SERVICE_ACCOUNT_KEY');

const credentials = credentialsForVertexAI();

/**
 * @param {string} statement The statement to fact-check.
 */
function requestLlmAuditorAdkAiAgent(statement) {
  return UrlFetchApp.fetch(
    `https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${credentials.projectId}/locations/${LOCATION}/reasoningEngines/${REASONING_ENGINE_ID}:streamQuery?alt=sse`,
    {
      method: 'post',
      headers: { 'Authorization': `Bearer ${credentials.accessToken}` },
      contentType: 'application/json',
      muteHttpExceptions: true,
      payload: JSON.stringify({
        "class_method": "async_stream_query",
        "input": {
          "user_id": "google_sheets_custom_function_fact_check",
          "message": statement,
        }
      })
    }
  ).getContentText();
}

/**
 * @param {string} prompt The Gemini prompt to use.
 */
function requestOutputFormatting(prompt) {
  const response = UrlFetchApp.fetch(
    `https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${credentials.projectId}/locations/${LOCATION}/publishers/google/models/${GEMINI_MODEL_ID}:generateContent`,
    {
      method: 'post',
      headers: { 'Authorization': `Bearer ${credentials.accessToken}` },
      contentType: 'application/json',
      muteHttpExceptions: true,
      payload: JSON.stringify({
        "contents": [{
          "role": "user",
          "parts": [{ "text": prompt }]
        }],
        "generationConfig": { "temperature": 0.1, "maxOutputTokens": 2048 },
        "safetySettings": [
          {
            "category": "HARM_CATEGORY_HARASSMENT",
            "threshold": "BLOCK_NONE"
          },
          {
            "category": "HARM_CATEGORY_HATE_SPEECH",
            "threshold": "BLOCK_NONE"
          },
          {
            "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
            "threshold": "BLOCK_NONE"
          },
          {
            "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
            "threshold": "BLOCK_NONE"
          }
        ]
      })
    }
  );
  return JSON.parse(response).candidates[0].content.parts[0].text
}

/**
 * Gets credentials required to call Vertex API using a Service Account.
 * Requires use of Service Account Key stored with project.
 * 
 * @return {!Object} Containing the Google Cloud project ID and the access token.
 */
function credentialsForVertexAI() {
  const credentials = SERVICE_ACCOUNT_KEY;
  if (!credentials) {
    throw new Error("service_account_key script property must be set.");
  }

  const parsedCredentials = JSON.parse(credentials);

  const service = OAuth2.createService("Vertex")
    .setTokenUrl('https://oauth2.googleapis.com/token')
    .setPrivateKey(parsedCredentials['private_key'])
    .setIssuer(parsedCredentials['client_email'])
    .setPropertyStore(PropertiesService.getScriptProperties())
    .setScope("https://www.googleapis.com/auth/cloud-platform");
  return {
    projectId: parsedCredentials['project_id'],
    accessToken: service.getAccessToken(),
  }
}

Dosyayı kaydetmeyi unutmayın.

Bu dosya şunları yapar:

• Hizmet hesabı anahtarı kullanarak Vertex AI'de güvenli bir şekilde kimlik doğrular. Belge metnini analiz etmek veya doğruluk kontrolü yapmak için dağıtılan ADK Aracınızı çağırır.
• Sonuçları okunabilir hale getirmek için akıllı yanıt biçimlendirmesinde Gemini'ı kullanır.

Code.gs

/**
 * Adds a custom menu in Google Docs to run the AI Audit directly.
 */
function onOpen() {
  DocumentApp.getUi()
    .createMenu('AI Audit Tools')
    .addItem('Run AI Audit', 'runAuditAndInsert')
    .addToUi();
}

/**
 * Returns the entire text content of the document.
 */
function getDocumentText() {
  const doc = DocumentApp.getActiveDocument();
  const body = doc.getBody();
  let text = body.getText();
  return text.trim();
}

/**
 * Runs the AI Audit and inserts the result as text at the end of the document.
 */
function runAuditAndInsert() {
  const docText = getDocumentText();
  const result = runAudit(docText);

  if (result) {
    const doc = DocumentApp.getActiveDocument();
    const body = doc.getBody();
    // Append the audit result as a new paragraph at the end of the document
    body.appendParagraph('AI Audit Result: ' + result);
  }
}

/**
 * Runs the AI Audit using ADK Agent and Gemini formatting.
 */
function runAudit(docText) {
  console.log('[INFO] Starting AI audit process...');
  if (!docText) {
    console.log('[WARN] No text in document.');
    return '⚠️ The document is empty. Please add some text to audit.';
  }

  // Check for excessive document length to avoid token limits
  if (docText.length > 10000) {
    console.log('[WARN] Document too long.');
    return '⚠️ Document exceeds 10,000 characters. Please shorten the text.';
  }

  console.log('[STEP] Sending text to ADK Agent...');
  const rawAudit = requestLlmAuditorAdkAiAgent(docText);

  // Check if rawAudit is an error message
  if (rawAudit.startsWith('ERROR:')) {
    console.error('[ERROR] ADK Agent returned error:', rawAudit);
    return rawAudit;
  }

  console.log('[STEP] Formatting AI response...');
  let formatted;
  try {
    formatted = requestOutputFormatting(
      `Here is a fact-checking result: ${rawAudit}.
       Summarize it. Keep the main verdict and reasoning. Remove markdown and make it concise.`
    );
  } catch (error) {
    console.error('[ERROR] Formatting failed:', error.toString());
    return `ERROR: Failed to format audit result - ${error.toString()}`;
  }

  console.log('[SUCCESS] Audit completed successfully.');
  console.log('[RESULT] Final Output:', formatted);
  return formatted;
}

Bu dosya, Dokümanlar kullanıcı arayüzünüzü yukarıdaki ADK mantığına bağlar. Denetlemeyi doğrudan özel bir Dokümanlar menüsünden tetiklemenize olanak tanır. Genel olarak şu işlemleri yapar:

• Google Dokümanlar'a Yapay Zeka Denetim Araçları adlı özel bir menü ekler.
• Belge metninizi alır ve analiz için ADK Aracınıza gönderir.
• Yapay zekayla üretilen denetleme sonuçlarını dokümanda gösterir.

3. adım : Hizmet hesabı oluşturun

Agent Calling işlevini bir Google Dokümanı'na entegre ettiğinizde, Gemini Enterprise Agent Platform'da dağıtılan Agent'ı çağırmak için doğru role sahip olacak şekilde Google Dokümanı'na bir kimlik sağlamamız gerekir. Bu amaçla, doğru role sahip bir hizmet hesabı (roles/aiplatform.user) kullanacağız.

Cloud Shell'de aşağıdaki komut dosyasını adım adım çalıştırın:

export PROJECT_ID="YOUR_PROJECT_ID"
export SA_NAME="docfactcheckeragentsa"

gcloud iam service-accounts create $SA_NAME \
  --project=$PROJECT_ID \
  --display-name="Doc Fact Checker Agent Service Account"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountTokenCreator"

Bu işlem, hizmet hesabını doğru izinlerle oluşturur.

Hizmet hesabı için bir JSON anahtarı oluştururuz. Apps Komut Dosyası projeniz kimlik doğrulamak için bunu kullanır. Anahtarı almak için şu adımları uygulayın:

1. Google Cloud Console'da IAM ve Yönetici > Hizmet Hesapları'na gidin.
2. Yeni oluşturduğunuz hizmet hesabını tıklayın.
3. Anahtarlar sekmesine gidin.
4. Anahtar Ekle → Yeni Anahtar Oluştur'u tıklayın.
5. JSON'u seçip Oluştur'u tıklayın.
6. Otomatik olarak bir JSON dosyası indirilir. Bu dosyayı güvenli bir yerde saklamanız gerekir. İçeriğini bir sonraki bölümde komut dosyası özelliklerinize yapıştıracaksınız.

4. adım : Komut dosyası özellikleri ekleyin

Google Dokümanlar'da Apps Komut Dosyası Düzenleyicisi'ne geri dönün.

Komut dosyanızı dağıtılan kaynaklarınıza bağlamak için Project Settings → Script Properties → Add Script Property simgesine gidin.

Komut Dosyası Özelliklerinize aşağıdakileri ekleyin:

1. LOCATION: Vertex AI dağıtımınızın bölgesi. Ör. us-central1
2. GEMINI_MODEL_ID: Kullanılacak Gemini modeli. Şu değeri kullanın: gemini-2.5-flash
3. REASONING_ENGINE_ID: Dağıtılan ADK temsilcisi kimliği. Bu, dağıttığınız belirli bir ajanın konsolundaki Gemini Enterprise Ajan Platformu seçeneğinden elde edilebilir. Dağıtılan temsilcinin kaynak adını görürsünüz. Aracı Kimliği, kaynak adındaki son sayısal değerdir (yani RESOURCE_ID). Örneğin, projects/SOME_ID/locations/REGION/reasoningEngines/RESOURCE_ID
4. SERVICE_ACCOUNT_KEY: Önceki adımda oluşturduğumuz hizmet hesabı için indirdiğiniz JSON anahtarının tüm içeriğini kopyalayın.

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

5. adım : OAuth2 kitaplığını ekleyin

Apps Komut Dosyası projemizin, API çağrılarının kimliğini doğrulamak için OAuth2 kitaplığına ihtiyacı var.

Eklemek için:

1. Services → Libraries uygulamasına gidin
2. Add a Library simgesini tıklayın.
3. Komut dosyası kimliğini girin: 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

6. adım : Google Dokümanlar'da Doğruluk Denetleyicisi Doküman Aracısı'nı test edin

Google Dokümanlar'da aracıyı test etme işleminin son adımındayız. Bunun için aşağıdakileri yapın:

1. Apps Komut Dosyası düzenleyicisinde onOpen() işlevini bir kez çalıştırın. Bu işlem, Google Dokümanlar'a yeni bir Yapay Zeka Denetleme Araçları menüsü ekler.
2. Dokümanınıza dönün. Ana menüde AI Audit Tools başlıklı ek bir menü öğesi görürsünüz. Bu seçeneği ve ardından Run AI Audit simgesini tıklayın.

Aşağıda örnek bir çalıştırma verilmiştir:

6. Temizleme

Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için bu atölye çalışması sırasında oluşturduğumuz kaynakları silmeniz önemlidir.

Artık Gemini Enterprise Ajan Platformu'nda Ajan'ın dağıtılmasına gerek yoksa aşağıdaki adımları uygulayarak Ajan'ı silebilirsiniz:

1. Google Cloud Console'da Gemini Enterprise Agent Platform sayfasına gidin.
2. Dağıtılan temsilciler listesinde silmek istediğiniz temsilciyi bulun.
3. Temsilcinin adının yanındaki üç nokta menüsünü (diğer işlemler) tıklayın.
4. Açılır menüden Sil'i seçin.
5. Onay iletişim kutusunda Aracı sil'i tıklayarak silme işlemini onaylayın.

İyi bir uygulama olarak hizmet hesabını da silin.

gcloud iam service-accounts delete ${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

7. Tebrikler

Yapay zeka temsilcinizi dağıttınız, Google Dokümanlar'a bağladınız ve içeriğinizin bulunduğu yerde analiz, muhakeme ve özetleme gibi işlemleri yaparken nasıl çalıştığını gördünüz. Burada oluşturduğumuz şey sadece bağımsız bir demo değildir. Google Workspace'te akıllı ve temsilci odaklı ortak çalışmanın temelini oluşturur.

ADK'nın akıl yürütme özelliklerini Gemini'ın üretken modelleriyle birleştirerek Google Dokümanlar'ı, metninizi bağlamla birlikte okuyabilen, denetleyebilen ve iyileştirebilen, yaşayan ve düşünen bir asistana dönüştürdük.

Aynı plan, E-Tablolar, Slaytlar, Drive ve Gmail'de de geçerlidir. Şu özellikleri içeren ajanlar oluşturabilirsiniz:

• E-Tablolar'da finansal verileri denetleme ve tutarsızlıkları işaretleme
• Slaytlar'da otomatik olarak şarkı önerisi sunumları ve özetler oluşturma
• Drive'da dokümanları akıllıca etiketleme ve düzenleme
• Hatta doğrudan Gmail'de e-posta taslağı oluşturup doğruluk kontrolü yapabilirsiniz.

Bu gösterimde, günlük Workspace araçlarınıza sorunsuz bir şekilde entegre olan, statik dokümanları dinamik yapay zeka iş arkadaşlarına dönüştüren, temsilci tabanlı iş akışları oluşturmanın temelleri açıklanmaktadır.

Referans belgeler

• Temsilci Geliştirme Kiti
• Gemini Enterprise Ajan Platformu