Risoluzione dei problemi - Amazon Q Developer
Errori di configurazioneProblemi di caricamento degli agenti personalizzatiProblemi di autorizzazione dello strumentoEseguire il debug del comportamento degli agenti personalizzatiOttenere ulteriore assistenza

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Risoluzione dei problemi

Questa sezione descrive i problemi più comuni che potresti riscontrare quando lavori con agenti personalizzati e come risolverli.

Errori di configurazione

Sintassi JSON non valida

Problema: l'agente personalizzato non viene caricato con errori di analisi JSON.

Sintomi:

  • Messaggi di errore che menzionano «JSON non valido» o «errore di sintassi»

  • L'agente personalizzato non viene visualizzato in /agent list

  • Torna al comportamento predefinito dell'agente

Soluzioni:

  • Convalida il tuo JSON utilizzando un validatore o un linter JSON

  • Verifica la presenza di errori JSON comuni:

    • Virgole mancanti tra gli elementi dell'array o le proprietà degli oggetti

    • Virgole finali dopo l'ultimo elemento

    • Staffe o bretelle senza eguali

    • Virgolette senza scampo nei valori di stringa

  • Utilizzatelo /agent schema per verificare la struttura della configurazione

Errori di convalida dello schema

Problema: la configurazione dell'agente personalizzato non corrisponde allo schema previsto.

Sintomi:

  • Avvertenze relative a campi di configurazione sconosciuti

  • Il comportamento personalizzato dell'agente non corrisponde alla configurazione

  • Errori mancanti nei campi obbligatori

Soluzioni:

  • Confronta la tua configurazione con lo schema utilizzando /agent schema

  • Controlla i nomi dei campi per eventuali errori di battitura (ad es. allowedTools vsallowedTool)

  • Verifica che i tipi di dati soddisfino i requisiti dello schema (array vs stringhe, booleani vs stringhe)

  • Consulta la documentazione sul formato dell'agente nella documentazione supplementare Amazon Q Developer CLI per una sintassi corretta

Problemi di caricamento degli agenti personalizzati

Agente personalizzato non trovato

Problema: l'agente personalizzato non viene visualizzato nell'elenco o non può essere utilizzato.

Sintomi:

  • /agent listnon mostra il tuo agente personalizzato

  • /agent use [name]fallisce con «agent not found»

  • Torna all'agente predefinito senza preavviso

Soluzioni:

  • Verifica che il file dell'agente personalizzato sia nella posizione corretta:

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

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

  • Controlla le autorizzazioni del file: assicurati che il file sia leggibile

  • Verifica che il nome del file corrisponda al nome dell'agente personalizzato che stai cercando di utilizzare

  • Assicurati che il file abbia un'estensione .json

Caricamento errato della versione dell'agente personalizzato

Problema: si sta caricando una versione del tuo agente personalizzato diversa da quella prevista.

Sintomi:

  • Il comportamento degli agenti personalizzati non corrisponde alle recenti modifiche alla configurazione

  • Messaggio di avviso sui conflitti tra agenti personalizzati

  • Disponibilità o autorizzazioni impreviste dello strumento

Soluzioni:

  • Verifica la presenza di conflitti tra i nomi degli agenti personalizzati tra le directory locali e globali

  • Ricorda che gli agenti doganali locali hanno la precedenza sugli agenti personalizzati globali

  • /agent listUtilizzatelo per vedere quale versione viene caricata

  • Se necessario, rimuovete o rinominate i file degli agenti personalizzati in conflitto

Problemi di autorizzazione dello strumento

Strumento non disponibile

Problema: l'agente personalizzato non può accedere a uno strumento che hai configurato.

Sintomi:

  • Messaggi di errore relativi a strumenti sconosciuti o non disponibili

  • Agente personalizzato che richiede l'autorizzazione per gli strumenti in allowedTools

  • Gli strumenti del server MCP non funzionano

Soluzioni:

  • Verificare che i nomi degli strumenti siano scritti correttamente nell'array tools

  • Per gli strumenti MCP, assicuratevi che il server sia configurato correttamente in mcpServers

  • Verificate che i server MCP siano funzionanti e accessibili

  • Usa la sintassi corretta per gli strumenti MCP: @server_name/tool_name

  • Verifica i nomi degli strumenti integrati confrontandoli con la documentazione degli strumenti integrati nella documentazione supplementare di Amazon Q Developer CLI

