문제 해결 - 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. 공통 워크플로를 테스트하여 사용자 지정 에이전트가 예상대로 작동하는지 확인합니다.

추가 도움말 받기

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