トラブルシューティング

「無効な JSON」または「構文エラー」に関するエラーメッセージ

カスタムエージェントが に表示されない /agent list

デフォルトのエージェント動作へのフォールバック

JSON バリデータまたは linter を使用して JSON を検証する

一般的な JSON エラーを確認します。

/agent schema を使用して設定構造を検証する

不明な設定フィールドに関する警告

カスタムエージェントの動作が設定と一致しません

必須フィールドの欠落エラー

を使用してスキーマと設定を比較する /agent schema

入力ミスのフィールド名を確認する (例: allowedToolsと allowedTool）

データ型がスキーマ要件 (配列と文字列、ブール値と文字列) に一致することを確認する

補足の Amazon Q Developer CLI ドキュメントのエージェント形式のドキュメントで正しい構文を確認してください。

/agent list カスタムエージェントが表示されない

/agent use [name] が「エージェントが見つかりません」で失敗する

警告なしでデフォルトエージェントにフォールバックする

カスタムエージェントファイルが正しい場所にあることを確認します。

ファイルのアクセス許可を確認する - ファイルが読み取り可能であることを確認します

ファイル名が、使用しようとしているカスタムエージェント名と一致することを確認します。

ファイルに.json拡張子があることを確認する

カスタムエージェントの動作が最近の設定変更と一致しません

カスタムエージェントの競合に関する警告メッセージ

予期しないツールの可用性またはアクセス許可

ローカルディレクトリとグローバルディレクトリ間のカスタムエージェント名の競合を確認する

ローカルカスタムエージェントはグローバルカスタムエージェントよりも優先されることに注意してください。

/agent list を使用して、ロードされているバージョンを確認します。

必要に応じて、競合するカスタムエージェントファイルを削除または名前を変更する

不明または使用できないツールに関するエラーメッセージ

でツールのアクセス許可を要求するカスタムエージェント allowedTools

MCP サーバーツールが機能しない

ツール名がtools配列で正しくスペルされていることを確認する

MCP ツールの場合、サーバーが で正しく設定されていることを確認します。 mcpServers

MCP サーバーが実行されていてアクセス可能であることを確認します。

MCP ツールには正しい構文を使用します。 @server_name/tool_name

組み込みツール名を Amazon Q Developer CLI の補足ドキュメントの組み込みツールドキュメントと照合する

/tools が空のリストを返す

予想されるツールがツールリストにない

カスタムエージェントには機能がないように見える

カスタムエージェント設定の空のtools配列

tools 配列内のツール名の入力ミス

MCP サーバーツール名が正しくない (サーバープレフィックスがない）

ツールのロードを妨げる MCP サーバー設定の問題

カスタムエージェント設定に有効なツール名のtools配列が含まれていることを確認します。

ツール名が正しくスペルされていることを確認する (大文字と小文字が区別される）

MCP ツールの場合は、正しいサーバープレフィックス形式を使用していることを確認してください。 server-name___tool-name

デフォルトのエージェントでテストして、ツールが使用可能であることを確認します。 q chat /tools

外部ツールを使用している場合は MCP サーバーのステータスを確認する

にリストされているツールのアクセス許可プロンプト allowedTools

カスタムエージェント設定にもかかわらずワークフローが中断する

ツールが 配列toolsと allowedTools配列の両方にリストされていることを確認する

2 つの配列間のツール名のタイプミスをチェックする

MCP ツールの場合は、 で完全なサーバープレフィックス名を使用します。 allowedTools

が正しく適用toolAliasesされていることを確認する

resources 配列内のファイルパスが正しく、ファイルが存在することを確認する

リソースの glob パターンが目的のファイルと一致していることを確認します。

フックコマンドが正常に実行され、出力が生成されていることを確認する

フックコマンドを手動でテストして、環境で動作することを確認します。

コマンドがカットオフされている場合はフックタイムアウト設定を確認する

MCP サーバーコマンドが正しく、実行可能ファイルが PATH にあることを確認する

必要な環境変数が設定されていることを確認します。

MCP サーバーを個別にテストして動作していることを確認する

MCP サーバーログでエラーメッセージを確認する

サーバーの起動が遅い場合はタイムアウト値を増やす

MCP のトラブルシューティングの詳細については、「Amazon Q Developer での MCP の使用」を参照してください。

補足の Amazon Q Developer CLI ドキュメントにある完全なエージェント設定ドキュメントを確認する

ツール固有の設定については、組み込みツールリファレンスを確認してください。

MCP 関連の問題については、MCP ドキュメントを参照してください。

よりシンプルなエージェント設定から開始し、徐々に複雑さを追加する

設定を エージェントの例とユースケースの例と比較する

エージェントの切り替えと編集には、セッション内コマンドを使用するのではなく、新しいチャットセッションを開始する必要があることに注意してください。