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

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

AI エージェントは、環境を自律的に認識し、推論を行い、定義された目標を達成するために複雑な複数ステップのアクションを実行します。このチュートリアルでは、 Gemini と Google 検索のグラウンディングを使用して事実を批判して修正する ADK LLM Auditor マルチエージェント サンプル をデプロイします。

Chat 用アプリとしての LLM Auditor マルチエージェント サンプル。

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

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

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

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

目標

  • 環境をセットアップする。
  • ADK AI エージェントをデプロイする。
  • Chat アプリをデプロイする。
  • Chat アプリを構成する。
  • Chat アプリをテストする。

前提条件

環境の設定

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 同意画面を構成すると、ユーザーとアプリの審査担当者に表示される内容が定義され、後で公開できるようにアプリが登録されます。

  1. Google API Console で、メニュー アイコン menu > [Google Auth Platform] > [ブランディング] に移動します。

    [ブランディング] に移動

  2. Google Auth Platform をすでに構成している場合は、[ブランディング]、[対象]、[データアクセス] で次の OAuth 同意画面の設定を構成できます。[**Google Auth Platform はまだ構成されていません**] というメッセージが表示されたら、[**スタートガイド**] をクリックします。
    1. [アプリ情報] の [アプリ名] に、アプリの名前を入力します。
    2. [**ユーザー サポートメール**] で、ユーザーが同意について問い合わせる際に使用するサポートのメールアドレスを選択します。
    3. [続行] をクリックします。
    4. [対象] で [内部] を選択します。
    5. [続行] をクリックします。
    6. [連絡先情報] で、プロジェクトに対する変更の通知を受け取る [メールアドレス] を入力します。
    7. [続行] をクリックします。
    8. [完了] で、Google API サービスのユーザーデータに関するポリシーを確認し、同意する場合は [Google API サービス: ユーザーデータに関するポリシーに同意します] を選択します。
    9. [続行] をクリックします。
    10. [作成] をクリックします。
  3. 現時点では、スコープの追加はスキップできます。 今後、 Google Workspace 組織外で使用するアプリを作成する場合は、[ユーザータイプ] を [外部] に変更する必要があります。次に、アプリに必要な承認スコープを追加します。詳細については、 OAuth 同意画面を構成するをご覧ください。

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

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

Google Cloud Console

  1. Google Cloud Console で、メニュー アイコン > [**IAM と管理**] > [**サービス アカウント**] に移動します。

    [サービス アカウント] に移動

    残りの手順は、Google Cloud Console に表示されます。

  2. Google Cloud プロジェクトを選択します。
  3. [サービス アカウントを作成] をクリックします。
  4. Google Cloud Console に表示するサービス アカウント名を入力します。
  5. アクセス制御を今すぐ設定しない場合は、[完了] をクリックしてサービス アカウントの作成を終了します。アクセス制御を今すぐ設定するには、[作成して続行] をクリックして次の手順に進みます。
  6. 省略可: サービス アカウントにロールを割り当て、Google Workspace リソースに加えて Google Cloud プロジェクトのリソースへのアクセス権を付与します。詳細については、プロジェクト、フォルダ、組織へのアクセスの管理をご覧ください。
  7. [続行] をクリックします。
  8. 省略可: このサービス アカウントで管理とアクションの実行が可能なユーザーまたはグループを入力します。詳細については、サービス アカウントの権限借用をご覧ください。
  9. [完了] をクリックして、サービス アカウントの作成を完了します。

    サービス アカウントのメールアドレスをメモします。

gcloud CLI

  1. サービス アカウントを作成します。 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. 省略可: サービス アカウントにロールを割り当て、Google Workspace リソースに加えて Google Cloud プロジェクトのリソースへのアクセス権を付与します。詳細については、プロジェクト、フォルダ、組織へのアクセスの管理をご覧ください。

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

