Transport-Agnostic

• Transport-agnostic는 프로토콜이 특정 전송 메커니즘에 결합되지 않은 설계 원칙
• 메시지 정의·교환 규칙을 **전송 계층(transport layer)**과 분리하는 추상화 전략
• 같은 프로토콜을 SSE·WebSocket·stdio·HTTP·gRPC 등 어떤 채널에서도 실행 가능한 이식성
• “agnostic”의 IT 용법 — underlying detail에 의존하지 않음

이 원칙이 필요한 이유

• transport 변화에 강건 — 새 전송 수단(예: HTTP/3, QUIC, IPC)이 나타나도 메시지 정의는 그대로
• 다중 환경 대응 — 같은 프로토콜이 브라우저(SSE), 서버(WebSocket), 데스크톱(stdio)에서 동작
• 테스트 용이성 — 메시지 의미는 transport 없이 단위 테스트 가능
• 다언어 SDK — transport 처리는 언어별 관용 방식을 따르되, 메시지 스키마는 공유
• OSI 계층 분리 원칙의 적용 — application 의미와 delivery 메커니즘은 다른 관심사

AS-IS — transport에 결합된 설계

flowchart TB
    subgraph "단일 패키지"
        Msg["메시지 타입"]
        HTTP["HTTP 클라이언트"]
        SSE["SSE 파서"]
        Logic["비즈니스 로직"]
    end

    Msg --> HTTP
    Msg --> SSE
    HTTP --> Logic
    SSE --> Logic

    style HTTP fill:#FFCDD2
    style SSE fill:#FFCDD2

문제:

• 메시지 정의를 import 하는 순간 HTTP 라이브러리까지 끌려옴
• 새 transport 추가 시 메시지 타입까지 수정 압력
• 다른 언어 SDK는 메시지 정의를 처음부터 다시 작성해야 함

TO-BE — transport 경계 분리 (패키지 분할)

flowchart TB
    subgraph CorePkg["@myproto/core (transport 모름)"]
        Schema["메시지 스키마<br/>이벤트 타입 정의"]
    end

    subgraph EncoderPkg["@myproto/encoder (HTTP 모름)"]
        Encoder["JSON/Binary 직렬화<br/>media type 라우팅"]
    end

    subgraph T1Pkg["@myproto/http-client"]
        T1["HTTP/SSE Transport"]
    end

    subgraph T2Pkg["@myproto/ws-client"]
        T2["WebSocket Transport"]
    end

    subgraph T3Pkg["@myproto/stdio-client"]
        T3["stdio Transport"]
    end

    CorePkg --> EncoderPkg
    EncoderPkg --> T1Pkg
    EncoderPkg --> T2Pkg
    EncoderPkg --> T3Pkg

    style CorePkg fill:#E3F2FD
    style EncoderPkg fill:#F3E5F5
    style T1Pkg fill:#E0F7E9
    style T2Pkg fill:#E0F7E9
    style T3Pkg fill:#E0F7E9

핵심: 의존이 한 방향(아래로)으로만 흐른다. core는 transport를 모르고, transport는 core를 import할 뿐 그 반대는 없다. 새 transport는 옆에 패키지를 하나 더 추가하면 끝.

핵심 정의 비교

권위 있는 사용처에서 어떻게 정의하는지 비교:

출처	정의
MCP (공식 스펙)	“The protocol is transport-agnostic and can be implemented over any communication channel that supports bidirectional message exchange.”
AG-UI (공식 docs)	“AG-UI doesn’t mandate how events are delivered, supporting various transport mechanisms including SSE, WebSockets, webhooks, etc.”
gRPC (공식 소개)	“transport-agnostic RPC framework” — HTTP/2가 기본이지만 추상상으로 transport 독립
NVM Express	NVMe 명령 집합과 transport(PCIe·TCP·RDMA)를 분리 — 같은 명령이 다른 transport 위에서 동작

공통 패턴: “X (메시지/이벤트/명령)은 정의되어 있고, 어떻게 전달할지는 별개”.

무엇이 transport인가

OSI 7계층 중 transport는 4계층(TCP/UDP)이지만, “transport-agnostic”의 transport는 더 넓은 의미다 — 메시지를 양 끝점 사이에 실어 나르는 모든 채널.

분류	예시
네트워크 기반	HTTP/1.1, HTTP/2, HTTP/3, WebSocket, gRPC, QUIC
스트리밍 의미	Server-Sent Events (SSE), Long-polling
로컬 IPC	stdio, Unix socket, Named pipe
메시지 큐	Kafka, RabbitMQ, NATS
RPC 채널	gRPC, Apache Thrift

