Agent2UI エージェントを使用して Google Chat 用アプリを構築する

このページでは、Google Chat で動作し、Agent2UI（A2UI）プロトコルを使用する AI エージェントと連携する Google Workspace アドオンを構築する方法について説明します。Agent Development Kit（ADK）を使用してエージェントを開発し、Vertex AI Agent Engine でホストします。

AI エージェントは、環境を自律的に認識し、推論し、定義された目標を達成するために複数のステップで構成される複雑なアクションを実行します。このチュートリアルでは、ツールから取得した静的プロファイル情報を返す基本的な AI エージェントをデプロイします。

A2UI を使用すると、AI エージェントはネイティブにレンダリングされる適応型でリッチなインタラクティブ UI を生成できます。これにより、UI ではなく AI エージェントのロジックに集中できます。

図 1: A2UI エージェントは、名前、画像、LinkedIn ボタンを含むテキストとカードでユーザーに応答します。
図 2. A2UI エージェントが更新され、プロファイルタイトルも返されるようになりました。
図 3. A2UI エージェントは、カードにプロフィール名を表示するメッセージでユーザーに応答します。

次の図は、アーキテクチャとメッセージングパターンを示しています。

A2UI AI エージェントで実装された Chat 用アプリのアーキテクチャ。

この図では、A2UI エージェントで実装された Chat 用アプリを操作するユーザーの情報の流れは次のようになります。

ユーザーが、ダイレクトメッセージまたは Chat スペースで Chat 用アプリにメッセージを送信します。
Apps Script または HTTP エンドポイントを備えたウェブサーバーとして実装された Chat 用アプリのロジックが、メッセージを受信して処理します。
Vertex AI Agent Engine でホストされている A2UI エージェントが、インタラクションを受信して処理します。
必要に応じて、Chat 用アプリまたは AI エージェントを Google Workspace サービス（カレンダー、スプレッドシートなど）や、Google サービス（Google マップ、YouTube など）と統合できます。
Chat 用アプリは、Google Chat API を使用して AI エージェントの進行状況を伝達し、適応型レスポンスを非同期で生成して送信します。
回答がユーザーに配信されます。

目標

環境をセットアップする。
A2UI エージェントをデプロイします。
Chat 用アプリをデプロイします。
Chat 用アプリを構成します。
Chat 用アプリをテストします。

前提条件

Google Chat へのアクセス権を持つ Business または Enterprise の Google Workspace アカウント。
課金を有効にした Google Cloud プロジェクト。既存のプロジェクトで課金が有効になっていることを確認するには、プロジェクトの課金ステータスを確認するをご覧ください。プロジェクトを作成して課金管理を設定するには、Google Cloud プロジェクトを作成するをご覧ください。
Python 3.11 以降: インストールについては、公式の Python ウェブサイトの手順に沿って操作してください。
Python Poetry: インストールについては、Poetry の公式ウェブサイトの手順に沿って操作してください。
Google Cloud CLI: インストールについては、Google Cloud の公式ウェブサイトの手順に沿って操作してください。

環境の設定

Google Cloud APIs を有効にする

Google API を使用する前に、Google Cloud プロジェクトで API を有効にする必要があります。1 つの Google Cloud プロジェクトで 1 つ以上の API を有効にできます。

Google Cloud コンソールで、Google Chat、Vertex AI、Cloud Resource Manager の各 API を有効にします。

API を有効にする

OAuth 同意画面を構成する

OAuth 2.0 を使用するすべてのアプリで、同意画面の構成が必要です。アプリの OAuth 同意画面を構成することで、ユーザーとアプリの審査担当者に表示されるものを定義し、後でアプリを公開できるようにアプリを登録します。

Google Cloud コンソールで、メニュー > Google Auth platform > [ブランディング] に移動します。
[ブランディング] に移動
Google Auth platformをすでに構成している場合は、[ブランディング]、[対象]、[データアクセス] で次の OAuth 同意画面の設定を構成できます。[Google Auth platform まだ設定されていません] というメッセージが表示された場合は、[使ってみる] をクリックします。

