버전 및 트래픽 관리

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 가져오기를 참고하세요.

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 및 수정사항

에이전트에서 에이전트 게이트웨이 바인딩을 연결, 변경 또는 분리하면 새 버전이 생성되고 변경 전의 모든 버전이 보관처리됩니다. 새 버전만 활성 상태로 유지됩니다. 이 작업은 되돌릴 수 없으며 보관된 버전은 복원할 수 없습니다.

바인딩 변경은 기존의 모든 버전을 보관처리하므로 모든 트래픽이 이미 최신 버전에 있는 경우에만 허용됩니다. 최신 버전에 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