Protocol Buffers

• Protocol Buffers는 Google이 만든 언어 중립 schema-first 직렬화 프레임워크
• .proto 단일 정의에서 다언어 코드 자동 생성하는 메커니즘
• JSON보다 작고 빠른 바이너리 wire format
• 필드 번호 기반의 하위 호환성 보장 설계

Protocol Buffers가 필요한 이유

• 다언어 협업: TS 서버와 Python 클라이언트가 같은 메시지를 주고받아야 할 때, 양쪽이 같은 스키마를 갖도록 강제
• JSON의 한계: 텍스트 기반이라 크기·속도 모두 비효율, 타입 안전성 없음, 스키마 강제력 없음
• API 진화: 필드 추가·제거 시에도 구버전 클라이언트가 깨지지 않아야 함
• 편집기 지원: 자동 생성된 타입으로 IDE 자동완성·타입 체크 가능

AS-IS — JSON으로 다언어 통신할 때

sequenceDiagram
    autonumber
    participant TS as TypeScript Server
    participant P as Python Client
    Note over TS,P: 양쪽이 별도 타입 정의 유지
    TS->>TS: TS interface로 Event 타입 정의
    P->>P: Pydantic BaseModel로 Event 타입 정의
    TS->>P: JSON 메시지 전송 (필드명 텍스트 그대로)
    P->>P: 수동 파싱, 런타임 타입 체크
    Note over TS,P: 한쪽이 필드 이름 바꾸면 깨짐<br/>스키마 검증은 코드 리뷰에 의존

TO-BE — Protocol Buffers 사용

sequenceDiagram
    autonumber
    participant Proto as events.proto
    participant TS as TypeScript Server
    participant P as Python Client
    Proto->>TS: protoc로 events_pb.ts 자동 생성
    Proto->>P: protoc로 events_pb2.py 자동 생성
    TS->>P: binary wire format 전송
    P->>P: 생성된 클래스로 자동 역직렬화
    Note over TS,P: 스키마 변경 시 양쪽 코드 자동 갱신<br/>필드 번호로 하위 호환 자동 보장

.proto 파일의 구조

AG-UI의 events.proto 일부:

syntax = "proto3";
 
package ag_ui;
 
enum EventType {
  TEXT_MESSAGE_START = 0;
  TEXT_MESSAGE_CONTENT = 1;
  TEXT_MESSAGE_END = 2;
  // ... 16종 이벤트
}
 
message TextMessageContentEvent {
  BaseEvent base_event = 1;
  string message_id = 2;
  string delta = 3;
}

핵심 요소:

• syntax = "proto3" — proto 버전 (현재 권장)
• package — 네임스페이스 (생성 코드의 모듈 경로에 영향)
• enum / message — 타입 정의
• 필드명 = 번호 — 번호가 wire format의 식별자, 절대 변경 금지

다언어 지원 (공식 protoc)

언어	지원 형태
C++	공식
C#	공식
Java	공식
Kotlin	공식
Objective-C	공식
PHP	공식
Python	공식
Ruby	공식
Dart	GitHub 플러그인
Go	GitHub 플러그인
TypeScript	서드파티 (ts-proto, @bufbuild/protobuf 등)

→ 동일 .proto 파일에서 protoc만 다르게 돌리면 8+개 언어로 코드 생성 가능. TypeScript는 공식 지원이 없어 AG-UI는 ts-proto/@bufbuild/protobuf를 사용.

코드 생성 워크플로

flowchart LR
    Proto[".proto 파일"]
    Protoc["protoc 컴파일러"]
    PluginTS["ts-proto 플러그인"]
    PluginPy["python-protoc 플러그인"]
    PluginKt["kotlin 플러그인"]
    OutTS["events_pb.ts"]
    OutPy["events_pb2.py"]
    OutKt["EventsProto.kt"]

    Proto --> Protoc
    Protoc --> PluginTS --> OutTS
    Protoc --> PluginPy --> OutPy
    Protoc --> PluginKt --> OutKt

AG-UI의 generate 스크립트(packages/proto/package.json):

protoc --ts_proto_out=./src/generated \
  --ts_proto_opt=esModuleInterop=true \
  -I ./src/proto ./src/proto/*.proto

필드 번호 — 하위 호환성의 비밀

message User {
  string name = 1;        // 번호 1번
  int32 id = 2;           // 번호 2번
  // string email = 3;    // 제거된 필드 — 번호 재사용 금지
  string phone = 4;       // 새 필드 추가
}

• wire format에는 필드 이름이 없음, 번호만 들어감 → 이름 바꿔도 호환됨
• 번호는 절대 재사용·변경 금지 → 구버전이 새 데이터를 만나면 모르는 번호는 무시
• 새 필드는 optional로 추가 → 옛 코드는 모르고 지나가도 안전

JSON과의 비교

항목	JSON	Protocol Buffers
형식	텍스트	바이너리
크기	큼 (필드명 포함)	작음 (필드 번호만)
속도	파싱 느림	매우 빠름
타입 안전성	런타임 검증 필요	컴파일 시점 보장
스키마	선택 (JSON Schema 등)	필수 (.proto)
가독성	높음 (디버깅 쉬움)	낮음 (binary)
다언어 코드 생성	없음	핵심 기능

→ AG-UI가 SSE(JSON 기반)와 protobuf 둘 다 지원하는 이유: 디버깅 편의(JSON) vs 성능(proto) 트레이드오프를 사용자에게 맡김.

AG-UI에서의 위치

AG-UI는 3개 .proto 파일을 사용:

• events.proto — 16종 이벤트 정의
• types.proto — Message, Tool 등 공통 타입
• patch.proto — JSON Patch 연산

현재는 TS SDK에서만 코드 생성을 돌리지만(Python SDK는 별도 타입 정의 사용), .proto 자체는 언어 중립이므로 누구나 다른 언어로 가져다 쓸 수 있는 형태로 정의되어 있음. 이것이 protobuf를 별도 패키지(@ag-ui/proto)로 분리한 의미.

참고 문서

• Protocol Buffers Overview (공식)
• proto3 Language Guide
• AG-UI events.proto