Gerenciar revisões e tráfego

Na Gemini Enterprise Agent Platform, é possível criar versões imutáveis, ou revisões, de um agente. Em seguida, é possível dividir o tráfego entre as diferentes revisões ativas. Com a divisão de tráfego, é possível testar e aumentar gradualmente o tráfego para novas revisões, além de dividir o tráfego entre revisões para outras finalidades.

A capacidade de criar revisões está sempre ativada. Não é necessário ativar o recurso. Para informações sobre como criar revisões, consulte Revisões e estados.

Se você ainda não criou nenhuma revisão, será necessário criar revisões antes de poder visualizá-las e configurar o tráfego entre elas, conforme descrito nesta página.

No momento, as revisões e a divisão de tráfego estão disponíveis na API v1beta1.

Nesta página, descrevemos como gerenciar revisões de agentes e divisão de tráfego.

Revisões e estados

Uma revisão é um snapshot de um agente. Quando você cria um agente ou atualiza os campos versionados dele, uma revisão imutável é criada. Uma revisão fica ativa quando está disponível para consultas. Dependendo da configuração de tráfego, talvez ele não esteja recebendo consultas. Quando uma revisão é arquivada, ela é desativada permanentemente da veiculação de tráfego e não pode ser restaurada. As revisões arquivadas são mantidas apenas para referência histórica.

É possível identificar uma revisão usando o nome do recurso, que pode ser encontrado listando as revisões do agente.

Limites de revisão

As revisões arquivadas param de ocupar um slot de revisão. Mudar uma vinculação do Gateway de Agente arquiva todas as revisões preexistentes (consulte Gateway de Agente e revisões). Portanto, uma mudança de vinculação libera a cota em vez de consumi-la. As revisões arquivadas ainda podem ser excluídas.

Campos com e sem versão

Esta seção lista os campos na definição ReasoningEngineSpec de um agente implantado que podem ser atualizados para criar uma revisão do agente.

Quando você atualiza campos com controle de versão,uma nova revisão é criada.

Quando você atualiza campos sem versão ou campos em uma definição de agente que não sejam os campos com versão, o agente é atualizado em todas as revisões.

Estes são os campos com versões:

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

Listar revisões do agente

É possível listar todas as revisões de um agente implantado.

Para encontrar o ID do recurso do seu agente, consulte Receber o ID do recurso do agente.

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

Conferir os detalhes de uma revisão

É possível recuperar os detalhes de uma revisão específica.

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

Configurar a distribuição de tráfego entre revisões

É possível gerenciar como o tráfego é distribuído entre as revisões ativas. Somente as consultas direcionadas ao recurso raiz reasoningEngine passam por divisão de tráfego. Direcionar uma consulta a um caminho de recurso de revisão específico ignora explicitamente as regras de tráfego.

O tráfego é distribuído usando um destes dois métodos:

• Por porcentagem: ao configurar por porcentagem, uma porcentagem especificada de tráfego vai para cada revisão do agente. Cada porcentagem especificada precisa ser um número inteiro. A soma das porcentagens precisa ser igual a 100%. Mesmo que haja apenas uma revisão ativa, você ainda pode configurar a divisão de tráfego (em que 100% redireciona para lá).
• Para a revisão mais recente: todo o tráfego é direcionado para a revisão mais recente. Quando uma nova revisão de agente é criada, o tráfego é direcionado automaticamente para ela.

Uma divisão manual só pode segmentar revisões ativas. Nomear uma revisão arquivada retorna 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
}

Consultar uma revisão específica

É possível consultar uma revisão específica usando o SDK ou as APIs. A revisão precisa estar ativa para ser consultada. Consultas diretas a uma revisão específica ignoram as regras de distribuição de tráfego.

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

Gateway de Agente e revisões

Anexar, mudar ou remover uma vinculação do Gateway de Agente em um agente cria uma nova revisão e arquiva todas as revisões que existiam antes da mudança. Somente a nova revisão permanece ativa. Essa ação é irreversível, e não é possível restaurar as revisões arquivadas.

