Google Workspace 内のエージェント ワークフロー: ADK を使用して Google ドキュメント エージェントを構築する

1. はじめに

Google Workspace は、仕事の拠点です。Google ドキュメントでのレポートの作成から、Google スプレッドシートでのデータの分析、Gmail と Google Meet での共同作業まで、さまざまな用途で活用できます。

Google ドキュメント、Google スプレッドシート、Gmail が単なるツールではなく、共同作業者になったらどうなるでしょうか。

Google の Agent Development Kit（ADK）と Vertex AI の Agent Engine を使用すると、それは単なるアイデアではなくなります。これらのフレームワークを使用してインテリジェント エージェントを構築し、エージェントを大規模にデプロイして、Google Workspace ツールにシームレスに統合することで、エージェントによる生産性の新しい時代が実現します。

この Codelab では、次の手順で進めます。

1. Agent Development Kit を使用して AI ファクト チェック エージェントを開発します。
2. エージェントを Agent Engine にデプロイします。Agent Engine は、エージェントを大規模に実行するためのフルマネージド環境です。
3. このエージェントを Google ドキュメントに統合して、ドキュメント内のテキストのファクト チェックを行います。

最終的なソリューションの仕組みを示す概念図を以下に示します。

Google ドキュメント内でファクト チェック エージェントがどのように機能するかの最終的な出力は次のとおりです。元のテキストにはいくつかのステートメントが含まれており、ドキュメント内の各ステートメントのファクト チェックが行われます。赤い角の付いたボックス内の出力は、エージェントからの出力です。

演習内容

• Google ドキュメント内でファクト チェックを行うエージェントを設計、構築、デプロイします。

学習内容

• Agent Development Kit（AK）を使用してエージェントを開発します。
• エージェントをローカルでテストし、Agent Engine にデプロイします。
• エージェントを Google Workspace ドキュメント（Google ドキュメント）に統合します。

必要なもの

• Chrome ウェブブラウザ
• Gmail アカウント
• 課金が有効になっている Cloud プロジェクト

この Codelab は、初心者を含むあらゆるレベルのデベロッパーを対象としており、サンプルコードでは Python と Apps Script を使用しています。ただし、これらのプログラミング言語の知識は前提条件ではなく、提示されたコンセプトを理解するには基本的なコードの読み取り能力で十分です。

2. 始める前に

Google Cloud クレジットの場合: こちらの リンクから無料の Google Cloud クレジットを引き換えて、ご利用ください。こちらの手順に沿って、クレジットを有効にして新しいプロジェクトを作成できます。

プロジェクトを作成する

1. Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
2. Cloud プロジェクトに対して課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
3. Cloud Shell（Google Cloud で動作するコマンドライン環境）を使用します。この環境には bq がプリロードされています。Google Cloud コンソールの上部にある「Cloud Shell をアクティブにする」アイコン をクリックします。

4. Cloud Shell に接続したら、次のコマンドを使用して、すでに認証済みであることと、プロジェクトがプロジェクト ID に設定されていることを確認します。

gcloud auth list

5. Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。

gcloud config list project

6. プロジェクトが設定されていない場合は、次のコマンドを使用して設定します。

gcloud config set project <YOUR_PROJECT_ID>

7. 次のコマンドを使用して、必要な API を有効にします。これには数分かかることがあります。

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

コマンドが正常に実行されると、次のようなメッセージが表示されます。

Operation "operations/..." finished successfully.

API が見つからない場合は、実装中にいつでも有効にできます。

gcloud コマンドとその使用方法については、ドキュメントをご覧ください。

3. ADK エージェントを構築する

Google のファクト チェック カスタム関数 サンプルを参考に、テキストのファクト チェックを行う AI ベースの監査ツールである ADK エージェント（Document Fact Checker Agent）を作成しましょう。サンプルの 1 ステップのアプローチとは異なり、このエージェントはマルチステップの推論を使用して主張を抽出し、google_search で検証して、構造化された JSON を出力します。

ステップ 1 : Agent Development Kit をインストールする

Cloud Shell で新しいターミナルタブを開き、次のように my-agents という名前のフォルダを作成します。my-agents フォルダにも移動します。

