Fehlerbehebung - Amazon Q Developer
KonfigurationsfehlerProbleme mit dem Laden von benutzerdefinierten AgentenTool-BerechtigungsproblemeDebuggen des benutzerdefinierten AgentenverhaltensWeitere Hilfe

Fehlerbehebung

Dieser Abschnitt behandelt häufige Probleme, die beim Arbeiten mit benutzerdefinierten Agenten auftreten können, und wie Sie diese beheben.

Konfigurationsfehler

Ungültige JSON-Syntax

Problem: Der benutzerdefinierte Agent kann aufgrund von JSON-Analysefehlern nicht geladen werden.

Symptome:

  • Fehlermeldungen, in denen „ungültiges JSON“ oder „Syntaxfehler“ erwähnt wird

  • Benutzerdefinierter Agent erscheint nicht in /agent list

  • Auf das Standardverhalten des Agenten zurückgreifen

Lösungen:

  • JSON mit einem JSON-Validator oder -Linter validieren

  • Auf häufig auftretende JSON-Fehler prüfen:

    • Fehlende Kommas zwischen Array-Elementen oder Objekteigenschaften

    • Nachfolgende Kommas nach dem letzten Element

    • Nicht übereinstimmende Klammern oder geschweifte Klammern

    • Nicht durch Escape-Zeichen geschützte Anführungszeichen in Zeichenfolgewerten

  • /agent schema verwenden, um Ihre Konfigurationsstruktur zu überprüfen

Schemavalidierungsfehler

Problem: Die benutzerdefinierte Agentenkonfiguration entspricht nicht dem erwarteten Schema.

Symptome:

  • Warnungen vor unbekannten Konfigurationsfeldern

  • Das Verhalten des benutzerdefinierten Agenten entspricht nicht der Konfiguration.

  • Fehler aufgrund fehlender Pflichtfelder

Lösungen:

  • Ihre Konfiguration unter Verwendung von /agent schema mit dem Schema vergleichen

  • Feldnamen auf Tippfehler überprüfen (z. B. allowedTools im Vergleich zu allowedTool)

  • Sicherstellen, dass die Datentypen den Schemaanforderungen entsprechen (Arrays im Vergleich zu Zeichenfolgen, Boolesche Werte im Vergleich zu Zeichenfolgen)

  • Die korrekte Syntax finden Sie in der Dokumentation zum Agentenformat in der ergänzenden Dokumentation für Amazon Q Developer CLI.

Probleme mit dem Laden von benutzerdefinierten Agenten

Der benutzerdefinierte Agent wurde nicht gefunden.

Problem: Der benutzerdefinierte Agent erscheint nicht in der Liste oder kann nicht verwendet werden.

Symptome:

  • /agent list zeigt Ihren benutzerdefinierten Agenten nicht an.

  • /agent use [name] schlägt fehl mit der Meldung „Agent wurde nicht gefunden“.

  • Fallback auf den Standard-Agenten ohne Warnung

Lösungen:

  • Stellen Sie sicher, dass sich die Datei des benutzerdefinierten Agenten am richtigen Speicherort befindet:

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

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

  • Die Dateiberechtigungen überprüfen – sicherstellen, dass die Datei lesbar ist

  • Sicherstellen, dass der Dateiname mit dem Namen des benutzerdefinierten Agenten übereinstimmt, den Sie verwenden möchten

  • Sicherstellen, dass die Datei eine .json-Erweiterung hat

Falsche Version des benutzerdefinierten Agenten wird geladen

Problem: Es wird eine andere Version Ihres benutzerdefinierten Agenten geladen als erwartet.

Symptome:

  • Das Verhalten des benutzerdefinierten Agenten entspricht nicht Ihren letzten Konfigurationsänderungen.

  • Warnmeldung zu Konflikten mit benutzerdefinierten Agenten

  • Unerwartete Verfügbarkeit oder Berechtigungen von Tools

Lösungen:

  • Auf Konflikte zwischen lokalen und globalen Verzeichnissen bei benutzerdefinierten Agentennamen prüfen

  • Bedenken, dass lokale benutzerdefinierte Agenten Vorrang vor globalen benutzerdefinierten Agenten haben

  • /agent list verwenden, um zu sehen, welche Version geladen wird

  • Dateien benutzerdefinierter Agenten, die Konflikte verursachen, entfernen oder umbenennen

Tool-Berechtigungsprobleme

Tool nicht verfügbar

Problem: Der benutzerdefinierte Agent kann nicht auf ein von Ihnen konfiguriertes Tool zugreifen.

Symptome:

  • Fehlermeldungen zu unbekannten oder nicht verfügbaren Tools

  • Benutzerdefinierter Agent bittet um Berechtigung für Tools in allowedTools

  • MCP-Servertools funktionieren nicht

Lösungen:

  • Sicherstellen, dass die Namen der Tools im tools-Array richtig geschrieben sind

  • Bei MCP-Tools sicherstellen, dass der Server in mcpServers ordnungsgemäß konfiguriert ist

  • Sicherstellen, dass die MCP-Server laufen und darauf zugegriffen werden kann

  • Die richtige Syntax für MCP-Tools verwenden: @server_name/tool_name

  • Die Namen der integrierten Tools anhand der Dokumentation zu den integrierten Tools in der ergänzenden Dokumentation für Amazon Q Developer CLI überprüfen

Der Befehl /tools gibt eine leere Liste zurück.

Problem: Der Befehl /tools zeigt keine verfügbaren Tools oder weniger Tools als erwartet an.

Symptome:

  • /tools gibt eine leere Liste zurück.

  • Erwartete Tools fehlen in der Tools-Liste.

  • Der benutzerdefinierte Agent scheint keine Funktionen zu haben.

Häufige Ursachen:

  • Leeres tools-Array in der benutzerdefinierten Agentenkonfiguration

  • Tippfehler in den Tool-Namen innerhalb des tools-Arrays

  • Falsche Namen der MCP-Servertools (fehlendes Serverpräfix)

  • Probleme mit der MCP-Serverkonfiguration verhindern das Laden von Tools.

Lösungen:

  • Überprüfen, dass Ihre benutzerdefinierte Agentenkonfiguration ein tools-Array mit gültigen Tool-Namen enthält

  • Sicherstellen, dass die Tool-Namen richtig geschrieben sind (mit Beachtung der Groß- und Kleinschreibung)

  • Bei MCP-Tools sicherstellen, dass Sie das richtige Format mit Serverpräfix verwenden: server-name___tool-name

  • Mit dem Standardagenten testen, um sicherzustellen, dass die Tools verfügbar sind: q chat, dann /tools

  • Den MCP-Serverstatus prüfen, wenn Sie externe Tools verwenden

Unerwartete Eingabeaufforderungen für Berechtigungen

Problem: Der benutzerdefinierter Agent fragt Sie nach Berechtigungen für Tools, von denen Sie dachten, dass sie vorab genehmigt wurden.

Symptome:

  • Eingabeaufforderungen für Berechtigungen für Tools, die unter allowedTools aufgeführt sind

  • Workflow-Unterbrechungen trotz benutzerdefinierter Agentenkonfiguration

Lösungen:

  • Sicherstellen, dass Tools sowohl in tools- als auch in allowedTools-Arrays aufgelistet sind

  • Die Tool-Namen in beiden Arrays auf Tippfehler überprüfen

  • Für MCP-Tools den vollständigen Namen mit Serverpräfix in allowedTools verwenden

  • Sicherstellen, dass toolAliases korrekt angewendet wurden

Debuggen des benutzerdefinierten Agentenverhaltens

Fehlender Kontext oder fehlende Ressourcen

Problem: Der benutzerdefinierte Agent scheint keinen Zugriff auf die erwarteten Dateien oder den erwarteten Kontext zu haben.

Lösungen:

  • Sicherstellen, dass die Dateipfade im resources-Array korrekt sind und Dateien vorhanden sind

  • Überprüfen, ob die Glob-Muster in den Ressourcen mit den entsprechenden Dateien übereinstimmen

  • Sicherstellen, dass Hook-Befehle erfolgreich ausgeführt werden und eine Ausgabe erzeugen

  • Hook-Befehle manuell testen, um sicherzustellen, dass sie in Ihrer Umgebung funktionieren

  • Die Einstellungen für das Hook-Timeout überprüfen, wenn Befehle unterbrochen werden

Probleme mit dem MCP-Server

Problem: MCP-Server funktionieren nicht oder Tools sind nicht verfügbar.

Lösungen:

  • Sicherstellen, dass die MCP-Serverbefehle korrekt sind und dass sich die ausführbaren Dateien in Ihrem PATH befinden

  • Überprüfen, ob die erforderlichen Umgebungsvariablen festgelegt sind

  • MCP-Server unabhängig voneinander testen, um sicherzustellen, dass sie funktionieren

  • MCP-Serverprotokolle auf Fehlermeldungen überprüfen

  • Die Timeout-Werte erhöhen, wenn Server langsam starten

  • Weitere Informationen zur MCP-Fehlerbehebung finden Sie unter Verwenden von MCP mit Amazon Q Developer.

Testen der Konfigurationen von benutzerdefinierten Agenten

So testen Sie die Konfiguration Ihres benutzerdefinierte Agenten systematisch:

  1. Überprüfen Sie die JSON-Syntax mit einem JSON-Validator.

  2. Überprüfen Sie die Konfiguration anhand des Schemas mit /agent schema.

  3. Testen Sie das Laden des benutzerdefinierten Agenten mit /agent list.

  4. Wechseln Sie zum benutzerdefinierten Agenten mit /agent use [name].

  5. Testen Sie jedes Tool einzeln, um Zugriff und Berechtigungen zu überprüfen.

  6. Stellen Sie sicher, dass Ressourcen und Hooks den erwarteten Kontext bieten.

  7. Testen Sie gängige Workflows, um sicherzustellen, dass sich der benutzerdefinierte Agent wie erwartet verhält.

Weitere Hilfe

Wenn Sie weiterhin Probleme mit Agenten haben:

  • Lesen Sie die Dokumentation zum Agentenformat in der ergänzenden Dokumentation für Amazon Q Developer CLI vollständig durch.

  • Informationen zur toolspezifischen Konfiguration finden Sie in der Referenz zu den integrierten Tools.

  • Informationen zu MCP-bezogenen Problemen finden Sie in der MCP-Dokumentation

  • Beginnen Sie mit einfacheren Agentenkonfigurationen und erhöhen Sie die Komplexität schrittweise.

  • Vergleichen Sie Ihre Konfiguration mit den Beispielen unter Agentenbeispiele und Anwendungsfälle.

  • Denken Sie daran, dass beim Wechseln und Bearbeiten von Agenten neue Chat-Sitzungen gestartet werden müssen, anstatt sitzungsinterne Befehle zu verwenden.