メインコンテンツまでスキップ

Google Chatボットの設定と利用ガイド

最終更新 2026/10/03

このドキュメントでは、Agentic EngineにGoogle Chatボットを接続する方法と、管理者による設定、一般ユーザーの連携、プライベートチャットとグループチャットでの利用、ファイル処理、よくある質問について説明します。内容は現在のシステム実装に基づいています。

ヒント

現在の推奨：新しくGoogle Chatアプリを作成する場合は、通常 Google Workspace Add-on モードを使用します。既存のプロジェクトでは従来のChat appモードも引き続き使用できます。Agentic Engineはこの2種類のHTTPコールバック形式の両方に対応しています。

プライベートチャットのみが必要な場合は、「Join spaces and group conversations」を有効にする必要はありません。Spaceでの@メンションとThread会話が必要な場合に有効にします。

1. 現在対応している機能​

機能ステータス説明
Google Chatのプライベートチャット対応ユーザーは連携後すぐにメッセージを送信できます。ボットは同じメッセージを編集しながら回答を更新し続けます。
Spaceでの@メンション任意Google Chat APIの設定で「Join spaces and group conversations」を有効にする必要があります。グループチャットではボットを明示的に@メンションする必要があります。
Thread会話対応グループチャット内の異なるThreadはそれぞれ独立した会話コンテキストを使用し、返信は元のThreadに返されます。
グループチャットの機能振り分け対応管理者は既定の Agent/Team、呼び出しコマンド、キーワードを設定できます。ユーザーは機能を明示的に呼び出すか、自動マッチングを利用できます。
画像とドキュメントの入力対応ユーザーがGoogle Chatに直接アップロードした画像と一般的なオフィス文書を読み取ります。Google Driveで共有されたファイルは読み取りません。
生成ファイル対応ユーザーがOAuthによるファイル認証を完了すると、ネイティブ添付ファイルとして送信します。未認証またはアップロードに失敗した場合は、短期間有効なHTTPSダウンロードリンクに自動的に切り替えます。

2. 設定前の準備​

  • 対象のGoogle CloudプロジェクトとGoogle Chat API Configurationを管理する権限があること
  • Google ChatにアクセスできるGoogle Workspaceアカウントを使用すること
  • Agentic Engineに公開ネットワークのHTTPSドメインでアクセスできること
  • Agentic Engineの「システム管理 → チャンネル管理」の権限があること
  • グループチャットを使う場合は、Workspace管理者が組織内でのChat appのインストールと使用を許可していること
警告

接続時の必須確認：Service Account JSONを入力しただけでは接続は完了しません。Google ChatのHTTPコールバックとアプリの表示範囲も設定し、必要に応じてグループチャットとユーザーOAuthを有効にする必要があります。

インスタンスとアイデンティティ：同じGoogle Chat Botのアイデンティティを、同じ実行環境内の複数のチャネルインスタンスに同時に接続したり、複数のクラスターに同時に接続したりしないでください。返信の重複、会話のずれ、取消コマンドが誤ったタスクに適用されるなどの問題が発生する可能性があります。

2つのService Accountの違い​

設定取得場所用途
Workspace Add-on サービス アカウントのメールGoogle Chat API → Configuration → Connection settingsGoogleがAgentic EngineのWebhookを呼び出す際に、OIDCの呼び出し元のアイデンティティを検証するために使用します。ここにはメールアドレスのみを入力し、鍵は不要です。
返信メッセージ用のService Account JSONGoogle Cloud → IAM と管理 → サービス アカウント → 鍵Agentic Engineはchat.bot Scopeを使用してGoogle Chat APIを呼び出し、ボットのメッセージを送信・更新します。

この2つのアイデンティティは同じアカウントではない場合があります。JSON内のclient_emailから、Configurationページに表示されるAdd-onのサービスアカウントのメールアドレスを推測したり、代わりに使用したりしないでください。

3. 設定フローの概要​

4. 管理者による設定​

1. 返信メッセージ用のService Accountを作成する​

  1. Google Cloud Consoleで対象のプロジェクトを作成または選択します。
  2. Google Chat API を有効にします。
  3. IAM と管理 → サービス アカウント に進み、このボット専用のService Accountを作成します。
  4. Service AccountのJSONキーを作成し、すぐにダウンロードします。
  5. JSONは機密性の高い認証情報として保管し、グループチャットやチケットに送信したり、コードリポジトリにコミットしたりしないでください。

