문제 해결 - Amazon Q Developer
구성 오류사용자 지정 에이전트 로드 문제도구 권한 문제사용자 지정 에이전트 동작 디버깅추가 도움말 받기

문제 해결

이 섹션에서는 사용자 지정 에이전트로 작업할 때 발생할 수 있는 일반적인 문제와 이를 해결하는 방법을 다룹니다.

구성 오류

잘못된 JSON 구문

문제: 사용자 지정 에이전트가 JSON 구문 분석 오류와 함께 로드되지 않습니다.

증상:

  • ‘잘못된 JSON’ 또는 ‘구문 오류’를 언급하는 오류 메시지

  • 사용자 지정 에이전트가 /agent list에 나타나지 않음

  • 기본 에이전트 동작으로 폴백

솔루션:

  • JSON 검사기 또는 린터를 사용하여 JSON 검증

  • 일반적인 JSON 오류를 확인합니다.

    • 배열 요소 또는 객체 속성 간에 쉼표 누락

    • 마지막 요소 뒤의 후행 쉼표

    • 일치하지 않는 대괄호 또는 중괄호

    • 문자열 값의 이스케이프 처리되지 않은 따옴표

  • /agent schema를 사용하여 구성 구조 확인

스키마 유효성 검사 오류

문제: 사용자 지정 에이전트 구성이 예상 스키마와 일치하지 않습니다.

증상:

  • 알 수 없는 구성 필드에 대한 경고

  • 사용자 지정 에이전트 동작이 구성과 일치하지 않음

  • 필수 필드 누락 오류

솔루션:

  • /agent schema를 사용하여 구성을 스키마와 비교

  • 필드 이름에서 오타 확인(예: allowedTools 대 allowedTool)

  • 데이터 유형이 스키마 요구 사항과 일치하는지 확인(배열 대 문자열, 부울 대 문자열)

  • 보조 Amazon Q Developer CLI 설명서의 에이전트 형식 설명서에서 올바른 구문 검토

사용자 지정 에이전트 로드 문제

사용자 지정 에이전트를 찾을 수 없음

문제: 사용자 지정 에이전트가 목록에 표시되지 않거나 사용할 수 없습니다.

증상:

  • /agent list에서 사용자 지정 에이전트를 표시하지 않음

  • /agent use [name]이 ‘에이전트를 찾을 수 없음’으로 실패

  • 경고 없이 기본 에이전트로 폴백

솔루션:

  • 사용자 지정 에이전트 파일이 올바른 위치에 있는지 확인합니다.

    • 글로벌: ~/.aws/amazonq/cli-agents/[name].json

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

  • 파일 권한 확인 - 파일을 읽을 수 있는지 확인

  • 파일 이름이 사용하려는 사용자 지정 에이전트 이름과 일치하는지 확인

  • 파일에 .json 확장자가 있는지 확인

잘못된 사용자 지정 에이전트 버전 로드

문제: 예상했던 것과 다른 버전의 사용자 지정 에이전트가 로드 중입니다.

증상:

  • 사용자 지정 에이전트 동작이 최근 구성 변경 사항과 일치하지 않음

  • 사용자 지정 에이전트 충돌에 대한 경고 메시지

  • 예상치 못한 도구 가용성 또는 권한

솔루션:

  • 로컬 디렉터리와 글로벌 디렉터리 간에 사용자 지정 에이전트 이름 충돌 확인

  • 로컬 사용자 지정 에이전트가 글로벌 사용자 지정 에이전트보다 우선한다는 점에 유의

  • /agent list를 사용하여 로드 중인 버전 확인

  • 필요한 경우 충돌하는 사용자 지정 에이전트 파일을 제거하거나 이름 변경

도구 권한 문제

도구를 사용할 수 없음

문제: 사용자 지정 에이전트가 구성한 도구에 액세스할 수 없습니다.

증상:

  • 알 수 없거나 사용할 수 없는 도구에 대한 오류 메시지

  • allowedTools에서 도구에 대한 권한을 요청하는 사용자 지정 에이전트

  • MCP 서버 도구가 작동하지 않음