[アプリ情報] の [アプリ名] に、アプリの名前を入力します。
[ユーザーサポートメール] で、ユーザーが同意について問い合わせる際に使用するサポートのメールアドレスを選択します。
[続行] をクリックします。
[対象] で [内部] を選択します。
[続行] をクリックします。
[連絡先情報] で、プロジェクトに対する変更の通知を受け取るメールアドレスを入力します。
[続行] をクリックします。
[完了] で、Google API サービスのユーザーデータに関するポリシーを確認し、同意する場合は [Google API サービス: ユーザーデータに関するポリシーに同意します] を選択します。
[続行] をクリックします。
[作成] をクリックします。

現時点では、スコープの追加はスキップできます。今後、Google Workspace 組織外で使用するアプリを作成する場合は、[ユーザータイプ] を [外部] に変更する必要があります。次に、アプリに必要な認可スコープを追加します。詳細については、OAuth 同意画面を構成するの完全なガイドをご覧ください。

Google Cloud コンソールでサービスアカウントを作成する

次の手順に沿って、ロール Vertex AI User を持つ新しいサービスアカウントを作成します。

Google Cloud コンソール

Google Cloud コンソールで、メニュー > [IAM と管理] > [サービスアカウント] に移動します。
[サービスアカウント] に移動
[サービスアカウントを作成] をクリックします。
サービスアカウントの詳細を入力し、[作成して続行] をクリックします。
注: デフォルトでは、Google は一意のサービスアカウント ID を作成します。ID を変更する場合は、サービスアカウント ID フィールドで ID を変更します。
省略可: サービスアカウントにロールを割り当て、Google Cloud プロジェクトのリソースへのアクセス権を付与します。詳細については、リソースへのアクセス権の付与、変更、取り消しをご覧ください。
[続行] をクリックします。
省略可: このサービスアカウントで管理とアクションの実行ができるユーザーまたはグループを入力します。詳細については、サービスアカウントの権限借用を管理するをご覧ください。
[完了] をクリックします。サービスアカウントのメールアドレスをメモします。

gcloud CLI

サービスアカウントを作成します。

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"

省略可: サービスアカウントにロールを割り当て、Google Cloud プロジェクトのリソースへのアクセス権を付与します。詳細については、リソースへのアクセス権の付与、変更、取り消しをご覧ください。

サービスアカウントが [サービスアカウント] ページに表示されます。

秘密鍵を作成する

サービスアカウントの秘密鍵を作成してダウンロードする手順は次のとおりです。

Google Cloud コンソールで、メニュー > [IAM と管理] > [サービスアカウント] に移動します。
[サービスアカウント] に移動
サービスアカウントを選択します。
[鍵] > [鍵を追加] > [新しい鍵を作成] をクリックします。
[JSON] を選択し、[作成] をクリックします。
新しい公開鍵と秘密鍵のペアが生成され、新しいファイルとしてパソコンにダウンロードされます。ダウンロードした JSON ファイルを、作業ディレクトリに credentials.json として保存します。このファイルはこの鍵の唯一のコピーです。キーを安全に保存する方法については、サービスアカウントキーの管理をご覧ください。
[閉じる] をクリックします。

サービスアカウントの詳細については、Google Cloud IAM ドキュメントのサービスアカウントをご覧ください。

A2UI エージェントをデプロイする

まだ行っていない場合は、Google Cloud アカウントで認証し、Google Cloud プロジェクトを使用するように Google Cloud CLI を構成します。
```
gcloud auth application-default login
gcloud config set project PROJECT_ID
gcloud auth application-default set-quota-project PROJECT_ID
```
PROJECT_ID は実際の Cloud プロジェクトの ID に置き換えます。
次のボタンを使用して googleworkspace/add-ons-samples GitHub リポジトリをダウンロードします。

リポジトリをダウンロードする
任意のローカル開発環境で、ダウンロードしたアーカイブファイルを抽出し、add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui ディレクトリを開きます。
```
unzip add-ons-samples-main.zip
cd add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui
```
ADK エージェント専用の新しい Cloud Storage バケットを作成します。
```
gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION
```
次のように置き換えます。
1. CLOUD_STORAGE_BUCKET_NAME は、使用する一意のバケット名に置き換えます。
2. PROJECT_ID は実際の Cloud プロジェクトの ID に置き換えます。
3. PROJECT_LOCATION は、Cloud プロジェクトのロケーションに置き換えます。
次の環境変数を設定します。
```
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
```
次のように置き換えます。
1. CLOUD_STORAGE_BUCKET_NAME は、作成したバケットの名前に置き換えます。
2. PROJECT_ID は実際の Cloud プロジェクトの ID に置き換えます。
3. PROJECT_LOCATION は、Cloud プロジェクトのロケーションに置き換えます。