mkdir workspace-agents
cd workspace-agents

次に、venv を使用して、次のように仮想 Python 環境を作成します。

python -m venv .venv

次のように仮想環境を有効にします。

source .venv/bin/activate

次のように ADK をインストールします。

pip install google-adk

これで、次のように adk ユーティリティを呼び出すことができます。

adk

コマンドのリストが表示されます。

$ 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 : ADK を使用してドキュメント ファクト チェック エージェントを開発する

次に、adk を使用して、アプリ名 **(docfactcheckeragent)**の adk create コマンドでエージェントのスキャフォールディングを作成します。

adk create docfactcheckeragent

手順に沿って、以下を選択します。

• ルート エージェントのモデルを選択するための Gemini モデル。
• バックエンドに Vertex AI を選択します。
• デフォルトの Google プロジェクト ID とリージョンが表示されます。デフォルト自体を選択します。

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

エージェントのデフォルト テンプレートと必要なファイルが作成されたフォルダを確認します。

最初は .env ファイルです。内容は次のとおりです。

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

これらの値は、Google Cloud プロジェクト ID とロケーションのそれぞれの値とともに Vertex AI 経由で Gemini を使用することを示しています。

次に、__init__.py ファイルがあります。このファイルはフォルダをモジュールとしてマークし、agent.py ファイルからエージェントをインポートする単一のステートメントを含んでいます。

from . import agent

最後に、agent.py ファイルがあります。この agent.py ファイルの内容を次のコードに置き換える必要があります。

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
)

上記のソースコードの重要なポイントは次のとおりです。

• AI エージェントを定義するには、名前、モデル、説明、非常に詳細な命令セットを指定します。
• 命令セットは、エージェントがどのように考え、動作するかを正確に定義する最も重要な部分です。この構造は、プロのファクト チェック担当者の作業方法を反映しており、AI を自律的な監査パイプラインに変えます。
• このエージェントの宣言が完了したら、Google Search tool を介してエージェントに現実世界の情報へのアクセス権を付与します。エージェントは、事前トレーニング済みのデータに依存するのではなく、ライブ検索を実行し、結果を評価して、最新の引用を提供できます。

これが、このシステムをエージェント化する理由です。モデルは回答を生成するだけでなく、ツールを使用して情報を検証するアクションを実行します。

ステップ 3 : エージェントをローカルでテストする

既存のターミナル ウィンドウから次のコマンドを実行します。docfactcheckeragent フォルダを含む親フォルダ (workspace-agents) にいることを確認します。

adk web

実行例を以下に示します。

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)

最後のリンクをクリックすると、エージェントをテストするためのウェブ コンソールが表示されます。最初のアクションは、エージェントが実際に何ができるかを理解することです。これにより、エージェントが description と instruction text を要約する能力をテストできます。

エージェントは、説明と命令セットから、その能力の簡潔な要約を提供します。

次に、2 つのステートメント（The sky is blue due to Rayleigh scattering. The Earth is flat. ）を提供すると、コンテンツが正常に監査され、構造化された JSON レスポンスが返されます。

仕組み:

• google_search ツールは、ウェブから関連するページを取得します。
• Gemini 2.5 Flash モデルは、これらのスニペットを解析して真実性を分類します。
• ADK は推論のオーケストレーションを処理し、ステップバイステップのロジックが確実に実行されるようにします。

このローカル テスト フェーズは、Vertex AI Agent Engine にデプロイする前にエージェントのワークフローを検証するのに役立ちます。Vertex AI Agent Engine では、Google ドキュメントや Google スプレッドシートなどの Google Workspace ツールに接続できます。

まとめると、Google の Agent Development Kit（ADK）を使用して強力な AI 監査エージェントを構築しました。このエージェントは、テキストの読み取り、事実の主張の特定、信頼できるソースの検索（google_search ツールを使用）、明確な判定の返信を行うことができます。

ADK ウェブ インターフェースを使用してすべてをローカルで構築してテストし、エージェントが次のようなステートメントを分析する方法を確認しました。

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

エージェントは 1 つの主張を true と検証し、もう 1 つを false とフラグ設定しました。これは、ローカル設定が完全に機能していることを示す小さな証拠です。

次は、ローカルからクラウドに移行するという大きなステップに進みます。次に進みましょう

4. エージェントを Vertex AI Agent Engine にデプロイする

実際のエージェントは、ノートパソコンでテストするだけでなく、大規模に実行し、他のシステムと統合して、アプリ全体で本番環境にデプロイできます。

デプロイする理由

エージェントをクラウドにデプロイする理由は次のとおりです。

• スケーラビリティ: ローカル ランタイムの制限なしに大量のリクエストを処理できます。
• 信頼性: 組み込みのモニタリングと自動スケーリング。2025 年 10 月 18 日の ADK ツール構成の更新などの修正。
• 統合の準備: シームレスな Workspace 呼び出し用の API エンドポイントを公開します。

Vertex AI Agent Engine を選ぶ理由

Vertex AI Agent Engine は、デプロイされた ADK エージェントのホームと考えることができます。信頼性、スケーラビリティ、統合のために構築されたマネージド環境です。

エージェントには次の機能が提供されます。

• 永続的な状態とメモリ
• 統合されたツール実行（Google 検索、Vertex AI モデルなど）
• 外部呼び出し用の安全な API エンドポイント
• Cloud Logging によるロギングとオブザーバビリティ
• マルチ エージェントのオーケストレーションのネイティブ サポート

つまり、ADK で一度記述したら、Agent Engine を使用してスケールアップできます。

ステップ 1 : デプロイの準備

エージェントを Vertex AI Agent Engine にデプロイする前に、いくつかの作業を行う必要があります。デプロイ プロセスでは、エージェント アーティファクト用の Google Cloud Storage バケット を作成する必要があります。また、エージェント コードの実行に必要なすべての依存関係が Agent Engine ランタイム環境で使用できるように、requirements.txt ファイルも用意する必要があります。

Cloud Shell ターミナルで次のコマンドを実行してバケットを作成します（YOUR_BUCKET_NAME、YOUR_PROJECT_ID、YOUR_PROJECT_REGION は、プロジェクトに固有の実際の値に置き換えてください）。

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

次に、ルートフォルダ（workspace-agents ）に次の requirements.txt ファイルを作成します。内容は次のとおりです。

google-cloud-aiplatform
google-adk
requests

ステップ 2 : エージェントをデプロイする

次のステップでは、adk deploy コマンドを使用して、エージェントを Vertex AI Agent Engine にデプロイします。

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/

これにより、エージェントを Agent Engine にデプロイするプロセスが開始されます。このプロセスには時間がかかり、約 5 分かかります。大まかな流れは次のとおりです。

1. エージェントの作成が開始されます。ADK CLI はコードをパッケージ化し、Cloud Storage バケットにアップロードして、Vertex AI をトリガーして新しい Agent Engine インスタンスを作成します。
2. ログリンクが表示されます。このリンクをクリックすると、プロジェクトの Cloud Logs エクスプローラが表示されます。クリックすると、設定手順、依存関係のインストール、モデルの初期化など、詳細な進行状況が表示されます。依存関係がない、権限の問題など、問題が発生した場合は、ここにエラー メッセージが表示されます。
3. 完了メッセージ - デプロイが完了すると、推論エンジン ID が記載された確認メッセージがターミナルに表示されます。サンプルを以下に示します。

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

ステップ 3 : Cloud コンソール（Agent Engine）でエージェントを確認する

デプロイが完了したら、Google Cloud コンソールの [Vertex AI] → [Agent Engine] セクションに移動します。次のように、デプロイされたエージェントがコンソールに表示されます。

🎉 以上で完了です。エージェントが Vertex AI で公開され、Google Workspace に統合するか、直接テストする準備が整いました。

ステップ 4 : デプロイ エージェントをテストする

おめでとうございます。エージェントが Vertex AI Agent Engine で公開されました。次のステップでは、正しくデプロイされ、リクエストに応答していることをテストします。

作業方法に応じて、いくつかの方法があります。

1. Google Cloud コンソールを使用する: デプロイされたエージェントを直接表示、管理、テストするためのビジュアル インターフェース。
2. REST API（cURL）を使用する: リクエストを手動で送信してレスポンスを検査したいデベロッパーに最適です。
3. Vertex AI SDK for Python を使用する: テストを開発ワークフローに統合するためのよりプログラマティックなオプション。

どのアプローチでも、エージェントがデプロイ後にどのように動作するか（クエリの処理、セッションの処理、レスポンスの返信など）を把握できます。各方法の詳細な手順、例、高度な構成については、こちらの公式ドキュメントをご覧ください。

AI 監査ツールは、Vertex AI Agent Engine にデプロイされたクラウドベースのエージェントになり、google_search を使用して大規模にファクト チェックを行う準備が整いました。信頼性の高い API ドリブン デジタル チームメイトに変わり、次のような JSON を生成します。

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

次のセクションでは、このエージェントを Google ドキュメントに統合し、ドキュメントに記載されている事実を検証します。

5. ファクト チェック エージェントを Google ドキュメントに統合する

このセクションでは、デプロイされたエージェントを Google ドキュメントに統合します。数行の Apps Script を使用すると、標準の Google ドキュメントを、デプロイされたエージェントを使用してコンテンツを自動的に分析してファクト チェックできる AI アシスト エディタに変換できます。

ステップ 1: Google ドキュメント環境を設定する

まず、新しい Google ドキュメント（docs.new）を開くか、既存の Google ドキュメントを開きます。

このチュートリアルで使用する Google ドキュメントには、次の内容が含まれています（ファクト チェックを行う予定のコンテンツを使用することもできます）。

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: Apps Script プロジェクトとファイルを設定する

この設定では、Apps Script プロジェクトに 2 つのファイルが必要です。

1. AIVertex.gs – Vertex AI と ADK エージェントとのすべての通信を処理します。
2. Code.gs – Google ドキュメントのインターフェース、メニュー、ドキュメント アクションを制御します。

メニューから Extensions -> Apps Script に移動して、エディタを開きます。このスペースを使用して、デプロイされた ADK エージェントに接続します。Code.gs ファイルはすでに作成されています。次のセクションで提供されている Code.gs コードで内容を置き換える必要があります。

それぞれ見ていきましょう。

AIVertex.gs

左側の [Files] セクションの横にある + 記号をクリックして新しいファイルを作成し、Script を選択して、次の内容をコピーします。

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

ファイルを保存するのを忘れないようにしてください。

このファイルでは、次の処理を行います。

• サービス アカウント キーを使用して Vertex AI に対して安全に認証します。デプロイされた ADK エージェントを呼び出して、ドキュメント テキストを分析またはファクト チェックします。
• Gemini を使用してスマート レスポンスの書式設定を行い、結果を人間が読めるようにします。

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

このファイルは、Google ドキュメントの UI を上記の ADK ロジックに接続します。カスタムの Google ドキュメント メニューから直接監査をトリガーできます。大まかな流れは次のとおりです。

• Google ドキュメントに [AI Audit Tools] というカスタム メニューを追加します。
• ドキュメント テキストを取得して、分析のために ADK エージェントに送信します。
• AI によって生成された監査結果をドキュメントに表示します。

ステップ 3 : サービス アカウントを作成する

エージェント呼び出し機能を Google ドキュメントに統合する場合は、Google ドキュメントに ID を提供する必要があります。これにより、Agent Engine にデプロイされたエージェントを呼び出すための適切なロールが設定されます。この目的のために、適切なロール roles/aiplatform.user を持つサービス アカウントを使用します。

Cloud Shell で次のスクリプトをステップごとに実行します。

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"

これにより、適切な権限を持つサービス アカウントが作成されます。

サービス アカウントの JSON キーを生成します。これは、Apps Script プロジェクトが認証に使用するものです。キーを取得する手順は次のとおりです。