transport-agnostic 프로토콜은 이 중 어떤 것을 골라 써도 메시지 의미가 보존되어야 한다.

자매 용어 — 무엇과 무엇이 독립인가

“agnostic”은 항상 무엇에 대한 agnostic인지가 핵심이다. 다른 축의 독립성과 비교:

용어	독립 대상	예시
Transport-agnostic	전송 채널	gRPC, MCP, AG-UI
Protocol-agnostic	application 프로토콜 자체	PASTE 연구, 다중 프로토콜 게이트웨이
Wire-format-agnostic	직렬화 형식 (JSON/Protobuf/Avro)	OpenAPI, Apache Avro
Language-agnostic	프로그래밍 언어	Protocol Buffers .proto
Cloud-agnostic	클라우드 프로바이더	Terraform, Kubernetes
Vendor-agnostic	특정 벤더 제품	OpenTelemetry vs APM 벤더

transport-agnostic은 이 중 delivery 채널만 추상화한다 — 메시지 형식이나 의미는 여전히 강하게 정의되어 있다.

실제 적용 사례 — 적용 전/후 비교

중요한 전제: transport-agnostic은 어떤 단위로 분리했는가가 아니라 분리되었는가가 핵심이다. 파일/모듈 분리만으로도 충분히 적용된 상태이며, 패키지·저장소 분리는 강제력이 더 강한 형태일 뿐이다. 아래 두 사례는 같은 원칙을 다른 강도로 적용한 예시다.

1. MCP 스타일 — 한 패키지 안에서 파일/클래스 분리

단위: 파일·클래스 (단일 패키지 mcp-sdk 안에서 분리)

적용 전 — 한 파일에 모든 책임이 뭉쳐 있음

mcp-sdk/                              ← 패키지 1개
└── mcp_client.py                     ← 파일 1개

# 📦 mcp-sdk / 📄 mcp_client.py
import json, subprocess
 
class MCPClient:
    def __init__(self, server_command):
        self.process = subprocess.Popen(server_command, ...)
 
    def call_tool(self, name, args):
        msg = {"jsonrpc": "2.0", "method": "tools/call", "params": {...}}
        # ❌ stdio 호출이 메시지 빌드와 뒤엉킴
        self.process.stdin.write(json.dumps(msg).encode() + b"\n")
        line = self.process.stdout.readline()
        return json.loads(line)

문제: HTTP 서버에 연결하려면 MCPClient 전체를 복제해야 함. JSON-RPC 빌드 로직이 stdio 호출과 한 메서드에 섞여 있다.

적용 후 — 같은 패키지 안에서 파일로 책임 분리

mcp-sdk/                              ← 여전히 패키지 1개
├── mcp/
│   ├── protocol.py                   ← transport 모름
│   ├── transport.py                  ← 추상 인터페이스
│   ├── client.py                     ← transport 주입받음
│   └── transports/
│       ├── stdio.py                  ← Transport 구현체
│       └── http.py                   ← Transport 구현체

# 📦 mcp-sdk / 📄 mcp/protocol.py — transport 모름
@dataclass
class JSONRPCRequest:
    method: str
    params: dict
    id: int
 
def build_tool_call(name: str, args: dict) -> JSONRPCRequest: ...
def parse_response(raw: bytes) -> dict: ...

# 📦 mcp-sdk / 📄 mcp/transport.py — 추상 인터페이스
class Transport(Protocol):
    async def send(self, msg: bytes) -> None: ...
    async def receive(self) -> bytes: ...

# 📦 mcp-sdk / 📄 mcp/transports/stdio.py
from mcp.transport import Transport
 
class StdioTransport(Transport):
    def __init__(self, cmd): self.proc = subprocess.Popen(cmd, ...)
    async def send(self, msg): self.proc.stdin.write(msg + b"\n")
    async def receive(self): return self.proc.stdout.readline()

# 📦 mcp-sdk / 📄 mcp/transports/http.py
from mcp.transport import Transport
 
class StreamableHTTPTransport(Transport):
    def __init__(self, url): self.url = url
    async def send(self, msg): await httpx.post(self.url, content=msg)
    async def receive(self): ...  # SSE 파싱

# 📦 mcp-sdk / 📄 mcp/client.py — transport 주입
from mcp.protocol import build_tool_call, parse_response
from mcp.transport import Transport
 
class MCPClient:
    def __init__(self, transport: Transport):
        self.transport = transport
 
    async def call_tool(self, name, args):
        req = build_tool_call(name, args)         # protocol layer
        await self.transport.send(serialize(req)) # transport layer
        return parse_response(await self.transport.receive())

# 사용자 코드 — transport만 갈아끼움
from mcp.client import MCPClient
from mcp.transports.stdio import StdioTransport
from mcp.transports.http import StreamableHTTPTransport
 
client = MCPClient(StdioTransport(["uvx", "mcp-server-git"]))
client = MCPClient(StreamableHTTPTransport("https://example.com/mcp"))

핵심: 모두 같은 mcp-sdk 패키지 안의 파일 분리다. 패키지를 쪼개지 않았어도 transport-agnostic은 이미 적용됐다. 새 transport 추가 = mcp/transports/ 디렉토리에 파일 하나 추가.

2. AG-UI 스타일 — 여러 패키지로 분리

단위: npm 패키지 (@ag-ui/core, @ag-ui/proto, @ag-ui/encoder, @ag-ui/client)

MCP 사례가 한 패키지 안에서 파일로 분리했다면, AG-UI는 한 단계 더 강하게 별도 npm 패키지로 분리해서 의존성 그래프 자체로 잘못된 import를 차단한다.

적용 전 — 단일 패키지에 모든 코드

ag-ui/                                     ← 가상의 단일 패키지
├── package.json
└── src/
    ├── events.ts                          ← 타입 정의
    ├── proto.ts                           ← Protobuf 인코딩
    ├── encoder.ts                         ← SSE/binary 라우팅
    └── http-agent.ts                      ← HTTP + RxJS

// 📦 ag-ui / 📄 package.json
{
  "name": "ag-ui",
  "dependencies": {
    "zod": "^3",
    "rxjs": "^7",
    "@bufbuild/protobuf": "^1",
    "fast-json-patch": "^3"
  }
}

// 📦 ag-ui / 📄 사용자 코드
import { Event, HttpAgent } from "ag-ui";
// ❌ Event 타입 하나만 import 해도 RxJS·protobuf 모두 번들에 포함

문제:

• 브라우저에서 타입만 쓰려 해도 모든 의존성 트리 동봉
• 다른 언어(Python) SDK가 .proto를 재사용하려 해도 TS 코드가 따라옴
• WebSocket transport를 추가하려면 패키지 전체 의존성에 영향

적용 후 — 4개 패키지로 분할 (AG-UI 실제 구조)