Agentic Engineはhttps://www.googleapis.com/auth/chat.bot Scopeのみを使用します。JSONは必要なフィールドに解析されて暗号化保存され、管理用のAPIで秘密鍵が再表示されることはありません。

2. Agentic Engineでチャネルを新規作成する​

  1. システム管理 → チャンネル管理 に進み、「新規チャンネル」をクリックします。
  2. チャンネルタイプで Google Chat を選択し、チャンネル名、モデル、システムプロンプトを入力します。
  3. Workspace Add-onモードを使用する場合は、Google Chat Configurationページに表示される Workspace Add-on サービス アカウントのメール を入力します。従来のChat appモードでは空欄のままで構いません。
  4. 返信メッセージ用の完全な Service Account JSON を設定欄に貼り付けます。
  5. ユーザーが自分のアイデンティティでネイティブ添付ファイルを受け取れるようにするには、「ユーザー OAuth 添付ファイルを有効化」をオンにし、OAuth Client IDとClient Secretを入力します。
  6. チャネルを保存します。そのチャネルを再度編集し、システムが生成した読み取り専用の Webhook URL をコピーします。
警告

Webhook URLにはチャネルIDとランダムなcallback tokenが含まれます。必ずチャンネル管理ページから完全なURLをコピーし、手入力したり、切り詰めたり、ドメイン、プロトコル、basePath、末尾のスラッシュを変更したりしないでください。

同じチャネルのService Accountを更新しても、Webhook URLは変わりません。チャネルを削除して作成し直すと新しいURLが生成されるため、Google Chat API Configurationも必ず更新してください。

3. Google Chat APIの設定：Workspace Add-onモード​

Chatアプリを新規作成する際、Google Cloud Consoleで「Build this Chat app as a Workspace add-on」が自動的に有効になり、オフにできない場合がありますが、これは正常な動作です。

  1. アプリ名、HTTPSのアバターURL、説明を入力します。
  2. Connection settings で「Use a common HTTP endpoint URL for all triggers」を選択します。
  3. Agentic Engineのチャンネル管理ページにある完全なWebhook URLを、HTTP endpointとして貼り付けます。
  4. 同じエリアに表示される Service Account email を控え、Agentic Engineの「Workspace Add-on サービス アカウントのメール」に入力します。
  5. プライベートチャット用に、「ユーザーがGoogle Chatでこのアプリを直接見つけてメッセージを送信できる」設定はそのままにしておきます。
  6. Spaceでの@メンションとThreadが必要な場合は「Join spaces and group conversations」を有効にします。プライベートチャットのみが必要な場合はオフのままにします。
  7. Visibility で、まずテストアカウントまたはGoogle Groupを追加し、アプリのステータスをテストユーザーが利用できる状態に設定します。
  8. 設定を保存します。

現在のシステムは、Add-onのメッセージ、Spaceへの追加/削除、ボタン、Widgetの更新、App Commandなどのイベントを識別できます。Agentに渡されるのはメッセージイベントのみで、その他のイベントは安全に受信確認されますが、会話はトリガーされません。

4. Google Chat APIの設定：従来のChat appモード​

  1. Interactive featuresで Receive 1:1 messages を有効にします。グループチャットが必要な場合は、Spacesへの参加も許可します。
  2. Connection settingsで HTTP endpoint URL を選択し、完全なWebhook URLを入力します。
  3. Authentication audienceで HTTP endpoint URL を選択し、Webhook URLと1文字単位で完全に一致していることを確認します。
  4. Visibilityをまずテストユーザーまたはテストグループに限定し、設定を保存します。

従来のモードでは「Workspace Add-on サービス アカウントのメール」を入力する必要はありません。Agentic EngineはGoogle Chatのシステムサービスのアイデンティティを検証します。

5. 任意：ユーザーOAuthによるネイティブ添付ファイルを設定する​

