本記事は AIエージェント構築＆運用 Advent Calendar 2025 の 5 日目の記事です。

はじめに

本記事では、Vertex AI Agent Engine と、開発フレームワークである ADK (Agent Development Kit) を組み合わせ、RAG エージェントを構築するフローを紹介します。

本記事で扱うアーキテクチャとスコープ

今回構築するシステムの全体像は以下の通りです。

概要

ADKを使ったRAGエージェントのローカル開発
Vertex AI RAG Engineを活用した検索拡張生成の実装
TerraformによるVertex AI Agent Engineのインフラ構築
ローカル環境から本番環境へのデプロイフロー

ハンズオン用レポジトリ

https://github.com/yapodu-inc/adk-rag-engine

前提知識

Google Cloud: オーナー権限を持つプロジェクトがあること
Terraform: 基礎的な操作が理解できていること

ハンズオン

ハンズオンレポジトリ Clone

git clone https://github.com/yapodu-inc/adk-rag-engine

Google Cloud API 有効化

Agent Engine や RAG Engine を利用するために必要な API を有効化します。

[API とサービス] -> [有効な API とサービス]

[API とサービスを有効にする]

Vertex AI を入力

有効化を行う

Cloud の概要 -> ダッシュボード

Terraform 用 GCS Bucket 手動作成

本ハンズオンでは、可能な限り Terraform でのリソース管理を行います。

gcloud 認証

gcloud init の実行済みが前提です

gcloud ログイン

gcloud auth login

プロジェクト設定

gcloud config set project yXXXXXX

リージョン設定
今回は RAG Engine が使用可能な europe-west4 を指定します。

gcloud config set compute/region europe-west4

gcloud 確認

$ gcloud config list
[compute]
region = europe-west4
[core]
account = code-tamura-ai@yapodu.co.jp
disable_usage_reporting = True
project = yXXXXXX 

Your active configuration is: [default]

tfstate バケット作成

terraform の tfstate 用バケットを gcloud で作成します。バケット名: ypd-hands-on-adk-ragengine-xxxx-tfstate

$ gcloud storage buckets create gs://ypd-hands-on-adk-ragengine-xxxx-tfstate \
    --location=EUROPE-WEST4 \
    --default-storage-class=STANDARD
Creating gs://ypd-hands-on-adk-ragengine-xxxx-tfstate/...

確認

$ gcloud storage buckets list --format="table(name, location, defaultStorageClass)"
NAME                                        LOCATION  DEFAULT_STORAGE_CLASS
ypd-hands-on-adk-ragengine-xxxx-tfstate  EUROPE-WEST4  STANDARD

Terraform init

自身の環境に合わせ terraform を修正します。

terraform/environments/dev/default/provider.tf bucket を修正

  #==============================
  #   tfstate保存用GCS
  #==============================

  backend "gcs" {
    # ★↓修正
    bucket = "ypd-hands-on-adk-ragengine-xxxx-tfstate" # 作成した GCS バケット名
    # ★↑修正
    prefix = "terraform/state/default" 

  }
}

terraform/environments/dev/default/local.tf
以下を修正します。

project 名
project 番号
リソース prefix

locals {
  # RAG Engine は asia-northeast1 は未対応 のため europe-west4 に固定
  region         = "europe-west4"
  # ★↓修正
  project        = "yXXXXXX "
  project_number = "12345678901"
  # ★↑修正
}

locals {
  #Main Prefix
  # ★↓任意のプレフィックスに修正
  prefix = "ypd-adk-ragengine"
  # ★↑修正
  #Environment
  env = "dev"

}

project 名, project 番号はコンソール画面の
[cloud の概要] -> [ダッシュボード] で確認できます。

tf ファイルディレクトリで terraform init を実行します。

$ cd terraform/environments/dev/default/
$ terrform init

$ terraform init 
Initializing the backend...

Successfully configured the backend "gcs"! Terraform will automatically
use this backend unless the backend configuration changes.
Initializing provider plugins...
- Finding hashicorp/google versions matching "7.9.0"...
- Installing hashicorp/google v7.9.0...
- Installed hashicorp/google v7.9.0 (signed by HashiCorp)
Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Terraform での Google Cloud リソース作成

以下のリソースを Terraform で作成します。

rag_engine_config: RAG Engine のコンフィグとマネージドDBの tier 設定
Staging Bucket: ADK がアプリをデプロイする際、一時ファイル置き場として使用するバケット
Service Account: Vertex AI Agent Engine が実行時に使用する権限

※RAG Engine の Corpus (データ格納場所) は Terraformリソース未サポートのため、コンソールから手動作成実施

terraform plan

to add のリソース作成予定を確認

$ terraform plan 
Plan: 4 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + rag_engine_config_id   = (known after apply)
  + rag_engine_config_name = (known after apply)
  + rag_engine_project     = "yxxxxx"
  + rag_engine_region      = "europe-west4"

─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you
run "terraform apply" now.

terraform apply

$ terraform apply

Acquiring state lock. This may take a few moments...

...

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

Outputs:

rag_engine_config_id = "projects/yxxxx/locations/europe-west4/ragEngineConfig"
rag_engine_config_name = "projects/yxxxx/locations/europe-west4/ragEngineConfig"
rag_engine_project = "yxxxx"
rag_engine_region = "europe-west4"

※コンソール画面のRAG Engine には何も表示されません。

RAG Engine Corpus の手動作成

