# [[JSON-RPC 2.0]]

## 📌 Brief Summary
JSON-RPC 2.0은 AI 에이전트 하네스 환경에서 모델(클라이언트)과 외부 도구 및 리소스(서버) 간의 통신을 표준화하는 기반 메시징 교환 프로토콜입니다. 주로 MCP(Model Context Protocol) 및 ACP(Agent Client Protocol)와 같은 에이전트 통신 표준의 기본 데이터 계층을 구성하여 메시지의 구조와 의미(Semantics)를 정의합니다. 요청(Request)과 응답(Response)을 고유 ID로 연관 짓고, 응답을 기대하지 않는 단방향 알림(Notification) 전송을 지원하여 에이전트와 외부 시스템 간의 결정론적 상호작용을 가능하게 합니다.

## 📖 Core Content
* **데이터 계층의 메시지 구조화:** JSON-RPC 2.0은 에이전트 하네스와 외부 도구 간의 통신을 위한 데이터 계층(Data layer) 프로토콜로 기능합니다. 클라이언트와 서버는 JSON-RPC 2.0 형식을 사용하여 서로 요청을 보내고 적절히 응답합니다. 특히 고유한 `id` 필드를 사용하여 요청과 응답 간의 상호 연관성(correlation)을 보장하며, 통신의 타입 안정성(Type safety)과 명확성을 확보합니다 [1-4].
* **알림(Notification) 시맨틱 지원:** 응답을 요구하지 않는 단방향 상태 업데이트를 위해 JSON-RPC 2.0의 알림 메시지를 지원합니다. 이 알림 메시지에는 `id` 필드가 포함되지 않는 것이 특징입니다. 이를 통해 서버는 도구 목록의 변경 사항이나 실시간 동적 업데이트를 연결된 클라이언트(AI 애플리케이션)에 즉각적으로 통지할 수 있습니다 [3, 5, 6].
* **전송 계층(Transport Layer)과의 결합:** JSON-RPC 2.0 메시지는 통신 메커니즘을 정의하는 전송 계층을 통해 전달됩니다. 주로 로컬 프로세스 간 직접 통신을 위해 네트워크 오버헤드가 없는 표준 입출력(stdio)을 사용하거나, 원격 서버와의 통신 및 실시간 데이터 스트리밍을 위해 Server-Sent Events(SSE)가 결합된 HTTP POST를 사용하여 전송됩니다 [7].
* **하네스 및 에이전트 프로토콜의 표준 기반:** Anthropic의 MCP는 Language Server Protocol(LSP)의 메시지 흐름 개념을 재사용하며 JSON-RPC 2.0 기반 위에서 동작합니다 [8]. 또한 에이전트와 IDE 클라이언트 간의 통신을 표준화하는 ACP(Agent Client Protocol) 역시 JSON-RPC 2.0을 사용하며, OpenAI의 Codex 하네스는 모든 클라이언트 표면에 에이전트 런타임을 노출하기 위해 stdio 기반의 JSON-RPC/JSONL 프로토콜(Item/Turn/Thread 프로토콜)을 구현했습니다 [9, 10].

## ⚖️ Trade-offs & Caveats
* **지연 시간과 확장성의 트레이드오프:** JSON-RPC 2.0을 stdio(표준 입출력) 전송과 결합하여 로컬 도구를 호출할 경우 2~15ms의 매우 낮은 지연 시간으로 단일 하네스 에이전트의 긴밀한 통합 루프에 최적화된 성능을 제공합니다. 하지만 이는 다중 테넌트(Multi-tenant) 또는 원격 환경으로 확장할 때 불리하며, 이 경우 JSON-RPC를 HTTP+SSE 전송으로 넘겨 처리해야 하므로 50~200ms 이상의 네트워크 지연이 발생할 수 있습니다 [11, 12].
* **프로토콜 자체의 보안 및 상태 관리 한계:** JSON-RPC 2.0 프로토콜 자체에는 상태 저장(Stateful) 세션 관리 기능이나 네임스페이스 스푸핑(Tool spoofing)을 방지하는 보안 모델이 내장되어 있지 않습니다. 따라서 JSON-RPC를 도입하는 에이전트 하네스는 프로토콜 계층에만 의존해서는 안 되며, 악의적인 도구 주입이나 권한 남용을 방지하기 위해 하네스의 수명주기 훅(Lifecycle Hooks, L-component)을 통한 강력한 사전/사후 검증 정책을 추가로 직접 구현해야 합니다 [13-15].

## 🔗 Knowledge Connections

### Related Concepts

#### [관계 유형 A (아키텍처/기반 기술)]
* [[Model Context Protocol]] (MCP)
  * 연결 이유: AI 에이전트와 외부 데이터, 도구를 연결하는 개방형 표준으로 JSON-RPC 2.0을 기본 데이터 통신 프로토콜로 사용합니다 [1, 3].
  * 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON-RPC 2.0이 실제 에이전트 런타임에서 도구 탐색(Discovery), 실행(Execution), 자원 접근에 활용되는 구체적인 데이터 교환 스키마를 이해할 수 있습니다.