秘密鍵を作成する

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

  1. Google Cloud Console で、メニュー アイコン menu > [IAM と管理] > [サービス アカウント] に移動します。

    [サービス アカウント] に移動

    残りの手順は、Google Cloud Console に表示されます。

  2. Google Cloud プロジェクトを選択します。
  3. キーを作成するサービス アカウントのメールアドレスをクリックします。
  4. [キー] タブをクリックします。
  5. [鍵を追加] プルダウン メニューをクリックして、[新しい鍵を作成] を選択します。
  6. [鍵のタイプ] として [JSON] を選択し、[作成] をクリックします。

    新しい公開鍵と秘密鍵のペアが生成され、サービス アカウント キーファイルとして マシンにダウンロードされます。ダウンロードした JSON ファイルを、作業ディレクトリに credentials.json として保存します。このファイルはこの鍵の唯一のコピーです。鍵ファイルをダウンロードした後、再度ダウンロードすることはできません。鍵を安全に保存する方法については、サービス アカウント キーの管理のベスト プラクティスをご覧ください。

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

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

  1. Vertex AI Agent Garden で LLM Auditor サンプル を開きます。

    サンプルを開く

  2. [デプロイ] をクリックします。

  3. 求められたら、Google Cloud プロジェクトを選択します。

  4. [Cloud Shell にデプロイ] をクリックします。

  5. 求められたら、[承認] をクリックして、Cloud Shell の OAuth フローを行います。

  6. Cloud Shell が完全に読み込まれたら、Enter キーを押して、プリロードされたコマンドラインを実行し、デプロイを開始します。

  7. リージョンを入力するよう求められたら、Enter キーを押してデフォルトを使用します。

  8. 完了したら、Vertex AI Agent Engine に移動します。

    Vertex AI Agent Engine を開く

  9. コピーを作成するためのアイコン をクリックして、新しくデプロイされたエージェントのリソース名をテーブルからコピーします。

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

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

    プロジェクトを開く

  2. [概要] > コピーを作成するためのアイコン [コピーを作成] をクリックします。

  3. Apps Script プロジェクトで、 プロジェクト設定のアイコン [**プロジェクトの設定**] > [**スクリプト プロパティを編集**] > [**スクリプト プロパティを追加**] をクリックして、次のスクリプト プロパティを追加します。

    1. 前の手順でコピーした Vertex AI エージェントのリソース名を持つ REASONING_ENGINE_RESOURCE_NAME。
    2. 前の手順でダウンロードしたサービス アカウントの JSON キー（{ ... } など）を持つ SERVICE_ACCOUNT_KEY。

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

  5. Google API Console で、メニュー アイコン > [IAM と管理] > [設定] に移動します。

    [IAM と管理] の [設定] に移動

  6. [プロジェクト番号] フィールドで、値をコピーします。

  7. Apps Script プロジェクトで、 [プロジェクト設定のアイコン プロジェクトの設定] をクリックします。

  8. [Google Cloud Platform（GCP）プロジェクト] で、[プロジェクトを変更] をクリックします。

  9. [GCP プロジェクト番号] に、 前の手順でコピーした Google Cloud プロジェクト番号を貼り付けます。

  10. [プロジェクトを設定] をクリックします。これで、Cloud プロジェクトと Apps Script プロジェクトが接続されました。

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

この Apps Script プロジェクトにはデプロイ ID が必要です。次のステップで使用します。

ヘッド デプロイ ID を取得する手順は次のとおりです。

  1. Chat アプリの Apps Script プロジェクトで、 [デプロイ] > [デプロイをテスト] をクリックします。
  2. [**ヘッド デプロイ ID**] で、コピーを作成するためのアイコン [**コピー**] をクリックします。
  3. [完了] をクリックします。

Chat アプリを構成する

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

  1. [API Console] で Google Chat API を検索し、 [Google Chat API] をクリックします。
  2. [管理] をクリックします。

  3. [構成] をクリックして、Chat アプリを設定します。

    1. [アプリ名] フィールドに「ADK Quickstart」と入力します。
    2. [アバター URL] フィールドに「https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png」と入力します。
    3. [説明] フィールドに「ADK Quickstart」と入力します。
    4. [機能] で、[スペースとグループの会話に参加する] を選択します。
    5. [接続設定] で [Apps Script プロジェクト] を選択します。
    6. [デプロイ ID] フィールドに、先ほどコピーしたヘッド デプロイ ID を貼り付けます。
    7. [可視性] で、[**ドメイン内の特定のユーザーとグループ**] を選択し、メールアドレスを入力します。

  4. [保存] をクリックします。

Chat アプリはメッセージに応答する準備ができました。

Chat アプリをテストする

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

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

    Google Chat に移動

  2. [**チャットを新規作成**] をクリックします。
  3. [1 人以上のユーザーを追加] フィールドに、Chat アプリの名前を入力します。

  4. 検索結果から Chat アプリを選択します。ダイレクト メッセージが開きます。

  5. アプリとの新しいダイレクト メッセージで、「The Eiffel Tower was completed in 1900」と入力して enter を押します。

    Chat アプリは、Critic サブエージェントと Reviser サブエージェントのレスポンスで応答します。

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

トラブルシューティング

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

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

クリーンアップ

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

  1. Google API Console で、[リソースの管理] ページに移動します。 [Menu] > [IAM & Admin] > [Manage Resources] をクリックします。

    [Resource Manager] に移動

  2. プロジェクト リストで、削除するプロジェクトを選択し、 [Delete] . をクリックします。
  3. ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。