Faça a gestão dos agentes implementados

Esta página descreve como gerir agentes que foram implementados no tempo de execução gerido do Vertex AI Agent Engine. Os agentes implementados são recursos do tipo reasoningEngine no Vertex AI.

Apresente uma lista dos agentes implementados

Apresenta todos os agentes implementados para um determinado projeto e localização:

Consola

  1. Na Google Cloud consola, aceda à página Vertex AI Agent Engine.

    Aceda ao motor do agente

Os agentes implementados que fazem parte do projeto selecionado aparecem na lista. Pode usar o campo Filtrar para filtrar a lista pela coluna especificada.

SDK Vertex AI para Python

import vertexai

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

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

Para filtrar a lista por display_name:

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

REST

Chame o método reasoningEngines.list.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto da GCP
  • LOCATION: uma região suportada

Método HTTP e URL:

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

Modo expresso do Vertex AI

Pode usar o SDK Vertex AI para Python ou o REST com o modo expresso do Vertex AI. Para mais informações sobre o modo expresso do Vertex AI e instruções sobre como se inscrever, consulte a vista geral do Vertex AI no modo expresso.

SDK Vertex AI

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    api_key="API_KEY",
)

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

Substitua API_KEY pela chave da API do modo expresso

Para filtrar a lista por display_name:

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

API REST

O seguinte comando REST chama o método reasoningEngines.list:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • API_KEY: a chave da API do modo expresso

Método HTTP e URL:

GET https://aiplatform.googleapis.com/v1/projects/reasoningEngines?key=API_KEY

Para enviar o seu pedido, expanda uma destas opções:

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

Obtenha um agente implementado

Cada agente implementado tem um identificador RESOURCE_ID exclusivo. Para saber mais, consulte o artigo Implemente um agente.

Consola

  1. Na Google Cloud consola, aceda à página Vertex AI Agent Engine.

    Aceda ao motor do agente

    Os agentes implementados que fazem parte do projeto selecionado aparecem na lista. Pode usar o campo Filtrar para filtrar a lista pela coluna especificada.

  2. Clique no nome do agente especificado. É apresentada a página Métricas do agente.

  3. (Opcional) Para ver os detalhes da implementação do agente, clique em Detalhes da implementação. É aberto o painel Detalhes da implementação. 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 é aberto. Para fechar o painel, clique em Concluído.

SDK Vertex AI para Python

O código seguinte permite-lhe obter um agente implementado específico:

import vertexai

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

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

REST

Chame o método reasoningEngines.get.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto da GCP
  • LOCATION: uma região suportada
  • RESOURCE_ID: o ID do recurso do agente implementado

Método HTTP e URL:

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

Modo expresso do Vertex AI

Pode usar o SDK Vertex AI para Python ou a API REST com o modo expresso do Vertex AI. Para mais informações sobre o modo expresso do Vertex AI e instruções sobre como se inscrever, consulte a vista geral do Vertex AI no modo expresso.

SDK Vertex AI

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    api_key="API_KEY",
)

remote_agent = client.agent_engines.get(
    name="RESOURCE_NAME"
)
# Resource Name: "projects/{PROJECT_NUMBER}/locations/{LOCATION}/reasoningEngines/{RESOURCE_ID}"
# RESOURCE_ID can be used for the REST commands

Substitua API_KEY pela chave da API do modo expresso

API REST

O seguinte comando REST chama o método reasoningEngines.get:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • RESOURCE_ID: o ID do recurso do agente implementado
  • API_KEY: a chave da API do modo expresso

Método HTTP e URL:

GET https://aiplatform.googleapis.com/v1/reasoningEngines/RESOURCE_ID?key=API_KEY

Para enviar o seu pedido, expanda uma destas opções:

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

Atualize um agente implementado

Pode atualizar um ou mais campos do agente implementado em simultâneo, mas tem de especificar, pelo menos, um dos campos a atualizar. O tempo necessário para atualizar o agente implementado depende da atualização que está a ser realizada, mas geralmente demora entre alguns segundos e alguns minutos.

Consola

  1. Na Google Cloud consola, aceda à página Vertex AI Agent Engine.

    Aceda ao motor do agente

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

  3. Clique em Edit. É aberto o painel Editar do agente.

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

  5. Clique em Guardar.

SDK Vertex AI para Python

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

import vertexai

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

client.agent_engines.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 que quando implementa um agente.

REST

Chame o método reasoningEngines.patch e forneça um update_mask para especificar os campos a atualizar.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto da GCP
  • LOCATION: uma região suportada
  • RESOURCE_ID: o ID do recurso do agente implementado
  • update_mask: uma lista de campos separados por vírgulas a 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 do pedido:

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

Modo expresso do Vertex AI

Pode usar o SDK Vertex AI para Python ou a API REST com o modo expresso do Vertex AI. Para mais informações sobre o modo expresso do Vertex AI e instruções sobre como se inscrever, consulte a vista geral do Vertex AI no modo expresso.

SDK Vertex AI

O código seguinte usa o SDK Vertex AI para Python para atualizar um agente implementado (correspondente a RESOURCE_NAME) para um agente atualizado (correspondente a UPDATED_AGENT):

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    api_key="API_KEY",
)

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

Substitua API_KEY pela chave da API do modo expresso

API REST

O seguinte comando REST chama o método reasoningEngines.patch e fornece um update_mask para especificar os campos a atualizar:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • RESOURCE_ID: o ID do recurso do agente implementado
  • API_KEY: a chave da API do modo expresso
  • update_mask: uma lista de campos separados por vírgulas a atualizar

