Bu sayfa, Cloud Translation API ile çevrilmiştir.

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şlemde yardımcı olur.

Ş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 Vertex AI'ın Agent Engine'i sayesinde bu artık sadece bir fikir değil. Bu çerçeveleri kullanarak akıllı bir temsilci oluşturacak, temsilciyi ölçekli olarak dağıtacak ve Google Workspace araçlarımıza sorunsuz bir şekilde entegre ederek temsilci tabanlı ü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:

Agent Development Kit'i kullanarak Yapay Zeka Bilgi Teyidi Aracısı'nı geliştirin.
Temsilciyi, Temsilcileri geniş ölçekte çalıştırmak için tümüyle yönetilen bir ortam olan Agent Engine'e dağıtın.
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österilmiştir:

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 aracı tasarlayın, oluşturun ve dağıtın.

Neler öğreneceksiniz?

Aracı Geliştirme Kitini (AK) kullanarak bir aracı geliştirin.
Temsilciyi yerel olarak test edin ve Temsilci Motoru'na dağıtın.
Aracı, Google Workspace dokümanına (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'de, örnek kodda Python ve Apps Komut Dosyası kullanılı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

Proje oluşturma

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Faturalandırmanın projede etkin olup olmadığını kontrol etmeyi öğrenin .

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ından Cloud Shell'i etkinleştir'i tıklayın.

Cloud Shell'i etkinleştir düğmesi resmi

Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulanıp doğrulanmadığını ve projenin proje kimliğinize ayarlanıp ayarlanmadığını kontrol edin:

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

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ürecinde 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, temsilcimiz 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 Doküman 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 iskelet oluşturmak üzere adk kullanacağız.

adk create docfactcheckeragent

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

Kök temsilci 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 kodla ilgili önemli noktalar şunlardır:

Yapay zeka temsilcisini adını, modelini, açıklamasını ve çok ayrıntılı bir talimat setini vererek tanımlarız.
Talimat seti, temsilcinin 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. Aracı, önceden eğitilmiş verilere güvenmek yerine canlı aramalar yapabilir, sonuçları değerlendirebilir ve güncel alıntılar sağlayabilir.

Bu sistemin etkin olmasını sağlayan da budur. Model yalnızca yanıt oluşturmaz, bilgileri doğrulamak için işlem (araçları kullanarak) yapar.

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

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 ne yapabileceğini anlamak. Bu, temsilcinin description ve instruction text özetleme yeteneğini test eder.

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

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ı Vertex AI Agent Engine'de dağıtmadan önce iş akışını doğrulamaya yardımcı olur. Vertex AI Agent Engine'de aracı, Dokümanlar veya E-Tablolar gibi Google Workspace araçlarına bağlayabilirsiniz.

Özetle, Google'ın Agent Development Kit'ini (ADK) kullanarak güçlü bir Yapay Zeka Denetçisi Aracı oluşturduk. Ajanımız metinleri okuyabiliyor, gerçeklere dayalı iddiaları belirleyebiliyor, güvenilir kaynakları (google_search aracını kullanarak) arayabiliyor ve net bir karar verebiliyordu.

Her şeyi ADK web arayüzü üzerinden yerel olarak oluşturup test ettik ve aracının şu gibi bir ifadeyi 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 de bir sonraki büyük adımı atma, yani yerelden buluta geçme zamanı. Şimdi bu işlemi yapalım.

4. Aracı Vertex AI Agent Engine'e 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: 18 Ekim 2025'teki ADK araç yapılandırması güncellemesi gibi düzeltmelerle birlikte yerleşik izleme ve otomatik ölçeklendirme.
Entegrasyona Hazır: Sorunsuz Workspace görüşmeleri için bir API uç noktası kullanıma sunun.

Neden Vertex AI Agent Engine?

Vertex AI Agent Engine'i, dağıtılan ADK aracılarınızın bulunduğu yer olarak düşünebilirsiniz. Bu, 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 API uç noktalarının güvenliğini sağlama
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 yazıp Agent Engine ile ölçeklendirirsiniz.

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

Vertex AI Agent Engine aracısını dağıtmadan önce yapmamız gereken birkaç şey var. Dağıtım sürecinde, aracı yapıtları için bir Google Cloud Storage paketi oluşturulması gerekir. Ayrıca, aracı kodunu çalıştırmak için gereken tüm bağımlılıkların Aracı Motoru çalışma zamanı ortamında kullanılabilmesi için bir requirements.txt dosyası sağlamamız gerekir.

Cloud Shell terminalinizde, bir paket oluşturmak için aşağıdaki komutu verin (YOUR_BUCKET_NAME, YOUR_PROJECT_ID ve YOUR_PROJECT_REGION değerlerini projenize özel gerçek değerlerle değiştirmeyi unutmayın):

gcloud storage buckets create gs://YOUR_BUCKET_NAME \
                              --project=YOUR_PROJECT_ID \
                              --location=YOUR_PROJECT_REGION

Ardından, kök klasörde (workspace-agents) aşağıdaki requirements.txt dosyasını oluşturun. Dosyanın içeriği aşağıda gösterilmiştir:

google-cloud-aiplatform
google-adk
requests

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

Bir sonraki adım, adk deploy komutunu kullanarak temsilcinizi Vertex AI Agent Engine'e dağıtmaktır.

adk deploy agent_engine \
    --project=YOUR_PROJECT_ID \
    --region=YOUR_PROJECT_REGION \
    --display_name "Doc Fact Checker" \
    --staging_bucket gs://YOUR_BUCKET_NAME \
    --requirements_file requirements.txt \
    docfactcheckeragent/

Bu işlem, aracımızı Agent Engine'e dağıtma sürecini başlatır. Bu işlem zaman alır ve yaklaşık 5 dakika sürebilir. Genel olarak şu işlemler gerçekleşir:

Temsilci oluşturma işlemi başlar. ADK KSA, kodunuzu paketler, Cloud Storage paketinize yükler ve Vertex AI'ı tetikleyerek yeni bir Agent Engine örneği oluşturur.
Projenizin Cloud Logs Gezgini'ni görüntüleyebileceğiniz bir Günlükler bağlantısı sağlanır. Kurulum adımları, bağımlılık yükleme ve model başlatma dahil olmak üzere ayrıntılı ilerleme durumunu görüntülemek için bu düğmeyi tıklayın. Bir sorun oluşursa (ör. eksik bağımlılık veya izin sorunu) hata mesajını burada görürsünüz.
Tamamlama mesajı: Dağıtım tamamlandığında terminalde, Reasoning Engine kimliğinizin yer aldığı bir onay mesajı gösterilir. Aşağıda bir örneği gösterilmektedir:

AgentEngine created. Resource name: projects/SOME_ID/locations/REGION/reasoningEngines/SOME_ID

3. adım : Cloud Console'da aracıyı doğrulayın (aracı motoru)

Dağıtım tamamlandıktan sonra Google Cloud konsolunuzun Vertex AI → Agent Engine 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. Aracınız artık Vertex AI'da 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. Aracınız artık Vertex AI Agent Engine'de 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:

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.
REST API'yi (cURL) kullanma: İstekleri manuel olarak göndermek ve yanıtları incelemek isteyen geliştiriciler için idealdir.
Python için Vertex AI SDK'sı: Testi geliştirme iş akışınıza entegre etmek için daha programatik bir seçenek.

Her yaklaşım, temsilciniz dağıtıldıktan sonra nasıl davrandığı (ör. sorguları işleyip işlemediği, oturumları yönetip yönetmediği veya yanıt döndürüp döndürmediği) hakkında bilgi verir. Her yöntemle ilgili ayrıntılı adımları, örnekleri ve gelişmiş yapılandırmaları incelemek için resmi belgelere buradan göz atın.

Yapay Zeka Denetçiniz artık Vertex AI Agent Engine'e dağıtılan, bulut destekli bir temsilci ve google_search ile büyük ö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}] }

Bu durumu doğrudan bir sonraki bölümde test edeceğiz. Burada, 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ğitimde kullandığımız Google Dokümanı aşağıdaki içerikleri barındırıyor (bu dokümanı veya doğruluğunu kontrol etmeyi planladığınız kendi içeriğinizi 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:

AIVertex.gs – Vertex AI ve ADK aracısıyla tüm iletişimi yönetir.
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. Önceden oluşturulmuş bir Code.gs dosyası bulacaksınız. 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, bu dosyayı 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

Aracı çağırma işlevini bir Google Dokümanı'na entegre ettiğinizde, Google Dokümanı'na bir kimlik sağlamamız gerekir. Bu kimlik, Agent Engine'de dağıtılan Aracı'yı çağırmak için doğru role sahip olmalıdır. 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:

Google Cloud Console'da IAM ve Yönetici > Hizmet Hesapları'na gidin.
Yeni oluşturduğunuz hizmet hesabını tıklayın.
Anahtarlar sekmesine gidin.
Anahtar Ekle → Yeni Anahtar Oluştur'u tıklayın.
JSON'u seçin ve Oluştur'u tıklayın.
Otomatik olarak bir JSON dosyası indirilir. Bu dosyayı güvenli bir yerde saklamanız gerekir. İçeriğini bir sonraki bölümdeki 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:

LOCATION: Vertex AI dağıtımınızın bölgesi. Ör. us-central1
GEMINI_MODEL_ID: Kullanılacak Gemini modeli. Şu değeri kullanın: gemini-2.5-flash
REASONING_ENGINE_ID: Dağıtılan ADK temsilcisi kimliği. Bu, dağıttığınız belirli aracınızın konsolundaki Agent Engine seçeneğinden alınabilir. 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
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:

Services → Libraries uygulamasına gidin
Add a Library simgesini tıklayın.
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:

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

Aracı artık Aracı Motoru'nda dağıtmanız gerekmiyorsa aşağıdaki adımları uygulayarak silebilirsiniz:

Google Cloud Console'da Vertex AI Agent Engine sayfasına gidin.
Dağıtılan aracıların listesinde silmek istediğiniz aracı bulun.
Temsilcinin adının yanındaki üç nokta menüsünü (diğer işlemler) tıklayın.
Açılır menüden Sil'i seçin.
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 aracı odaklı ortak çalışmanın temelini oluşturur.

ADK'nın muhakeme yeteneklerini Gemini'ın üretken modelleriyle birleştirerek Google Dokümanlar'ı etkili bir şekilde yaşayan, düşünen bir asistana dönüştürdük. Bu asistan, metninizi bağlamla birlikte okuyabilir, denetleyebilir ve iyileştirebilir.

Aynı plan, E-Tablolar, Slaytlar, Drive ve Gmail'de de geçerlidir. Şu özellikleri içeren temsilciler 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şturabilir ve e-postaların doğruluğunu kontrol edebilirsiniz.

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, etkili iş akışları oluşturmanın temelleri açıklanmaktadır.