Fehlerbehebung - Amazon Q Developer
KonfigurationsfehlerProbleme beim Laden benutzerdefinierter AgentenProbleme mit ToolberechtigungenDebuggen des benutzerdefinierten AgentenverhaltensZusätzliche Hilfe erhalten

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Fehlerbehebung

In diesem Abschnitt werden häufig auftretende Probleme behandelt, die bei der Arbeit mit benutzerdefinierten Agenten auftreten können, und deren Lösung.

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

  • Gehen Sie auf das Standardverhalten des Agenten zurück

Lösungen:

  • Validieren Sie Ihr JSON mit einem JSON-Validator oder Linter

  • Suchen Sie nach häufigen JSON-Fehlern:

    • Fehlende Kommas zwischen Array-Elementen oder Objekteigenschaften

    • Nachfolgende Kommas nach dem letzten Element

    • Nicht übereinstimmende Klammern oder geschweifte Klammern

    • Nicht maskierte Anführungszeichen in Zeichenkettenwerten

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

Fehler bei der Schemavalidierung

Problem: Die benutzerdefinierte Agentenkonfiguration entspricht nicht dem erwarteten Schema.

Symptome:

  • Warnungen vor unbekannten Konfigurationsfeldern

  • Das Verhalten des benutzerdefinierten Agenten entspricht nicht der Konfiguration

  • Fehler wegen fehlender Pflichtfelder

Lösungen:

  • Vergleichen Sie Ihre Konfiguration mit dem Schema unter /agent schema

  • Überprüfen Sie die Feldnamen auf Tippfehler (z. B. allowedTools vsallowedTool)

  • Stellen Sie sicher, dass die Datentypen den Schemaanforderungen entsprechen (Arrays im Vergleich zu Zeichenketten, Boolesche Werte im Vergleich zu Zeichenketten)

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

Probleme beim Laden benutzerdefinierter Agenten

Benutzerdefinierter Agent wurde nicht gefunden

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

Symptome:

  • /agent listzeigt Ihren benutzerdefinierten Agenten nicht

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

  • Ohne Warnung auf den Standard-Agenten zurückgreifen

Lösungen:

  • Stellen Sie sicher, dass sich die benutzerdefinierte Agentendatei am richtigen Speicherort befindet:

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

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

  • Überprüfen Sie die Dateiberechtigungen — stellen Sie sicher, dass die Datei lesbar ist

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

  • Stellen Sie sicher, dass die Datei eine .json Erweiterung hat

Falsche benutzerdefinierte Agentenversion wird geladen

Problem: Eine andere Version Ihres benutzerdefinierten Agenten wird 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:

  • Suchen Sie nach Konflikten zwischen lokalen und globalen Verzeichnissen bei benutzerdefinierten Agentennamen

  • Denken Sie daran, dass lokale benutzerdefinierte Agents Vorrang vor globalen benutzerdefinierten Agents haben

  • Verwenden Sie diese /agent list Option, um zu sehen, welche Version geladen wird

  • Entfernen Sie gegebenenfalls widersprüchliche benutzerdefinierte Agentdateien oder benennen Sie sie um

Probleme mit Toolberechtigungen

Das Tool ist 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 Erlaubnis für Tools in allowedTools

  • Die MCP-Servertools funktionieren nicht

Lösungen:

  • Stellen Sie sicher, dass die Namen der Tools im Array richtig geschrieben sind tools

  • Stellen Sie bei MCP-Tools sicher, dass der Server ordnungsgemäß konfiguriert ist in mcpServers

  • Stellen Sie sicher, dass die MCP-Server laufen und darauf zugegriffen werden kann

  • Verwenden Sie die richtige Syntax für MCP-Tools: @server_name/tool_name

  • Überprüfen Sie die Namen der integrierten Tools anhand der Dokumentation zu den integrierten Tools in der ergänzenden Amazon Q Developer CLI-Dokumentation

Der Befehl /tools gibt eine leere Liste zurück

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

Symptome:

  • /toolsgibt eine leere Liste zurück

  • Erwartete Tools fehlen in der Werkzeugliste

  • Der benutzerdefinierte Agent scheint keine Funktionen zu haben

Häufige Ursachen:

  • Leeres tools Array in der benutzerdefinierten Agentenkonfiguration

  • Tippfehler in den Werkzeugnamen innerhalb des Arrays tools

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

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

Lösungen:

  • Vergewissern Sie sich, dass Ihre benutzerdefinierte Agentenkonfiguration ein tools Array mit gültigen Toolnamen enthält

  • Stellen Sie sicher, dass die Toolnamen richtig geschrieben sind (Groß- und Kleinschreibung beachten)

  • Stellen Sie bei MCP-Tools sicher, dass Sie das richtige Format mit Serverpräfix verwenden: server-name___tool-name

  • Testen Sie mit dem Standardagenten, um sicherzustellen, dass Tools verfügbar sind: dann q chat /tools

  • Überprüfen Sie den MCP-Serverstatus, wenn Sie externe Tools verwenden

Unerwartete Genehmigungsaufforderungen

Problem: Ein benutzerdefinierter Agent fordert Sie zur Genehmigung von Tools auf, von denen Sie dachten, dass sie vorab genehmigt wurden.

Symptome:

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

  • Workflow-Unterbrechungen trotz benutzerdefinierter Agentenkonfiguration

Lösungen:

  • Stellen Sie sicher, dass Tools sowohl in Arrays als auch in tools allowedTools Arrays aufgeführt sind

  • Überprüfen Sie die Werkzeugnamen zwischen den beiden Arrays auf Tippfehler

  • Verwenden Sie für MCP-Tools den vollständigen Namen mit Serverpräfix in allowedTools

  • Stellen Sie sicher, dass toolAliases sie 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:

  • Stellen Sie sicher, dass die Dateipfade im resources Array korrekt sind und Dateien vorhanden sind

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

  • Stellen Sie sicher, dass Hook-Befehle erfolgreich ausgeführt werden und eine Ausgabe erzeugen

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

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

Probleme mit dem MCP-Server

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

Lösungen:

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

  • Vergewissern Sie sich, dass die erforderlichen Umgebungsvariablen gesetzt sind

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

  • Überprüfen Sie die MCP-Serverprotokolle auf Fehlermeldungen

  • Erhöhen Sie die Timeout-Werte, wenn Server langsam starten

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

Testen von benutzerdefinierten Agentenkonfigurationen

So testen Sie Ihre benutzerdefinierte Agentenkonfiguration 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

Zusätzliche Hilfe erhalten

Wenn Sie weiterhin Probleme mit Agenten haben:

  • Lesen Sie die vollständige Dokumentation zur Agentenkonfiguration in der ergänzenden Amazon Q Developer CLI-Dokumentation.

  • 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