0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@GL_Tsukasa
in

ADKエージェントをGemini Enterprise Agent Platform(旧Vertex AI)のAgent Engineにデプロイし、GitLab CIで自動化する完全ガイド

0
Posted at

はじめに

ADK(Agent Development Kit)で作ったエージェントを、Gemini Enterprise Agent Platform(旧 Vertex AI)のAgent Engineにデプロイし、Gemini Enterprise appから使えるようにして、さらにGitLab CIで自動デプロイまで持っていく手順をまとめました。

「Vertex AI」は現在、「Gemini Enterprise Agent Platform」(旧称 Vertex AI)という名称に統合されています。この記事では、旧称からの混乱を避けるため、CLIやAPIのコマンド名としてはそのまま残っている「Agent Engine」という呼び方は維持しつつ、プラットフォーム全体を指す際は「Gemini Enterprise Agent Platform(旧 Vertex AI)」と表記します。また、エージェントの登録・管理を行うアプリ側は「Gemini Enterprise app」という名称です。

このガイドの通りに進めれば、次の状態が完成します。

  • ローカルで作ったADKエージェントが、Gemini Enterprise Agent Platform(旧 Vertex AI)のAgent Engine上で動いている
  • そのエージェントがGemini Enterprise appに登録され、実際にチャットで呼び出せる
  • git pushするだけで、GitLab CIが自動的にAgent Engineへエージェントを再デプロイする

前提条件

  • Google Cloudプロジェクト(課金有効化済み)
  • そのプロジェクトへの権限(オーナーまたは同等の権限を推奨)
  • GitLabアカウント・プロジェクト(GitLab.com、またはGitLab 17.1以降)
  • ローカル環境: Python 3.11以降、gcloud CLI、Git

全体構成

最終的にできあがるリポジトリは、以下のような構成になります。

demo-1/                      # GitLabリポジトリのルート
├── .gitlab-ci.yml
└── my_agent/
    ├── __init__.py
    ├── agent.py
    ├── .env                 # ローカル専用。コミットしない
    └── .gitignore

my_agent/.envにはプロジェクトIDなどの設定値が入ります。.gitignoreで必ず除外し、絶対にコミット・共有しないでください。

Step 1. ローカルでエージェントを作る

1-1. GitLabリポジトリをクローンする

最初にGitLab側で空のプロジェクトを作成し、そのリポジトリをローカルにクローンします。最初からクローンしておくことで、後々のリモートとの履歴不一致を避けられます。

GitLabの [設定] > [アクセストークン] で、write_repositoryスコープのPersonal Access Tokenを発行しておきます。

git clone https://gitlab.com/YOUR_NAMESPACE/YOUR_PROJECT.git
cd YOUR_PROJECT

認証を求められたら、ユーザー名とパスワード欄に発行したトークンを入力します。

1-2. ADKエージェントの雛形を作る

pip install google-adk --break-system-packages
adk create my_agent

1-3. agent.pyを編集する

都市名を受け取って、その都市の現在時刻を返すシンプルなエージェントを作ります。

my_agent/agent.py
import datetime
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

from google.adk.agents import Agent


def get_current_time(city: str) -> dict:
    """指定した都市の現在時刻を返す。

    Args:
        city (str): 都市の IANA タイムゾーン名(例: "Asia/Tokyo", "America/New_York")

    Returns:
        dict: 実行結果。成功時は {"status": "success", "report": "..."}、
              失敗時は {"status": "error", "error_message": "..."}
    """
    try:
        tz = ZoneInfo(city)
    except ZoneInfoNotFoundError:
        return {
            "status": "error",
            "error_message": (
                f"'{city}' はタイムゾーンとして認識できませんでした。"
                " IANA タイムゾーン名(例: Asia/Tokyo)で指定してください。"
            ),
        }

    now = datetime.datetime.now(tz)
    report = f"{city} の現在時刻は {now.strftime('%Y-%m-%d %H:%M:%S %Z')} です。"
    return {"status": "success", "report": report}


