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 uma variedade de problemas comuns, incluindo falhas de serialização, erros de permissão e violações de limite 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 Mecanismo de raciocínio" e selecione 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 da implantação do 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 locais e remotos 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 no 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ê usa a Agent Platform em um ambiente do VPC-SC, precisa criar uma regra de entrada no perímetro para permitir a entrada do agente de serviço do mecanismo de raciocínio (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) no serviço storage.googleapis.com e no serviço artifactregistry.googleapis.com.

Erros de conta de serviço personalizada

Se você estiver com problemas com 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 é o comportamento esperado.

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

Consulte Conta de serviço personalizada entre projetos para ver 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. Nesse caso, peça para o administrador 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 da plataforma de IA não tiver a permissão iam.serviceAccounts.getAccessToken na conta de serviço personalizada.

Consulte Conta de serviço personalizada entre projetos para ver 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 da plataforma de IA 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 mecanismo de raciocínio da plataforma de IA precisa estar localizado no mesmo projeto que você usa para implantar seu agente. A vinculação do IAM da concessão do papel precisa estar no projeto em que a conta de serviço personalizada reside.

Erros de recurso esgotado ou 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 limitação de taxa de API ou as cotas de solicitações simultâneas.

Soluções recomendadas:

  • Implementar uma estratégia de espera exponencial e nova tentativa nos scripts de implantação.
  • Verifique o uso atual em relação aos limites na página de cotas do Google Cloud para a "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 com a capacidade máxima de memória ou CPU permitida.

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 é compartilhado por todos os clientes nessa região. 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. Ele não aparece na página Google Cloud Cotas e não pode ser aumentado com uma solicitação de aumento de cota.

Soluções recomendadas:

  • Implantar em outra região com disponibilidade. Essa é a maneira mais rápida de desbloquear uma implantação.
  • Tente de novo mais tarde. Uma região com capacidade máxima é um problema temporário que geralmente se resolve sozinho.
  • Solicite uma quantidade menor de memória ou CPU para o agente. Uma implantação menor pode se encaixar na capacidade restante.
  • Entre em contato com o suporte se as implantações em uma região continuarem falhando dessa maneira. Não podemos aumentar o limite, mas 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 ela não é consumida apenas pelo seu projeto.
  • Solicitar um aumento de cota não tem efeito, porque o limite não é uma cota de 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:

Quando você implanta 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 veiculaçã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 de cpu ou memory por instância em spec.deployment_spec.resource_limits.
  • Implante o agente em outra região com disponibilidade que tenha 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 ao projeto de exibição gerenciado pelo Google, e não ao seu projeto.
  • Excluir outros agentes no projeto ou tentar novamente sem alterar max_instances ou resource_limits não resolve esse erro, porque a verificação avalia a alocação de pico 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 à seguinte:

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 do secret ou da versão especificado em secret_env não existe no Secret Manager no mesmo projeto que o agente implantado ou contém um erro de digitação.
  • DESTROYED ou DISABLED: a versão do secret referenciada no Secret Manager está em um estado destruído ou desativado.
  • 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 de 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 da plataforma de IA (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.

O tempo limite da criação da imagem do contêiner foi atingido

Problema:

A implantação falha com um status 504, DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT) e uma mensagem informando que a imagem do contêiner do agente não foi criada a tempo.

Possíveis causas:

Quando você implanta de arquivos de origem, o Agent Runtime cria uma imagem de contêiner que instala seu código e as dependências dele. A implantação falhará se o build ainda estiver em execução quando o tempo permitido acabar. As versões geralmente demoram muito para serem criadas devido às dependências que instalam, por exemplo:

  • Uma longa lista de pacotes em requirements, incluindo aqueles que o agente não usa.
  • Pacotes sem wheels pré-criados para o ambiente de build, que são compilados da origem durante o build.
  • Versões não fixadas ou fixadas de forma imprecisa, o que atrasa a resolução de dependências.

Soluções recomendadas:

  • Verifique os registros de build vinculados no campo logs_url dos metadados de erro para ver qual etapa estava em execução quando o build foi interrompido.
  • Remova as dependências desnecessárias e fixe as versões de todos os pacotes necessários.
  • Priorize pacotes e versões que publicam wheels pré-criados para que nada seja compilado durante o build.
  • Tente implantar de novo. Às vezes, um build pode levar mais tempo do que o normal por motivos não relacionados ao seu código.

O contêiner não foi iniciado a tempo

Problema:

A implantação falha com um status 504, DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT) e uma mensagem informando que o contêiner do agente não começou a veiculação a tempo.

Possíveis causas:

Depois que a imagem é criada, o Agent Runtime inicia o contêiner do agente e aguarda até que ele esteja pronto para atender às solicitações. A implantação falhará se o contêiner ainda estiver sendo iniciado quando o tempo permitido acabar. As causas comuns podem incluir:

  • Trabalho lento no momento da importação, como carregar modelos ou arquivos grandes quando os módulos do agente são importados.
  • Trabalho lento ou de bloqueio no método set_up() do agente, como chamadas de rede que aguardam um serviço inacessível.

Soluções recomendadas:

  • Verifique os registros do contêiner vinculados no campo logs_url dos metadados de erro para ver onde a inicialização foi interrompida.
  • Mova a inicialização cara para fora do tempo de importação do módulo e minimize o número de etapas em set_up() rapidamente. Adie o trabalho que não é necessário para atender à primeira solicitação.
  • Verifique se todos os serviços que o agente chama durante a inicialização estão acessíveis para ele e defina tempos limite nessas chamadas para que elas não bloqueiem a inicialização indefinidamente.
  • Se os registros do contêiner mostrarem que o agente foi iniciado normalmente, tente novamente a implantação. Às vezes, a inicialização pode demorar mais do que o normal por motivos não relacionados ao seu código.

Recursos de suporte

Se o problema persistir, consulte nosso guia de suporte para receber ajuda.