* [[Agent Client Protocol]] (ACP)
  * 연결 이유: 코딩 에이전트와 IDE 등의 클라이언트 애플리케이션 간의 통합을 표준화하기 위해 JSON-RPC 2.0을 사용하는 프로토콜입니다 [9].
  * 이 개념을 통해 더 깊게 이해할 수 있는 부분: 에이전트 하네스의 실행 루프(E-component)가 사용자 인터페이스와 상호작용하고 상태 업데이트 및 취소(Cancellation) 명령을 관리하는 방식을 파악할 수 있습니다.

#### [관계 유형 B (구현/전송 매커니즘)]
* [[stdio transport]]
  * 연결 이유: JSON-RPC 2.0 메시지를 네트워크 오버헤드 없이 로컬 머신에서 가장 빠르게 전송하기 위해 사용되는 표준 입출력 전송 방식입니다 [7].
  * 이 개념을 통해 더 깊게 이해할 수 있는 부분: 단일 하네스 내에서 도구 실행(T-component) 지연 시간을 밀리초 단위로 최소화하기 위한 시스템 레벨의 최적화 기법을 이해할 수 있습니다.
* [[Lifecycle Hooks]] (하네스 L-component)
  * 연결 이유: JSON-RPC 2.0을 기반으로 통신하는 도구 및 서버에 대해, 실제 실행 권한을 통제하고 정책을 집행(Policy enforcement)하는 하네스의 필수 보안/거버넌스 계층입니다 [13, 14, 16].
  * 이 개념을 통해 더 깊게 이해할 수 있는 부분: 단순히 JSON-RPC 메시지를 주고받는 것을 넘어, 엔터프라이즈 하네스 환경에서 도구 호출을 신뢰할 수 있도록 보장하는 방어 계층을 어떻게 구축하는지 배울 수 있습니다.

### Deeper Research Questions
* 다중 에이전트(Multi-agent) 시스템에서 JSON-RPC 2.0 기반의 알림(Notification) 메시지는 에이전트 간의 작업 상태(Task graph)를 동기화하는 데 어떤 방식으로 활용될 수 있는가?
* JSON-RPC 2.0 메시지를 처리하는 에이전트 하네스의 실행 루프(E-component)는 네트워크 시간 초과(Timeout)나 스키마 불일치 등 외부 도구 서버의 실패를 어떻게 분류하고 복구(Retry/Graceful degradation)하는가?
* 로컬 프로세스 간의 JSON-RPC 통신(stdio)과 분산 환경에서의 HTTP 통신 간에 트랜잭션의 상태와 컨텍스트 출처(Provenance)를 보존하기 위해 하네스 설계는 어떻게 변경되어야 하는가?
* JSON-RPC 2.0 포맷을 통해 오가는 대용량 도구 출력 결과를 프롬프트 윈도우 한계 내에서 처리하기 위해, 하네스의 컨텍스트 관리자(C-component)는 어떤 계층적 요약 및 아티팩트 분리 전략을 사용하는가?

### Practical Application Contexts
* **Implementation:** MCP 서버 구축 시 JSON-RPC 2.0 규격에 맞춰 `tools/list`, `tools/call` 등 고유 ID를 포함한 요청과 결과를 처리하는 핸들러를 코드로 구현합니다.
* **System Design:** 에이전트 하네스 설계 시, 로컬 보안 샌드박스 내부의 도구는 stdio 기반 JSON-RPC로 연결하고 원격 에이전트 간 위임은 HTTP 기반으로 처리하도록 전송 계층을 분리하는 하이브리드 아키텍처를 도입합니다.
* **Operation / Maintenance:** 하네스의 평가 인터페이스(V-component)나 관측 가능성(Observability) 시스템을 통해 JSON-RPC 2.0 메시지 페이로드의 로그를 캡처하여, 에이전트의 실행 궤적(Trajectory)과 도구 호출 실패 원인을 추적 및 디버깅합니다.
* **Learning Path:** LLM 모델의 출력이 외부 세계와 상호작용하기 위해 어떻게 구조화된 명령으로 변환되는지 이해하고자 할 때, 기반이 되는 JSON-RPC 2.0 사양을 학습하고 이를 적용한 MCP 아키텍처 스펙으로 나아갑니다.
* **My Project Relevance:** 맞춤형 AI 업무 자동화 에이전트를 구축할 때, 내부 데이터베이스나 레거시 API를 JSON-RPC 2.0 기반의 표준 MCP 서버로 래핑(Wrapping)하여 특정 에이전트 프레임워크 종속성 없이 범용적으로 통신하도록 통합합니다.

### Adjacent Topics
* [[Language Server Protocol]] (LSP)
  * 확장 방향: JSON-RPC를 기반으로 하는 또 다른 주요 표준으로, 코딩 에이전트 하네스가 복잡한 소프트웨어 프로젝트 환경에서 시맨틱 코드 분석 및 심볼 탐색(find_symbol 등)을 효율적으로 수행하기 위해 어떻게 도구화하는지 그 개념을 연장할 수 있습니다.
* [[Agent-to-Agent Protocol]] (A2A)
  * 확장 방향: 에이전트와 도구 간 통신(MCP)이 아닌, 원격 에이전트 간의 위임과 상호작용을 처리하는 통신 규약으로서 다중 에이전트 하네스 오케스트레이션 계층에 대한 이해를 확장할 수 있습니다.

---
*Last updated: 2026-05-01*