Gerenciar agentes implantados

O Agent Runtime permite gerenciar agentes que foram implantados na plataforma. É possível listar, receber, atualizar e excluir agentes implantados usando o console, o SDK ou a API REST.

Este documento explica como gerenciar agentes implantados na Agent Platform. Se você quiser implantar um novo agente, consulte Implantar um agente.

Listar agentes implantados

Liste todos os agentes implantados em um determinado projeto e local:

Console

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    Acessar "Implantações"

Os agentes implantados que fazem parte do projeto selecionado aparecem na lista (as instâncias independentes do Memory Bank sem um ambiente de execução implantado aparecem na página Memory Bank). Use o campo Filtro para filtrar a lista pela coluna especificada.

SDK da plataforma de agentes

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

for agent in client.runtimes.list():
    print(agent)

Para filtrar a lista por display_name:

for agent in client.runtimes.list(
    config={
        "filter": 'display_name="DISPLAY_NAME"',
    },
):
    print(agent)

REST

Chame o método reasoningEngines.list.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: ID do projeto do GCP
  • LOCATION: uma região com disponibilidade

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines

Para enviar a solicitação, expanda uma destas opções:

Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

Receber um agente implantado

Cada agente implantado tem um identificador RESOURCE_ID exclusivo. Para saber mais, consulte Implantar um agente.

Console

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    Acessar "Implantações"

    Os agentes implantados que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

  2. Clique no nome do agente especificado. A página Métricas do agente é aberta.

  3. Opcional: para ver os detalhes da implantação do agente, clique em Detalhes da implantação. O painel Detalhes da implantação é aberto. Para fechar o painel, clique em Concluído.

  4. Opcional: para ver os URLs query e streamQuery do agente, clique em URLs da API. O painel URLs da API será aberto. Para fechar o painel, clique em Concluído.

SDK da plataforma de agentes

O código a seguir permite receber um agente implantado específico:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

