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

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

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

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

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

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

リビジョンと状態

リビジョンはエージェントのスナップショットです。エージェントを作成するか、バージョン管理されたフィールドを更新すると、エージェントの変更不可のリビジョンが作成されます。リビジョンは、クエリで使用できる場合にアクティブになります。トラフィック構成によっては、クエリを受信していない可能性があります。リビジョンをアーカイブすると、トラフィックの処理から完全に削除され、復元できなくなります。アーカイブされたリビジョンは、履歴としてのみ保持されます。

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

リビジョンの上限

アーカイブされたリビジョンは、リビジョン スロットを占有しなくなります。エージェント Gateway バインディングを変更すると、既存のすべてのリビジョンがアーカイブされるため（エージェント Gateway とリビジョンを参照）、バインディングの変更によって割り当てが消費されるのではなく、割り当てが解放されます。アーカイブされたリビジョンは削除できます。

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

このセクションでは、エージェントのリビジョンを作成するために更新できる、デプロイされたエージェントの 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 を取得するをご覧ください。

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

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

for revision in revisions:
    print(revision)

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions" | Select-Object -Expand Content

{
  "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"
      }...
    ]
}

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

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

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

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

print(revision)

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID" | Select-Object -Expand Content

{
  "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% リダイレクト）を構成できます。
• 最新のリビジョンに: すべてのトラフィックが最新のリビジョンに転送されます。新しいエージェント リビジョンが作成されると、トラフィックはその新しいリビジョンに自動的に転送されます。

手動分割の対象にできるのは、アクティブなリビジョンのみです。アーカイブされたリビジョンに名前を付けると、FAILED_PRECONDITION が返されます。

Traffic target revision {revision} is not an active revision of this Agent Engine. Update traffic_config to reference only active revisions.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

client.runtimes.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,
                    },
                ]
            }
        }
    },
)

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

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

{
  "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
          }
        ]
      }
    }
}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config" | Select-Object -Expand Content

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "done": false
}

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

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

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revision = client.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)

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query" | Select-Object -Expand Content

Agent Gateway とリビジョン

エージェントで Agent Gateway バインディングを関連付け、変更、または関連付け解除すると、新しいリビジョンが作成され、変更前に存在していたすべてのリビジョンがアーカイブされます。新しいリビジョンのみがアクティブなままになります。この操作は元に戻せません。アーカイブされたリビジョンは復元できません。

バインディングの変更では既存のすべてのリビジョンがアーカイブされるため、すべてのトラフィックがすでに最新のリビジョンにある場合にのみ許可されます。手動分割が設定されている場合、トラフィックの 100% が最新のリビジョンに割り当てられる場合でも、API は変更を拒否します。拒否は FAILED_PRECONDITION を返します。

Changing spec.deployment_spec.agent_gateway_config archives every existing runtime revision, so it is only allowed while all traffic is on the latest revision. Set traffic_config.traffic_split_always_latest, or clear traffic_config, before changing the Agent Gateway configuration.

手動トラフィック分割を使用するエージェントのゲートウェイを変更するには:

1. traffic_config.traffic_split_always_latest を設定する（または traffic_config をクリアする）ことで、常に最新のルーティングに切り替えます。リビジョン間のトラフィック分配を構成するをご覧ください。
2. spec.deployment_spec.agent_gateway_config を変更します。これにより、新しいリビジョンが作成され、以前のリビジョンがすべてアーカイブされます。
3. 手動分割が再度必要な場合は、バインディングの変更後に作成されたリビジョンから作成します。

アーカイブされたリビジョンには API を通じてアクセスでき、完全な ReasoningEngineSpec が保持されます。アーカイブされたリビジョンと同等の新しいリビジョンを作成するには、アーカイブされたリビジョンの詳細を取得し、同じバージョン管理されたフィールドを使用して新しいリビジョンをデプロイします。同じコンテナ イメージ URI を再利用すると同じランタイムが再現され、同じソースコードの場所とクラスメソッドを再利用すると同じ動作が再現されます。

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

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

新しいエージェント リビジョンを作成する

新しいリビジョンを作成するには、デプロイされたエージェントのバージョン付きフィールドを更新します。手順については、デプロイされたエージェントを更新するをご覧ください。

バージョニングされたフィールドを更新すると、新しいリビジョンが自動的に作成されます。バージョン管理されていないフィールドを更新すると、新しいリビジョンを作成せずに、既存のすべてのリビジョンでエージェントが更新されます。

リビジョンのクリーンアップを管理する

Gemini Enterprise Agent Platform は、古いリビジョンを自動的に削除して、リビジョンの上限を超えないようにします。リビジョンを手動で削除することもできます。

自動ガベージ コレクション

デフォルトでは、Gemini Enterprise Agent Platform はすべてのエージェントで自動ガベージ コレクションを有効にします。無効にすることはできません。ガベージ コレクションは、エージェントの更新オペレーションの一部としてのみ実行されます。バックグラウンド ジョブとしては実行されません。

• 実行タイミング: 更新オペレーションで構成されたリビジョン上限を超えようとすると、Gemini Enterprise Agent Platform は、新しいリビジョンを作成する前に、同じオペレーションで最も古い対象リビジョンを削除します。上限を引き下げると、Gemini Enterprise Agent Platform は、新しい上限を満たすために、最も古い対象リビジョンをすぐに削除します。
• 削除対象のリビジョン: リビジョンが削除対象となるのは、次のすべての条件を満たしている場合に限られます。
  • ACTIVE 状態です。
  • トラフィック構成に含まれていない（トラフィックを 0% 受信）。
• 失敗: スペースを解放するのに十分な適格なリビジョンがない場合、Gemini Enterprise Agent Platform は FAILED_PRECONDITION エラーで更新オペレーションを拒否します。リビジョンの削除や新しいリビジョンの作成は行いません。再試行する前に、トラフィック構成からリビジョンを削除するか、上限を引き上げる必要があります。

上限を構成する

上限は、エージェントの revision_garbage_collection_strategy.keep_n_latest.max_revisions フィールドで定義されます。このフィールドは、エージェントの作成時に設定するか、後で更新リクエストで変更できます。

• 新しいエージェントのデフォルト: 100 個のリビジョン。
• 既存のエージェントのデフォルト: 950 リビジョン。
• 指定できる範囲: 1 ～ 950。0 以下の値は拒否されます。950 を超える値は、950 が引き上げることができないハード割り当てであるため、拒否されます。

手動削除

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

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

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

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

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID" | Select-Object -Expand Content