M3-6. 문제 해결 Troubleshooting — 오류 코드 9종
한 줄 요약 — 새 환경 에이전트가 실패하면 표준 오류 코드 9종 중 하나가 표시됩니다. 코드마다 재시도가 통하는지와 누가 조치해야 하는지(최종 사용자/작성자/관리자/지원)가 정해져 있습니다. (기능·화면·명칭은 프리뷰 기준 · subject to change)
1. 오류 코드는 어디에 나타나나
- Preview 탭 — 테스트 대화 실패 시
- Preview history 표 — Failed 상태 대화의 Error 열
- 활동 추적(activity trace) — 실패한 단계에 코드 표시
- Evaluate 결과 — 실패한 테스트 케이스의 실행 상세(run details)
즉, M3-1에서 배운 활동 추적·History와 M3-2의 평가 결과가 그대로 오류 코드의 발견 경로입니다.
2. 오류 코드 요약표 (9종 전체)
| 오류 코드 | 의미 | 동일 입력 재시도 | 조치 담당 |
|---|---|---|---|
| CONTENT_FILTERED | 콘텐츠 안전 정책이 요청/응답 차단 | 아니오 | 최종 사용자 |
| CONTEXT_LENGTH_EXCEEDED | 요청이 모델 최대 입력 크기 초과 | 아니오 | 작성자(maker) |
| CONVERSATION_BUSY | 같은 대화의 이전 메시지가 아직 처리 중 | 예(이전 턴 완료 후) | 최종 사용자 |
| CROSS_GEO_NOT_ALLOWED | 테넌트 데이터 상주(data residency) 설정이 처리 차단 | 아니오 | 관리자 |
| DEPLOYMENT_NOT_FOUND | 구성된 AI 모델 배포를 찾을 수 없음 | 아니오 | 관리자 또는 작성자 |
| MODEL_CONSENT_DENIED | 선택한 AI 모델이 조직에서 미활성화 | 아니오 | 관리자 |
| QUOTA_EXCEEDED | 조직의 AI 서비스 할당량 소진 | 예(더 오래 기다린 후) | 관리자 |
| RATE_LIMIT_REACHED | AI 서비스 일시 과부하 | 예(잠시 후) | 최종 사용자 |
| SYSTEM_ERROR | 조사 필요한 예기치 않은 오류(catch-all) | 경우에 따라 | 지원(Support) |
3. 자주 만나는 코드별 해결 포인트
- CONTENT_FILTERED — 증오·폭력·성적 콘텐츠·자해·탈옥(jailbreak)·간접 공격 등 Microsoft 콘텐츠 안전 정책 위반. 요청을 다시 표현하거나, Build 탭 Instructions로 범위를 명확히 하거나, 활동 추적의 대화 ID와 함께 관리자에게 문의.
- CONTEXT_LENGTH_EXCEEDED — 지침+대화 기록+도구 정의+도구 결과의 합산이 모델 한도 초과(긴 대화·많은 도구가 흔한 원인). 지침 단축 / 도구 수 축소 / 새 미리보기 대화 시작 / 더 큰 컨텍스트 창 모델 선택.
- CONVERSATION_BUSY — 대화당 한 번에 한 턴만 처리. 이전 응답 완료를 기다리면 되고, Send 이중 클릭이면 중복이 자동 거부되므로 조치 불필요. 멈춘 듯하면 새 대화 시작.
- CROSS_GEO_NOT_ALLOWED — 지역 내 모델 배포가 없고 타 지역 이동이 정책상 금지. 관리자가 테넌트 설정에서 지역 간 데이터 이동 허용 또는 지역 내 배포 제공 / 작성자는 자기 지역 배포 모델로 변경.
- DEPLOYMENT_NOT_FOUND — 모델이 사용 중단(retired)·제거·비가용. Build 탭 모델 선택기(model picker) 에서 가용 모델 선택.
- MODEL_CONSENT_DENIED — 일부 모델은 테넌트/환경 수준 동의(consent) 필요. 관리자가 활성화하거나 모델 변경. 대체 모델(fallback model)이 구성돼 있으면 자동 재시도되므로 조치 불필요.
- QUOTA_EXCEEDED vs RATE_LIMIT_REACHED — 전자는 청구 기간 단위 할당량 도달(정해진 일정에 리셋 — 대규모 평가는 피크 시간대 밖으로), 후자는 단기 버스트 과부하(몇 초 후 재시도, Evaluate에서 실패 케이스만 재실행).
- SYSTEM_ERROR — 일시적 인프라·내부 오류의 포괄 코드. 재시도 후 지속되면 활동 추적의 대화 ID + 실패 시각을 확보해 지원 문의. 광범위 장애면 관리자가 Microsoft 365 서비스 상태 대시보드 확인.
상위 호환성(forward compatibility) — 오류 코드 목록은 향후 릴리스에서 늘어날 수 있습니다. 자동화·대시보드를 만들 때 알 수 없는 코드는 SYSTEM_ERROR와 동일하게(일반 메시지 표시 + 재시도 허용) 처리하세요.
4. 디버깅 동선 — 추적과 기록을 함께 쓰기
- 활동 추적 — 메이커 뷰(End user preview OFF)에서 실패 노드를 펼쳐 오류 메시지·컨텍스트 확인. 흔한 원인: 인증 실패 · 지식 소스 접근 오류 · 타임아웃 · 콘텐츠 조정 플래그. 필(pill) 클릭으로 Build 탭 해당 컴포넌트로 점프.
- Preview 기록(History) — 상태 필터 Failed로 실패 대화만 모아 보고, Find by ID로 특정 대화 추적. Error 열의 코드 → 위 표에서 담당·조치 확인.
- 수정은 Build 탭 또는 Settings에서 → Preview 재테스트 → 필요하면 Evaluate 재실행으로 회귀 확인.
핵심 정리
- 오류 코드는 Preview / History Error 열 / 활동 추적 / Evaluate 결과 4곳에서 만난다
- 판단 축 2개: 재시도가 통하는가(BUSY·RATE_LIMIT·QUOTA는 대기 후 예) + 누가 고치는가(사용자/작성자/관리자/지원)
- 모르는 코드는 SYSTEM_ERROR처럼 처리 — 상위 호환성 지침
이전: 설정 Settings · M3 운영으로 · 다음 모듈: M4. 실습: 에이전트 Lab
출처: Error codes reference for agents (MS Learn) · Use the activity trace to debug your agent (MS Learn) · Manage preview conversations (MS Learn)