リビジョンとトラフィックを管理する

Gemini Enterprise Agent Platform では、エージェントの不変バージョン（リビジョン）を作成できます。その後、アクティブなリビジョン間でトラフィックを分割できます。トラフィック分割を使用すると、新しいリビジョンをテストしてトラフィックを段階的に増やしたり、他の目的でリビジョン間でトラフィックを分割したりできます。

リビジョンを作成する機能は常に有効になっています。この機能を有効にする必要はありません。リビジョンの作成については、リビジョンと状態をご覧ください。

まだリビジョンを作成していない場合は、このページで説明するように、リビジョンを表示してリビジョン間のトラフィックを構成する前に、リビジョンを作成する必要があります。

現時点では、リビジョンとトラフィック分割は v1beta1 API で使用できます。

このページでは、エージェントのリビジョンとトラフィック分割を管理する方法について説明します。

リビジョンと状態

リビジョンはエージェントのスナップショットです。エージェントを作成するか、バージョン管理されたフィールドを更新すると、エージェントの不変リビジョンが作成されます。リビジョンには次の状態があります。

  • アクティブ: リビジョンはクエリに使用できます。トラフィック構成によっては、クエリを受信していない可能性があります。
  • 非推奨: リビジョンをクエリできません。

リビジョンは、リソース名を使用して識別できます。リソース名は、エージェント リビジョンを一覧表示することで確認できます。

バージョン管理されたフィールドとバージョン管理されていないフィールド

このセクションでは、デプロイされたエージェントの ReasoningEngineSpec 定義で、エージェントのリビジョンを作成するために更新できるフィールドの一覧を示します。

バージョン管理されたフィールドを更新すると、新しいリビジョンが作成されます。

バージョン管理されていないフィールド、またはバージョン管理されているフィールド以外のエージェントの定義のフィールドを更新すると、エージェントはすべてのリビジョンで更新されます。

バージョン管理されたフィールドは次のとおりです。

  • PackageSpec
    • pickleObjectGcsUri
    • dependencyFilesGcsUri
    • requirementsGcsUri
    • pythonVersion
  • DeploymentSpec
    • env[]
    • secretEnv[]
    • firstPartyImageOverride
    • agentServerMode
    • pscInterfaceConfig
    • minInstances
    • maxInstances
    • resourceLimits
    • containerConcurrency
  • classMethods[]
  • agentFramework
  • SourceCodeSpec
    • source
    • languageSpec
  • identityType
  • agentCard[]

エージェント リビジョンを一覧表示する

デプロイされたエージェントのすべてのリビジョン（アクティブと非推奨の両方）を一覧表示できます。

エージェントのリソース ID を確認するには、エージェントのリソース ID を取得するをご覧ください。

コンソール

  1. Google Agent Platform で、[管理] > [デプロイ] に移動します。

    [デプロイメント] に移動

  2. エージェントの名前をクリックします。

  3. [リビジョン] タブを選択します。

  4. ページの上部には、次のようなリビジョンに関する情報が表示されます。

    1. 分割モード: 「手動」または「最新」のいずれかを選択できます。詳細については、「リビジョンへのトラフィックを管理する」をご覧ください。
    2. アクティブなリビジョン: リビジョンの総数に対するアクティブなリビジョンの数。
    3. 最新のリビジョン: 最新のリビジョンの名前と、そのリビジョンが受信しているトラフィックの割合。
    4. プライマリ リビジョン: トラフィックの大部分を受け取るプライマリ リビジョンの名前。

  5. リストには、エージェントのすべてのリビジョンが表示され、次の情報が含まれます。

    1. 名前: リビジョンの名前または番号。
    2. 状態: リビジョンがデプロイされているか、非推奨になっているか。
    3. トラフィック: リビジョンに転送されるトラフィックの割合。
    4. 作成日: リビジョンが作成された日時。

Agent Platform SDK