sdks/typescript/packages/
├── core/                                  ← 📦 @ag-ui/core
│   ├── package.json
│   └── src/
│       ├── events.ts                      ← 이벤트 타입
│       ├── types.ts                       ← 메시지 타입
│       └── capabilities.ts                ← capability 협상
│
├── proto/                                 ← 📦 @ag-ui/proto
│   ├── package.json
│   └── src/
│       ├── proto/*.proto                  ← 언어 중립 스키마
│       └── proto.ts                       ← encode/decode
│
├── encoder/                               ← 📦 @ag-ui/encoder
│   ├── package.json
│   └── src/
│       ├── encoder.ts                     ← SSE/binary 라우터
│       └── media-type.ts
│
└── client/                                ← 📦 @ag-ui/client
    ├── package.json
    └── src/
        ├── agent/HttpAgent.ts             ← HTTP transport
        └── run/                           ← RxJS streaming

// 📦 @ag-ui/core / 📄 package.json
{
  "name": "@ag-ui/core",
  "dependencies": { "zod": "^3" }          // ✅ zod만 — transport·HTTP·RxJS 없음
}

// 📦 @ag-ui/proto / 📄 package.json
{
  "name": "@ag-ui/proto",
  "dependencies": {
    "@ag-ui/core": "*",
    "@bufbuild/protobuf": "^1"             // ✅ binary 인코딩만
  }
}

// 📦 @ag-ui/encoder / 📄 package.json
{
  "name": "@ag-ui/encoder",
  "dependencies": {
    "@ag-ui/core": "*",
    "@ag-ui/proto": "*"                    // ✅ HTTP·RxJS 여전히 없음
  }
}

// 📦 @ag-ui/client / 📄 package.json
{
  "name": "@ag-ui/client",
  "dependencies": {
    "@ag-ui/core": "*",
    "@ag-ui/encoder": "*",
    "rxjs": "^7",                          // ✅ HTTP·RxJS는 이 패키지에서만
    "fast-json-patch": "^3"
  }
}

// 📦 사용자 앱 / 📄 client.ts
import type { Event } from "@ag-ui/core";
// → zod만 끌려옴. RxJS·protobuf 트리쉐이킹으로 제거됨
 
import { HttpAgent } from "@ag-ui/client";
// → HTTP가 필요할 때만 명시적으로 import

새 transport 추가 시나리오:

+ packages/ws-client/                      ← 📦 @ag-ui/ws-client (새 패키지)
+ ├── package.json: dependencies = {
+ │     "@ag-ui/core": "*",                ← 메시지 정의 재사용
+ │     "@ag-ui/encoder": "*"              ← 인코더 재사용
+ │   }                                    ← @ag-ui/client는 import하지 않음
+ └── src/agent/WsAgent.ts

기존 @ag-ui/client 패키지는 한 줄도 수정하지 않는다.

MCP 스타일과의 차이:

축	MCP 스타일 (파일 분리)	AG-UI 스타일 (패키지 분리)
분리 단위	한 패키지 안의 파일·클래스	별도 npm 패키지
강제력	약함 (잘못 import 해도 동작)	강함 (의존성 그래프로 차단)
번들 최적화	트리쉐이킹에 의존	패키지 단위로 명확히 분리
다언어 공유	어려움 (스키마 추출 필요)	쉬움 (.proto가 이미 별도 패키지)
적합 상황	단일 언어 SDK, 작은 규모	다언어 + 브라우저 번들 최적화 필요

3. libp2p — multi-address로 transport 정보를 주소에 캡슐화

/ip4/192.168.1.1/tcp/8080/ws/p2p/QmPeer... 같이 transport와 프로토콜을 주소 자체에 명시하는 multi-address 형식. “이 peer는 WebSocket으로 연결해라”가 주소 한 줄에 표현된다 — transport 선택 자체를 데이터로 다룬다.

패턴 정리 — 어느 수준까지 갈 것인가

수준	분리 방식	언제 충분한가
클래스 분리	Transport 추상 클래스/인터페이스 + 구현체	단일 언어, 단일 패키지로 충분한 작은 SDK
모듈 분리	같은 패키지 안에서 디렉토리(transports/)로 격리	의존성 부풀림이 아직 문제는 아닌 단계
패키지 분리	npm/PyPI 패키지를 4-layer로 쪼갬	브라우저 번들·다언어 SDK·서드파티 transport 확장 필요
저장소 분리	.proto/스키마를 별도 repo로	여러 팀/회사가 같은 프로토콜을 구현할 때

대부분 클래스 분리부터 시작하고, 의존성이나 다언어 요구가 생기면 패키지 분리로 격상하는 것이 현실적이다.

흔히 하는 오해

오해 1. “transport-agnostic” = “어떤 transport든 실시간 streaming 가능”

아니다. transport마다 능력이 다르므로 (예: 단방향 SSE vs 양방향 WebSocket), 프로토콜은 최소공통분모에 맞춰 설계되거나, capability negotiation으로 능력을 협상한다. AG-UI의 TransportCapabilities가 그 예시다.

오해 2. “transport-agnostic” = “어떤 transport든 동등한 성능”

아니다. transport마다 latency·throughput·헤더 오버헤드가 다르다. agnostic은 의미 보존이지 성능 동등이 아니다.

오해 3. “transport-agnostic”이면 “wire format도 자유롭게 바꿀 수 있다”

wire format: 메시지가 채널을 따라 흐를 때의 바이트 표현 규약 — 직렬화 형식(JSON, Protobuf, MessagePack, Avro 등). “transport는 어디로 흐르나”라면, “wire format은 무엇이 흐르나”.

별개 차원이다. transport-agnostic이면서 wire format은 고정인 프로토콜도 많다 (gRPC는 transport는 유연하지만 wire format은 Protobuf 강제).

설계 시 체크리스트

새 프로토콜을 transport-agnostic으로 설계하려 할 때:

• 메시지 정의에 transport 어휘가 섞이지 않았는가 (HTTP status code, WebSocket frame 같은 단어가 메시지 필드에 등장하면 위험)
• streaming 의미가 transport에 의존하지 않는가 (이벤트 시퀀스를 transport와 무관하게 정의)
• bidirectional이 필요하면 명시했는가 (단방향 transport에서 fallback 전략)
• capability negotiation이 있는가 (transport별 능력 차이를 런타임에 협상)
• 패키지/모듈 경계로 강제했는가 (말이 아닌 의존성 그래프로)

참고 문서

• Model Context Protocol — Transports (공식 스펙) — "The protocol is transport-agnostic..." 명시
• AG-UI Architecture (공식 docs) — Core Design Principles 중 Transport Agnostic 항목
• The Case for Transport-Agnostic Congestion Control (arXiv:2209.04729) — SDN 환경에서 transport-agnostic 혼잡 제어 논의
• What is Agnostic in an IT Context? — TechTarget — IT에서 agnostic 일반 용법
• PASTE: Protocol-agnostic Services & Transport Enrichment (IEEE) — 자매 용어 protocol-agnostic 사례