Gerenciar agentes implantados

Nesta página, descrevemos como gerenciar agentes implantados no ambiente de execução gerenciado do Vertex AI Agent Engine. Os agentes implantados são recursos do tipo reasoningEngine na Vertex AI.

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 Vertex AI Agent Engine.
   

   Acessar o Agent Engine

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

SDK da Vertex AI para Python

Observação: consulte o guia de migração do Agent Engine para instruções de migração para o SDK da Vertex AI para Python baseado em cliente se você ainda estiver em uma versão do google-cloud-aiplatform anterior a 1.112.0.

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 os dados da solicitação abaixo, faça as substituições a seguir:

• PROJECT_ID: ID do projeto do GCP
• LOCATION: uma região compatível

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:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines" | Select-Object -Expand Content

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

Modo express da Vertex AI

É possível usar o SDK da Vertex AI para Python ou REST com o modo express da Vertex AI. Para mais informações sobre o modo rápido da Vertex AI e instruções de como se inscrever, consulte a Visão geral do modo rápido da Vertex AI.

SDK da 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 de 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 comando REST a seguir chama o método reasoningEngines.list:

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

• API_KEY: sua chave de API do modo expresso

Método HTTP e URL:

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

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

curl (Linux, macOS ou Cloud Shell)

Execute o seguinte comando:

curl -X GET \
     "https://aiplatform.googleapis.com/v1/projects/reasoningEngines?key=API_KEY"

PowerShell (Windows)

Execute o seguinte comando:

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://aiplatform.googleapis.com/v1/projects/reasoningEngines?key=API_KEY" | Select-Object -Expand Content

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 Vertex AI Agent Engine.
   

   Acessar o Agent Engine

   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 conferir os detalhes da implantação do agente, clique em Detalhes da implantação. O painel Detalhes da implantação será aberto. Para fechar o painel, clique em Concluído.

4. (Opcional) Para conferir 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 Vertex AI para Python

Observação: consulte o guia de migração do Agent Engine para instruções de migração para o SDK da Vertex AI para Python baseado em cliente se você ainda estiver em uma versão do google-cloud-aiplatform anterior a 1.112.0.

O código a seguir permite receber um agente implantado 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 os dados da solicitação abaixo, faça as substituições a seguir:

• PROJECT_ID: ID do projeto do GCP
• LOCATION: uma região compatível
• 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:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID" | Select-Object -Expand Content

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

Modo express da Vertex AI

É possível usar o SDK da Vertex AI para Python ou REST com o modo expresso da Vertex AI. Para mais informações sobre o modo rápido da Vertex AI e instruções de como se inscrever, consulte a Visão geral do modo rápido da Vertex AI.

SDK da 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 de API do modo expresso.

API REST

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

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

• RESOURCE_ID: o ID do recurso do agente implantado
• API_KEY: sua chave de API do modo expresso

Método HTTP e URL:

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

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

curl (Linux, macOS ou Cloud Shell)

Execute o seguinte comando:

curl -X GET \
     "https://aiplatform.googleapis.com/v1/reasoningEngines/RESOURCE_ID?key=API_KEY"

PowerShell (Windows)

Execute o seguinte comando:

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://aiplatform.googleapis.com/v1/reasoningEngines/RESOURCE_ID?key=API_KEY" | Select-Object -Expand Content

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. 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 Vertex AI Agent Engine.
   

   Acessar o Agent Engine

2. No 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 Vertex AI para Python

Observação: consulte o guia de migração do Agent Engine para instruções de migração para o SDK da Vertex AI para Python baseado em cliente se você ainda estiver em uma versão do google-cloud-aiplatform anterior a 1.112.0.