Como uma mudança de vinculação arquiva todas as revisões atuais, ela só é permitida quando todo o tráfego já está na revisão mais recente. A API rejeita a mudança se houver uma divisão manual definida, mesmo que ela coloque 100% do tráfego na revisão mais recente. A rejeição retorna 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.

Para mudar o gateway em um agente que usa uma divisão manual de tráfego:

1. Mude para o roteamento sempre mais recente definindo traffic_config.traffic_split_always_latest ou limpando traffic_config. Consulte Configurar a distribuição de tráfego entre revisões.
2. Mude spec.deployment_spec.agent_gateway_config. Isso cria a nova revisão e arquiva todas as anteriores.
3. Se você precisar de uma divisão manual novamente, crie-a com base nas revisões criadas após a mudança de vinculação.

As revisões arquivadas continuam acessíveis pela API, e o ReasoningEngineSpec completo delas é preservado. Para criar uma revisão equivalente a uma arquivada, receba os detalhes da revisão arquivada e implante uma nova revisão com os mesmos campos versionados. Reutilizar o mesmo URI de imagem de contêiner reproduz o mesmo tempo de execução. Reutilizar o mesmo local de código-fonte e métodos de classe reproduz o mesmo comportamento.

Monitorar revisões

Monitore revisões de atividades e problemas rastreando o número da revisão como metadados nos registros. Consulte Configurar a geração de registros para informações sobre como fazer isso.

Criar uma nova revisão do agente

Para criar uma nova revisão, atualize os campos versionados de um agente implantado. Consulte Atualizar um agente implantado para instruções.

Se você atualizar os campos com controle de versão, uma nova revisão será criada automaticamente. Se você atualizar campos sem versão, o agente será atualizado em todas as revisões atuais sem criar uma nova.

Gerenciar a limpeza de revisões

A Gemini Enterprise Agent Platform remove automaticamente revisões antigas para ajudar você a ficar dentro dos limites. Também é possível excluir revisões manualmente.

Coleta automática de lixo

Por padrão, a Gemini Enterprise Agent Platform ativa a coleta automática de lixo para todos os agentes. Não é possível desativar. A coleta de lixo é executada apenas como parte de uma operação de atualização do agente, não como um job em segundo plano.

• Quando ele é executado:se uma operação de atualização tentar exceder o limite de revisão configurado, a Gemini Enterprise Agent Platform vai excluir as revisões mais antigas qualificadas na mesma operação antes de criar a nova revisão. Se você diminuir o limite, a Gemini Enterprise Agent Platform vai excluir imediatamente revisões qualificadas mais antigas até atingir o novo limite.
• Revisões qualificadas:uma revisão só pode ser excluída se atender a todas as condições a seguir:
  • Ele está no estado ACTIVE.
  • Ela não está incluída na configuração de tráfego (recebe 0% do tráfego).
• Falhas:se não houver revisões qualificadas suficientes para liberar espaço, a Gemini Enterprise Agent Platform vai rejeitar a operação de atualização com um erro FAILED_PRECONDITION. Ele não exclui nem cria uma revisão. Remova as revisões da configuração de tráfego ou aumente o limite antes de tentar novamente.

Configurar o limite

O limite é definido pelo campo revision_garbage_collection_strategy.keep_n_latest.max_revisions no agente. É possível definir esse campo ao criar o agente ou mudá-lo depois com uma solicitação de atualização.

• Padrão para novos agentes:100 revisões.
• Padrão para agentes atuais:950 revisões.
• Intervalo permitido:de 1 a 950. Um valor igual ou menor que 0 é rejeitado. Um valor maior que 950 é rejeitado porque 950 é uma cota fixa que não pode ser aumentada.

Exclusão manual

É possível remover manualmente uma revisão de agente excluindo-a. Só é possível excluir revisões que não estão ativas para gerenciamento de tráfego porque não estão configuradas para receber tráfego. Consulte Configurar a distribuição de tráfego entre revisões para instruções sobre como configurar se uma revisão recebe tráfego.

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