Ta strona została przetłumaczona przez Cloud Translation API.

Przepływy pracy oparte na agentach w Google Workspace: tworzenie agenta Dokumentów Google za pomocą ADK

1. Wprowadzenie

Google Workspace to miejsce pracy. Od tworzenia raportów w Dokumentach po analizowanie danych w Arkuszach i współpracę w Gmailu i Meet.

A teraz wyobraź sobie, że Dokumenty, Arkusze i Gmail to nie tylko narzędzia, ale też współpracownicy.

Dzięki pakietowi Google Agent Development Kit (ADK) i usłudze Agent Engine w Vertex AI to już nie tylko pomysł. Użyjemy tych platform do utworzenia inteligentnego agenta, wdrożenia go na dużą skalę i bezproblemowego zintegrowania go z naszymi narzędziami Google Workspace, co zapoczątkuje nową erę produktywności opartej na agentach.

W tym module wykonasz te czynności:

Opracuj agenta AI Facts Checker za pomocą pakietu ADK.
Wdróż agenta w Agent Engine, w pełni zarządzanym środowisku do uruchamiania agentów na dużą skalę.
Zintegruj tego agenta z Dokumentami Google, aby weryfikować informacje w tekście dokumentu.

Poniżej znajduje się schemat koncepcyjny wyjaśniający działanie końcowego rozwiązania:

Oto końcowy wynik działania agenta weryfikującego w Dokumentach Google. W dokumencie znajdował się tekst oryginalny zawierający kilka stwierdzeń, a agent sprawdził każde z nich. Dane wyjściowe w ramce z czerwonym rogiem to dane wyjściowe agenta.

Co musisz zrobić

Zaprojektuj, zbuduj i wdroż agenta, który będzie weryfikować informacje w Dokumentach Google.

Czego się nauczysz

Tworzenie agenta za pomocą pakietu Agent Development Kit (ADK).
Przetestuj agenta lokalnie i wdroż go w Agent Engine.
Zintegruj agenta z dokumentem Google Workspace (Dokumentem Google).

Czego potrzebujesz

przeglądarki Chrome,
konto Gmail,
Projekt w chmurze z włączonymi płatnościami

Ten przewodnik, przeznaczony dla deweloperów na wszystkich poziomach zaawansowania (w tym dla początkujących), zawiera przykładowy kod w Pythonie i Apps Script. Znajomość tych języków programowania nie jest jednak wymagana, a do zrozumienia przedstawionych koncepcji wystarczy umiejętność czytania kodu na poziomie podstawowym.

2. Zanim zaczniesz

Utwórz projekt

W konsoli Google Cloud na stronie selektora projektów wybierz lub utwórz projekt Google Cloud.
Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności .

Będziesz używać Cloud Shell, czyli środowiska wiersza poleceń działającego w Google Cloud, które jest wstępnie załadowane narzędziem bq. U góry konsoli Google Cloud kliknij Aktywuj Cloud Shell.

Obraz przycisku Aktywuj Cloud Shell

Po połączeniu z Cloud Shell sprawdź, czy jesteś już uwierzytelniony i czy projekt jest ustawiony na Twój identyfikator projektu, używając tego polecenia:

gcloud auth list

Aby potwierdzić, że polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:

gcloud config list project

Jeśli projekt nie jest ustawiony, użyj tego polecenia, aby go ustawić:

gcloud config set project <YOUR_PROJECT_ID>

Włącz wymagane interfejsy API za pomocą polecenia pokazanego poniżej. Może to potrwać kilka minut, więc zachowaj cierpliwość.

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

Po pomyślnym wykonaniu polecenia powinien wyświetlić się komunikat podobny do tego poniżej:

Operation "operations/..." finished successfully.

Jeśli pominiesz jakiś interfejs API, możesz go włączyć w trakcie wdrażania.

Informacje o poleceniach gcloud i ich użyciu znajdziesz w dokumentacji.

3. Tworzenie agenta ADK

Utwórzmy agenta ADK (Document Fact Checker Agent), czyli opartego na AI audytora, który weryfikuje tekst. Inspiracją jest przykładowa funkcja niestandardowa Google do weryfikowania informacji. W przeciwieństwie do jednostopniowego podejścia w przykładzie nasz agent używa wieloetapowego rozumowania, aby wyodrębniać twierdzenia, weryfikować je za pomocą google_search i generować uporządkowany kod JSON.

Krok 1. Zainstaluj pakiet Agent Development Kit

Otwórz nową kartę terminala w Cloud Shell i utwórz folder o nazwie my-agents w ten sposób: Przejdź też do folderu my-agents.