Google Chat Media Upload APIは、chat.botのアプリのアイデンティティによるファイルのアップロードに対応していません。生成ファイルをネイティブ添付ファイルとして送信したい場合は、ユーザーOAuthを追加で設定する必要があります。

  1. 同じGoogle CloudプロジェクトでOAuth consent screenを設定し、テストユーザーまたは公開範囲を追加します。
  2. Web application タイプのOAuth Clientを作成します。
  3. 現在のサイトの完全なコールバックURLをAuthorized redirect URIsに追加します：https://{域名}{basePath}/api/google-chat-oauth/callback。
  4. Agentic Engineのチャンネル管理で「ユーザー OAuth 添付ファイルを有効化」をオンにし、OAuth Client IDとClient Secretを入力します。

システムが申請するのはopenidとhttps://www.googleapis.com/auth/chat.messages.createのみです。OAuth TokenとClient Secretは暗号化して保存され、管理用のAPIや通常のログで再表示されることはありません。

6. HTTPS、リバースプロキシ、ローカルでの連携テスト​

  • Google Chatのコールバックは、公開ネットワークからアクセスできるHTTPSアドレスである必要があります。http://localhostや内部ネットワークのHTTPアドレスを直接使用することはできません。
  • ローカルでの連携テストでは、Cloudflare Tunnel、ngrokなどのHTTPSトンネルを使ってローカルサービスに転送できます。
  • 公開ドメインが変わった場合は、ALLOWED_ORIGINSを更新してサービスを再起動し、Google Chat APIの完全なエンドポイントも更新する必要があります。
  • リバースプロキシはHost、X-Forwarded-Host、X-Forwarded-Protoを正しく転送する必要があります。

1. Google Chatでアプリを見つける​

  1. 現在のGoogle Workspaceアカウントが、アプリのVisibilityまたはテストユーザーの範囲に追加されていることを確認します。
  2. Google Chatを開き、「新しいチャット」または「アプリを検索」をクリックします。
  3. Google Chat Configurationで入力した完全なアプリ名で検索します。Cloud Project ID、Service Accountのメールアドレス、Agentic Engineのチャンネル名では検索しないでください。
  4. 「アプリ」ラベルが付いた結果を選択してインストールします。プライベートチャットのみで使う場合は1:1の会話を開くことを選択し、Spaceには追加しないでください。
チャネルの状態ユーザーの操作
管理者がユーザーOAuthを有効にしているAgentic Engine左下のアカウントメニューから「チャネル連携」に進み、Google Chatを選択して連携して認証をクリックします。Googleのページで、Google Chatで使用しているものと同じアカウントを選択し、認証に同意します。
管理者がユーザーOAuthを有効にしていない「チャネル連携」でワンタイムコマンド（例：+bind ABC234）をコピーし、Google Chatでアプリにプライベートチャットで送信します。連携コードの有効期間は10分で、1回のみ使用できます。
連携済みだがファイルが未認証「チャネル連携」でファイルを認証をクリックし、既存のGoogle Chat連携と同じGoogleアカウントを選択します。アカウントが一致しない場合、連携先の変更や認証情報の保存は行われません。
ヒント

ワンタイムコードの漏洩を防ぐため、連携コードはプライベートチャットでのみ送信できます。1つのGoogle Chatアカウントは1人のAgentic Engineユーザーにのみ連携できます。他のユーザーに連携済みと表示された場合は、先に元のアカウントで連携を解除してください。

6. 一般ユーザー：会話とコマンド​

プライベートチャット​

  • 連携に成功したら、通常のテキストを送信するだけで会話を開始できます。
  • ボットはまず返信を作成し、その後、完全な回答になるまで更新し続けます。
  • +newを送信すると、新しいプライベートチャットの会話を開始します。実行中または回答待ちのタスクがある場合は、先にやり取りを完了するか取り消してください。
  • +cancelを送信すると、現在のタスクを停止します。

SpaceとThread​

管理者がGoogle Chat Configurationで「Join spaces and group conversations」を有効にしている場合のみ利用できます。

  • Spaceでは @ボット + 質問 で入口のボットを明示的に呼び出します。
  • 同じThread内では同じ会話コンテキストが保持され、異なるThread同士は互いに分離されます。
  • 管理者がグループチャットの機能振り分けを設定すると、通常の質問は既定のAgent/Teamに渡されます。+<呼び出しコマンド> <質問>、@<呼び出しコマンド> <質問>、または設定済みのキーワードで機能を選択することもできます。
  • +helpまたは「能力清单」を送信すると、現在利用できる機能を確認できます。
  • +cancelを送信すると、現在のグループチャットのタスクを停止します。
  • グループチャットでは+newは使用できません。新しいタスクをそのまま送信するか、先に現在のタスクを取り消してください。

