Solução de problemas - Amazon Q Developer
Erros de configuraçãoProblemas de carregamento de agentes personalizadosProblemas de permissão da ferramentaDepurando o comportamento personalizado do agenteObter ajuda adicional

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Solução de problemas

Esta seção aborda problemas comuns que você pode encontrar ao trabalhar com agentes personalizados e como resolvê-los.

Erros de configuração

Sintaxe JSON inválida

Problema: falha no carregamento do agente personalizado com erros de análise de JSON.

Sintomas:

  • Mensagens de erro mencionando “JSON inválido” ou “erro de sintaxe”

  • O agente personalizado não aparece em /agent list

  • Retorne ao comportamento padrão do agente

Soluções:

  • Valide seu JSON usando um validador ou linter JSON

  • Verifique se há erros comuns de JSON:

    • Vírgulas ausentes entre elementos da matriz ou propriedades do objeto

    • Vírgulas à direita após o último elemento

    • Suportes ou chaves incomparáveis

    • Aspas sem escape em valores de string

  • Use /agent schema para verificar sua estrutura de configuração

Erros de validação do esquema

Problema: a configuração personalizada do agente não corresponde ao esquema esperado.

Sintomas:

  • Avisos sobre campos de configuração desconhecidos

  • O comportamento personalizado do agente não corresponde à configuração

  • Erros de campos obrigatórios ausentes

Soluções:

  • Compare sua configuração com o esquema usando /agent schema

  • Verifique se há erros de digitação nos nomes dos campos (por exemplo, allowedTools vsallowedTool)

  • Verifique se os tipos de dados correspondem aos requisitos do esquema (matrizes versus cadeias de caracteres, booleanos versus cadeias de caracteres)

  • Consulte a documentação do formato do agente na documentação suplementar do Amazon Q Developer CLI para obter a sintaxe correta

Problemas de carregamento de agentes personalizados

Agente personalizado não encontrado

Problema: o agente personalizado não aparece na lista ou não pode ser usado.

Sintomas:

  • /agent listnão mostra seu agente personalizado

  • /agent use [name]falha com “agente não encontrado”

  • Volte para o agente padrão sem aviso

Soluções:

  • Verifique se o arquivo personalizado do agente está no local correto:

    • Global: ~/.aws/amazonq/cli-agents/[name].json

    • Local: amazonq/cli-agents/[name].json

  • Verifique as permissões do arquivo - certifique-se de que o arquivo esteja legível

  • Verifique se o nome do arquivo corresponde ao nome do agente personalizado que você está tentando usar

  • Verifique se o arquivo tem uma .json extensão

Carregamento incorreto da versão do agente personalizado

Problema: uma versão diferente do seu agente personalizado está sendo carregada do que a esperada.

Sintomas:

  • O comportamento personalizado do agente não corresponde às suas mudanças recentes de configuração

  • Mensagem de aviso sobre conflitos de agentes personalizados

  • Disponibilidade ou permissões inesperadas da ferramenta

Soluções:

  • Verifique se há conflitos de nomes de agentes personalizados entre diretórios locais e globais

  • Lembre-se de que os agentes personalizados locais têm precedência sobre os agentes personalizados globais

  • Use /agent list para ver qual versão está sendo carregada

  • Remova ou renomeie arquivos de agentes personalizados conflitantes, se necessário

Problemas de permissão da ferramenta

Ferramenta não disponível

Problema: o agente personalizado não consegue acessar uma ferramenta que você configurou.

Sintomas:

  • Mensagens de erro sobre ferramentas desconhecidas ou indisponíveis

  • Agente personalizado solicitando permissão para ferramentas em allowedTools

  • As ferramentas do servidor MCP não funcionam

Soluções:

  • Verifique se os nomes das ferramentas estão escritos corretamente na matriz tools

  • Para ferramentas MCP, verifique se o servidor está configurado corretamente no mcpServers

  • Verifique se os servidores MCP estão funcionando e acessíveis

  • Use a sintaxe correta para ferramentas MCP: @server_name/tool_name

  • Verifique os nomes das ferramentas integradas em relação à documentação de ferramentas incorporadas na documentação suplementar do Amazon Q Developer CLI