mkdir workspace-agents
cd workspace-agents

Teraz utwórzmy wirtualne środowisko Pythona za pomocą narzędzia venv:

python -m venv .venv

Aktywuj środowisko wirtualne w ten sposób:

source .venv/bin/activate

Zainstaluj ADK w ten sposób:

pip install google-adk

Narzędzie adk możesz teraz wywołać w ten sposób.

adk

Wyświetli się lista poleceń.

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

Krok 2. Opracuj agenta weryfikującego fakty w dokumentach za pomocą ADK

Teraz użyjemy adk, aby utworzyć szkielet agenta za pomocą polecenia adk create z nazwą aplikacji **(docfactcheckeragent)**jak poniżej.

adk create docfactcheckeragent

Wykonaj te czynności i wybierz:

Model Gemini do wyboru modelu dla agenta głównego.
Wybierz Vertex AI jako backend.
Wyświetli się domyślny identyfikator projektu Google i region. Wybierz domyślne ustawienie.

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

Sprawdź folder, w którym utworzono szablon domyślny i wymagane pliki dla agenta.

Pierwszy to plik .env. Ich zawartość jest widoczna poniżej:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

Wartości te wskazują, że będziemy korzystać z Gemini w Vertex AI wraz z odpowiednimi wartościami identyfikatora projektu Google Cloud i lokalizacji.

Następnie mamy plik __init__.py, który oznacza folder jako moduł i zawiera jedno stwierdzenie importujące agenta z pliku agent.py.

from . import agent

Ostatni jest plik agent.py. Zawartość tego pliku agent.py musisz zastąpić kodem podanym poniżej:

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
)

Najważniejsze informacje o powyższym kodzie źródłowym:

Definiujemy agenta AI, nadając mu nazwę, a następnie podając model, opis i bardzo szczegółowy zestaw instrukcji.
Zestaw instrukcji to najważniejsza część, która określa, jak dokładnie agent powinien myśleć i działać. Ta struktura odzwierciedla sposób pracy profesjonalnych weryfikatorów faktów, dzięki czemu AI staje się autonomicznym potokiem audytowym.
Po złożeniu deklaracji agenta przejdziemy do przyznania mu dostępu do informacji ze świata rzeczywistego za pomocą Google Search tool. Zamiast korzystać z wcześniej wytrenowanych danych, agent może przeprowadzać wyszukiwania na żywo, oceniać wyniki i podawać aktualne cytaty.

Dzięki temu system jest autonomiczny – model nie tylko generuje odpowiedzi, ale też podejmuje działania (za pomocą narzędzi), aby weryfikować informacje.

Krok 3. Przetestuj agenta lokalnie

W otwartym oknie terminala wpisz to polecenie. Upewnij się, że jesteś w folderze nadrzędnym (workspace-agents) zawierającym folder docfactcheckeragent.

adk web

Przykładowe wykonanie jest pokazane poniżej:

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)

Kliknij ostatni link. Powinna się otworzyć konsola internetowa, w której możesz przetestować agenta. Pierwsza interakcja jest kluczowa: musimy zrozumieć, co agent może zrobić. Sprawdzamy w ten sposób jego umiejętność podsumowania description i instruction text.

Agent podaje zwięzłe podsumowanie swoich możliwości, korzystając z opisu i zestawu instrukcji.

Następnie przekazujemy mu 2 oświadczenia (The sky is blue due to Rayleigh scattering. The Earth is flat.), a on sprawdza ich zawartość i zwraca dobrze sformatowaną odpowiedź w formacie JSON.

Dla zaawansowanych:

Narzędzie google_search pobiera z internetu odpowiednie strony.
Model Gemini 2.5 Flash analizuje te fragmenty i określa ich wiarygodność.
ADK zarządza orkiestracją wnioskowania i zapewnia, że logika jest stosowana krok po kroku.

Ta lokalna faza testów pomaga zweryfikować przepływ pracy agenta, zanim wdrożysz go w Vertex AI Agent Engine, gdzie można go połączyć z narzędziami Google Workspace, takimi jak Dokumenty czy Arkusze.

Podsumowując, stworzyliśmy zaawansowanego agenta AI Auditor Agent za pomocą zestawu Agent Development Kit (ADK) od Google. Nasz agent potrafił czytać tekst, identyfikować twierdzenia oparte na faktach, wyszukiwać wiarygodne źródła (za pomocą narzędzia google_search) i wydawać jasne werdykty.

Wszystko zbudowaliśmy i przetestowaliśmy lokalnie za pomocą interfejsu internetowego ADK. Sprawdziliśmy, jak agent analizuje takie stwierdzenie:

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

Agent zweryfikował jedno roszczenie jako true, a drugie jako false. To niewielki, ale trafny dowód na to, że nasza lokalna konfiguracja działa bez zarzutu.

Nadszedł czas na kolejny ważny krok – przejście z lokalnego środowiska na chmurę. Zróbmy to teraz.

4. Wdrażanie agenta w Vertex AI Agent Engine

Prawdziwy agent to nie tylko coś, co możesz przetestować na laptopie. Możesz go uruchamiać na dużą skalę, integrować z innymi systemami i wdrażać w aplikacjach na potrzeby produkcji.

Dlaczego warto wdrożyć aplikację?

Oto kilka powodów, dla których warto wdrożyć agentów w chmurze.

Skalowalność: obsługa dużej liczby żądań bez lokalnych limitów czasu działania.
Niezawodność: wbudowane monitorowanie i autoskalowanie z poprawkami, takimi jak aktualizacja konfiguracji narzędzia ADK z 18 października 2025 r.
Gotowość do integracji: udostępnij punkt końcowy interfejsu API, aby umożliwić płynne połączenia w Workspace.

Dlaczego warto korzystać z Vertex AI Agent Engine?

Vertex AI Agent Engine to miejsce, w którym możesz wdrażać agentów ADK. Jest to zarządzane środowisko stworzone z myślą o niezawodności, skalowalności i integracji.

Dzięki temu agent:

Trwały stan i pamięć
Wykonanie zintegrowanego narzędzia (np. Google Search, modele Vertex AI)
Zabezpieczanie punktów końcowych interfejsu API dla wywołań zewnętrznych
Logowanie i obserwacja za pomocą Cloud Logging
Natywna obsługa orkiestracji wielu agentów

Krótko mówiąc, piszesz raz za pomocą ADK, a potem skalujesz za pomocą Agent Engine.

Krok 1. Przygotowanie do wdrożenia

Zanim wdrożymy agenta Vertex AI Agent Engine, musimy wykonać kilka czynności. Proces wdrażania wymaga utworzenia zasobnika Google Cloud Storage na potrzeby artefaktów agenta. Musimy też podać plik requirements.txt, aby wszystkie zależności wymagane do uruchomienia kodu agenta były dostępne w środowisku wykonawczym Agent Engine.

W terminalu Cloud Shell wpisz to polecenie, aby utworzyć zasobnik (pamiętaj, aby zastąpić YOUR_BUCKET_NAME, YOUR_PROJECT_ID i YOUR_PROJECT_REGION rzeczywistymi wartościami, które są specyficzne dla Twojego projektu):

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

Następnie utwórz w folderze głównym (workspace-agents) plik requirements.txt o podanej niżej zawartości:

google-cloud-aiplatform
google-adk
requests

Krok 2. Wdróż agenta

Następnym krokiem jest wdrożenie agenta w Vertex AI Agent Engine za pomocą polecenia adk deploy.

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/

Powinno to rozpocząć proces wdrażania agenta w Agent Engine. Ten proces jest czasochłonny i może potrwać około 5 minut. Ogólnie rzecz biorąc, przebiega to w ten sposób:

Rozpoczyna się tworzenie agenta – interfejs ADK CLI pakuje kod, przesyła go do zasobnika Cloud Storage i wywołuje Vertex AI, aby utworzyć nową instancję Agent Engine.
Otrzymasz link do logów, w którym możesz wyświetlić eksplorator logów Cloud dla swojego projektu. Kliknij go, aby wyświetlić szczegółowy postęp, w tym kroki konfiguracji, instalację zależności i inicjowanie modelu. Jeśli coś pójdzie nie tak (np. brak zależności lub problem z uprawnieniami), pojawi się tu komunikat o błędzie.
Komunikat o zakończeniu – po zakończeniu wdrażania w terminalu pojawi się komunikat z potwierdzeniem i identyfikatorem silnika wnioskowania. Przykładowy kod jest widoczny poniżej:

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

Krok 3. Zweryfikuj agenta w Cloud Console (Agent Engine)

Po zakończeniu wdrażania otwórz sekcję Vertex AI → Agent Engine w konsoli Google Cloud. W konsoli powinien być widoczny wdrożony agent, jak pokazano poniżej:

🎉 To wszystko! Twój agent jest już dostępny w Vertex AI i możesz go zintegrować z Google Workspace lub przetestować bezpośrednio.

Krok 4. Testowanie agenta wdrażania

Gratulacje – Twój agent jest już aktywny w Vertex AI Agent Engine. Następnym krokiem jest sprawdzenie, czy jest prawidłowo wdrożony i odpowiada na żądania.

Możesz to zrobić na kilka sposobów, w zależności od tego, jak wolisz pracować:

W konsoli Google Cloud: wizualny interfejs do bezpośredniego wyświetlania wdrożonych agentów, zarządzania nimi i ich testowania.
Korzystanie z interfejsu REST API (cURL): idealne rozwiązanie dla deweloperów, którzy chcą ręcznie wysyłać żądania i sprawdzać odpowiedzi.
Za pomocą pakietu SDK Vertex AI dla Pythona: bardziej programistyczna opcja integracji testowania z przepływem pracy dewelopera.

Każde podejście pozwala sprawdzić, jak agent zachowuje się po wdrożeniu, czyli czy przetwarza zapytania, obsługuje sesje czy zwraca odpowiedzi. Szczegółowe instrukcje, przykłady i zaawansowane konfiguracje każdej metody znajdziesz w oficjalnej dokumentacji tutaj.

Twój audytor AI jest teraz agentem opartym na chmurze, wdrożonym w Vertex AI Agent Engine, gotowym do sprawdzania faktów na dużą skalę za pomocą wyszukiwarki Google. Przekształca się w niezawodnego cyfrowego współpracownika opartego na interfejsie API, który generuje kod JSON, np.:

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

W następnej sekcji przetestujemy to bezpośrednio, integrując agenta w Dokumentach Google i sprawdzając fakty podane w dokumencie.

5. Integracja agenta weryfikującego fakty z Dokumentami Google

W tej sekcji połączymy wszystkie elementy, aby wdrożony agent był dostępny w Dokumentach Google. Za pomocą kilku wierszy kodu Apps Script przekształcisz standardowy dokument Google w edytor wspomagany przez AI, który może automatycznie analizować i sprawdzać fakty w treści za pomocą wdrożonego agenta.

Krok 1. Skonfiguruj środowisko Dokumentów Google

Zacznij od otwarcia nowego lub istniejącego dokumentu Google (docs.new).

Dokument Google, którego używamy w tym samouczku, zawiera te treści (możesz użyć ich lub własnych treści, które chcesz zweryfikować):

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.

Krok 2. Skonfiguruj projekt i pliki Apps Script

W projekcie Apps Script musisz mieć 2 pliki:

AIVertex.gs – obsługuje całą komunikację z Vertex AI i agentem ADK.
Code.gs – steruje interfejsem, menu i działaniami w Dokumentach Google.

W menu kliknij Extensions -> Apps Script, aby otworzyć edytor. Użyjemy tego miejsca do połączenia z wdrożonym agentem ADK. Znajdziesz tam utworzony już plik Code.gs, którego zawartość musisz zastąpić kodem Code.gs podanym w następnej sekcji.

Przyjrzyjmy się każdemu z nich.

AIVertex.gs

Utwórz nowy plik, klikając znak + obok sekcji Pliki po lewej stronie, wybierz go jako Script i skopiuj do niego poniższą zawartość.

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(),
  }
}

Pamiętaj, aby zapisać plik.

Ten plik wykonuje te czynności:

Bezpieczne uwierzytelnianie w Vertex AI za pomocą klucza konta usługi. Wywołuje wdrożonego agenta ADK, aby przeanalizować tekst dokumentu lub sprawdzić go pod kątem faktów.
Korzysta z Gemini do inteligentnego formatowania odpowiedzi , dzięki czemu wyniki są czytelne dla człowieka.

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;
}

Ten plik łączy interfejs Dokumentów z logiką ADK opisaną powyżej. Umożliwia to uruchomienie audytu bezpośrednio z niestandardowego menu Dokumentów. Ogólnie rzecz biorąc, wykonuje te czynności:

Dodaje w Dokumentach Google niestandardowe menu o nazwie Narzędzia do audytu AI.
Pobiera tekst dokumentu i wysyła go do agenta ADK w celu analizy.
Wyświetla w dokumencie wyniki kontroli wygenerowane przez AI.

Krok 3. Utwórz konto usługi

Gdy zintegrujesz funkcję połączeń z agentem z dokumentem Google, musimy przypisać do tego dokumentu tożsamość, aby miał odpowiednią rolę do wywoływania agenta wdrożonego w Agent Engine. W tym celu użyjemy konta usługi z odpowiednią rolą: roles/aiplatform.user.

W Cloud Shell uruchom krok po kroku ten skrypt:

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"

Spowoduje to utworzenie konta usługi z odpowiednimi uprawnieniami.

Wygenerujemy klucz JSON konta usługi. Będzie on używany przez Twój projekt Apps Script do uwierzytelniania. Aby uzyskać klucz:

W konsoli Google Cloud kliknij Administracja > Konta usługi.
Kliknij konkretne konto usługi, które właśnie zostało utworzone.
Otwórz kartę Klucze.
Kliknij Dodaj klucz → Utwórz nowy klucz.
Wybierz JSON, a następnie kliknij Utwórz.
Plik JSON zostanie pobrany automatycznie. Zachowaj go w bezpiecznym miejscu. W następnej sekcji wkleisz jego zawartość do właściwości skryptu.

Krok 4. Dodaj właściwości skryptu

Wróć do edytora Apps Script w Dokumencie Google.

Aby połączyć skrypt z wdrożonymi zasobami, kliknij Project Settings → Script Properties → Add Script Property.

Dodaj do właściwości skryptu te informacje:

LOCATION: region wdrożenia Vertex AI. np. us-central1
GEMINI_MODEL_ID: model Gemini do użycia. Użyj wartości: gemini-2.5-flash
REASONING_ENGINE_ID: identyfikator wdrożonego agenta ADK. Możesz go uzyskać z opcji Agent Engine w konsoli w przypadku konkretnego wdrożonego agenta. Zobaczysz nazwę zasobu wdrożonego agenta. Identyfikator agenta to ostatnia wartość liczbowa w nazwie zasobu (czyli RESOURCE_ID). Na przykład projects/SOME_ID/locations/REGION/reasoningEngines/RESOURCE_ID
SERVICE_ACCOUNT_KEY: skopiuj całą zawartość klucza JSON pobranego dla konta usługi utworzonego w poprzednim kroku.

Kliknij Zapisz właściwości skryptu.

Krok 5. Dodaj bibliotekę OAuth2

Nasz projekt Apps Script wymaga biblioteki OAuth2 do uwierzytelniania wywołań interfejsu API.

Aby ją dodać:

Przejdź do: Services → Libraries
Kliknij Add a Library
Wpisz identyfikator skryptu: 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

Krok 6. Przetestuj agenta Dokumentów Google do sprawdzania faktów

Jesteśmy na ostatnim etapie testowania agenta w Dokumentach Google. Aby to zrobić:

W edytorze Apps Script uruchom funkcję onOpen(). Spowoduje to dodanie nowego menu Narzędzia do kontroli AI w Dokumentach Google.
Wróć do dokumentu. W menu głównym zobaczysz dodatkowy element menu o nazwie AI Audit Tools. Kliknij ten element, a potem Run AI Audit.

Oto przykładowe wykonanie:

6. Czyszczenie

Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, usuń zasoby utworzone podczas tych warsztatów.

Jeśli nie potrzebujesz już, aby Agent był wdrażany w Agent Engine, możesz go usunąć, wykonując te czynności:

W konsoli Google Cloud otwórz stronę Vertex AI Agent Engine.
Na liście wdrożonych agentów znajdź agenta, którego chcesz usunąć.
Obok nazwy agenta kliknij menu z 3 kropkami (więcej działań).
W menu wybierz Usuń.
Potwierdź usunięcie, klikając Usuń agenta w oknie potwierdzenia.

Zalecamy też usunięcie konta usługi.

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

7. Gratulacje

Agent AI został wdrożony, połączony z Dokumentami Google i przetestowany w praktyce – analizuje, wnioskuje i podsumowuje treści bezpośrednio w miejscu, w którym się znajdują. To, co tu stworzyliśmy, to nie tylko samodzielna wersja demonstracyjna. Jest to podstawa inteligentnej współpracy opartej na agentach w Google Workspace.

Łącząc możliwości rozumowania ADK z modelami generatywnymi Gemini, przekształciliśmy Dokumenty Google w żywego, myślącego asystenta, który potrafi czytać, sprawdzać i ulepszać tekst w kontekście.

Ten sam wzorzec jest naturalnie stosowany w Arkuszach, Prezentacjach, na Dysku i w Gmailu. Wyobraź sobie agentów, którzy:

Sprawdzanie danych finansowych i oznaczanie niespójności w Arkuszach
Automatyczne generowanie prezentacji i podsumowań w Prezentacjach
Inteligentne etykietowanie i porządkowanie dokumentów na Dysku
Możesz też tworzyć i sprawdzać e-maile bezpośrednio w Gmailu.

Ta prezentacja stanowi podstawę do tworzenia przepływów pracy opartych na agentach, które można płynnie zintegrować z codziennymi narzędziami Workspace, przekształcając statyczne dokumenty w dynamicznych współpracowników AI.