Resolver problemas de implantação de um agente

Neste documento, descrevemos como resolver erros que podem ocorrer ao implantar um agente no Agent Runtime. Ele aborda vários problemas comuns, incluindo falhas de serialização, erros de permissão e violações de limites do VPC-SC.

Observação: para pesquisar e filtrar registros de erros do agente, use a Análise de registros, selecione RESOURCE TYPE para "Vertex AI Reasoning Engine" e escolha o valor RESOURCE CONTAINER correspondente (ou seja, o número do projeto) e o valor REASONING ENGINE ID.

Erros no modelo predefinido

Ao encontrar erros no modelo LangchainAgent durante a implantação, isso pode ser devido a um dos problemas nesta seção.

Erros internos do servidor

Problema:

Você recebe uma mensagem de erro semelhante a esta:

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

Infelizmente, esse é um erro geral relacionado a problemas com o contêiner no ambiente de execução, e a causa possível pode consistir em muitos erros diferentes.

Causas possíveis:

  • Estado sujo em LangchainAgent. Isso pode acontecer quando .set_up() é chamado em um LangchainAgent antes da implantação do agente.
  • Versões de pacote inconsistentes. Isso pode acontecer quando os pacotes instalados no ambiente de desenvolvimento são diferentes daqueles instalados no ambiente remoto no Agent Runtime.

Soluções recomendadas:

  • Estado sujo em LangchainAgent. Crie outra instância de LangchainAgent ou remova agent.set_up() do código antes de implantar o agente.
  • Especificações de pacote inconsistentes. Consulte a seção sobre como solucionar problemas de erros de serialização.

Erros de serialização

Em geral, é importante garantir que os ambientes "local" e "remoto" estejam sincronizados ao implantar o agente. Para isso, especifique requirements= ao implantar o agente.

Quando erros ocorrem na serialização (erros relacionados a pickle ou pickling são sinônimos de erros de serialização), isso pode ser devido a um dos problemas descritos nesta seção.

Versão do Pydantic

Problema:

Você recebe uma mensagem de erro semelhante a esta:

PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator

Possível causa:

Isso pode acontecer quando a versão do pacote pydantic é anterior à 2.6.4. Para verificar a versão em uso, execute o seguinte comando no terminal:

pip show pydantic

Solução recomendada:

Atualize o pacote executando o seguinte comando no terminal:

pip install pydantic --upgrade

Execute o seguinte comando no terminal para verificar se você está usando a versão 2.6.4 ou mais recente:

pip show pydantic

No caso de uma instância de notebook (por exemplo, Jupyter, Colab ou Workbench), talvez seja necessário reiniciar o ambiente de execução para usar os pacotes atualizados.

Versão do Cloudpickle

Problema:

Você recebe uma mensagem de erro semelhante a esta:

AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>

Possível causa:

Isso pode acontecer quando a versão do pacote cloudpickle é diferente nos ambientes de desenvolvimento e de implantação. Para verificar qual versão você está usando no ambiente de desenvolvimento, execute o seguinte comando no terminal:

pip show cloudpickle

Solução recomendada:

Implante a mesma versão do Cloudpickle nos dois ambientes, como o ambiente de desenvolvimento local e o agente implantado remotamente, especificando requirements= ao implantar o agente.

Erros internos do servidor

Problema:

Você recebe uma mensagem de erro semelhante a esta:

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

Possível causa:

Isso pode acontecer quando sys_version= é diferente do ambiente de desenvolvimento ao implantar o agente.

Solução recomendada:

Depois de implantar o agente, considere remover sys_version= dos argumentos de entrada. Se você ainda tiver problemas, envie um relatório de bug.

Erros de bucket do Cloud Storage

Em caso de erros no bucket de preparação do Cloud Storage usado no momento da implantação para coletar e fazer upload do agente, isso pode ser devido a um dos seguintes problemas:

Erros de permissão

Solução recomendada:

Para usar um bucket atual: verifique se o principal autenticado para usar a plataforma de agentes (você ou uma conta de serviço) tem acesso Storage Admin ao bucket e conceda permissões à conta de serviço.

Como alternativa, é possível especificar um novo bucket ao implantar o agente e o SDK vai criar o bucket com as permissões necessárias.

Se você ainda tiver problemas, envie um relatório de bug.

O subdiretório do bucket do Cloud Storage não foi criado

Problema:

Você recebe uma mensagem de erro semelhante a esta:

NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.

O erro 404 ocorre quando o sistema tenta fazer uma cópia em uma pasta que não existe.

