Solução de problemas - Amazon Q Developer
Erros de configuraçãoProblemas de carregamento do agente personalizadoProblemas com permissões da ferramentaDepurar o comportamento do agente personalizadoObter ajuda adicional

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

  • Fallback ao comportamento padrão do agente

Soluções:

  • Validar o JSON usando um validador ou linter JSON

  • Verificar se há erros comuns de JSON:

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

    • Vírgulas finais após o último elemento

    • Colchetes ou chaves incompatíveis

    • Aspas sem escape em valores de string

  • Usar /agent schema para verificar a estrutura de configuração

Erros de validação de esquema

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

Sintomas:

  • Avisos sobre campos de configuração desconhecidos

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

  • Erros de campos obrigatórios ausentes

Soluções:

  • Comparar a configuração com o esquema usando /agent schema

  • Verificar se há erros de digitação nos nomes dos campos (por exemplo, allowedTools vs. allowedTool)

  • Verificar se os tipos de dados correspondem aos requisitos do esquema (arrays vs. strings, booleanos vs. strings)

  • Consultar a documentação doe formato do agente na documentação complementar da CLI do Amazon Q Developer para obter a sintaxe correta

Problemas de carregamento do agente personalizado

Agente personalizado não encontrado

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

Sintomas:

  • /agent list não exibe o agente personalizado

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

  • Fallback para o agente padrão sem aviso

Soluções:

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

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

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

  • Verificar as permissões do arquivo; o arquivo deve estar legível

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

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

Carregamento incorreto da versão do agente personalizado

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

Sintomas:

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

  • Mensagem de aviso sobre conflitos de agentes personalizados

  • Disponibilidade ou permissões inesperadas da ferramenta

Soluções:

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

  • Lembre-se: agentes personalizados locais têm precedência sobre agentes personalizados globais

  • Usar /agent list para consultara qual versão está sendo carregada

  • Remover ou renomear os arquivos de agentes personalizados conflitantes, se necessário

Problemas com permissões da ferramenta

Ferramenta indisponível

Problema: o agente personalizado não consegue acessar uma ferramenta configurada.

Sintomas:

  • Mensagens de erro sobre ferramentas desconhecidas ou indisponíveis

  • Agente personalizado solicitando permissão para acessar ferramentas em allowedTools

  • As ferramentas do servidor MCP não funcionam

Soluções:

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

  • Para ferramentas MCP, verificar se o servidor está configurado corretamente em mcpServers

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

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

  • Verificar os nomes das ferramentas integradas em relação à documentação de ferramentas integradas na documentação complementar da CLI do Amazon Q Developer

O comando /tools retorna uma lista vazia

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

Sintomas:

  • /tools retorna uma lista vazia

  • As ferramentas esperadas estão ausentes da lista de ferramentas

  • O agente personalizado parece não ter recursos

Causas comuns:

  • Matriz tools vazia na configuração do agente personalizado

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

  • Nomes incorretos de ferramentas do servidor MCP (prefixo de servidor ausente)

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

Soluções:

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

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

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

  • Testar o agente padrão para confirmar se as ferramentas estão disponíveis: q chat e, depois, /tools

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

Prompts de permissão inesperados

Problema: o agente personalizado faz um prompt de permissão para ferramentas que você acha que foram pré-aprovadas.

Sintomas:

  • Prompts de permissão para ferramentas listadas em allowedTools

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

Soluções:

  • Verificar se as ferramentas estão listadas em ambas as matrizes tools e allowedTools

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

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

  • Verificar se toolAliases estão aplicados corretamente

Depurar o comportamento do agente personalizado

Contexto ou recursos ausentes

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

Soluções:

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

  • Verificar se os padrões glob nos recursos correspondem aos arquivos pretendidos

  • Verificar se os comandos do hook estão sendo executados com sucesso e produzindo saídas

  • Testar os comandos do hook manualmente para verificar se eles funcionam em seu ambiente

  • Verificar as configurações de tempo limite do hook 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:

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

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

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

  • Analisar os logs do servidor MCP em busca de mensagens de erro

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

  • Para obter mais soluções de problemas de MCP, consulte Using MCP with Amazon Q Developer

Testar as configurações do agente personalizado

Para testar sistematicamente a configuração do agente personalizado, é preciso:

  1. Validar a sintaxe JSON usando um validador JSON

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

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

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

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

  6. Verificar se os recursos e hooks estão fornecendo o contexto esperado

  7. Testar os 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, você pode:

  • Consultar a documentação completa de configuração do agente na documentação complementar da CLI do Amazon Q Developer

  • Verificar a referência de ferramentas integradas para obter a configuração específica da ferramenta

  • Consultar a documentação do MCP para revisar problemas relacionados ao MCP

  • Começar com configurações de agentes mais simples e aumentar gradualmente a complexidade

  • Comparar sua configuração com os exemplos em Agent examples and use cases

  • Lembre-se: a alternância e a edição de agentes exigem o início de novas sessões de chat em vez do uso de comandos na sessão