버전 및 트래픽 관리

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: 두 번째 버전의 버전 ID

REST

트래픽이 항상 최신 버전으로 이동하도록 구성하려면 (기본값) traffic_config 필드를 사용하여 ReasoningEngine 리소스를 업데이트하고 trafficSplitAlwaysLatest를 지정합니다.

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

에이전트의 런타임 버전 간에 트래픽을 분할하려면 traffic_config 필드로 ReasoningEngine 리소스를 업데이트하고 트래픽 타겟 목록과 각 비율을 제공합니다. 다음은 두 버전에서 수동 분할을 설정하는 방법을 보여줍니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID
  • LOCATION: 지원되는 리전
  • RESOURCE_ID: 배포된 출시 버전의 리소스 ID
  • REVISION_ID_1: 첫 번째 버전의 버전 ID
  • REVISION_ID_2: 두 번째 버전의 버전 ID
  • TRAFFIC_PERCENTAGE_1: 첫 번째 버전에 원하는 트래픽 흐름의 백분율
  • TRAFFIC_PERCENTAGE_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 Runtime 에이전트 중 버전을 사용하는 에이전트에는 Agent Gateway가 지원되지 않습니다. 에이전트 게이트웨이가 에이전트의 구성에 연결된 경우 트래픽 분할 구성, 버전별 쿼리와 같은 버전 관리 관련 기능을 사용할 수 없습니다.