Possível causa:

Isso provavelmente se deve a um problema com a interpolação de strings em versões de google-cloud-aiplatform anteriores à 1.49.0. Isso foi corrigido em versões mais recentes. Para verificar qual versão de google-cloud-aiplatform você está usando, execute o seguinte comando no terminal:

pip show google-cloud-aiplatform

Solução recomendada:

Atualize o pacote executando o seguinte comando no terminal:

pip install google-cloud-aiplatform --upgrade

Verifique se você está usando a versão 1.49.0 ou mais recente de google-cloud-aiplatform executando o seguinte comando no terminal:

pip show google-cloud-aiplatform

No caso de uma instância de notebook (por exemplo, Jupyter, Colab ou Workbench), talvez seja necessário reiniciar o ambiente de execução para usar os pacotes atualizados.

Erros de violação do VPC-SC

Se você estiver com problemas com o VPC-SC, um dos seguintes problemas pode ser a causa:

Erros de permissão

Problema:

Você recebe uma mensagem de erro semelhante a esta:

Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.

ou

Request is prohibited by organization's policy.

Possível causa:

Isso provavelmente é causado pela falta de regras de entrada obrigatórias no perímetro do VPC-SC.

Solução recomendada:

Se você usar a Agent Platform em um ambiente do VPC-SC, será necessário criar uma regra de entrada no perímetro para permitir a entrada do agente de serviço do Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) nos serviços storage.googleapis.com e artifactregistry.googleapis.com.

Erros de conta de serviço personalizadas

Se você estiver com problemas nas contas de serviço, um dos seguintes problemas pode ser a causa:

Agir como conta de serviço

Problema:

Você recebe uma mensagem de erro semelhante a esta:

You do not have permission to act as service_account.

Possível causa:

Talvez você não tenha a permissão iam.serviceAccounts.actAs na conta de serviço personalizada usada para implantação. Em um sistema multiagente com várias contas de serviço personalizadas, um autor ou implantador de agente pode atuar como algumas das contas de serviço. Se você estiver usando a conta de serviço errada, esse erro será o comportamento esperado.

Além disso, esse erro pode ocorrer se a conta de serviço personalizada estiver em um projeto diferente daquele em que você implanta o agente, e a política da organização iam.disableCrossProjectServiceAccountUsage estiver aplicada no projeto da conta de serviço.

Consulte Conta de serviço personalizada entre projetos para conferir a lista completa de configurações necessárias para esse cenário.

Solução recomendada:

Verifique se você está usando a conta de serviço correta. Verifique se você tem o papel de Usuário da conta de serviço (roles/iam.serviceAccountUser) nessa conta de serviço. Caso contrário, peça ao administrador para conceder a você o papel nessa conta de serviço.

Se você estiver no cenário entre projetos, verifique se o projeto da conta de serviço tem a política da organização iam.disableCrossProjectServiceAccountUsage aplicada. Se for esse o caso, peça para o admin desativar a política.

Servidor de metadados indisponível

Problema:

Você recebe uma mensagem de erro semelhante a esta:

ServiceUnavailable: 503 Getting metadata from plugin failed with error

ou

Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token

Possível causa:

Isso pode acontecer se a conta de serviço personalizada e o agente estiverem em projetos diferentes e o agente de serviço do mecanismo de raciocínio do AI Platform não tiver a permissão iam.serviceAccounts.getAccessToken na conta de serviço personalizada.

Consulte Conta de serviço personalizada entre projetos para conferir a lista completa de configurações necessárias para esse cenário.

Solução recomendada:

Peça ao administrador para conceder ao agente de serviço do mecanismo de raciocínio do AI Platform do projeto do agente o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) na conta de serviço personalizada.

O agente de serviço do AI Platform Reasoning Engine precisa estar no mesmo projeto usado para implantar o agente. A vinculação do IAM da concessão de papel precisa estar no projeto em que a conta de serviço personalizada reside.

Erros de recurso esgotado ou de limite de taxa (erro 429)

Problema:

A implantação falha com um status Error 429 ou RESOURCE_EXHAUSTED.

Possível causa:

O projeto excedeu os limites de taxa de API ou as cotas de solicitações simultâneas.

Soluções recomendadas:

  • Implemente uma estratégia de espera exponencial e de novas tentativas nos scripts de implantação.
  • Verifique o uso atual em relação aos limites na página Google Cloud Cotas da "API Agent Platform".
  • Reduza a frequência de implantações simultâneas.

Região temporariamente na capacidade máxima

