Custom Agents 트러블슈팅
Table of contents
커스텀 에이전트(Custom Agents) 구성 및 사용 과정에서 발생할 수 있는 일반적인 문제를 진단하고 해결하는 방법을 안내합니다.
1. 구성 오류
1.1. 잘못된 JSON 문법
문제 - 커스텀 에이전트가 JSON 구문 오류로 인해 로드되지 않음.
증상
- “invalid JSON”, “syntax error” 등의 오류 메시지 출력
/agent list목록에 에이전트가 표시되지 않음- 기본 에이전트로 자동 폴백(fallback)
해결 방법
- JSON Validator 또는 Linter로 구문 검사
- 다음과 같은 일반적인 JSON 오류 확인:
- 배열 또는 객체 항목 간 쉼표 누락
- 마지막 요소 뒤의 트레일링 콤마
- 괄호/중괄호 불일치
- 문자열 내 따옴표 미이스케이프
/agent schema명령으로 스키마 검증 수행
1.2. 스키마 검증 오류
문제 - 에이전트 설정이 스키마 요구 사항을 충족하지 않음.
증상
- 알 수 없는 필드(unknown field)에 대한 경고
- 설정과 다른 동작 수행
- required 필드 누락에 대한 오류
해결 방법
/agent schema를 사용하여 설정 구조 검증- 필드 이름 오타 확인 (allowedTools vs allowedTool)
- 타입 일치 여부 확인 (예: 문자열 vs 배열, 문자열 vs boolean 등)
2. 에이전트 로딩 문제
2.1. 에이전트 검색 불가
증상
/agent list에 에이전트가 표시되지 않음- 경고 없이 기본 에이전트로 전환됨
해결 방법
- 파일 위치 확인:
- 글로벌:
~/.kiro/agents/[name].json - 워크스페이스:
.kiro/agents/[name].json
- 글로벌:
- 파일 읽기 권한 확인
- 파일명과 에이전트 name 일치 여부 확인
- .json 확장자 여부 확인
2.2. 잘못된 버전의 에이전트 로드
증상
- 최근 변경 내용이 반영되지 않음
- 에이전트 충돌 경고 메시지 표시
- 예상과 다른 도구 또는 권한 세트 로드
해결 방법
- 동일 이름의 로컬/글로벌 에이전트 중복 여부 확인
- 로컬 에이전트가 항상 우선됨
/agent list로 실제 로드된 파일 확인- 충돌 파일 삭제 또는 이름 변경
3. 도구 권한 문제
3.1. 도구 사용 불가
증상
- “unknown tool” 또는 “unavailable tool” 오류
- allowedTools에 포함했음에도 불구하고 승인 요청 발생
- MCP 서버 도구 호출 실패
해결 방법
- tools 배열에 정확한 도구 이름 포함 여부 확인
- MCP 도구는 반드시 @server/tool 형식 사용
- MCP 서버가 정상 실행 중인지 확인
- 내장 도구 이름은 Built-in Tools 문서 참고
3.2. /tools Command Returns Empty List (도구 목록 비어 있음)
증상
/tools실행 시 아무 도구도 표시되지 않음- 기대했던 도구가 목록에 없음
주요 원인
- tools 배열이 비어 있음
- 도구 이름 오타
- MCP 도구에서 server prefix 누락
- MCP 서버 로딩 실패
해결 방법
- tools 배열에 유효한 이름이 포함되어 있는지 확인
- 도구 이름은 대소문자 구분됨
- MCP 도구는 @server/tool 형식 사용
- 디폴트 에이전트로 /tools 테스트하여 도구 정상 여부 확인
- MCP 서버 상태 점검
3.3. 예상치 못한 권한 요청
증상
- allowedTools에 포함된 도구가 계속 승인 요청을 표시
- 워크플로우가 중단됨
해결 방법
- 동일 도구가 tools 및 allowedTools 양쪽에 모두 정의되었는지 확인
- 도구 이름 오타 여부 확인
- MCP 도구의 경우 @server/tool 전체 경로 사용
- toolAliases 사용 시 이름 변환이 정상적으로 적용되었는지 확인
4. 에전트 동작 디버깅)
4.1. 리소스 또는 컨텍스트 누락
해결 방법
- resources 배열의 파일 경로 유효성 확인
- Glob 패턴이 원하는 파일 집합을 정확히 매칭하는지 점검
- hook 명령이 정상적으로 실행되고 있는지 확인
- hook을 수동으로 실행하여 환경에서 정상 동작하는지 테스트
- hook이 제한 시간(timeout)으로 중단되는지 확인
4.2. MCP 서버 관련 문제
해결 방법
- MCP 서버 실행 명령이 정확한지 확인
- PATH, ENV 등 환경 변수가 올바르게 설정되었는지 확인
- MCP 서버를 단독 실행하여 정상 동작 여부 확인
- MCP 로그에서 오류 메시지 확인
- 서버 시작 시간이 긴 경우 timeout 증가
5. 커스텀 에이전트 테스트 절차
문제를 체계적으로 진단하기 위해 다음 순서로 테스트하는 것이 좋습니다:
- JSON 구문 검사 — Validator 사용
- 스키마 검증 —
/agent schema - 로드 확인 —
/agent list - 에이전트 전환 —
/agent swap [name] - 도구 동작 확인 — 각 tool 호출 테스트
- 리소스 및 hook 확인
- 실제 워크플로우 실행 테스트
이 과정을 통해 대부분의 커스텀 에이전트 문제를 빠르게 진단하고 해결할 수 있습니다.