仮想環境から ADK エージェントをインストールしてデプロイします。

python3 -m venv myenv
source myenv/bin/activate
poetry install --with deployment
python3 deployment/deploy.py --create

エージェント ID を取得します。この情報は、後で Chat 用アプリを構成するときに必要になります。
```
python3 deployment/deploy.py --list
```

Chat 用アプリのプロジェクトを作成して構成する

次のボタンをクリックして、A2UI AI エージェントのクイックスタート Apps Script プロジェクトを開きます。

プロジェクトを開く
[概要] > [コピーを作成] をクリックします。
Apps Script プロジェクトで、 [プロジェクトの設定] > [スクリプトのプロパティを編集] > [スクリプトのプロパティを追加] の順にクリックして、次のスクリプトのプロパティを追加します。
1. REASONING_ENGINE_RESOURCE_NAME は、前の手順でコピーした Vertex AI エージェントのリソース名に置き換えます。
2. SERVICE_ACCOUNT_KEY は、前の手順でダウンロードしたサービスアカウントの JSON キー（{ ... } など）に置き換えます。
[スクリプトプロパティを保存] をクリックします。
Google Cloud コンソールで、メニューアイコン > [IAM と管理] > [設定] に移動します。

[IAM と管理] の [設定] に移動
[プロジェクト番号] フィールドで、値をコピーします。
Apps Script プロジェクトで、 [プロジェクトの設定] をクリックします。
[Google Cloud Platform（GCP）プロジェクト] で、[プロジェクトを変更] をクリックします。
[GCP プロジェクト番号] に、前の手順でコピーした Google Cloud プロジェクト番号を貼り付けます。
[プロジェクトを設定] をクリックします。これで、Cloud プロジェクトと Apps Script プロジェクトが接続されました。

テストデプロイを作成する

次のステップで使用できるように、この Apps Script プロジェクトのデプロイ ID が必要です。

ヘッドデプロイ ID を取得するには、次の操作を行います。

Chat 用アプリの Apps Script プロジェクトで、[デプロイ] > [デプロイをテスト] をクリックします。
[ヘッドデプロイ ID] で、 [コピー] をクリックします。
[完了] をクリックします。

Chat 用アプリを構成する

Apps Script のデプロイを使用して、次の手順でテスト用の Google Chat 用アプリをデプロイします。

コンソールで Google Chat API を検索し、[Google Chat API] をクリックします。
[管理] をクリックします。
[構成] をクリックして、Chat 用アプリを設定します。
1. [アプリ名] フィールドに「A2UI Quickstart」と入力します。
2. [アバターの URL] フィールドに「https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png」と入力します。
3. [説明] フィールドに「A2UI Quickstart」と入力します。
4. [機能] で、[スペースとグループの会話に参加する] を選択します。
5. [接続設定] で [Apps Script プロジェクト] を選択します。
6. [Deployment ID] フィールドに、先ほどコピーした Head デプロイ ID を貼り付けます。
7. [公開設定] で、[ドメイン内の特定のユーザーとグループ] を選択し、メールアドレスを入力します。
[保存] をクリックします。

Chat アプリでメッセージに返信できるようになりました。

Chat アプリをテストする

Chat 用アプリをテストするには、Chat 用アプリとのダイレクトメッセージスペースを開いてメッセージを送信します。

信頼できるテスターとして登録した際に指定した Google Workspace アカウントを使用して、Google Chat を開きます。

Google Chat に移動
[ チャットを新規作成] をクリックします。
[ユーザーを 1 人以上追加] フィールドに、Chat 用アプリの名前を入力します。
検索結果から Chat 用アプリを選択します。ダイレクトメッセージが開きます。

注: 結果のリストに Chat 用アプリが表示されない場合は、Google Cloud コンソールの Chat API 構成ページの [公開設定] に Google Workspace アカウントが含まれていることを確認してください。
そのアプリの新しいダイレクトメッセージに、「Hello!」と入力して enter を押します。