1. Google Cloud コンソールで、[IAM と管理] > [サービス アカウント] に移動します。
2. 作成したサービス アカウントをクリックします。
3. [鍵] タブに移動します。
4. [鍵を追加] → [新しい鍵を作成] をクリックします。
5. [JSON] を選択し、[作成] をクリックします。
6. JSON ファイルが自動的にダウンロードされます。安全に保管してください。次のセクションで、その内容をスクリプト プロパティに貼り付けます。

ステップ 4 : スクリプト プロパティを追加する

Google ドキュメントの Apps Script エディタに戻ります。

スクリプトをデプロイされたリソースに接続するには、Project Settings → Script Properties → Add Script Property に移動します。

スクリプト プロパティに次のように追加します。

1. LOCATION: Vertex AI デプロイのリージョン。例: us-central1
2. GEMINI_MODEL_ID: 使用する Gemini モデル。値 gemini-2.5-flash を使用します。
3. REASONING_ENGINE_ID: デプロイされた ADK エージェント ID。これは、デプロイした特定のエージェントのコンソールで [Agent Engine] オプションから取得できます。デプロイされたエージェントのリソース名が表示されます。エージェント ID は、リソース名の最後の数値（RESOURCE_ID）です。例: projects/SOME_ID/locations/REGION/reasoningEngines/RESOURCE_ID
4. SERVICE_ACCOUNT_KEY: 前のステップで作成したサービス アカウント用にダウンロードした JSON キーの内容全体をコピーします。

[スクリプト プロパティを保存] をクリックします。

ステップ 5 : OAuth2 ライブラリを追加する

Apps Script プロジェクトには、API 呼び出しを認証するための OAuth2 ライブラリが必要です。

追加する手順は次のとおりです。

1. Services → Libraries に移動します。
2. [Add a Library] をクリックします。
3. スクリプト ID「1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF」を入力します。

ステップ 6 : Google ドキュメントでファクト チェック ドキュメント エージェントをテストする

Google ドキュメント内でエージェントをテストする最後のステップです。手順は次のとおりです。

1. Apps Script エディタで、onOpen() 関数を 1 回実行します。これにより、Google ドキュメントに新しい [AI Audit Tools] メニューが追加されます。
2. ドキュメントに戻ります。メインメニューに [AI Audit Tools] という追加のメニュー項目が表示されます。それをクリックし、[Run AI Audit] をクリックします。

実行例を以下に示します。

6. クリーンアップ

Google Cloud アカウントに継続的に課金されないようにするには、このワークショップで作成したリソースを削除することが重要です。

エージェントを Agent Engine にデプロイする必要がなくなった場合は、次の手順で削除できます。

1. Google Cloud コンソールで Vertex AI Agent Engine ページに移動します。
2. デプロイされたエージェントのリストから、削除するエージェントを見つけます。
3. エージェント名の横にあるその他メニュー（3 つのドット）をクリックします。
4. プルダウン メニューから [削除] を選択します。
5. 確認ダイアログで [エージェントを削除] をクリックして、削除を確定します。

ベスト プラクティスとして、サービス アカウントも削除します。

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

7. 完了

AI エージェントをデプロイし、Google ドキュメントに接続して、コンテンツが存在する場所で分析、推論、要約を行う様子を確認しました。ここで構築したものは、スタンドアロンのデモではありません。これは、Google Workspace 内のインテリジェントなエージェント ドリブン コラボレーションの基盤です。

ADK の推論機能と Gemini の生成モデルを組み合わせることで、Google ドキュメントを、コンテキストに基づいてテキストを読み取り、監査し、推敲できる、生きている思考アシスタントに変えることができました。

同じブループリントは、Google スプレッドシート、スライド、ドライブ、Gmail にも自然に拡張されます。次のようなエージェントを想像してみてください。

• 財務データを監査し、Google スプレッドシートの不整合にフラグを設定する
• Google スライドでピッチデッキと概要を自動生成する
• ドライブ内のドキュメントにインテリジェントにラベルを付けて整理する
• Gmail で直接メールの下書きを作成してファクト チェックする

このデモは、日々の Workspace ツールにシームレスに統合されるエージェント ワークフローを構築するための基盤となり、静的なドキュメントを動的な AI コラボレーターに変えます。

リファレンス ドキュメント

• Agent Development Kit
• エージェント エンジン