次のコードは、指定されたデプロイ済みエージェントの変更履歴を一覧表示します。リビジョンを一覧表示するには、エージェントの一意のリソース ID を特定する必要があります。

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revisions = client.agent_engines.runtimes.revisions.list(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

for revision in revisions:
    print(revision)

コード内の次の変数を置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • LOCATION: サポートされているリージョン
  • RESOURCE_ID: デプロイされたエージェントのリソース ID

REST

reasoningEngineRuntimeRevisions.list メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • LOCATION: サポートされているリージョン
  • RESOURCE_ID: デプロイされたエージェントのリソース ID。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

{
  "reasoningEngineRuntimeRevisions": [
      {
        "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
        "spec": {
          // Revision-specific config attributes (e.g., package specs, requirements)
        },
        "createTime": "2026-05-01T13:26:01Z",
        "state": "ACTIVE"
      }...
    ]
}

リビジョンの詳細を取得する

特定のリビジョンの詳細を取得できます。

Agent Platform SDK

次のコードは、指定されたデプロイ済みエージェント リビジョンのリソースの詳細を取得します。

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revision = client.agent_engines.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

print(revision)

コード内の次の変数を置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • LOCATION: サポートされているリージョン
  • RESOURCE_ID: デプロイされたエージェントのリソース ID
  • REVISION_ID: 特定のランタイム リビジョンの一意の ID

REST

reasoningEngineRuntimeRevisions.get メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • LOCATION: サポートされているリージョン
  • RESOURCE_ID: デプロイされたエージェントのリソース ID
  • REVISION_ID: 特定のランタイム リビジョンの一意の ID

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
  "spec": {
    // Revision-specific config attributes (e.g., package specs, requirements)
  },
  "createTime": "2026-05-06T13:05:24Z",
  "state": "ACTIVE"
}

リビジョン間のトラフィック分配を構成する

アクティブなリビジョン間でトラフィックを分散する方法を管理できます。トラフィック分割が行われるのは、ルート reasoningEngine リソースに送信されたクエリのみです。特定のリビジョン リソースパスにクエリを送信すると、トラフィック ルールが明示的にバイパスされます。

トラフィックは次のいずれかの方法で分散されます。

  • 割合別: 割合別に構成すると、指定した割合のトラフィックが各エージェント リビジョンに転送されます。指定する割合は整数にする必要があります。割合の合計は 100% にする必要があります。アクティブなリビジョンが 1 つしかない場合でも、トラフィック分割（100% がリダイレクトされる）を構成できます。

  • 最新のリビジョンに: すべてのトラフィックが最新のリビジョンに転送されます。新しいエージェント リビジョンが作成されると、トラフィックはその新しいリビジョンに自動的に転送されます。

コンソール

トラフィック管理を構成する手順は次のとおりです。

  1. [管理] > [デプロイ] に移動します。

    [デプロイメント] に移動

  2. エージェントの名前をクリックします。

  3. [リビジョン] タブに移動します。

  4. リビジョンの詳細ページで、[トラフィックの管理] をクリックします。

  5. [分割モード] で、次のいずれかのオプションを選択します。

    1. 手動: 各リビジョンに転送するトラフィックの割合を指定します。
    2. 常に最新: この場合、トラフィックの 100% が最新（最近作成された）リビジョンに転送されます。

  6. [保存] を選択して変更を保存します。

Agent Platform SDK

次のコードは、割合ベースのトラフィック分配を構成する例を示しています。

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

client.agent_engines.update(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "traffic_config": {
            "trafficSplitManual": {
                "targets": [
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
                        "percent": 50,
                    },
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
                        "percent": 50,
                    },
                ]
            }
        }
    },
)

コード内の次の変数を置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • LOCATION: サポートされているリージョン
  • RESOURCE_ID: デプロイされたエージェントのリソース ID
  • REVISION_ID_1: 最初のリビジョンのリビジョン ID
  • REVISION_ID_2: 2 番目のリビジョンのリビジョン ID

REST

トラフィックが常に最新のリビジョンに転送されるように構成する（デフォルト）には、traffic_config フィールドを使用して ReasoningEngine リソースを更新し、trafficSplitAlwaysLatest を指定します。

{
  "trafficConfig": {
    "trafficSplitAlwaysLatest": {}
  }
}

エージェントのランタイム リビジョン間でトラフィックを分割するには、traffic_config フィールドを使用して ReasoningEngine リソースを更新し、トラフィック ターゲットのリストとそれぞれの割合を指定します。次の例は、2 つのリビジョン間で手動分割を設定する方法を示しています。

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • LOCATION: サポートされているリージョン
  • RESOURCE_ID: デプロイされたエージェントのリソース ID
  • REVISION_ID_1: 最初のリビジョンのリビジョン ID
  • REVISION_ID_2: 2 番目のリビジョンのリビジョン ID
  • TRAFFIC_PERCENTAGE_1: 最初のリビジョンで必要なトラフィック フローの割合
  • TRAFFIC_PERCENTAGE_2: 2 番目のリビジョンに必要なトラフィック フローの割合

HTTP メソッドと URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config

リクエストの本文（JSON）: 

{
  "trafficConfig": {
    "trafficSplitManual": {
      "targets": [
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
            "percent": TRAFFIC_PERCENTAGE_1
          },
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
            "percent": TRAFFIC_PERCENTAGE_2
          }
        ]
      }
    }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

このリクエストにより、長時間実行オペレーション（LRO）が開始されます。最初は、標準のオペレーション レスポンスが返されます。構成の変更が完了すると、レスポンスに done が表示され、構成設定が繰り返されます。
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "done": false
}

特定のリビジョンをクエリする

SDK または API を使用して特定のリビジョンをクエリできます。リビジョンをクエリするには、リビジョンがアクティブである必要があります。特定のリビジョンに直接クエリを送信すると、トラフィック分配ルールがバイパスされます。

Agent Platform SDK

次のコードは、特定のアクティブなリビジョンをクエリします。

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revision = client.agent_engines.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

response = revision.query(
    input={"your_input_key": "your_input_value"},
    config={"class_method": "your_class_method"},
)

print(response)

コード内の次の変数を置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • LOCATION: サポートされているリージョン
  • RESOURCE_ID: デプロイされたエージェントのリソース ID
  • REVISION_ID: 特定のランタイム リビジョンの一意の ID

REST

reasoningEngineRuntimeRevisions.query メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • LOCATION: サポートされているリージョン
  • RESOURCE_ID: デプロイされたエージェントのリソース ID
  • REVISION_ID: 特定のランタイム リビジョンの一意の ID

HTTP メソッドと URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query

リクエストを送信するには、次のいずれかのオプションを展開します。

 

リビジョンをモニタリングする

ログのメタデータとしてリビジョン番号を追跡することで、アクティビティと問題のリビジョンをモニタリングします。ロギングの設定については、ロギングを設定するをご覧ください。

リビジョンを更新する

デプロイされたエージェントを更新するの手順に沿って、デプロイされたエージェントを更新します。バージョン管理されたフィールドまたはバージョン管理されていないフィールドを更新できます。バージョニングされたフィールドを更新すると、新しいリビジョンが作成されます。

エージェント リビジョンを削除する

エージェント リビジョンは、削除することで削除できます。トラフィック管理でアクティブでないリビジョンは、非推奨であるか、トラフィックを受信するように構成されていないため、削除できます。リビジョンがトラフィックを受信するかどうかを構成する手順については、リビジョン間のトラフィック分配を構成するをご覧ください。

コンソール

エージェントのリビジョンを削除するには:

  1. [管理] > [デプロイ] に移動します。

    [デプロイメント] に移動

  2. エージェントの名前をクリックします。

  3. [リビジョン] タブに移動します。

  4. リビジョンの詳細ページで、リビジョン名をクリックします。

  5. 削除するリビジョンの行を見つけます。

  6. [削除]（ゴミ箱）アイコンをクリックします。

  7. メッセージが表示されたら、リビジョンの削除を確定します。

Agent Platform SDK

次のコードは、指定されたエージェント リビジョンを削除します。

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

client.agent_engines.runtimes.revisions.delete(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

コード内の次の変数を置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • LOCATION: サポートされているリージョン
  • RESOURCE_ID: デプロイされたエージェントのリソース ID
  • REVISION_ID: 特定のランタイム リビジョンの一意の ID

REST

reasoningEngineRuntimeRevisions.delete メソッドを呼び出します。

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID
  • LOCATION: サポートされているリージョン
  • RESOURCE_ID: デプロイされたエージェントのリソース ID
  • REVISION_ID: 特定のランタイム リビジョンの一意の ID

HTTP メソッドと URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

リクエストを送信するには、次のいずれかのオプションを展開します。

 

制限事項

  • Agent Gateway は、リビジョンを使用している Agent Runtime エージェントではサポートされていません。Agent Gateway がエージェントの構成に関連付けられている場合、トラフィック分割構成やリビジョンごとのクエリなどのバージョン管理関連機能は使用できません。