まず、以下の環境が整っていることを確認してください。

• Google Cloud プロジェクト: 以下のサービスが有効である必要があります。
  
  • Agent Runtime（デプロイ先）
  • GCS / BigQuery（資料の保管場所）
  • Agent Platform
  • Gemini Enterprise

• Gemini Enterprise ライセンス: 該当プロジェクトで Gemini アプリケーションを利用できる必要があります。
• Python 環境: Python 3.10 以上、google-adk 1.28.1 以上がインストールされている必要があります。

実行に先立ち、以下の権限設定を完了させました。

ユーザー側 (デプロイ担当)

• AI Platform 編集者: エージェントのデプロイ・管理
• ストレージ管理者: Google Cloud Storage (GCS) へのテストデータアップロード
• BigQuery 管理者: BigQuery へのテストデータアップロード
• ディスカバリーエンジン管理者: Agent Search のセットアップ
• Cloud Run 管理者: Cloud Run へのデプロイ（今回は実施しないため、不要かもしれません）
• Service Usage コンシューマー: デプロイコマンドの実行
• サービスアカウント ユーザー: サービスアカウントを各種リソースに紐付け
• ディスカバリーエンジン管理者: Agent Search データストアへの接続
• 閲覧者: 必要最低限の権限

エージェント側 (Reasoning Engine サービスアカウント)

Reasoning Engine のサービスアカウント（service-{プロジェクト番号}@gcp-sa-aiplatform-re.iam.gserviceaccount.com）に対して、GCS 等への読み取り権限を付与してください。
具体的な手順は、データサイエンスエージェントをAgent Engineにデプロイしてみた！の「2. サービスアカウントへの権限付与」にまとまっています。

以下の4つのステップで構築を進めます。

3.1. データの準備と検索エンジンの作成

1. 資料の配置: 就業規則などのドキュメントを GCS バケットに保存します（今回は、生成AIにテストドキュメントを生成させました）。
2. データストアの作成: Agent Search (旧 Vertex AI Search) でデータストアを作成し、GCS の資料をインデックス化します。※詳しい方法は、検索データストアを作成する – Cloud Storage からインポートするをご参照ください。

3.2. プログラムの実装

1. ツールの作成: tools/search_tool.py に google-cloud-discoveryengine を用いた検索関数を実装します。
2. エージェントの定義: Agent クラスでモデルとツールを紐付けます。

詳しい方法は、Agent Search tool for ADKをご参照ください。

3.3. ディレクトリの構成

プロジェクト内は以下のような構成にします。

/adk-dev_01/

├── agent.py            # メインプログラム

├── tools/

│   └── search_tool.py  # 検索用ツール

├── utils/

│   ├── config.py       # 設定ファイル

│   └── generate_content_config.py

├── .env                # 環境変数

├── .gcloudignore       # 除外設定

└── requirements.txt

特に、agent.py は次のコードになっています。パッケージの競合を避けるために相対インポートを使います。

from google.adk.agents import Agent

from google.adk.tools.preload_memory_tool import PreloadMemoryTool



from .tools.search_tool import search_vertex_ai

from .utils.config import settings

from .utils.generate_content_config import generate_content_config



root_agent = Agent(

    name=settings.app_name,

    model=settings.model_name,

    description="Agent Search を使用して回答する RAG チャットボットエージェントです。",

    instruction=settings.system_instruction,

    generate_content_config=generate_content_config,

    tools=[search_vertex_ai, PreloadMemoryTool()],

)

4.1. ADK でのデプロイ

以下のコマンドを実行して、Agent Runtime にデプロイします。

adk deploy agent_engine . \

	--project=$PROJECT_ID \

	--region=$LOCATION \

	--display_name=$CHATBOT_NAME \

	--adk_app_object=root_agent

デプロイ成功時のコンソール出力が画像のようになります。

「Created agent engine」と表示されれば成功です。

Google Cloud コンソールで、Agent Runtime にデプロイされていることを確認できます。

デプロイされたエージェントを表示したり、削除する方法はデプロイされたエージェントを管理するをご参照ください。

4.2. Gemini Enterprise appへの登録

Gemini Enterprise Agent Platform でホストされている ADK エージェントの登録と管理 – ADK エージェントを Gemini Enterprise に登録する を参照し、実際にGemini Enterprise app に登録しました。

アプリの作成の仕方はアプリを作成するをご参照ください。

登録が完了すると、画像のようにリストにエージェントが表示されます。

4.3. ユーザー権限の付与

Gemini Enterprise app に追加したエージェントをすぐに使えるわけではありません。
エージェントにアクセスできる権限を設定する必要があります。

登録したエージェントを選択し、「ユーザ権限」>「ユーザを追加」をクリック

メンバー、ロールの割り当てを入力/選択し、「保存」をクリック

これによって、メンバーがエージェントを使えるようになります。

5.1. 実際の動作イメージ

Gemini Enterprise app の画面から、デプロイしたエージェントを介して社内資料を検索できるか確認しましょう。

まずは、Google Cloud コンソール から、自身が作成したアプリを選択し、ダッシュボードからGemini Enterprise app を開きましょう。

次に左の「エージェント」ペインを選択し、「自分の組織から」配下の連携済みのエージェントを選択してください。

そうすると、先ほどデプロイしたエージェントをツールとして使えるチャットができるようになります。

以下の画像のように、インデックス化した資料が検索され、エージェントの動作が正常であることを確認できました。

補足ですが、Gemini Enterprise app に連携済みのエージェントを更新すると、再度連携しなおさなくても、エージェントの更新が反映されていました。これは個人的に非常にありがたい仕様です。

5.2. よくあるトラブルと解決策

開発中につまずきやすいポイントをまとめました。

1. デプロイサイズが 8MB を超えてしまう
   • 現象: 仮想環境（.venv）が含まれてしまい、エラーになることがあります。
   • 対策: .gcloudignore を正しく設定するか、デプロイ時に一時的にフォルダを外へ出しましょう。
2. インポートエラーが発生する
   • 現象: フォルダ名がシステムの予約語と重なり、読み込めないことがあります。
   • 対策: メインのファイル名を agent.py にし、内部の呼び出しは from .module ... のように書きましょう。
3. ファイルが見つからない
   • 現象: 資料が英語のままでは、日本語の質問に対する検索ヒット率が著しく低下します。
   • 対策: 資料の言語とクエリ（質問）の言語を統一させましょう。

本記事では、ADK を用いたカスタムエージェントの構築から Gemini Enterprise app への連携、そして現場で直面したトラブルシューティングまでを網羅しました。

エージェントを Gemini Enterprise app に連携することで、全社規模での AI 活用を低コストかつセキュアに実現できます。ぜひ、本記事のトラブルシューティングを参考に、皆さんのプロジェクトでもカスタムエージェントのデプロイに挑戦してみてください。

システムサポートでは、Google Cloudの導入や活用を支援しております。

Google Cloudを導入したい・導入したけど使いこなせていない…という方は、お気軽にご相談ください！