2026 AI Agent 총 산출물 잘못된 JSON? 데이터 흐름으로 문제 찾기

파싱기는 JSON을 읽지 못하고 도구 실행기는 빈 인자를 받는데, 모델 응답만 다시 보내고 있습니까?

가장 빠른 해결법은 오류를 모델 탓으로 묶지 않고 입력 계약 → 모델 생성 → API 응답 → 파싱과 검증 → 도구 실행 → 결과 회수 순서로 분리하는 것입니다. 플랫폼이 엄격한 구조화 출력을 지원하면 먼저 활성화하고, 그 뒤에 애플리케이션 계층의 의미 검증을 유지해야 합니다.

이 글이 필요한 팀

파싱 오류가 반복되는 백엔드 개발자는 실패 지점에 따라 조사 범위를 줄일 수 있습니다. 여러 단계의 AI Agent를 운영하는 엔지니어는 호출 식별자와 상태 회수를 점검할 수 있습니다. 운영 담당자는 원본 응답과 실행 결과를 연결하는 로그 기준을 만들 수 있습니다.

먼저 고장 난 위치를 데이터 흐름에 표시합니다

AI Agent JSON 오류는 화면에 나타난 마지막 예외만으로는 원인을 확정하기 어렵습니다. 예를 들어 도구 실행이 실패했더라도 실제 원인은 다음 중 하나일 수 있습니다.

• 요청에 포함한 스키마가 플랫폼의 지원 범위를 벗어났습니다.
• 모델 응답이 거부되었거나 길이 제한으로 중간에 끝났습니다.
• 응답은 JSON이지만 애플리케이션 검증기가 다른 스키마 방언으로 검사했습니다.
• 도구 인자는 문법적으로 올바르지만 경로, 계정, 권한 또는 주문 상태가 유효하지 않습니다.
• 여러 단계 사이에서 호출 식별자나 이전 도구 결과가 사라졌습니다.
• 개발 환경과 운영 환경의 SDK 또는 검증기 버전이 다릅니다.

따라서 파서 예외가 발생한 순간에 응답 문자열만 재시도하는 방식은 적절하지 않습니다. 원본 상태와 종료 이유를 먼저 확인해야 합니다.

입력 계약을 가장 작은 형태로 줄여 플랫폼부터 통과시킵니다

Function Calling에서 인자에 필수 필드가 빠지는 문제는 모델이 임의로 누락했다는 뜻일 수도 있지만, 입력 계약 자체가 불안정하다는 신호일 수도 있습니다. 먼저 업무 필드와 중첩 구조를 모두 제거하고, 문자열 하나와 필수 여부처럼 최소 조건만 남긴 스키마로 호출합니다.

그다음 아래 순서로 제약을 하나씩 복원합니다.

• 필드 이름과 자료형을 확인합니다.
• 필수 필드와 선택 필드를 분리합니다.
• 배열과 중첩 객체를 추가합니다.
• 열거형, 길이, 패턴 같은 제약을 추가합니다.
• 참조와 조건부 규칙을 마지막에 복원합니다.

$schema 선언은 검증기가 어떤 규칙 집합을 기준으로 해석할지 결정하는 단서입니다. JSON Schema의 규격 계열과 $schema 사용 방식은 공식 규격 안내와 기본 선언 가이드에서 확인할 수 있습니다. 운영 로그에는 스키마 원문뿐 아니라 해당 선언과 검증기 버전도 함께 남겨야 합니다.

Gemini의 Structured Output처럼 지원 자료형과 제약 조건의 일부만 허용하는 플랫폼도 있습니다. 따라서 일반적인 JSON Schema 전체가 그대로 통과한다고 가정하지 말고, Gemini 구조화 출력의 지원 범위를 기준으로 최소 재현을 먼저 실행해야 합니다.

거부와 잘린 응답은 파싱 오류와 따로 처리합니다

Structured Output을 켰더라도 모든 응답이 파싱 가능한 데이터가 되는 것은 아닙니다. 안전 정책에 따른 거부, 토큰 한도, 스트리밍 중단, API 오류는 정상적인 구조화 결과와 다른 상태입니다.

응답 처리기는 최소한 다음 분기를 가져야 합니다.

