Solução de problemas de armazenamento de dados do Gemini Enterprise

Use esta página para diagnosticar e resolver problemas com os repositórios de dados do Gemini Enterprise. Quando um repositório de dados não consegue recuperar informações, é possível depurar o problema de forma independente seguindo uma jornada de observabilidade coesa e detalhada.

Para ter uma visão completa de um erro, entenda como as ferramentas de observabilidade do Google Cloudfuncionam juntas:

  • Cloud Monitoring: detecta quando há um problema. Use-o para conferir tendências gerais, taxas de erro e configurar alertas para seus repositórios de dados.
  • Cloud Trace: descobre onde o problema está ocorrendo. Use-o para visualizar o ciclo de vida de uma solicitação, analisar períodos e identificar exatamente qual etapa causou alta latência ou falha.
  • Cloud Logging: explica por que o problema está ocorrendo. Use-o para ler as mensagens de erro e os payloads exatos associados a uma solicitação com falha.
  • Registros de auditoria do Cloud: identifica quem ou qual política bloqueou a ação. Use-o para acompanhar a conformidade de segurança, as mudanças de permissão e as ações administrativas que podem estar causando negações de acesso.

Fluxo de trabalho de depuração

Ao investigar um problema no repositório de dados, siga este fluxo de trabalho sequencial para isolar e resolver a causa raiz:

  1. Verificar tendências de taxa de erro
  2. Encontrar a solicitação com falha específica
  3. Ver o payload do erro
  4. Comparar registros de auditoria de uso

  1. No console do Google Cloud , acesse a página do Metrics Explorer.

    Acessar o Metrics Explorer

  2. Verifique seus painéis e as contagens de solicitações do repositório de dados e filtre por ID da ferramenta e ID do mecanismo. É possível determinar se o problema é um erro único ou um pico sistêmico generalizado que requer atenção imediata.

Encontrar a solicitação com falha específica

  1. No console Google Cloud , acesse a página Explorador de traces:

    Acessar o Explorador de traces

    Também é possível encontrar essa página usando a barra de pesquisa.

  2. Examine o gráfico de dispersão em busca de traces com um ícone de erro (um ponto de exclamação vermelho) ou latência excepcionalmente alta.
  3. Clique em um trace para ver o gráfico de Gantt dele.
  4. Verifique o período de invoke_connector para ver onde o processo foi interrompido ou falhou.
  5. Além disso, é possível encontrar o token de assistência exclusivo associado a uma solicitação específica. Se você precisar encaminhar um problema complexo ao suporte do Google Cloud , compartilhe este token de assistência para acelerar a investigação.

Ver o payload do erro

  1. Clique no período com falha no Trace Explorer.
  2. No painel de detalhes, clique em Mostrar registros.
  3. Isso redireciona você automaticamente para o Cloud Logging, filtrado para essa solicitação exata. Aqui, você pode ler o payload do registro bruto para identificar a assinatura exata do erro (como RESOURCE_EXHAUSTED ou PERMISSION_DENIED).

Comparar registros de auditoria de uso

Se o payload do registro indicar um problema do IAM, um escopo ausente ou uma negação de permissão, compare os registros de auditoria do Cloud:

  1. No console do Google Cloud , acesse a página Análise de registros.

    Acessar a Análise de registros

  2. Revise o histórico administrativo. Verifique se o administrador modificou recentemente um filtro de ação ou revogou uma permissão necessária.

Exemplo: rastrear uma solicitação de repositório de dados com falha

Imagine que um usuário peça ao agente do Gemini Enterprise para verificar o status de um problema no Jira, mas o agente retorne uma mensagem de erro genérica. Veja como usar o fluxo de trabalho de observabilidade para encontrar a causa raiz:

  1. Verifique as tendências de erro: antes de procurar erros individuais, você quer saber se o problema é generalizado. Abra o Metrics Explorer no Cloud Monitoring e filtre as métricas de solicitação do repositório de dados por tool_id: get_issue. Pode haver um aumento enorme e repentino nos erros RESOURCE_EXHAUSTED. Isso confirma que é um problema sistêmico, não apenas um erro de digitação pontual do usuário.
  2. Encontre a solicitação com falha: abra o Trace Explorer e defina o filtro de tempo para a última hora. No gráfico de dispersão, você percebe um cluster de traces com um ícone de erro vermelho indicando falhas. Clique em um desses traces recentes para investigar.
  3. Analise o diagrama de Gantt: ele mostra a jornada da solicitação. Você vê um período pai bem-sucedido para o roteamento inicial do agente, mas aninhado abaixo dele há um período invoke_connector com falha que segmenta especificamente o repositório de dados do Jira Cloud.
  4. Alternar para registros: clique no período invoke_connector com falha. No painel de detalhes do Trace, clique em Mostrar registros.

  5. Identificar a causa raiz: a Análise de registros é aberta, pré-filtrada para o ID de trace exato. Agora é possível examinar o payload de registro gerado pelo repositório de dados para identificar o erro exato:

    
"message": "Connector Error: Cause: Failed to execute spec-based tool 'get_issue': Request failed: HTTP error 403: {\"errorMessages\":[\"permission denied: [User] does not have access to [Resource]"],\"errors\":{}}"

    Nessa mensagem de erro de payload, é possível ver a ferramenta específica (get_issue) que falhou e a mensagem explícita indicando que o usuário que executa a solicitação não tem acesso ao recurso específico no sistema de destino.

  6. Resolução: usando a seção Erros comuns, é possível identificar esse erro como Acesso ausente ao recurso do usuário final. O agente do Gemini Enterprise se conectou ao Jira Cloud, mas o Jira Cloud rejeitou a consulta porque o usuário não tem permissões. Para resolver isso, peça ao administrador do Jira Cloud para conceder ao usuário acesso ao recurso específico.