Método HTTP e URL:

PATCH https://aiplatform.googleapis.com/v1/reasoningEngines/RESOURCE_ID?update_mask="display_name,description"&key=API_KEY

Corpo JSON do pedido:

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

Configure a telemetria para o agente implementado

Se ativou os rastreios durante o desenvolvimento do agente, pode usar a consola Google Cloud para configurar a telemetria para o agente implementado.

Configure a telemetria para agentes implementados com a telemetria ativada:

  1. Na Google Cloud consola, aceda à página Vertex AI Agent Engine.

    Aceda ao motor do agente

    As instâncias do Agent Engine que fazem parte do projeto selecionado aparecem na lista. Pode usar o campo Filtrar para filtrar a lista pela coluna especificada.

  2. Encontre a linha da sua instância do Agent Engine. Na coluna Configuração da telemetria, clique em Configurar. É aberto o painel Configuração do serviço.

  3. Pode fazer as seguintes configurações:

    • Observabilidade: pode configurar o seguinte:

      • Ativar a instrumentação de registos e rastreios do OpenTelemetry: para preencher o painel de controlo de observabilidade do agente e as páginas de rastreios, clique no botão ativar/desativar para a posição ativada.

      • Ativar o registo de entradas de comandos e resultados de respostas: para recolher e armazenar o conteúdo completo dos comandos e das respostas dos utilizadores, clique no botão para o ativar.

      Se a recolha de telemetria estiver desativada para o seu agente, tem de voltar a implementar o agente e atualizar a versão do SDK Vertex AI para >= 1.126.1 para ver as opções de configuração da observabilidade.

    • Contentores: configure as definições do contentor para o agente implementado:

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

      • Recursos: selecione limites para Memória e CPU para cada contentor.

      • Concorrência de contentores: introduza um Número mínimo de instâncias para definir a concorrência para cada contentor e servidor de agente. O valor recomendado é (2 * CPU + 1) e o valor predefinido é 9.

    • Acesso e autorizações: clique em Gerir autorizações na IAM para gerir as autorizações de agente na conta de serviço associada.

    • Detalhes da implementação: veja os detalhes da implementação do agente, incluindo o nome do recurso e o nome a apresentar.

    • Banco de memória: veja os detalhes do banco de memória do agente, incluindo a geração de memória e a pesquisa de memória.

  4. Clique em Atualizar ou Fechar.

Veja as métricas do seu agente implementado

Para agentes implementados, pode usar a consola para ver métricas do seu agente:

  1. Na Google Cloud consola, aceda à página Vertex AI Agent Engine.

    Aceda ao motor do agente

    Os agentes implementados que fazem parte do projeto selecionado aparecem na lista. Pode usar o campo Filtrar para filtrar a lista pela coluna especificada.

  2. Clique no nome do agente. O painel de controlo é apresentado para o agente selecionado.

  3. Selecione um dos seguintes separadores do Painel de controlo:

    • Vista geral: veja um painel de controlo de resumo das métricas do seu agente, incluindo a latência do agente, a contagem de pedidos do agente e a taxa de erros do agente.

    • Modelos: veja um painel de controlo de métricas para o modelo do seu agente, incluindo o número de chamadas do modelo, a taxa de erro do modelo e a utilização de tokens do modelo.

    • Ferramentas: veja um painel de controlo de métricas para as ferramentas do seu agente, incluindo o número de chamadas de ferramentas, a taxa de erros de ferramentas e a latência das ferramentas.

    • Utilização: veja um painel de controlo de métricas para a utilização do seu agente, incluindo a utilização de tokens por entrada e saída, a atribuição de CPU do contentor e a atribuição de memória do contentor.

    • Registos: veja os registos do seu agente, se ativou o Cloud Logging para o seu agente.

Painel de controlo do Vertex AI Agent Engine

Elimine um agente implementado

Elimine um agente implementado do tempo de execução gerido do Vertex AI Agent Engine.

Consola

  1. Na Google Cloud consola, aceda à página Vertex AI Agent Engine.

    Aceda ao motor do agente

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

  3. Clique em Eliminar.

  4. Clique em Eliminar agente.

SDK Vertex AI para Python

Se já tiver uma instância existente do agente implementado (como remote_agent), pode executar o seguinte comando:

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

Em alternativa, pode chamar agent_engines.delete() para eliminar o agente implementado correspondente a RESOURCE_NAME da seguinte forma:

import vertexai

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

client.agent_engines.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 qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto da GCP
  • LOCATION: uma região suportada
  • RESOURCE_ID: o ID do recurso do agente implementado

Método HTTP e URL:

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

Modo expresso do Vertex AI

Pode usar o SDK Vertex AI para Python ou a API REST com o modo expresso do Vertex AI.

SDK Vertex AI

O código seguinte usa o SDK do Vertex AI para Python para eliminar o agente implementado correspondente a RESOURCE_NAME da seguinte forma:

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    api_key="API_KEY",
)

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

Substitua API_KEY pela chave da API do modo expresso

API REST

O seguinte comando REST chama o método reasoningEngines.delete:

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • RESOURCE_ID: o ID do recurso do agente implementado
  • API_KEY: a chave da API do modo expresso

Método HTTP e URL:

DELETE https://aiplatform.googleapis.com/v1/projects/reasoningEngines/RESOURCE_ID?key=API_KEY

Para enviar o seu pedido, expanda uma destas opções:

Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

O que se segue?