Chat 用アプリは、挨拶文と、プロフィール名、画像、LinkedIn ボタンを含むカードを含むメッセージを返信します。

A2UI エージェントの実装を更新して、プロファイルタイトルも返すようにします。

ローカル開発環境で a2ui/agent.py ファイルを開き、返されたデータにタイトルを追加するツールの行のコメントを解除します。

apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py

GitHub で表示

# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""A2UI agent."""

from google.adk.agents import LlmAgent
from google.adk.tools.tool_context import ToolContext
import json

# The schema for any A2UI message. This never changes.
from .a2ui_schema import A2UI_SCHEMA

def get_user_profile(tool_context: ToolContext) -> str:
    """Call this tool to get the current user profile."""
    return json.dumps({
        "name": "Pierrick Voulet",
        # "title": "DevRel Engineer @ Google Workspace | Gen AI & AI Agents & Agentic AI | Automation & Digital Transformation",
        "imageUrl": "https://io.google/2024/speakers/3ea87822-3160-4d54-89dd-57e185085f79_240.webp",
        "linkedin": "https://www.linkedin.com/in/pierrick-voulet/"
    })

AGENT_INSTRUCTION="""
You are a user profile assistant. Your goal is to help users get their profile information using a rich UI.

To achieve this, you MUST follow these steps to answer user requests:

1.  You MUST call the `get_user_profile` tool and extract all the user profile information from the result.
2.  You MUST generate a final a2ui UI JSON based on the user profile information extracted in the previous step."""

A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f"""

To generate a valid a2ui UI JSON, you MUST follow these rules:
1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
2.  The first part is your conversational text response.
3.  The second part is a single, raw JSON object which is a list of A2UI messages.
4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.

To represent the user profile, you MUST use the following A2UI message types:
1.  Buttons MUST be used to represent links (e.g., LinkedIn profile link).
2.  Image MUST be used to represent the user's profile picture.

---BEGIN A2UI JSON SCHEMA---
{A2UI_SCHEMA}
---END A2UI JSON SCHEMA---
"""

root_agent = LlmAgent(
    name="user_profile",
    model="gemini-2.5-flash",
    instruction=A2UI_AND_AGENT_INSTRUCTION,
    description="An agent that returns the current user profile.",
    tools=[get_user_profile]
)

以前にデプロイした ADK を新しいバージョンの実装で更新します。
```
python3 deployment/deploy.py --update --resource_id=RESOURCE_ID
```
RESOURCE_ID は、前の手順でコピーした Vertex AI エージェントのリソース名に置き換えます。
アプリとのダイレクトメッセージで、「Hello again!」と入力して enter を押します。

Chat 用アプリは、テキストとプロフィールタイトルを含むカードでメッセージに返信します。

信頼できるテスターを追加してインタラクティブ機能のテストについて詳しくは、Google Chat 用アプリのインタラクティブ機能をテストするをご覧ください。

トラブルシューティング

Google Chat 用アプリまたはカードがエラーを返すと、Chat インターフェースに「エラーが発生しました」というメッセージが表示されます。または「リクエストを処理できませんでした。」と表示されます。Chat UI にエラーメッセージが表示されない場合でも、Chat 用アプリやカードで予期しない結果が生じることがあります。たとえば、カードメッセージが表示されないことがあります。

Chat UI にエラーメッセージが表示されない場合でも、Chat 用アプリのエラーロギングが有効になっている場合は、エラーの修正に役立つ説明的なエラーメッセージとログデータを利用できます。エラーの表示、デバッグ、修正については、Google Chat のエラーのトラブルシューティングと修正をご覧ください。

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、Cloud プロジェクトを削除することをおすすめします。

注意: プロジェクトを削除すると、次のような影響があります。

プロジェクト内のすべてのものが削除されます。このチュートリアルで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
カスタムプロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタムプロジェクト ID を作成した可能性があります。appspot.com の URL など、プロジェクト ID を使用する URL を保持するには、プロジェクト全体ではなく、プロジェクト内の選択したリソースを削除します。

複数のチュートリアルとクイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにできます。

Google Cloud コンソールで、[リソースの管理] ページに移動します。メニュー アイコン > [IAM と管理] > [リソースの管理] をクリックします。
Resource Manager に移動
プロジェクトリストで、削除するプロジェクトを選択し、[削除] をクリックします。
ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。