remote_agent = client.runtimes.get(
    name="projects/PROJECT_ID_OR_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

REST

Chame o método reasoningEngines.get.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: ID do projeto do GCP
  • LOCATION: uma região com disponibilidade
  • RESOURCE_ID: o ID do recurso do agente implantado.

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

Atualizar um agente implantado

É possível atualizar um ou mais campos do agente implantado ao mesmo tempo, mas é necessário especificar pelo menos um dos campos a serem atualizados.

É possível atualizar os campos com ou sem versão de um agente implantado. Se você atualizar os campos com controle de versão, uma nova revisão será criada. Para mais informações sobre campos com controle de versão e gerenciamento de revisões, consulte Gerenciar revisões e tráfego.

O tempo necessário para atualizar o agente implantado depende da atualização que está sendo realizada, mas geralmente leva de alguns segundos a alguns minutos.

Console

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    Acessar "Implantações"

  2. Para o agente especificado, clique no menu mais ações ().

  3. Clique em Editar. O painel Editar do agente é aberto.

  4. Edite o Nome de exibição ou a Descrição do agente.

  5. Clique em Salvar.

SDK da plataforma de agentes

Para atualizar um agente implantado (correspondente a RESOURCE_NAME) para um agente atualizado (correspondente a UPDATED_AGENT):

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

client.runtimes.update(
    name=RESOURCE_NAME,                    # Required.
    agent=UPDATED_AGENT,                   # Optional.
    config={                                                # Optional.
        "requirements": REQUIREMENTS,      # Optional.
        "display_name": "DISPLAY_NAME",    # Optional.
        "description": "DESCRIPTION",      # Optional.
        "extra_packages": EXTRA_PACKAGES,  # Optional.
    },
)

Os argumentos são os mesmos de quando você implanta um agente.

REST

Chame o método reasoningEngines.patch e forneça um update_mask para especificar quais campos serão atualizados.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: ID do projeto do GCP
  • LOCATION: uma região com disponibilidade
  • RESOURCE_ID: o ID do recurso do agente implantado.
  • update_mask: uma lista de campos separados por vírgulas para atualizar.

Método HTTP e URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask="display_name,description"

Corpo JSON da solicitação:

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION"
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

Configurar a telemetria para o agente implantado

Se você ativou os traces durante o desenvolvimento do agente, use o console do Google Cloud para configurar a telemetria do agente implantado.

Configure a telemetria para agentes implantados com a telemetria ativada:

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    Acessar "Implantações"

    As instâncias da Agent Platform que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

  2. Encontre a linha da sua instância da Agent Platform. Na coluna Configuração de telemetria, clique em Configurar. O painel Configurações de serviço é aberto.

  3. Você pode fazer as seguintes configurações:

    • Observabilidade: é possível configurar o seguinte:

      • Ativar a instrumentação de traces e registros do OpenTelemetry: para preencher o painel de observabilidade do agente e as páginas de traces, clique no botão para a posição ativada.

      • Ativar a geração de registros de entradas de comandos e saídas de respostas: para coletar e armazenar o conteúdo completo dos comandos e respostas dos usuários, clique no botão para ativar.

      Se a coleta de telemetria estiver desativada para seu agente, será necessário reimplantar o agente e atualizar a versão do SDK da Vertex AI para >= 1.126.1 para ver as opções de configuração de Observabilidade.

    • Contêineres: defina as configurações do contêiner para o agente implantado:

      • Escalonamento: insira um Número mínimo de instâncias e um Número máximo de instâncias.

      • Recursos: selecione limites de Memória e CPU para cada contêiner.

      • Simultaneidade de contêiner: insira um Número mínimo de instâncias para definir a simultaneidade de cada contêiner e servidor de agente. O valor recomendado é (2 * CPU + 1), e o valor padrão é 9.

    • Acesso e permissões: clique em Gerenciar permissões no IAM para gerenciar as permissões do agente na conta de serviço associada.

    • Detalhes da implantação: confira os detalhes da implantação do agente, incluindo o Nome do recurso e o Nome de exibição.

    • Banco de memória: confira e edite as configurações de geração, recuperação e retenção do banco de memória para o agente. A edição requer a permissão aiplatform.reasoningEngines.update. Sem essa permissão, essas configurações são somente leitura.

  4. Clique em Atualizar ou Fechar.

Ver métricas do agente implantado

Para agentes implantados, use o console para conferir as métricas do seu agente:

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    Acessar "Implantações"

    Os agentes implantados que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.

  2. Clique no nome do agente. O Painel é exibido para o agente selecionado.

  3. Selecione uma das seguintes guias do Painel:

    • Visão geral: confira um painel de resumo das métricas do seu agente, incluindo latência, contagem de solicitações e taxa de erros.

    • Modelos: confira um painel de métricas do modelo do agente, incluindo o número de chamadas, a taxa de erro e o uso de tokens do modelo.

    • Ferramentas: confira um painel de métricas das ferramentas do agente, incluindo o número de chamadas de ferramenta, a taxa de erro da ferramenta e a latência da ferramenta.

    • Uso: confira um painel de métricas de uso do agente, incluindo o uso de tokens por entrada e saída, a alocação de CPU do contêiner e a alocação de memória do contêiner.

    • Registros: confira os registros do agente, se você ativou o Cloud Logging para ele.

Painel da Gemini Enterprise Agent Platform

Parada de emergência e revogação de acesso

Quando um agente implantado se comporta de maneira inesperada, exibe um uso anômalo de ferramentas ou está envolvido em um incidente de segurança, é possível interromper a atividade dele encerrando ou redirecionando a instância de ambiente de execução ou revogando o acesso downstream por meio de controles de política no Gateway de Agente e no Identity and Access Management (IAM) (IAM).

Como as operações de ambiente de execução e as atualizações de política têm modelos de aplicação e janelas de propagação diferentes, escolha o controle que corresponde aos requisitos de tempo de resposta a incidentes.

Mecanismos de parada de emergência e tempos de propagação

A tabela a seguir compara os mecanismos disponíveis para interromper um agente ou revogar o acesso dele, o impacto no tráfego ativo e os tempos de propagação esperados:

Mecanismo Efeito no tráfego e nas sessões ativos Tempo de propagação típico
Excluir o agente implantado (runtimes.delete ou reasoningEngines.delete) Encerra todas as instâncias de contêiner do ambiente de execução, interrompe as invocações ativas e as sessões de streaming (streamQuery) e invalida permanentemente a identidade SPIFFE do agente (principal://...). Imediata, assim que a operação de exclusão é concluída (normalmente, de segundos a alguns minutos).
Redirecionar o tráfego de revisão ou arquivar revisões (trafficSplitManual ou agent_gateway_config) Muda 100% do tráfego enviado ao Agent Endpoint raiz para uma revisão ativa conhecida como boa ou arquiva as revisões atuais ao atualizar spec.deployment_spec.agent_gateway_config. As solicitações diretas para um caminho de recurso de revisão ativa específico continuam até que essa revisão seja arquivada ou excluída. De segundos a alguns minutos para que a operação de atualização seja concluída.
Aplicar uma regra de negação nas políticas de acesso unificadas (UAPs) no Gateway de Agente (iamEnforcementMode: "ENFORCE") Bloqueia chamadas de ferramentas de saída, solicitações do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) e chamadas de agente para agente roteadas pelo Gateway de Agente, mantendo o contêiner de ambiente de execução ativo para inspeção. Avaliado em novas verificações de autorização. Não encerra as conexões de streaming abertas, a menos que sejam autorizadas novamente. Consistência posterior: geralmente entra em vigor em até 2 minutos, mas pode levar 7 minutos ou mais para se propagar globalmente. As atualizações de associação de grupos ou principalSet podem levar de vários minutos a horas para serem sincronizadas.
Aplicar uma política de negação do IAM, revogar papéis do IAM ou vincular uma política de limite de acesso de principal Bloqueia a identidade do agente ou a conta de serviço anexada de chamar APIs e recursos do Google Cloud . Avaliado em cada solicitação de API. Não encerra o contêiner de ambiente de execução. Consistência posterior: geralmente entra em vigor em até 2 minutos, mas pode levar até 7 minutos ou mais (consulte Propagação de mudança de acesso).

Fazer uma parada de emergência

Para interromper imediatamente um agente comprometido ou com comportamento inadequado e evitar outras ações downstream, siga estas etapas:

  1. Interromper a execução do ambiente de execução ativo ou isolar o tráfego:
    • Encerramento total (kill switch): para interromper imediatamente todos os contêineres em execução e invalidar a identidade SPIFFE do agente, exclua o agente implantado usando o console do Google Cloud , client.runtimes.delete(name="RESOURCE_NAME", force=True) no SDK da plataforma de agentes ou o método REST reasoningEngines.delete.
    • Reversão de tráfego sem excluir o agente: para preservar o recurso do agente e a identidade dele ao interromper o tráfego para uma revisão com falha, atualize o agente com trafficSplitManual para rotear 100% do tráfego raiz para uma revisão em boas condições ou atualize spec.deployment_spec.agent_gateway_config para arquivar revisões pré-existentes. Se os autores de chamada invocarem um caminho de recurso de revisão diretamente, exclua ou arquive essa revisão específica. Para instruções, consulte Gerenciar revisões e tráfego.
  2. Revogar o acesso a ferramentas e recursos downstream:
  3. Considere as janelas de propagação e verifique a contenção:
    • Quando um agente estiver executando ativamente chamadas de ferramentas não intencionais, não dependa apenas de uma atualização de política do IAM ou da UAP. As mudanças na política levam de 2 a 7 minutos (ou mais para atualizações de principalSet) para serem propagadas globalmente. Sempre combine a revogação da política com a exclusão do ambiente de execução ou o redirecionamento do tráfego da revisão para conseguir uma interrupção imediata.
    • Confirme se a atividade do agente foi interrompida consultando o Cloud Logging para ver as negações de is_agentic=true e networkservices.googleapis.com/gateway_requests. Para detalhes sobre a ingestão de registros e a latência de descoberta de segurança, consulte Auditoria de ações do agente e Monitorar o tráfego pelo Gateway de Agente.

Excluir um agente implantado

Excluir um agente implantado do ambiente de execução gerenciado do Agent Runtime. A exclusão do Agent Runtime invalida a identidade do agente. Qualquer política de acesso unificado (UAP, na sigla em inglês) do IAM que conceda permissões a esse principal mantém o principal desativado nas regras. Além disso, a vinculação de política permanece ativa. Para remover um principal desativado, atualize a UAP para remover o principal das regras dela. Se a política não tiver mais principais ativos, exclua a vinculação de política.

Console

  1. No console do Google Cloud , acesse a página Implantações da plataforma de agentes.

    Acessar "Implantações"

  2. Para o agente especificado, clique no menu mais ações ().

  3. Clique em Excluir.

  4. Clique em Excluir agente.

SDK da plataforma de agentes

Se você já tiver uma instância do agente implantado (como remote_agent), execute o seguinte comando:

remote_agent.delete(
    force=True, # Optional, if the agent has resources (e.g. sessions, memory)
)

Como alternativa, é possível chamar runtimes.delete() para excluir o agente implantado correspondente a RESOURCE_NAME da seguinte maneira:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

client.runtimes.delete(
    name=RESOURCE_NAME,
    force=True, # Optional, if the agent has resources (e.g. sessions, memory)
)

REST

Chame o método reasoningEngines.delete.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: ID do projeto do GCP
  • LOCATION: uma região com disponibilidade
  • RESOURCE_ID: o ID do recurso do agente implantado.

Método HTTP e URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

Para enviar a solicitação, expanda uma destas opções:

Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

A seguir

Guia

Usar um agente com o ambiente de execução da plataforma de agentes.