Problema:

A implantação falha com um status 429, RESOURCE_EXHAUSTED e uma mensagem informando que a região está temporariamente na capacidade máxima para uma quantidade total permitida de memória ou CPU.

Possível causa:

As implantações de agentes em uma região usam um pool de capacidade de veiculação que o Agent Runtime gerencia em seu nome e que todos os clientes nessa região compartilham. Quando o pool se esgota, novas implantações nessa região falham até que a capacidade seja liberada.

Esse limite não é uma das cotas do seu projeto. Ela não aparece na páginaGoogle Cloud Cotas e não pode ser aumentada com uma solicitação de aumento de cota.

Soluções recomendadas:

  • Implante em outra região com disponibilidade. Essa é a maneira mais rápida de desbloquear um implantação.
  • Tente de novo mais tarde. Uma região com capacidade total é um problema temporário que geralmente se resolve sozinho.
  • Solicite uma quantidade menor de memória ou CPU para seu agente. Uma implantação menor pode caber na capacidade restante.
  • Entre em contato com o suporte se as implantações em uma região continuarem falhando dessa forma. Embora não seja possível aumentar o limite, seus relatórios nos ajudam a direcionar a capacidade para onde ela é necessária.

Soluções que não se aplicam:

  • Excluir os agentes atuais não libera capacidade para esse limite, porque a capacidade não é consumida apenas pelo seu projeto.
  • Solicitar um aumento de cota não tem efeito porque o limite não é uma cota do projeto.

O número máximo de instâncias excede o limite regional

Problema:

A implantação falha com um status 429, RESOURCE_EXHAUSTED e uma mensagem informando que spec.deployment_spec.max_instances excede o número máximo de instâncias compatíveis com a CPU ou memória solicitada no resource_limits da região.

Possível causa:

Ao implantar um agente, o Agent Runtime multiplica spec.deployment_spec.max_instances pelo cpu e memory por instância em spec.deployment_spec.resource_limits e verifica se a alocação de pico desse único agente se encaixa no limite regional do projeto de serviço subjacente. Se você não especificar max_instances, o Agent Runtime vai aplicar um valor padrão (como 200), que, em regiões com limites mais baixos, pode exceder o máximo de instâncias compatíveis quando multiplicado pelo cpu ou memory configurado por instância.

Soluções recomendadas:

  • Defina spec.deployment_spec.max_instances como o valor máximo mostrado na mensagem de erro (ou menos).
  • Reduza o valor cpu ou memory por instância em spec.deployment_spec.resource_limits.
  • Implante o agente em outra região com disponibilidade compatível com um limite maior.

Soluções que não se aplicam:

  • Solicitar um aumento de cota na página Google Cloud Cotas do seu projeto não tem efeito, porque esse limite é aplicado no projeto de veiculação gerenciado pelo Google, e não no seu projeto.
  • Excluir outros agentes no projeto ou tentar de novo sem mudar max_instances ou resource_limits não resolve esse erro, porque a verificação avalia o pico de alocação da implantação única em relação a um limite estático.

Erros de acesso do Secret Manager

Problema:

A implantação falha com um status 400, INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED) e uma mensagem semelhante a esta:

The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).

Possíveis causas:

  • NOT_FOUND: o ID ou a versão do secret especificados em secret_env não existem no Secret Manager no mesmo projeto do agente implantado ou contêm um erro de digitação.
  • DESTROYED ou DISABLED: a versão do secret referenciada no Secret Manager está destruída ou desativada.
  • PERMISSION_DENIED: a conta de serviço usada pelo agente não tem o papel de acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) no secret referenciado.

Soluções recomendadas:

  • Para NOT_FOUND, DESTROYED ou DISABLED:
    1. Na página do Secret Manager do projeto em que você está implantando o agente, verifique se cada SECRET_ID e VERSION_ID referenciado em secret_env existe e está no estado Ativado.
    2. Se uma versão referenciada foi desativada ou destruída, ative uma versão válida ou atualize secret_env para referenciar uma versão ativada.
  • Para PERMISSION_DENIED: conceda o papel Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) no secret (ou no projeto que contém o secret) à conta de serviço que busca o secret:
    • Conta de serviço padrão: conceda o papel ao agente de serviço do mecanismo de raciocínio do AI Platform (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com).
    • Conta de serviço personalizada: conceda o papel à conta de serviço personalizada configurada no agente.

Recursos de suporte

Se o problema ainda não for resolvido, consulte nosso guia de suporte para receber ajuda.