AI 에이전트의 JSON 호출이 파싱은 되지만 실행에 실패한다면, JSON 문법만 확인하지 말고 스키마, 도구 선택, 권한, 호출 아이디, 결과 형식을 순서대로 검증해야 합니다. AI 에이전트 JSON 데이터 흐름은 모델이 혼자 완성하는 값이 아니라 모델, 오케스트레이터, 실행기, API와 MCP 서버가 함께 만드는 계약입니다.
이 글은 세 부류의 독자를 위한 내용입니다.
- 에이전트 개발자: 호출 체인에서 JSON이 어떤 역할을 하는지 확인하려는 경우
- 장애 대응 엔지니어: 파라미터, 상태, MCP 결과 오류를 빠르게 분리하려는 경우
- 플랫폼 설계자: 통합 이벤트 로그와 스키마 버전을 설계하려는 경우
실패한 호출은 어느 층에서 깨졌는지부터 나눠야 합니다
예를 들어 사용자가 “맥에서 테스트 앱을 실행하고 결과를 알려 달라”고 요청했다고 가정해 보겠습니다. 모델은 실행 도구를 선택하고 인자를 JSON으로 생성합니다. 오케스트레이터는 이 인자를 검증한 뒤 권한을 확인하고, 실행기는 원격 환경에서 명령을 수행합니다. 마지막으로 결과가 다시 모델에 전달됩니다.
이때 실패 원인은 서로 다릅니다.
| 확인 층 | 정상적으로 확인할 내용 | 대표적인 실패 |
|---|---|---|
| 문법 | JSON으로 해석되는가 | 닫는 괄호 누락, 잘못된 문자열 |
| 스키마 | 필수 필드와 자료형이 맞는가 | timeout이 숫자가 아닌 문자열 |
| 선택 | 올바른 도구와 인자를 골랐는가 | 조회 도구 대신 삭제 도구 선택 |
| 실행 | 인증, 권한, 네트워크, 업무 조건이 통과하는가 | 토큰 만료, 앱 미실행 |
| 상태 | 호출 아이디와 대화 순서가 이어지는가 | 결과가 다른 호출에 연결됨 |
| 결과 | 도구 출력이 다음 단계의 형식에 맞는가 | structuredContent 불일치 |
이 구분이 필요한 이유는 각 층의 책임자가 다르기 때문입니다. 모델은 도구를 선택하고 인자를 제안하지만 실제 함수 실행은 애플리케이션의 책임입니다. Google의 Function Calling 문서도 모델이 함수를 직접 실행하지 않으며, 애플리케이션이 이름과 인자를 추출해 실행한 뒤 결과를 다시 모델에 보내야 한다고 설명합니다. (공식 Function Calling 문서)
JSON은 왜 AI 에이전트의 공용 운반 형식이 될까요?
AI 에이전트가 JSON을 사용하는 핵심 이유는 추론을 JSON으로 하기 위해서가 아닙니다. 자연어로 표현된 의도를 도구와 API가 처리할 수 있는 필드, 배열, 숫자, 불리언으로 바꾸고, 각 단계에서 검증하기 위해서입니다.
예를 들어 다음 데이터는 문법상 정상입니다.
{
"path": "/build/app",
"timeout": "짧게"
}
그러나 스키마가 timeout에 숫자를 요구한다면 구조적으로는 부적합합니다. 반대로 아래처럼 자료형이 맞아도 도구가 잘못 선택되면 실행은 실패합니다.
{
"path": "/build/app",
"timeout": 30
}
Function Calling의 JSON은 일반적으로 모델이 생성한 호출 정보와 애플리케이션이 실행한 결과를 함께 포함합니다. OpenAI API의 도구 호출에는 함수 이름, 인자, 호출 아이디가 포함되며, 공식 문서도 생성된 인자가 항상 유효한 JSON이거나 스키마에 정의된 파라미터라는 보장은 없으므로 코드에서 검증해야 한다고 명시합니다. (공식 도구 호출 문서)
Anthropic의 도구 사용도 같은 원칙을 따르지만 메시지 블록 구조는 다릅니다. 모델은 tool_use 블록에 이름, 아이디, 입력을 넣고, 실행 결과는 tool_result 블록으로 돌려받습니다. 결과 블록은 해당 도구 사용 블록 바로 뒤에 와야 하므로, 플랫폼별 메시지 형식을 하나의 공통 필드명으로 억지로 통합하면 오류가 생깁니다. (공식 도구 사용 문서)
첫 번째 점검: JSON은 합법인데 왜 호출이 실패할까요?
가장 흔한 오해는 json.parse() 또는 동일한 파서가 성공하면 호출도 정상이라고 보는 것입니다. 실제로는 다음 세 가지 검증을 분리해야 합니다.
- 문법 검증: 문자열이 JSON으로 읽히는지 확인합니다.
- 스키마 검증: 필수 필드, 자료형, 열거값, 중첩 구조를 확인합니다.
- 업무 검증: 해당 리소스가 존재하고 현재 계정이 작업을 수행할 수 있는지 확인합니다.
플랫폼마다 지원하는 JSON Schema 하위 집합도 다를 수 있습니다. 따라서 서버에서 사용하는 복잡한 조건부 스키마를 모든 모델 호출 인터페이스가 그대로 이해한다고 가정하면 안 됩니다. 스키마 버전을 저장하고, 실제 플랫폼이 허용하는 키워드만 별도로 관리해야 합니다.
스키마가 맞는데도 도구 선택이 틀렸다면 필드 타입을 더 엄격하게 만드는 방식으로는 해결되지 않습니다. 다음 항목을 먼저 조정해야 합니다.
- 도구 이름에 동작과 대상을 함께 넣습니다.
- 설명에 사용 조건과 사용하지 말아야 할 조건을 씁니다.
- 한 번에 노출하는 후보 도구 수를 줄입니다.
- 사용자 요청의 대상, 권한, 현재 상태를 호출 직전에 함께 전달합니다.
- 파괴적 작업과 조회 작업을 별도 도구로 분리합니다.
파라미터가 맞아도 API가 거부되는 실행 단계
이 단계부터는 모델의 문제가 아니라 실행기의 문제일 가능성이 높습니다. 다음 항목을 구분해 기록해야 합니다.
- 인증 실패: 토큰 만료, 서명, 계정 상태를 확인합니다.
- 권한 부족: 역할과 프로젝트 범위를 확인합니다.
- 리소스 상태 오류: 앱 실행 여부, 잠금, 작업 상태를 확인합니다.
- 네트워크 오류: 연결, 지연, 도메인 이름 해석, 방화벽을 확인합니다.
- 업무 규칙 위반: 중복 요청이나 잘못된 상태 전이를 확인합니다.
실행기는 단순한 문자열 "failed"를 반환하지 않는 편이 좋습니다. 예를 들어 error_code, retryable, required_permission, resource_state를 구조화하면 오케스트레이터가 재시도, 사용자 확인, 종료를 결정할 수 있습니다. 모델에게 원인을 추측하게 만들면 인증 실패를 네트워크 오류로 설명하거나, 권한 문제를 같은 요청으로 반복하는 루프가 생깁니다.
세 번째 점검: 호출 아이디가 사라지면 무엇이 꼬일까요?
여러 도구를 병렬로 실행할 때 호출 아이디는 단순한 추적용 문자열이 아닙니다. 결과를 어느 요청에 연결할지 결정하는 키입니다.
호출 아이디가 유실되면 다음 문제가 발생합니다.
- 첫 번째 도구의 결과를 두 번째 도구의 결과로 잘못 해석합니다.
- 실패한 호출이 성공한 것으로 표시됩니다.
- 같은 작업을 다시 실행해 중복 생성이나 중복 결제가 발생할 수 있습니다.
- 이전 상호작용이나 대화 기록이 끊겨 에이전트 루프가 중단됩니다.
Google의 현재 상호작용 방식은 함수 결과를 보낼 때 호출 단계의 아이디를 함께 전달하고, 상태를 직접 관리하는 방식에서는 이전 모델 단계와 함수 결과를 전체 기록에 보존하도록 안내합니다. (공식 함수 호출 문서)
OpenAI의 스트리밍 호출에서도 인자 조각과 호출 아이디가 별도 이벤트로 전달될 수 있습니다. 따라서 스트리밍 환경에서는 마지막 조각만 저장하지 말고 response_id, item_id, call_id, 인자 누적 상태를 함께 기록해야 합니다. (공식 실시간 이벤트 문서)
MCP 결과는 어떻게 모델까지 돌아가야 할까요?
Model Context Protocol은 도구 목록, 입력 스키마, 호출 요청, 결과 전달 방식을 표준화하는 프로토콜입니다. MCP 도구 정의에는 이름, 설명, inputSchema, 선택적인 outputSchema가 포함됩니다. 호출은 tools/call로 전달되고, 결과에는 content, 선택적인 structuredContent, 오류 여부가 들어갈 수 있습니다. (공식 MCP 도구 사양)
MCP 결과를 처리할 때는 다음 원칙을 지키는 편이 안전합니다.
- 서버가 제공한
outputSchema를 저장합니다. structuredContent를 클라이언트에서 다시 검증합니다.- 호환성을 위해 직렬화된 JSON을 텍스트 콘텐츠에도 보존합니다.
isError가 설정된 결과와 전송 계층 오류를 구분합니다.- 클라이언트가 모든 선택 필드를 지원한다고 가정하지 않습니다.
MCP 사양은 구조화된 결과를 반환할 때 호환성을 위해 텍스트 콘텐츠에도 직렬화된 JSON을 함께 제공하도록 권고합니다. 즉, structuredContent만 믿으면 일부 클라이언트에서 결과가 사라질 수 있고, 텍스트만 믿으면 타입 검증 기회를 잃을 수 있습니다. (공식 MCP 도구 결과 사양)
MCP 내부 오류는 모델이 볼 수 있도록 결과 객체 안에 오류를 담고 오류 상태를 표시하는 방식이 권장됩니다. 반면 도구를 찾을 수 없거나 서버가 호출을 지원하지 않는 경우처럼 프로토콜 자체의 예외는 별도 MCP 오류로 처리해야 합니다. (공식 MCP 스키마 문서)
호출 체인을 고치는 6단계 점검표
아래 항목을 장애 대응 순서로 사용하면 모델 프롬프트를 무작정 수정하는 일을 줄일 수 있습니다.
- [ ] 원본 사용자 요청과 모델이 선택한 도구 이름을 같은 이벤트에 저장합니다.
- [ ] 요청 당시 사용한 입력 스키마와 스키마 버전을 기록합니다.
- [ ] 생성된 JSON의 문법 검증 결과와 스키마 검증 결과를 분리해 남깁니다.
- [ ] 권한 결정, 인증 상태, 리소스 상태, 네트워크 결과를 실행 로그에 저장합니다.
- [ ] 호출 아이디와 결과 아이디가 일치하는지 병렬 실행마다 확인합니다.
- [ ] MCP 결과의
content,structuredContent,outputSchema, 오류 상태를 함께 검증합니다. - [ ] 최종 답변 전에 업무 규칙 검증을 한 번 더 수행합니다.
- [ ] 재시도 횟수와 동일한 작업의 멱등성 여부를 기록합니다.
운영 로그에는 최소한 request_id, conversation_id, call_id, 도구 이름, 스키마 버전, 권한 판단, 실행 시작과 종료 상태, 원본 오류 코드, 결과 검증 결과를 넣는 것이 좋습니다. 이 구조라면 모델이 잘못 선택했는지, 실행기가 거부했는지, MCP 클라이언트가 결과를 버렸는지 한 화면에서 분리할 수 있습니다.
macOS 도구를 호출하는 장기 실행 에이전트라면 이 이벤트에 원격 환경 상태도 연결해야 합니다. 운영 중인 맥 지원 안내를 참고해 운영체제 권한, 세션 상태, 접근 가능한 작업 디렉터리와 같은 실행 조건을 별도 필드로 관리하면 코드 문제와 환경 문제를 구분하기 쉽습니다.
어떤 실행 환경이 장애 재현에 유리한지 비교해 보세요
| 환경 | 장점 | 주의할 점 | 적합한 경우 |
|---|---|---|---|
| 개발자 로컬 맥 | 빠른 코드 수정과 로그 확인 | 계정, 권한, 설치 상태가 사람마다 다름 | 단일 개발자 재현 |
| 고정된 사내 서버 | 의존성과 접근 정책을 통제하기 쉬움 | macOS 전용 도구 검증에 제약 | 공통 API 실행 |
| 원격 맥 환경 | macOS 권한과 실제 도구를 분리 재현 | 세션, 네트워크, 파일 접근을 함께 관리해야 함 | 교차 계층 장애 재현 |
| 매번 새로 만드는 임시 환경 | 오염된 상태를 줄임 | 설치와 초기화 과정 자체가 변수 | 설치 자동화 검증 |
현재 환경에서만 오류가 나고 다른 컴퓨터에서는 정상이라면 JSON 수정부터 시작하지 마십시오. 먼저 의존성 버전, 권한 승인 상태, 실행 사용자, 환경 변수, 파일 경로, 네트워크 정책을 고정한 뒤 같은 request_id로 재현해야 합니다.
지속적인 장애 분석이 필요하다면 맥 미니 렌탈 환경처럼 실행 환경을 분리하는 방법도 검토할 수 있습니다. 특히 에이전트가 macOS 명령, 앱 자동화, 빌드 도구를 함께 호출한다면 로컬 맥의 개인 설정이 섞이는 것보다 고정된 원격 환경에서 로그와 상태를 함께 수집하는 편이 판단하기 쉽습니다.
결국 JSON은 에이전트의 두뇌가 아니라 호출 체인을 연결하는 검증 가능한 운반 형식입니다. 현재 방식이 로컬 맥에 의존하면 권한과 설치 상태가 사람마다 달라지고, 일반 서버만 쓰면 macOS 도구를 재현할 수 없으며, 매번 새 환경을 만들면 장애 당시 상태가 사라지는 단점이 있습니다. 여러 계층의 실패를 반복 재현해야 한다면 Kvmzen의 맥 환경을 임시 테스트와 원격 검증에 활용하는 편이 더 현실적입니다. 다만 장기간 고정된 고부하 작업이나 물리 장비 연결이 필요한 경우에는 직접 장비를 운영하는 방식이 더 적합합니다.
필요한 것은 무조건 새로운 모델이 아니라, 호출 이벤트와 실행 환경을 함께 고정할 수 있는 재현 공간입니다. Kvmzen의 맥 미니 대여 안내에서 현재 에이전트의 테스트 조건에 맞는 운영 방식을 확인해 보십시오.