root_agent = Agent(
    name="root_agent",
    model="gemini-2.5-flash",
    description="指定された都市の現在時刻を回答するエージェント。",
    instruction=(
        "あなたはユーザーから都市名を聞き、get_current_time ツールを使って"
        "その都市の現在時刻を答えるエージェントです。"
        "ユーザーが都市名を一般的な名称(例: 東京、ニューヨーク)で伝えてきた場合は、"
        "対応する IANA タイムゾーン名(例: Asia/Tokyo, America/New_York)に"
        "変換してからツールを呼び出してください。"
    ),
    tools=[get_current_time],
)

modelにはgemini-2.5-flashを指定しています。安定版で特定のリージョンに縛られずに動作するため、このあとの手順すべてがシンプルになります。

1-4. .envを用意する

my_agent/.envを作成します。

my_agent/.env
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=global

1-5. .gitignoreを用意する

my_agent/.gitignore
.env
__pycache__/
*.pyc
.adk/

1-6. ローカルで動作確認する

cd YOUR_PROJECT   # my_agent の外側
adk run my_agent

「東京の今の時刻を教えて」のように話しかけ、正しく時刻が返ってくることを確認します。

Step 2. 手動でAgent Engineにデプロイする(Gemini Enterprise Agent Platform)

2-1. Google Cloud側の準備

gcloud auth login
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
gcloud services enable aiplatform.googleapis.com

2-2. デプロイ用のPythonパッケージをインストール

pip install google-adk google-cloud-aiplatform --break-system-packages

2-3. デプロイを実行する

cd YOUR_PROJECT   # my_agent の外側

adk deploy agent_engine \
  --project=YOUR_PROJECT_ID \
  --region=us-central1 \
  --display_name="My Agent" \
  my_agent

数分で完了し、以下のようなリソース名が出力されます。

Deployed to Agent Platform: projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/AGENT_ENGINE_ID

このリソース名は必ず控えておいてください。以降すべての手順で使います。

2-4. 動作確認する

出力に表示されるプレイグラウンドのURLをブラウザで開き、「東京の今の時刻を教えて」のようなメッセージを送って、正しい応答が返ってくることを確認します。

2-5. 以降の更新デプロイについて

このあとagent.pyを修正して再デプロイする際は、必ず--agent_engine_id(リソース名の末尾の数字部分)を指定してください。指定しないと、実行のたびに新しいインスタンスが作られてしまいます。

adk deploy agent_engine \
  --project=YOUR_PROJECT_ID \
  --region=us-central1 \
  --agent_engine_id=AGENT_ENGINE_ID \
  --display_name="My Agent" \
  my_agent

Step 3. Gemini Enterprise appにエージェントを登録する

3-1. Gemini Enterprise appを準備する

Google Cloud コンソール上部の検索窓で「Gemini Enterprise」と入力して開きます。アプリがまだない場合は、案内に従って作成します(新規プロジェクトの場合、30日間の無料トライアルが利用できます)。

3-2. エージェントを追加する

  1. アプリを開き、左メニューの [エージェント] を選択
  2. [エージェントを作成] をクリック
  3. エージェントタイプで 「Agent Engine によるカスタム エージェント」 を選択
  4. 以下を入力する
項目 内容
名前 例: City Time Agent
説明 指定された都市の現在時刻を回答するエージェント。現在時刻・タイムゾーンに関する質問で使用する。
Agent Engine 推論エンジンのリソースパス https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/reasoningEngines/AGENT_ENGINE_ID

説明欄は、アシスタントが自動判断でこのエージェントを呼ぶかどうかの判断材料になります。呼び出されるべき条件が伝わるように具体的に書いてください。

  1. [作成] をクリックする

3-3. 動作確認する

Gemini Enterpriseのチャット画面から、@メンションで明示的にエージェントを呼び出します。

@City Time Agent 東京の今の時刻を教えて

正しい応答が返ってくれば、登録は成功です。

個人のGoogleアカウントだけで作った、Google Cloud組織(Organization)に属さないプロジェクトの場合、Gemini Enterpriseは「プレビュー」モードで動作します。検証目的であれば、プレビューモードのままで問題なくここまでの動作確認ができます。

Step 4. GitLabとGoogle CloudのWorkload Identity Federationを設定する

サービスアカウントキーを保存せずに、GitLab CIからGoogle Cloudへ認証できるようにします。

4-1. GitLabのガイド付きセットアップを実行する

  1. GitLabプロジェクトの [設定] > [インテグレーション] を開く
  2. Google Cloud IAM インテグレーションを探して [設定] をクリック
  3. [ガイド付きセットアップ] を選ぶと、実行すべきgcloudコマンド2つが画面に表示される
  4. 表示されたコマンド(workload-identity-pools createとproviders create-oidc)を、Google Cloud Shellまたはローカルのgcloudで実行する
  5. 実行が完了したら、画面に戻って [Save changes] をクリックする

このとき、画面には以下の値が表示されるので控えておきます。

  • Project number
  • Pool ID
  • Provider ID

4-2. Agent Engineへのデプロイ権限を付与する

GitLabのプロジェクトパス(例: YOUR_NAMESPACE/YOUR_PROJECT)を使って、WIFのプリンシパルセットに直接IAMロールを付与します。

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.project_path/YOUR_NAMESPACE/YOUR_PROJECT" \
  --role="roles/aiplatform.user" \
  --condition=None

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.project_path/YOUR_NAMESPACE/YOUR_PROJECT" \
  --role="roles/serviceusage.serviceUsageConsumer" \
  --condition=None

4-3. GitLab CI/CD変数を登録する

GitLabプロジェクトの [設定] > [CI/CD] > [変数] で、以下を登録します。

変数名 値
GCP_PROJECT_ID Google CloudプロジェクトID
GCP_REGION us-central1(Step 2でデプロイしたリージョンと合わせる)
AGENT_ENGINE_ID Step 2で控えたリソースIDの数字部分

Step 5. .gitlab-ci.ymlを作成する

リポジトリのルートに.gitlab-ci.ymlを作成します。

.gitlab-ci.yml
stages:
  - test
  - deploy

verify_gcp_auth:
  stage: test
  image: google/cloud-sdk:slim
  identity: google_cloud
  script:
    - gcloud config set project "${GCP_PROJECT_ID}"
    - gcloud projects describe "${GCP_PROJECT_ID}"

deploy_agent_engine:
  stage: deploy
  image: google/cloud-sdk:slim
  identity: google_cloud
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - pip install --break-system-packages --quiet google-adk google-cloud-aiplatform
    - >
      adk deploy agent_engine
      --project="${GCP_PROJECT_ID}"
      --region="${GCP_REGION}"
      --agent_engine_id="${AGENT_ENGINE_ID}"
      --display_name="My Agent"
      my_agent 2>&1 | tee deploy_output.log
    - '! grep -q "Deploy failed" deploy_output.log'

このジョブのポイント

  • identity: google_cloudを指定するだけで、GitLabが裏側で認証情報を自動的にセットします。サービスアカウントキーの発行・保存は一切不要です。
  • verify_gcp_authジョブは認証確認用。deploy_agent_engineはmainブランチへのプッシュ時のみ実行されます。
  • --agent_engine_idを指定することで、実行のたびにインスタンスが増えるのを防ぎ、既存のリソースを更新します。
  • 出力をteeでログに保存し、Deploy failedという文字列がないかをgrepで確認することで、コマンドの終了コードに関わらずデプロイの成否を確実に検知します。

Step 6. コミット・プッシュして自動デプロイを確認する

git add .
git status   # my_agent/.env が含まれていないことを必ず確認する
git commit -m "Add ADK agent and GitLab CI deployment"
git push

GitLabのパイプライン画面(https://gitlab.com/YOUR_NAMESPACE/YOUR_PROJECT/-/pipelines)を開き、verify_gcp_authとdeploy_agent_engineの両方がpassedになることを確認します。

その後、Gemini Enterpriseのチャット画面で再度@メンションでエージェントに話しかけ、正しく応答が返ってくることを確認します。

以上で、git pushだけでAgent Engineへの自動デプロイが完了し、Gemini Enterprise経由でエージェントを呼び出せる状態が完成しました。

まとめ

最終的に、以下の仕組みが完成しました。

  1. ローカルでagent.pyを編集する
  2. git pushする
  3. GitLab CIが自動的にadk deploy agent_engineを実行し、既存のAgent Engineインスタンスを更新する
  4. Gemini Enterpriseに登録済みのエージェントが、更新後の内容で応答する

以降の開発は、agent.pyを編集してプッシュするだけで、Gemini Enterprise側の再登録作業なしに反映されます。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?