Erros comuns

Ao analisar os payloads de erro no Cloud Logging, concentre-se nas assinaturas de erro amplas. A maioria dos erros do repositório de dados é totalmente resolvida pelo próprio sistema. Encontre o erro que você encontrou na lista a seguir para determinar a causa raiz e corrigir.

Erros de autenticação e acesso

Esses erros ocorrem quando há problemas com credenciais, escopos ou políticas administrativas que impedem o acesso aos recursos necessários. Se você encontrar esses erros, os Registros de Auditoria do Cloud serão úteis para depurar mudanças recentes do IAM, atualizações de filtros de ação ou permissões revogadas.

Token OAuth expirado ou inválido

  • Assinatura do erro: HTTP request failed with status code 401 / 401 Unauthorized
  • Causa raiz: o token OAuth expirou ou é inválido.
  • Resolução: autorize novamente o repositório de dados nas configurações do Gemini Enterprise para gerar um novo token.

Ferramenta bloqueada por um filtro de ação

  • Assinatura do erro: Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
  • Causa raiz: o administrador bloqueou a ferramenta usando um filtro de ação.
  • Solução: o administrador precisa atualizar a lista de permissões de ações ou ferramentas.

Escopos do OAuth ausentes

  • Assinaturas de erro: Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted OU Cause: Insufficient Permission
  • Causa raiz: o registro do aplicativo na plataforma de terceiros não tem os escopos necessários.
  • Resolução: um administrador precisa conceder os escopos exatos nomeados no registro e autorizar o app novamente.

Permissões do IAM de projeto ausentes

  • Assinatura do erro: Access Denied: User does not have [permission] / mcp.tools.call permission
  • Causa raiz: o autor da chamada ou a conta de serviço não tem as permissões do IAM do Google Cloud necessárias no projeto de destino.
  • Solução: conceda a permissão do IAM nomeada ao autor da chamada.

Erros de desempenho e limitação

Esses erros são acionados quando os volumes de solicitação excedem os limites definidos pela API ou pelo serviço de destino. O Cloud Trace ajuda a identificar exatamente quanto tempo essas solicitações limitadas ficam travadas antes de falharem.

Limitação 429 da API de terceiros

  • Assinatura do erro: Cause: Request has been rate limited
  • Causa raiz: você está fazendo solicitações mais rápido do que a API de terceiros permite.
  • Resolução: reduza a taxa de solicitações, implemente estratégias de espera ou solicite um aumento de cota ao provedor terceirizado.

O botão "Ativar ações" não está visível

  • Assinatura do erro: o botão Ativar ações não está visível ou está desativado no console após a criação de um repositório de dados.
  • Causa raiz: o repositório de dados tem funcionalidade limitada (como apenas pesquisa federada, apenas ingestão ou apenas pesquisa) e não aceita ações.
  • Resolução: não é possível ativar ações nesses tipos de repositório de dados.

Erros de visibilidade e de recursos

Esses erros indicam que, embora a autenticação possa ser bem-sucedida, o usuário ou aplicativo não tem os direitos específicos para visualizar ou interagir com os dados solicitados.

Restrição de visibilidade de terceiros

  • Assinatura do erro: 422 ... you do not have permission to view [Resource/Users]
  • Causa raiz: uma restrição de visibilidade ou política da organização na plataforma de terceiros está impedindo a recuperação de dados.
  • Resolução: ajuste sua associação à organização de terceiros ou reduza o limite do escopo da consulta.

Acesso ausente ao recurso do usuário final

  • Assinatura do erro: permission denied: [user] does not have access to [Resource]
  • Causa raiz: o usuário final que executa a solicitação não tem acesso ao componente ou recurso específico no sistema de destino.
  • Resolução: conceda ao usuário acesso ao recurso diretamente no sistema de destino.

Erros do sistema e do lado do servidor

Esses erros resultam de problemas de infraestrutura, tempos limite ou configurações incorretas de back-end e, normalmente, não são resolvidos automaticamente.

Endpoint de terceiros lento ou sobrecarregado

  • Assinatura do erro: context deadline exceeded
  • Causa raiz: o endpoint de terceiros está lento ou sobrecarregado, o que faz com que a solicitação do Google expire.
  • Resolução: tente fazer a solicitação novamente. Se o erro persistir, entre em contato com o suporte do Google Cloud para ajustar o tempo limite.

Configuração incorreta da vinculação de credenciais do servidor MCP

  • Assinatura do erro: CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • Causa raiz: há um problema de política do lado do servidor em que a vinculação de credenciais do servidor MCP está configurada incorretamente. Não é possível que o cliente resolva isso.
  • Resolução: entre em contato com o suporte do Google Cloud .

Receber suporte

Se você encontrar um erro context deadline exceeded ou CredsPermissionException persistente, talvez seja necessário enviar um tíquete de suporte para o suporte do Google Cloud .

Para agilizar a resolução, reúna os seguintes artefatos das suas ferramentas de observabilidade antes de abrir um tíquete:

  • Do Cloud Logging: o payload de registro JSON completo do erro.
  • Do Cloud Trace: o token de assistência e os detalhes específicos do período (incluindo o ID do trace) associados à solicitação com falha.
  • Dos registros de auditoria de uso: todos os carimbos de data/hora de modificação do IAM ou mudanças na política que possam ter acionado o problema.