Il comando /tools restituisce un elenco vuoto

Problema: il /tools comando non mostra nessuno strumento disponibile o mostra un numero inferiore di strumenti del previsto.

Sintomi:

  • /toolsrestituisce una lista vuota

  • Gli strumenti previsti non sono presenti nell'elenco degli strumenti

  • L'agente personalizzato sembra non avere funzionalità

Cause comuni:

  • toolsArray vuoto nella configurazione personalizzata dell'agente

  • Errori di battitura nei nomi degli strumenti all'interno dell'array tools

  • Nomi degli strumenti del server MCP errati (prefisso del server mancante)

  • Problemi di configurazione del server MCP che impediscono il caricamento degli utensili

Soluzioni:

  • Verificate che la configurazione dell'agente personalizzato includa un tools array con nomi di strumenti validi

  • Verifica che i nomi degli strumenti siano scritti correttamente (distinzione tra maiuscole e minuscole)

  • Per gli strumenti MCP, assicurati di utilizzare il formato con prefisso server corretto: server-name___tool-name

  • Esegui un test con l'agente predefinito per confermare che gli strumenti siano disponibili: quindi q chat /tools

  • Controllate lo stato del server MCP se utilizzate strumenti esterni

Richieste di autorizzazione impreviste

Problema: l'agente personalizzato richiede l'autorizzazione per gli strumenti che ritenevi fossero preapprovati.

Sintomi:

  • Richieste di autorizzazione per gli strumenti elencati in allowedTools

  • Interruzioni del flusso di lavoro nonostante la configurazione personalizzata dell'agente

Soluzioni:

  • Assicurati che gli strumenti siano elencati in entrambi tools gli allowedTools array

  • Verifica la presenza di errori di battitura nei nomi degli strumenti tra i due array

  • Per gli strumenti MCP, utilizzate il nome completo con prefisso del server in allowedTools

  • Verificate che siano applicati correttamente toolAliases

Eseguire il debug del comportamento degli agenti personalizzati

Contesto o risorse mancanti

Problema: l'agente personalizzato non sembra avere accesso ai file o al contesto previsti.

Soluzioni:

  • Verificare che i percorsi dei file nell'resourcesarray siano corretti e che i file esistano

  • Verifica che i modelli a globo nelle risorse corrispondano ai file previsti

  • Assicurati che i comandi hook vengano eseguiti correttamente e producano output

  • Prova manualmente i comandi hook per verificare che funzionino nel tuo ambiente

  • Controlla le impostazioni del timeout dell'hook se i comandi vengono interrotti

Problemi con il server MCP

Problema: i server MCP non funzionano o gli strumenti non sono disponibili.

Soluzioni:

  • Verifica che i comandi del server MCP siano corretti e che gli eseguibili siano presenti nel tuo PATH

  • Verificate che le variabili di ambiente richieste siano impostate

  • Testa i server MCP in modo indipendente per assicurarti che funzionino

  • Esamina i registri del server MCP per verificare la presenza di messaggi di errore

  • Aumentate i valori di timeout se i server si avviano lentamente

  • Per ulteriori informazioni sulla risoluzione dei problemi MCP, consulta Uso di MCP con Amazon Q Developer

Test di configurazioni di agenti personalizzate

Per testare sistematicamente la configurazione personalizzata dell'agente:

  1. Convalida la sintassi JSON utilizzando un validatore JSON

  2. Controlla la configurazione rispetto allo schema utilizzando /agent schema

  3. Prova il caricamento di un agente personalizzato con /agent list

  4. Passa all'agente personalizzato con /agent use [name]

  5. Testa ogni strumento singolarmente per verificare l'accesso e le autorizzazioni

  6. Verifica che le risorse e gli hook forniscano il contesto previsto

  7. Verifica i flussi di lavoro comuni per assicurarti che l'agente personalizzato si comporti come previsto

Ottenere ulteriore assistenza

Se continui a riscontrare problemi con gli agenti: