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

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

プレビュー版 - The Python buildpack supports default entrypoint detection for the Agent Development Kit (ADK) framework google-adk

この機能は サービス固有の規約の対象となります。 一般提供前の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

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

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

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

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

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

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

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

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

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

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

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

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

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

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

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

Verify that billing is enabled for your Google Cloud project.

1. Enable the Cloud Run Admin API, Vertex AI API, and Cloud Build APIs:

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   gcloud services enable run.googleapis.com aiplatform.googleapis.com cloudbuild.googleapis.com

2. Agent Development Kit のドキュメントの手順に沿って ADK をインストールします。

3. ドメイン制限の組織のポリシーでプロジェクトの未認証呼び出しが制限されている場合は、限定公開サービスのテストの説明に従って、デプロイされたサービスにアクセスする必要があります。

4. 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 サービス アカウントとして使用している場合は、サービス アカウントのメールアドレスに次の形式を使用します。

[e-mail]

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

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

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

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

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

1. parent_folder という名前の新しい親ディレクトリを作成し、そのディレクトリに移動します。

   mkdir parent_folder
   cd parent_folder
   

2. parent_folder ディレクトリに、multi_tool_agent という名前の新しいサブディレクトリを作成し、そのディレクトリに移動します。

   mkdir multi_tool_agent
   cd multi_tool_agent
   

3. エージェントをインポートするための __init__.py ファイルを作成します。

   from . import agent
   

4. 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],
   )
   

5. .env ファイルを作成し、次の変数を追加します。

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT=PROJECT_ID
   GOOGLE_CLOUD_LOCATION=REGION
   

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

   • PROJECT_ID: Google Cloud プロジェクト ID。
   • REGION: サービスをデプロイする予定のリージョン。

6. 親フォルダのディレクトリ parent_folder に移動し、google-adk 依存関係を追加する requirements.txt ファイルを作成します。

   google-adk
   

   ソース プロジェクトには次の構造が含まれています。

   parent_folder/
   ├── requirements.txt
   └── multi_tool_agent/
       ├── __init__.py
       ├── agent.py
       └── .env
   

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

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

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

1. ソースコード ディレクトリ（parent_folder）で、次のコマンドを使用して Cloud Run にデプロイします。

   gcloud beta 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 コマンドを実行します。

1. アプリのリストを取得するには、次のコマンドを実行します。

   curl -X GET SERVICE_URL/list-apps
   

   SERVICE_URL は、デプロイされたサービスの URL に置き換えます。

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

   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}'
   

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

   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 サーバーを使用するをご覧ください。

成功: エージェント開発キットを使用して AI エージェントを Cloud Run にデプロイしました。

クリーンアップ

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

リポジトリを削除する

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

サービスを削除する

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

コンソール

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

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

   Cloud Run に移動

2. 削除するサービスをサービスリストで探し、そのチェックボックスをクリックして選択します。

3. [削除] をクリックします。これにより、サービスのすべてのリビジョンが削除されます。

gcloud

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

gcloud run services delete SERVICE --region REGION

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

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

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

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

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

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

次のステップ

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

• Cloud Run サービスを開発する
• コンテナをビルドする
• Cloud Run サービスをローカルでテストする
• ソースコードからデプロイする