Para atualizar um agente implantado (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 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 compatível
• RESOURCE_ID: o ID do recurso do agente implantado
• update_mask: uma lista de campos separados por vírgulas a serem atualizados

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:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask="display_name,description""

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask="display_name,description"" | Select-Object -Expand Content

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

Modo express da Vertex AI

É possível usar o SDK da Vertex AI para Python ou REST com o modo express da Vertex AI. Para mais informações sobre o modo rápido da Vertex AI e instruções de como se inscrever, consulte a Visão geral do modo rápido da Vertex AI.

SDK da Vertex AI

O código a seguir usa o SDK da Vertex AI para Python para atualizar um agente implantado (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 de API do modo expresso.

API REST

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

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

• RESOURCE_ID: o ID do recurso do agente implantado
• API_KEY: sua chave de API do modo expresso
• update_mask: uma lista de campos separados por vírgulas a serem atualizados

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

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

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X PATCH \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/reasoningEngines/RESOURCE_ID?update_mask="display_name,description"&key=API_KEY"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$headers = @{  }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/reasoningEngines/RESOURCE_ID?update_mask="display_name,description"&key=API_KEY" | Select-Object -Expand Content

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

Configurar a telemetria do agente implantado

Se você ativou os rastreamentos 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 Vertex AI Agent Engine.
   

   Acessar o Agent Engine

   As instâncias do Agent Engine 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 do Agent Engine. Na coluna Configuração de telemetria, clique em Configurar. O painel Configuração do serviço é aberto.

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

   • Observabilidade: é possível configurar o seguinte:

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

     • 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 na chave para a posição ativada.

     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 em para ver as opções de configuração da observabilidade.

   • Contêineres: configure as configurações de 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 para Memória e CPU de cada contêiner.

     • Simultaneidade de contêineres: 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 permissões do agente na conta de serviço associada.

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

   • Banco de memória: confira os detalhes do Banco de memória do agente, incluindo Geração de memória e Pesquisa na memória.

4. Clique em Atualizar ou Fechar.

Ver métricas do seu 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 Vertex AI Agent Engine.
   

   Acessar o Agent Engine

   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 do agente selecionado é exibido.

3. Selecione uma das seguintes guias 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 seu agente, incluindo o número de chamadas, a taxa de erros e o uso de tokens.

   • Ferramentas: confira um painel de métricas das ferramentas do seu agente, incluindo número de chamadas de ferramentas, taxa de erros e latência.

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

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

Excluir um agente implantado

Excluir um agente implantado do ambiente de execução gerenciado do Vertex AI Agent Engine.

Console

1. No console do Google Cloud , acesse a página Vertex AI Agent Engine.
   

   Acessar o Agent Engine

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

3. Clique em Excluir.

4. Clique em Excluir agente.

SDK da Vertex AI para Python

Observação: consulte o guia de migração do Agent Engine para instruções de migração para o SDK da Vertex AI para Python baseado em cliente se você ainda estiver em uma versão do google-cloud-aiplatform anterior a 1.112.0.

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, chame agent_engines.delete() para excluir o agente implantado correspondente a RESOURCE_NAME da seguinte maneira:

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 os dados da solicitação abaixo, faça as substituições a seguir:

• PROJECT_ID: ID do projeto do GCP
• LOCATION: uma região compatível
• 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:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Execute o seguinte comando:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID" | Select-Object -Expand Content

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

Modo express da Vertex AI

É possível usar o SDK da Vertex AI para Python ou REST com o modo express da Vertex AI.

SDK da Vertex AI

O código a seguir usa o SDK da Vertex AI para Python para excluir o agente implantado correspondente a RESOURCE_NAME da seguinte maneira:

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 de API do modo expresso.

API REST

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

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

• RESOURCE_ID: o ID do recurso do agente implantado
• API_KEY: sua chave de API do modo expresso

Método HTTP e URL:

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

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

curl (Linux, macOS ou Cloud Shell)

Execute o seguinte comando:

curl -X DELETE \
     "https://aiplatform.googleapis.com/v1/projects/reasoningEngines/RESOURCE_ID?key=API_KEY"

PowerShell (Windows)

Execute o seguinte comando:

$headers = @{  }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://aiplatform.googleapis.com/v1/projects/reasoningEngines/RESOURCE_ID?key=API_KEY" | Select-Object -Expand Content

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

A seguir

• Use um agente.
• Resolver problemas de gerenciamento de agentes implantados.