現状、Vertex AI RAG Engine の Corpus（データ格納領域）の作成は Terraform プロバイダは未対応なため、今回はコンソールから手動で作成します。

[Vertex AI] -> [RAG Engine] -> [リージョン: europe-west4(オランダ)]
[コーパスを作成]

コーパス名: "任意のコーパス名"

[続行]

エンベディングモデル: Text Multilingual Embedding 002 ベクトルデータベース: RagManaged ベクトルストア

[コーパスを作成]

作成後に [データインポート] RAG に読み込ませたいデータをアップロードします。
ここではレポジトリ内の rag-data/ 内 md ファイルをアップロードしますが、各自試験したいファイルをアップロードしてください。

ADK を用いたローカル開発

インフラの準備が整ったので、アプリケーション開発に移ります。まずはGoogle Cloud へデプロイする前に、ローカル環境確認を行います。

環境変数設定

ADK の環境変数を修正します。

RAG Corpus リソース名確認

作成した Coupus 名を選択 [詳細] -> リソース名をコピー

.env 作成

$ cp -p services/backend/multi_tool_agent/.env.example services/backend/multi_tool_agent/.env

services/backend/multi_tool_agent/.env

GOOGLE_CLOUD_PROJECT: プロジェクト名 GOOGLE_CLOUD_LOCATION=europe-west4 VERTEX_AI_RAG_CORPUS_ID: にコピーした Corpus リソース指定 STAGING_BUCKET: terraform で作成したい staging 用バケット名

GOOGLE_GENAI_USE_VERTEXAI=TRUE
  # ★↓修正
GOOGLE_CLOUD_PROJECT=yxxxxxx
GOOGLE_CLOUD_LOCATION=us-east4
VERTEX_AI_RAG_CORPUS_ID=projects/yxxxx/locations/europe-west3/ragCorpora/2345678901234567890
  # ★↑修正


# Deploy用の設定
  # ★↓修正
STAGING_BUCKET=gs://tamura-adk-ragengine-dev-adk-staging
  # ★↑修正

venv 環境設定

ここでは adk の get-start を踏襲し venv を設定します。

$ cd services/backend
$ source .venv/bin/activate
(.venv) $ pip install google-adk
(.venv) $ pip install python-dotenv

adk local 起動

ローカルサーバーを起動します。

(.venv) $ adk web

+-----------------------------------------------------------------------------+
| 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)

ブラウザで http://localhost:8000 にアクセスすると、ADK のチャット UI が表示されます。

RAG 確認

プロンプトにCorpus にアップロードした情報について質問します。

Dr.DRE について教えてください。

RAG Engine のデーターに基づいて回答されます。

このように、Service Account の権限をしていれば ADK を使うことでお手軽にプロンプトの検証が可能です。

Vertex AI Agent Engine へデプロイと確認

ローカル環境での確認が完了したので、Vertex AI Agent Engine にデプロイしします。

(.venv) $ python deploy.py

このスクリプトにより、以下の処理が実行されます。

アプリケーションコードのパッケージング
Staging バケットへのアップロード
Cloud Build によるコンテナビルド（バックグラウンド）
Vertex AI Reasoning Engine へのデプロイ

デプロイ完了まで数分かかります。成功すると Resource name が出力されます。

deploy 開始

Create AgentEngine backing LRO: projects/2/locations/europe-west4/reasoningEngines/
View progress and logs at https://console.cloud.google.com/logs/query?project=y

完了まで5分ほどかかり、終了時に以下のメッセージが出力されます。

==================================================
Deployment successful!
Resource name: projects/223344455000/locations/europe-west4/reasoningEngines/6666688888888880000
==================================================

Vertex AI -> Agent Engine

リージョンを選択し deploy された日時の [名前] 項目を選択してください。

[セッション]を選択しプレイグランドに質問を入力してください。

作成リソース削除

terraform destroy

terraform で作成したリソースを削除します。

$ cd terraform/environments/dev/default/
$ terraform destroy

RAG Corpus 手動削除

Terraform destroy 実行時に削除されているはずですが、未削除であれば手動で削除を行ってください。

Agent Engine

Agent Engine も Terraform 管理外（deploy.py で作成）のため、API で削除が必要です。今回は curl で削除する例を示します。

デプロイ時に出力された Resource name を確認

==================================================
Deployment successful!
Resource name: projects/223344455000/locations/europe-west4/reasoningEngines/6666688888888880000
==================================================

変数を設定 (適宜書き換えてください)

$ export RESOURCE_NAME="projects/223344455000/locations/europe-west4/reasoningEngines/6666688888888880000"
$ export PROJECT_ID="yxxxxxxxxxxxxx"
$ export LOCATION="europe-west4"

削除実行

curl -X DELETE \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://${LOCATION}-aiplatform.googleapis.com/v1beta1/${RESOURCE_NAME}?force=true"

まとめ

本記事では、Vertex AI RAG Engine と Agent Engine を組み合わせ、ADK で開発する一連のフローを体験しました。

RAG Engine: インフラ管理不要で高精度な検索基盤を利用可能
ADK: ローカル開発とクラウドデプロイのシームレスな連携

これらを組み合わせることで、local 確認レベルからGoogle Cloud へのエージェント開発への移行がスムーズになります。ぜひ自身のデータを使って試してみてください。

Yapodu Tech Blog

株式会社ヤポドゥの技術ブログです。

【ハンズオン】Vertex AI RAG Engine - ローカル開発から Agent Engine 環境まで