솔루션:

  • tools 배열에서 도구 이름의 철자가 올바른지 확인

  • MCP 도구의 경우 mcpServers에서 서버가 올바르게 구성되었는지 확인

  • MCP 서버가 실행 중이고 액세스 가능한지 확인

  • MCP 도구에 올바른 구문 사용: @server_name/tool_name

  • 보조 Amazon Q Developer CLI 설명서의 기본 제공 도구 설명서와 비교하여 기본 제공 도구의 이름 확인

/tools 명령이 빈 목록을 반환

문제: /tools 명령에 사용 가능한 도구가 없거나 예상보다 적은 도구가 표시됩니다.

증상:

  • /tools에서 빈 목록을 반환

  • 도구 목록에서 예상 도구가 누락됨

  • 사용자 지정 에이전트에 기능이 없는 것으로 보임

일반적인 원인:

  • 사용자 지정 에이전트 구성의 tools 배열이 비어 있음

  • tools 배열 내 도구 이름의 오타

  • 잘못된 MCP 서버 도구 이름(서버 접두사 누락)

  • 도구 로딩을 방해하는 MCP 서버 구성 문제

솔루션:

  • 사용자 지정 에이전트 구성에 유효한 도구 이름이 있는 tools 배열이 포함되어 있는지 확인

  • 도구 이름의 철자가 올바른지 확인(대소문자 구분)

  • MCP 도구의 경우 올바른 서버 접두사 형식인 server-name___tool-name을 사용하고 있는지 확인

  • 기본 에이전트로 테스트하여 도구를 사용할 수 있는지 확인: q chat 다음 /tools

  • 외부 도구를 사용하는 경우 MCP 서버 상태 확인

예기치 않은 권한 프롬프트

문제: 사용자 지정 에이전트가 사전 승인되었다고 생각되는 도구에 대한 권한을 묻는 메시지를 표시합니다.

증상:

  • allowedTools에 나열된 도구에 대한 권한 프롬프트

  • 사용자 지정 에이전트 구성에도 불구하고 워크플로 중단

솔루션:

  • 도구가 tools 및 allowedTools 배열 모두에 나열되어 있는지 확인

  • 두 배열 사이의 도구 이름에 오타가 있는지 확인

  • MCP 도구의 경우 allowedTools에서 전체 서버 접두사 이름을 사용

  • toolAliases가 올바르게 적용되었는지 확인

사용자 지정 에이전트 동작 디버깅

컨텍스트 또는 리소스 누락

문제: 사용자 지정 에이전트가 정상적인 파일 또는 컨텍스트에 액세스할 수 없는 것 같습니다.

솔루션:

  • resources 배열의 파일 경로가 올바르고 파일이 존재하는지 확인

  • 리소스의 glob 패턴이 의도한 파일과 일치하는지 확인

  • 후크 명령이 성공적으로 실행되고 출력을 생성하는지 확인

  • 후크 명령을 수동으로 테스트하여 환경에서 작동하는지 확인

  • 명령이 잘리는 경우 후크 제한 시간 설정 확인

MCP 서버 문제

문제: MCP 서버가 작동하지 않거나 도구를 사용할 수 없습니다.

솔루션:

  • MCP 서버 명령이 올바르고 실행 파일이 PATH에 있는지 확인

  • 필수 환경 변수가 설정되었는지 확인

  • MCP 서버를 독립적으로 테스트하여 작동하는지 확인

  • MCP 서버 로그에서 오류 메시지 검토

  • 서버 시작 속도가 느린 경우 제한 시간 값 증가

  • MCP 문제 해결에 대한 자세한 내용은 Amazon Q Developer에서 MCP 사용을 참조하세요.

사용자 지정 에이전트 구성 테스트

사용자 지정 에이전트 구성을 체계적으로 테스트하려면 다음을 수행하세요.

  1. JSON 검사기를 사용하여 JSON 구문 검증

  2. /agent schema를 사용하여 스키마에 대한 구성 확인

  3. /agent list를 사용하여 사용자 지정 에이전트 로드 테스트

  4. /agent use [name]을 사용하여 사용자 지정 에이전트로 전환

  5. 각 도구를 개별적으로 테스트하여 액세스 및 권한 확인

  6. 리소스와 후크가 예상 컨텍스트를 제공하는지 확인

  7. 공통 워크플로를 테스트하여 사용자 지정 에이전트가 정상적으로 작동하는지 확인

추가 도움말 받기

에이전트와 관련된 문제가 계속 발생하는 경우: