AG-UI Package Structure

AG-UI TypeScript SDK 패키지 구조는 선형 의존성을 가진 4개 프로토콜 패키지 + 1개 CLI 도구
core → proto → encoder → client 단방향 의존 체인
각 layer가 단일 책임 원칙을 따르는 분리 설계
Transport-Agnostic 원칙을 패키지 경계로 강제하는 구조

이 구조가 필요한 이유

언어 중립 스키마 격리: .proto 파일을 별도 패키지에 두어, 다른 언어 SDK가 동일 스키마를 가져다 쓸 수 있는 형태로 정의
Transport-Agnostic 보존: core가 HTTP·Observable을 모르기 때문에 다른 transport(WebSocket 등) 추가가 쉬움
번들 크기 최적화: 브라우저 앱이 binary 형식을 안 쓰면 proto·protobuf 라이브러리를 트리쉐이킹으로 제거 가능
테스트 용이성: core는 순수 함수처럼 검증 가능, encoder는 HTTP 없이 단위 테스트 가능
확장 지점 노출: 누구나 core 위에 새 client(e.g. WebSocketAgent)를 만들 수 있음

AS-IS — 만약 한 패키지였다면

flowchart TB
    subgraph "ag-ui (단일 패키지)"
        Types["타입 정의"]
        Events["이벤트 스키마"]
        Proto["Protobuf 직렬화"]
        SSE["SSE 직렬화"]
        HTTP["HttpAgent (RxJS)"]
        StatePatch["JSON Patch 적용"]
    end

    Types --> Events
    Events --> Proto
    Events --> SSE
    Proto --> HTTP
    SSE --> HTTP
    HTTP --> StatePatch

문제:

브라우저에서 단순히 타입만 import 하려 해도 RxJS·protobuf·uuid 가 끌려옴
다른 언어 SDK와 스키마 공유 불가 — 별도 정의 필요
HTTP 외 transport 추가 시 패키지 전체 의존성에 영향

TO-BE — 4-layer 분리

flowchart TB
    Core["@ag-ui/core<br/>타입·이벤트·Zod 스키마"]
    Proto["@ag-ui/proto<br/>Protobuf 바이너리 인코딩"]
    Encoder["@ag-ui/encoder<br/>SSE/Binary 선택"]
    Client["@ag-ui/client<br/>HttpAgent + 런타임"]

    Core --> Proto
    Core --> Encoder
    Core --> Client
    Proto --> Encoder
    Proto --> Client
    Encoder --> Client

    style Core fill:#E3F2FD
    style Proto fill:#FFF3E0
    style Encoder fill:#F3E5F5
    style Client fill:#E0F7E9

각 layer가 아래 layer만 의존 → 의존이 위로 흐르지 않음.

4개 프로토콜 패키지의 역할 분담

1. core — 타입과 스키마의 기준점

src/
├── types.ts          # 메시지·도구·런타임 입력 타입
├── events.ts         # 16종 BaseEvent 정의
├── capabilities.ts   # Agent capability negotiation
└── event-factories.ts

외부 의존: zod 하나. transport·IO 없음. 다른 모든 패키지의 진리 원천.

2. proto — 바이너리 직렬화 채널

src/
├── proto/*.proto     # 언어 중립 스키마
└── proto.ts          # encode/decode 함수

핵심 export: encode, decode, AGUI_MEDIA_TYPE = "application/vnd.ag-ui.event+proto" 의존: core, @bufbuild/protobuf.

왜 분리되었나 — .proto 파일은 Protocol Buffers의 표준 포맷으로, protoc 컴파일러는 공식적으로 C++, Java, Kotlin, Python 등 8개 언어에 대해 코드를 자동 생성하고 Go·Dart도 플러그인으로 지원한다. 즉 이 패키지의 .proto는 단지 TS 바이너리 인코딩용이 아니라, 누구든 다른 언어 SDK를 만들 때 가져다 쓸 수 있는 언어 중립 스키마 원천이다. 별도 패키지로 둔 덕분에 코드 생성 워크플로(pnpm generate)도 깔끔하게 분리된다.

(참고: 현재 AG-UI Python SDK는 protobuf 코드 생성을 사용하지 않고 별도 타입 정의로 운영 중. 하지만 .proto가 이미 분리되어 있으므로 언제든 다언어 공유로 전환 가능한 구조.)

3. encoder — 직렬화 오케스트레이터

src/
├── encoder.ts
└── media-type.ts

의존: core, proto. 얇은 wrapping layer. SSE(텍스트) vs proto(바이너리)를 media type으로 선택해주는 라우터 역할. HTTP를 모름 — 단지 바이트/텍스트로의 변환만 담당.

4. client — 런타임 통합

src/
├── agent/        # HttpAgent
├── run/          # run loop
├── apply/        # JSON Patch 상태 적용
├── verify/       # 이벤트 시퀀스 검증
├── transform/    # 이벤트 변환
├── chunks/       # streaming chunk 처리
├── compact/      # 메시지 압축
├── middleware/   # 미들웨어 체인
└── legacy/       # 구버전 호환

의존: core, encoder, proto, rxjs, fast-json-patch, uuid. 처음으로 RxJS와 HTTP가 등장하는 layer. 이 layer만 환경 의존적(브라우저/Node 둘 다 동작하지만 streaming 모델은 RxJS).

CLI 패키지의 위치

create-ag-ui-app (cli)은 프로토콜 스택과 무관한 스캐폴딩 도구. inquirer, commander, giget 만 의존 — core를 import 하지 않음. “왜 4개냐”고 말할 때 cli를 빼고 세는 이유.

의존성 그래프가 알려주는 설계 원칙

의존은 한 방향으로만 흐른다

client를 수정해도 core는 안전. 반대로 core 수정은 모든 layer에 파급. → 변화의 영향 반경이 패키지 layer로 명시적으로 표현됨.

proto와 encoder를 분리한 이유

proto: 언어 중립 — .proto 파일은 어떤 언어에서도 protoc로 코드 생성 가능
encoder: TS 전용 — SSE 분기와 media type 처리

만약 한 패키지로 묶었다면, 다른 언어 SDK가 .proto를 재사용하려 할 때 TS 전용 SSE 코드까지 함께 끌고 와야 하는 부조화가 생긴다.

client에만 rxjs가 있다

→ “다른 streaming 모델”이 가능하다는 뜻. 예: Python SDK는 Observable 대신 async iterator. core 타입은 그대로 재사용.

블로그 1편 핵심 메시지

패키지 경계는 디렉토리 구조가 아니라 의존성 흐름의 방벽이다. AG-UI는 “transport-agnostic”이라는 추상 원칙을 4개의 패키지 경계로 물리적으로 강제했다. 그래서 다음 편(AbstractAgent)부터 보게 될 코드는 항상 “이 코드가 어느 layer에 있는가”를 먼저 묻게 된다.

Explorer

날짜별 보기

2026년 (148)

2025년 (8)