7. 画像とファイル​

ユーザーからボットへの送信​

  • デフォルトでは、ユーザーがGoogle Chatに直接アップロードしたPNG、JPEG、GIF、WebP画像に対応しています。
  • デフォルトではtxt、md、csv、json、pdf、doc、docx、xls、xlsx、ppt、pptxに対応しています。
  • デフォルトでは、1ファイルあたり最大2MB、1メッセージあたり最大5個の添付ファイル、添付ファイル1個あたりのダウンロードタイムアウトは10秒です。管理者はサーバー側の設定で調整できますが、システムのハード上限を超えることはできません。
  • 処理対象はGoogle ChatのUPLOADED_CONTENTのみです。Google Driveから共有されたファイルはスキップされます。
  • 画像とPDFは実際のファイル内容が検証され、宣言されたタイプとファイル内容が一致しない場合は処理が拒否されます。

ボットからユーザーへの送信​

  • ユーザーがファイルのOAuth認証を完了している場合、生成ファイルは元のプライベートチャットまたは元のSpace/Threadに送信され、現在のユーザーがアプリ経由で送信したものとして表示されます。
  • ユーザーが未認証の場合、Tokenの更新に失敗した場合、またはGoogleへのアップロードに失敗した場合、システムは署名付きの短期間有効なHTTPSダウンロードリンクを自動的に送信します。
  • ダウンロードリンクはデフォルトで10分後に無効になります。期限切れになった場合、元のメッセージや実行が削除された場合、ファイル内容が変更された場合は、再生成する必要があります。
  • 回答にMarkdownの表が含まれる場合、システムはデフォルトでresult.csvを生成します。回答がデフォルトのしきい値である6000文字を超える場合、またはユーザーがファイルを明示的に求めた場合はresult.txtを生成します。

8. よくある質問​

現象優先して確認する項目
アプリが検索で見つからないGoogle ChatとCloud Consoleで同じWorkspace組織のアカウントを使用しているか。アカウントがVisibilityに含まれているか。アプリのステータスが利用可能か。設定が保存されているか。変更後、反映まで数分かかる場合があります。
アプリが応答しない / Webhook 401Workspace Add-onのサービスアカウントのメールアドレスがConfigurationページと完全に一致しているか。従来のモードのAuthentication audienceでHTTP endpointを選択しているか。Webhook URL、HTTPS、リバースプロキシ、ALLOWED_ORIGINSが正しいか。
Webhook 404チャネルが無効化または削除されていないか。URL内のチャネルIDとcallback tokenがまだ有効か。チャネルを削除して作成し直した後、新しいURLに更新したか。
2xxだがボットの返信がない返信メッセージ用のService Account JSONが有効か。Google Chat APIが有効になっているか。サーバー側でのGoogle OAuth Tokenの取得、Chat APIの呼び出し、モデルの実行でエラーが発生していないか。
連携に失敗する連携コードをプライベートチャットで送信したか、10分の有効期間内で未使用か。Google Chatのアイデンティティが他のユーザーに連携済みでないか。OAuthで、Chatで使用しているものと同じGoogleアカウントを選択したか。
画像やドキュメントが解析されないGoogle Driveのファイルではなく、ユーザーが直接アップロードしたものか。対応しているタイプか。サイズ、数、ダウンロードタイムアウトの上限を超えていないか。サーバー側でファイルの受信が有効になっているか。
ダウンロードリンクのみが届き、ネイティブ添付ファイルがない管理者がユーザーOAuthを設定しているか。ユーザーが「ファイルを認証」を完了しているか。OAuth Tokenが失効していないか。アップロードに失敗した場合、システムは自動的にダウンロードリンクに切り替えます。
Spaceで応答がない「Join spaces and group conversations」が有効になっているか。メッセージでボットを明示的に@メンションしているか。「チャットスペース」と「既定の Agent/Team」が設定・検証済みか。

関連ページと次のステップ

  • 他のプラットフォームの接続手順を確認する：チャンネル管理。
  • チャネル接続と連携の全体的な流れを確認する：チャネルの概要と連携。
  • 使用するAgentを設定する：Agent。
  • プラットフォーム内での会話の使い方を確認する：会話。
このページは役に立ちましたか？
このページの内容