O comando /tools retorna uma lista vazia

Problema: O /tools comando não mostra ferramentas disponíveis ou menos ferramentas do que o esperado.

Sintomas:

  • /toolsretorna uma lista vazia

  • As ferramentas esperadas estão faltando na lista de ferramentas

  • O agente personalizado parece não ter recursos

Causas comuns:

  • toolsMatriz vazia na configuração personalizada do agente

  • Erros de digitação nos nomes das ferramentas dentro da matriz tools

  • Nomes incorretos da ferramenta do servidor MCP (prefixo de servidor ausente)

  • Problemas de configuração do servidor MCP que impedem o carregamento da ferramenta

Soluções:

  • Verifique se a configuração personalizada do agente inclui uma tools matriz com nomes de ferramentas válidos

  • Verifique se os nomes das ferramentas estão escritos corretamente (diferencia maiúsculas de minúsculas)

  • Para ferramentas MCP, verifique se você está usando o formato correto com prefixo do servidor: server-name___tool-name

  • Teste com o agente padrão para confirmar se as ferramentas estão disponíveis: q chat então /tools

  • Verifique o status do servidor MCP se estiver usando ferramentas externas

Solicitações de permissão inesperadas

Problema: o agente personalizado solicita permissão para ferramentas que você acha que foram pré-aprovadas.

Sintomas:

  • Solicitações de permissão para ferramentas listadas em allowedTools

  • Interrupções do fluxo de trabalho apesar da configuração personalizada do agente

Soluções:

  • Certifique-se de que as ferramentas estejam listadas em ambas tools as allowedTools matrizes

  • Verifique se há erros de digitação nos nomes das ferramentas entre as duas matrizes

  • Para ferramentas MCP, use o nome completo com prefixo do servidor em allowedTools

  • Verifique se toolAliases estão aplicados corretamente

Depurando o comportamento personalizado do agente

Contexto ou recursos ausentes

Problema: o agente personalizado parece não ter acesso aos arquivos ou ao contexto esperados.

Soluções:

  • Verifique se os caminhos dos arquivos na resources matriz estão corretos e se os arquivos existem

  • Verifique se os padrões globais nos recursos correspondem aos arquivos pretendidos

  • Certifique-se de que os comandos do gancho estejam sendo executados com sucesso e produzindo saída

  • Teste os comandos do gancho manualmente para verificar se eles funcionam em seu ambiente

  • Verifique as configurações de tempo limite do gancho se os comandos estiverem sendo cortados

Problemas com o servidor MCP

Problema: os servidores MCP não estão funcionando ou as ferramentas não estão disponíveis.

Soluções:

  • Verifique se os comandos do servidor MCP estão corretos e se os executáveis estão em seu PATH

  • Verifique se as variáveis de ambiente necessárias estão definidas

  • Teste os servidores MCP de forma independente para garantir que estejam funcionando

  • Examine os registros do servidor MCP em busca de mensagens de erro

  • Aumente os valores de tempo limite se os servidores demorarem a iniciar

  • Para obter mais soluções de problemas de MCP, consulte Como usar o MCP com o Amazon Q Developer

Testando configurações personalizadas de agentes

Para testar sistematicamente sua configuração personalizada de agente:

  1. Valide a sintaxe JSON usando um validador JSON

  2. Verifique a configuração em relação ao esquema usando /agent schema

  3. Teste o carregamento personalizado do agente com /agent list

  4. Mude para o agente personalizado com /agent use [name]

  5. Teste cada ferramenta individualmente para verificar o acesso e as permissões

  6. Verifique se os recursos e ganchos estão fornecendo o contexto esperado

  7. Teste fluxos de trabalho comuns para garantir que o agente personalizado se comporte conforme o esperado

Obter ajuda adicional

Se você continuar enfrentando problemas com agentes: