クイックスタート: Agent Development Kit（ADK）を使用して AI エージェントをビルドして Cloud Run にデプロイする

Python 用の Agent Development Kit（ADK）を使用して、1 つのコマンドで AI エージェントをビルドして Cloud Run にデプロイする方法を学習します。デプロイしたエージェントは、指定した都市の天気予報を取得します。

このクイックスタートの手順に沿って、ソースコードからデプロイすると、Cloud Run によって Dockerfile が自動的にビルドされます。

Python Buildpack が Cloud Run ソースデプロイのデフォルトのエントリポイントを決定する方法の詳細については、Python アプリケーションのビルドをご覧ください。

始める前に

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

Google Cloud CLI をインストールします。

注: すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して、最新バージョンがインストールされていることを確認してください。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

このガイドで既存のプロジェクトを使用する場合は、このガイドを完了するために必要な権限があることを確認します。新しいプロジェクトを作成した場合は、必要な権限がすでに付与されています。

Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

Google Cloud CLI をインストールします。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Google Cloud プロジェクトを作成または選択します。

プロジェクトの選択または作成に必要なロール

プロジェクトを選択する: プロジェクトの選択に特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトであれば、どのプロジェクトでも選択できます。
プロジェクトを作成する: プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者ロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。

Google Cloud プロジェクトを作成します。
```
gcloud projects create PROJECT_ID
```
PROJECT_ID は、作成する Google Cloud プロジェクトの名前に置き換えます。
作成した Google Cloud プロジェクトを選択します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、 Google Cloud プロジェクトの名前に置き換えます。

Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

Cloud Run Admin API、Vertex AI API、Cloud Build API を有効にします。
API を有効にするために必要なロール
API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。
```
gcloud services enable run.googleapis.com aiplatform.googleapis.com cloudbuild.googleapis.com
```
Agent Development Kit のドキュメントの手順に沿って ADK をインストールします。
ドメイン制限の組織のポリシーでプロジェクトの未認証呼び出しが制限されている場合は、限定公開サービスのテストの説明に従って、デプロイされたサービスにアクセスする必要があります。
Cloud Run の料金を確認するか、料金計算ツールで費用を見積もります。

必要なロール

このクイックスタートを完了するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。

プロジェクトに対する Cloud Run ソースデベロッパー（roles/run.sourceDeveloper）
プロジェクトに対する Vertex AI ユーザー（roles/aiplatform.user）
サービス ID に対するサービスアカウントユーザー（roles/iam.serviceAccountUser）
プロジェクトに対するログ閲覧者（roles/logging.viewer）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

Cloud Build サービスアカウントにプロジェクトへのアクセス権を付与する

この動作をオーバーライドしない限り、Cloud Build は、ソースコードと Cloud Run リソースのビルドにデフォルトの Cloud Build サービスアカウントとして Compute Engine のデフォルトのサービスアカウントを自動的に使用します。

Cloud Build がソースをビルドできるようにするには、プロジェクトの Cloud Build サービスアカウントに Cloud Run ビルダー（roles/run.builder）のロールを付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder

PROJECT_ID は実際の Google Cloudプロジェクト ID に置き換え、SERVICE_ACCOUNT_EMAIL_ADDRESS は Cloud Build サービスアカウントのメールアドレスに置き換えます。Compute Engine のデフォルトサービスアカウントを Cloud Build サービスアカウントとして使用している場合は、サービスアカウントのメールアドレスに次の形式を使用します。

PROJECT_NUMBER-compute@developer.gserviceaccount.com

PROJECT_NUMBER は、使用する Google Cloudプロジェクト番号に置き換えます。

プロジェクト ID とプロジェクト番号を確認する方法については、プロジェクトの作成と管理をご覧ください。

Cloud Run ビルダーのロールを付与すると、反映されるまでに数分かかることがあります。

サンプルアプリケーションを作成する

Python でアプリケーションを作成するには:

parent_folder という名前の新しい親ディレクトリを作成し、そのディレクトリに移動します。
```
mkdir parent_folder
cd parent_folder
```
parent_folder ディレクトリに、multi_tool_agent という名前の新しいサブディレクトリを作成し、そのディレクトリに移動します。
```
mkdir multi_tool_agent
cd multi_tool_agent
```
エージェントをインポートする __init__.py ファイルを作成します。
```
from . import agent
```

agent.py ファイルを作成して、指定された都市の時刻と天気に関する質問に回答するエージェントを定義します。

import datetime
from zoneinfo import ZoneInfo
from google.adk.agents import Agent

def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Args:
        city (str): The name of the city for which to retrieve the weather report.

    Returns:
        dict: status and result or error msg.
    """
    if city.lower() == "new york":
        return {
            "status": "success",
            "report": (
                "The weather in New York is sunny with a temperature of 25 degrees"
                " Celsius (77 degrees Fahrenheit)."
            ),
        }
    else:
        return {
            "status": "error",
            "error_message": f"Weather information for '{city}' is not available.",
        }

def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city.

    Args:
        city (str): The name of the city for which to retrieve the current time.

    Returns:
        dict: status and result or error msg.
    """

    if city.lower() == "new york":
        tz_identifier = "America/New_York"
    else:
        return {
            "status": "error",
            "error_message": (
                f"Sorry, I don't have timezone information for {city}."
            ),
        }

    tz = ZoneInfo(tz_identifier)
    now = datetime.datetime.now(tz)
    report = (
        f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
    )
    return {"status": "success", "report": report}

root_agent = Agent(
    name="weather_time_agent",
    model="gemini-2.0-flash",
    description=(
        "Agent to answer questions about the time and weather in a city."
    ),
    instruction=(
        "You are a helpful agent who can answer user questions about the time and weather in a city."
    ),
    tools=[get_weather, get_current_time],
)

.env ファイルを作成し、次の変数を追加します。
```
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=REGION
```
次のように置き換えます。
- PROJECT_ID: Google Cloud プロジェクト ID。
- REGION: サービスをデプロイする予定のリージョン。
親フォルダディレクトリ parent_folder に移動し、google-adk 依存関係を追加する requirements.txt ファイルを作成します。
```
google-adk
```
ソースプロジェクトには次の構造が含まれています。
```
parent_folder/
├── requirements.txt
└── multi_tool_agent/
    ├── __init__.py
    ├── agent.py
    └── .env
```

これでアプリが完成し、デプロイできるようになりました。

ソースから Cloud Run にデプロイする

ソースからのデプロイでは、ソースコードからコンテナイメージが自動的にビルドされて、デプロイされます。

ソースコードディレクトリ（parent_folder）で、次のコマンドを使用して Cloud Run にデプロイします。
```
gcloud run deploy --source .
```
1. サービス名の入力を求められたら、Enter キーを押して、デフォルトの名前（weather-agent など）を受け入れます。
2. プロジェクトで追加の API（Artifact Registry API など）を有効にするよう求められたら、y を押して応答します。
3. リージョンの入力を求められたら、任意のリージョン（europe-west1 など）を選択します。
4. 指定したリージョンにリポジトリを作成するように求められたら、y を押します。
5. 公開アクセスを許可するように求められたら、y を押します。ドメイン制限の組織のポリシーが原因でこのメッセージが表示されない場合があります。詳細については、始める前にのセクションをご覧ください。
デプロイが完了するまで少しお待ちください。成功すると、コマンドラインにサービス URL が表示されます。サービス URL から /list-apps に移動します。例: https://weather-agent-123456789101.us-central1.run.app/list-apps

エージェントを実行する

ADK エージェントをクエリするには、次の curl コマンドを実行します。

アプリのリストを取得するには、次のコマンドを実行します。
```
curl -X GET SERVICE_URL/list-apps
```
SERVICE_URL は、デプロイされたサービスの URL に置き換えます。

セッションを開始するには、次のコマンドを実行します。

curl -X POST SERVICE_URL/apps/multi_tool_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": 42}'

エージェントをクエリするには、次のコマンドを実行します。

curl -X POST SERVICE_URL/run \
-H "Content-Type: application/json" \
-d "{\"appName\": \"multi_tool_agent\",\"userId\": \"u_123\",\"sessionId\": \"s_123\",\"newMessage\": { \"role\": \"user\", \"parts\": [{ \"text\": \"What's the weather in New York today?\" }]}}"

エージェントは、クエリの結果として天気情報を返します。

サポートされている curl コマンドの詳細と例については、ADK ドキュメントのAPI サーバーを使用するをご覧ください。

クリーンアップ

Google Cloud アカウントで追加料金が発生しないようにするには、このクイックスタートでデプロイしたすべてのリソースを削除します。

リポジトリを削除する

デプロイされたサービスが使用されていない場合、Cloud Run の料金は発生しません。ただし、コンテナイメージを Artifact Registry に保存した場合にも料金が発生する可能性があります。Artifact Registry リポジトリを削除するには、Artifact Registry ドキュメントのリポジトリを削除するの手順を行います。

サービスを削除する

Cloud Run サービスの費用は、リクエストを受け取るまでは発生しません。Cloud Run サービスを削除するには、次のいずれかの操作を行います。

コンソール

サービスを削除するには:

Google Cloud コンソールで、Cloud Run の [サービス] ページに移動します。

Cloud Run に移動
削除するサービスをサービスリストで探し、そのチェックボックスをクリックして選択します。
[削除] をクリックします。これにより、サービスのすべてのリビジョンが削除されます。

gcloud

サービスを削除するには、次のコマンドを実行します。

gcloud run services delete SERVICE --region REGION

次のように置き換えます。

SERVICE: サービスの名前。
REGION: サービスの Google Cloud リージョン。

テストプロジェクトを削除する

Google Cloud プロジェクトを削除すると、そのプロジェクト内のすべてのリソースに対する課金が停止します。プロジェクト内のすべての Google Cloud リソースを解放する手順は次のとおりです。

注意: プロジェクトを削除すると、次のような影響があります。

プロジェクト内のすべてのものが削除されます。既存のプロジェクトを使用してこのドキュメントのタスクを行った場合、そのプロジェクトを削除すると、プロジェクト内で行った他の作業もすべて削除されます。
カスタムプロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタムプロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（例: appspot.com）を保持するには、プロジェクト全体ではなく、プロジェクト内の選択したリソースだけを削除します。

Google Cloud プロジェクトを削除します。

gcloud projects delete PROJECT_ID

次のステップ

コードソースからコンテナをビルドし、リポジトリに push する方法については、以下をご覧ください。

クイックスタート: Agent Development Kit（ADK）を使用して AI エージェントをビルドして Cloud Run にデプロイする

始める前に

必要なロール

Cloud Build サービス アカウントにプロジェクトへのアクセス権を付与する

サンプル アプリケーションを作成する

ソースから Cloud Run にデプロイする

エージェントを実行する

クリーンアップ

リポジトリを削除する

サービスを削除する

コンソール

gcloud

テスト プロジェクトを削除する

次のステップ

Cloud Build サービスアカウントにプロジェクトへのアクセス権を付与する

サンプルアプリケーションを作成する

テストプロジェクトを削除する