• 성공 상태: 원본 구조를 보존한 뒤 문법 검증과 의미 검증을 진행합니다.
• 거부 상태: 거부 사유와 요청 식별자를 기록하고, 재시도 대신 정책에 맞는 대체 경로를 선택합니다.
• 중단 상태: 종료 이유와 수신한 조각의 범위를 기록합니다.
• API 오류: 상태 코드, 재시도 가능 여부, 공급자 요청 식별자를 저장합니다.
• 알 수 없는 상태: 자동 실행을 중단하고 운영 큐로 보냅니다.

OpenAI의 스트리밍 응답에는 거부 관련 델타 상태가 별도로 정의되어 있습니다. 따라서 스트림을 단순히 문자열로 합친 뒤 JSON 파서에 넘기기보다 공식 거부 응답 설명을 확인해야 합니다. OpenAI Structured Outputs의 작동 조건과 제한도 공식 안내에서 인터페이스별로 대조해야 합니다.

주의: 일시적인 네트워크 오류에는 제한된 재시도가 유효할 수 있지만, 스키마 거부나 의미 검증 실패를 무한 재시도로 덮으면 원인과 비용만 함께 커집니다.

검증기를 모델 계약과 같은 언어로 맞춥니다

JSON Schema 오류처럼 보이지만 실제로는 검증기와 플랫폼이 서로 다른 규칙을 적용하는 경우가 있습니다. 개발 환경에서는 한 방언을 허용하고 운영 환경에서는 다른 기본값을 사용하는 식입니다. 이 차이는 특정 필드에서만 실패하므로 발견이 늦습니다.

배포 전에 다음을 고정합니다.

• 스키마의 $schema 선언
• 검증기 패키지와 버전
• 허용되는 형식 키워드의 동작
• 날짜, 숫자, 널 값의 해석 방식
• 플랫폼이 실제로 반환하는 구조
• 개발과 운영의 직렬화 설정

스키마 검증은 문법 통과 여부를 판단하는 단계입니다. 계정이 실제로 존재하는지, 호출 주체가 해당 리소스에 접근할 수 있는지, 두 필드의 조합이 업무 규칙에 맞는지는 별도 검증으로 분리해야 합니다.

JSON이 맞아도 도구 실행이 실패하는 이유를 분리합니다

유효한 JSON은 실행 가능한 명령과 같은 뜻이 아닙니다. 다음 검사를 도구 어댑터 앞에 배치해야 합니다.

• 리소스 식별자가 실제 저장소에 존재하는지 확인합니다.
• 호출 주체의 권한과 작업 범위를 확인합니다.
• 경로가 허용된 작업 영역 안에 있는지 확인합니다.
• 시작일과 종료일처럼 필드 사이의 관계를 검사합니다.
• 주문, 배포, 결제처럼 현재 상태에서 허용되는 작업인지 확인합니다.
• 외부 시스템의 응답을 원래 호출 식별자와 연결합니다.

Gemini의 Function Calling은 모델이 도구 호출을 제안하고 애플리케이션이 실제 함수를 실행한 뒤 결과를 다시 전달하는 흐름입니다. 이 과정에서 모델 출력을 곧바로 실행하지 말고, 공식 도구 호출 흐름에 맞춰 승인과 업무 검증 단계를 두어야 합니다.

MCP를 사용하는 경우에도 도구 이름, 인자, 결과 구조와 오류 처리 규칙을 서버와 클라이언트가 동일하게 이해해야 합니다. MCP 도구 규격과 전체 규격을 기준으로 호출과 결과 회수의 경계를 문서화해야 합니다.

여러 단계에서 사라지는 상태와 호출 식별자를 복구합니다

도구 결과를 모델에 다시 전달한 뒤 문맥이 사라진다면, 대화 내용 자체보다 호출 구조가 누락되었을 가능성이 큽니다. 특히 중간 계층이 모델 응답을 새 메시지로 바꾸면서 도구 호출 식별자, 도구 이름, 원래 인자 또는 실행 결과를 버리는 경우가 있습니다.

각 단계에서 다음 항목이 원형 그대로 이어지는지 확인합니다.

• 요청과 응답의 호출 식별자
• 모델이 반환한 도구 호출 블록
• 도구 이름과 인자
• 도구 실행 결과와 오류 내용
• 다음 모델 호출에 포함한 이전 상태
• 스트리밍 조각을 합친 최종 구조

인터페이스마다 상태를 보존하는 방식은 다를 수 있습니다. 어떤 호출은 이전 응답 식별자를 요구하고, 어떤 호출은 애플리케이션이 전체 메시지와 도구 결과를 직접 다시 구성해야 합니다. 그러므로 하나의 재사용 함수로 모든 API를 감싸기보다, 플랫폼별 공식 상태 규칙을 각각 검증해야 합니다.

증상별로 수리 순서를 선택합니다

증상	먼저 확인할 위치	우선 조치	뒤로 미룰 작업
JSON 파싱 자체가 실패함	원시 응답과 종료 상태	거부·중단·오류 분기 추가	모델 재시도
필수 인자가 빠짐	요청 스키마와 도구 호출 구조	최소 스키마로 재현	복잡한 조건 규칙
구조는 맞지만 실행이 거부됨	권한과 리소스 상태	의미 검증과 승인 단계 추가	프롬프트 문구 수정
도구 결과 뒤 문맥이 사라짐	호출 식별자와 메시지 회수	원형 구조와 상태 연결 복구	온도나 모델 변경
개발만 성공하고 운영이 실패함	검증기와 SDK 버전	버전과 방언 고정	무제한 재시도

이 표의 판단 기준은 “어느 모델이 더 똑똑한가”가 아니라 “어느 경계에서 데이터가 변했는가”입니다. 경계가 확인된 뒤에만 프롬프트, 모델, 재시도 정책을 조정해야 합니다.

최소 재현과 연결 로그로 원인을 고정합니다

운영 장애를 재현할 때는 전체 대화와 개인정보를 그대로 복사하지 않습니다. 다음 항목을 비식별화해 하나의 사건으로 묶습니다.

• 입력 메시지와 도구 정의
• 실제 전송한 스키마
• 모델, 인터페이스, SDK 버전
• 원본 응답과 종료 상태
• 파싱 결과와 검증 오류 경로
• 도구 실행 인자와 실행 결과
• 호출 식별자와 상위 작업 식별자
• 재시도 횟수와 각 시도의 사유

그 뒤 업무 규칙을 하나씩 제거한 최소 입력을 만들고, 같은 오류가 재현되는지 확인합니다. 최소 스키마에서도 실패하면 플랫폼 응답이나 직렬화 계층을 먼저 봅니다. 최소 스키마는 통과하지만 업무 스키마에서만 실패하면 지원되지 않는 제약, 검증기 차이 또는 필드 관계 규칙을 의심해야 합니다.

운영과 격리 환경이 달라 재현이 어려운 팀은 한국 맥 환경 신청처럼 별도 원격 맥 환경을 마련해 개발 환경과 실행 환경을 분리할 수 있습니다. 해외 리전에서만 나타나는 연결 또는 권한 문제를 확인해야 한다면 원격 맥 환경 선택도 비교 대상이 될 수 있습니다. 다만 물리 장비 접근이 필수이거나 장기간 일정한 고부하를 유지해야 한다면 직접 구매가 더 적합할 수 있습니다.

로컬 환경만으로 계속 조사하는 방식은 팀마다 SDK와 검증기 설치 상태가 달라지고, 운영 데이터와 재현 데이터가 섞이며, 특정 맥 환경의 권한이나 네트워크 조건을 복제하기 어렵다는 단점이 있습니다. 이런 조건에서 일시적인 장애 격리나 팀 단위 재현이 목적이라면 nuvcloud의 맥 대여 환경이 장비 구매보다 빠르게 비교 가능한 선택지가 될 수 있습니다. 반대로 장기 상시 실행과 물리 인터페이스가 핵심이면 대여를 선택하지 않는 편이 합리적입니다.

문제 해결의 출발점은 새 모델을 고르는 일이 아니라, 실패한 호출의 입력과 출력 사이에 어떤 데이터가 사라졌는지 확인하는 일입니다. 최소 재현 로그를 정리한 뒤 격리된 환경에서 다시 실행하면, AI Agent JSON 오류를 모델 문제와 계약, 파서, 도구, 상태 관리 문제로 나누어 수정할 수 있습니다.

추가 읽기

• 구조화된 출력을 안정적으로 받는 방법
• 함수 호출과 출력 형식 검증으로 제이슨 오류 줄이기