에러 처리와 관측

실패를 결과로 남기기

에이전트 작업에서 실패는 도구가 거부된 경우, 명령이 실패한 경우, 권한 승인이 거부된 경우, 모델·네트워크 제한에 도달한 경우처럼 여러 층에서 생긴다. 실패를 단순 텍스트 로그로만 남기지 말고 작업 ID, 프롬프트 버전, 허용 도구, 종료 상태, 도구 이름, 테스트 결과를 연결해 기록한다. 그래야 재시도와 원인 분석에서 원래의 권한·입력·환경을 재현할 수 있다.

작업 시작 → 도구 제안 → 승인/정책 → 실행 결과
                               │
                           실패 발생
                               │
          hook·로그·추적 → 사용자에게 안전한 요약 → 재시도 또는 중단

hooks는 결정적 후처리에 사용

공식 hooks는 도구 사용과 작업 생명주기의 특정 이벤트에 명령, HTTP, MCP 도구, 프롬프트 기반 처리를 연결할 수 있다. 실패 알림이나 감사 로그를 추가할 때는 hook 자체가 실패해도 본 작업을 어떻게 처리할지 정하고, 네트워크로 보낼 데이터에는 비밀·소스 코드가 포함되지 않도록 필터링한다.

| 목적 | 권장 위치 | 확인할 점 | | --- | --- | --- | | 위험 명령 차단 | 실행 전 정책·권한 | matcher와 경로 범위를 최소화 | | 실패 알림 | 실패 후 hook·관측 시스템 | 비밀과 원문 로그 마스킹 | | 결과 품질 검사 | 테스트·정적 검사 | 모델 요약과 분리해 실행 | | 장기 분석 | OpenTelemetry 등 관측 파이프라인 | 보존 기간·접근 권한 |

비용과 사용량 관측

Agent SDK의 result 메시지와 공식 비용·사용량 기능은 작업별 비용, 턴, 종료 상태를 관측하는 근거가 된다. 다만 모델·프롬프트·도구 결과·캐시 조건이 다르므로 특정 토큰 수, 비용 비율, 컨텍스트 임계값을 모든 환경에 적용하는 규칙으로 두지 않는다. 팀은 실제 작업 유형별 기준선을 만들고, 예산 한도와 오류 재시도 횟수를 정책으로 결정한다.

작업 지표 → 비용·지연·오류율·검증 통과율
     │
     ├─ 범위가 큰 프롬프트를 줄이기
     ├─ 허용 도구를 좁히기
     └─ 사람 검토가 필요한 작업을 분리하기

관측 데이터는 개선을 위한 것이지, 위험한 자동 변경을 정당화하는 근거가 아니다. 오류가 발생하거나 지표가 예상 밖으로 증가하면, 우선 권한을 줄이고 입력·MCP 서버·세션 재개 경로를 검토한 뒤에 재시도한다.

---

퀴즈를 불러오는 중...