Event Type System

• AG-UI 이벤트 타입 시스템은 Zod discriminated union 하나로 33개 이벤트의 schema·타입·검증을 단일 진실 공급원으로 묶은 설계
• z.infer로 schema에서 TypeScript 타입을 자동 도출하는 schema-first 아키텍처
• BaseEvent + .passthrough()로 확장성과 타입 안전성을 동시에 확보한 구조

해당 개념이 필요한 이유

• 33개 이벤트 × 카테고리별 다른 필드를 if/else로 받으면 타입 안전성과 가독성 동시 손실
• 프로토콜 스펙(런타임)과 TypeScript 타입(컴파일타임)이 분리되면 drift 발생 — 한쪽만 업데이트되어 버그
• 다중 transport(SSE/Binary)와 다중 SDK(TS/Python)가 같은 데이터를 다루므로 하나의 schema가 source of truth여야 일관성 유지

AS-IS — 타입 분기를 수동 if/else로

function handle(event: { type: string; [k: string]: any }) {
  if (event.type === "TEXT_MESSAGE_CONTENT") {
    console.log(event.delta);     // any — 타입 미보장
  } else if (event.type === "RUN_STARTED") {
    console.log(event.threadId);  // any — 타입 미보장
  }
  // 새 이벤트 추가해도 컴파일러가 경고 안 함
}

TO-BE — discriminated union으로 자동 narrowing

function handle(event: AGUIEvent) {
  switch (event.type) {
    case EventType.TEXT_MESSAGE_CONTENT:
      console.log(event.delta);     // string으로 자동 좁힘
      break;
    case EventType.RUN_STARTED:
      console.log(event.threadId);  // string으로 자동 좁힘
      break;
    // 누락 시 exhaustiveness 경고
  }
}

핵심 설계 1 — schema가 곧 타입이다

events.ts는 모든 이벤트를 Zod schema로 먼저 정의하고, TypeScript 타입은 그걸 z.infer로 도출한다.

export const TextMessageContentEventSchema = BaseEventSchema.extend({
  type: z.literal(EventType.TEXT_MESSAGE_CONTENT),
  messageId: z.string(),
  delta: z.string(),
});
 
export type TextMessageContentEvent = z.infer<typeof TextMessageContentEventSchema>;

왜 schema-first인가:

• 런타임 검증(schema.parse())과 컴파일타임 타입을 한 정의로 둘 다 얻음
• 프로토콜 스펙 = schema → 변경 시 드리프트 불가능
• transport 계층이 wire에서 받은 값을 같은 schema로 검증 — 신뢰 경계 명시화 (AG-UI Serialization에서 다시 등장)

핵심 설계 2 — discriminated union으로 33개를 하나로

export const EventSchemas = z.discriminatedUnion("type", [
  TextMessageStartEventSchema,
  TextMessageContentEventSchema,
  // ... 33개
]);
 
export type AGUIEvent = z.infer<typeof EventSchemas>;

discriminator는 type 필드. 각 schema가 type: z.literal(EventType.X)로 자기를 선언하므로, TypeScript가 event.type을 보고 나머지 필드를 자동 좁힌다.

일반 union과 차이:

• A | B | C는 narrowing이 약함 — 사용자가 type guard를 직접 작성
• discriminated union은 공통 필드 하나로 컴파일러가 자동 분기

핵심 설계 3 — BaseEvent + .passthrough()

export const BaseEventSchema = z
  .object({
    type: z.nativeEnum(EventType),
    timestamp: z.number().optional(),
    rawEvent: z.any().optional(),
  })
  .passthrough();

.passthrough()는 정의되지 않은 필드도 통과시키는 Zod 옵션:

• 새 SDK 버전에서 필드를 추가해도 구버전 클라이언트가 부서지지 않음
• rawEvent로 외부 시스템 이벤트를 그대로 보존
• forward compatibility 확보 — 프로토콜 진화의 안전판

6개 카테고리 한눈에

자세한 라이프사이클·필드는 AG-UI Event에 있다. 본 글은 타입 시스템 관점에 집중.

카테고리	대표 이벤트	패턴	깊은 설명
Lifecycle	RUN_STARTED / FINISHED / ERROR	실행 경계	AG-UI Event
Text Message	TEXT_MESSAGE_START / CONTENT / END	Start-Content-End	AG-UI Messages
Tool Call	TOOL_CALL_START / ARGS / END / RESULT	Start-Content-End + Result	AG-UI Tools
State	STATE_SNAPSHOT / DELTA	Snapshot-Delta	AG-UI State Management
Activity	ACTIVITY_SNAPSHOT / DELTA	Snapshot-Delta	AG-UI Event
Reasoning	REASONING_*	Nested Start-End	AG-UI Event

부가 — 타입 도구 3종

export type AGUIEventByType = { [EventType.TEXT_MESSAGE_CONTENT]: TextMessageContentEvent; ... };
export type AGUIEventOf<T extends EventType> = AGUIEventByType[T];
export type EventPayloadOf<T extends EventType> = Omit<AGUIEventOf<T>, keyof BaseEventFields>;

• AGUIEventByType: type → event 룩업
• AGUIEventOf<T>: 특정 타입 하나만 꺼내기 (예: AGUIEventOf<EventType.RUN_STARTED>)
• EventPayloadOf<T>: BaseEvent 공통 필드 제외 — factory 입력에 필요한 필드만 노출

schema-first의 자연스러운 파생. 핵심은 아니지만 콜러측 보일러플레이트를 줄여준다.

설계 회고 — 다른 선택지와 비교

선택지	장점	단점
TypeScript union만 (Zod 없이)	의존성 0	wire에서 받은 값 런타임 검증 불가
JSON Schema	표준 / 다언어	TS 타입 도출에 별도 도구 필요
Protobuf만	다언어 + 검증	브라우저에서 무거움, schema 진화 제약
Zod discriminated union	TS 1급, 타입+검증 통합	TS 외 언어는 별도 정의 필요

AG-UI는 TS는 Zod, Python은 Pydantic, wire는 SSE+Protobuf — 각 계층이 같은 모양을 다른 도구로 표현. “schema가 진실 공급원”이라는 원칙이 일관된다. 이 wire 변환의 실제 동작은 AG-UI Serialization에서 다룬다.

블로그 글로 옮길 때 핵심 흐름

1. Hook — 33개 이벤트를 어떻게 타입 안전하게 다룰까?
2. 예측 — 그냥 union type으로 충분할까? → 런타임 검증 누락, 카테고리별 필드 다름
3. 코드 확인 — Zod discriminated union + z.infer 패턴
4. 회고 — 왜 Zod인가: 타입과 검증을 한 정의에 묶기
5. 떡밥 — 그런데 SSE wire format에서 어떻게 직렬화할까? → 4편 AG-UI Serialization

참고 문서

• AG-UI Event — 28개 이벤트의 의미와 라이프사이클 (프로토콜 reference)
• AbstractAgent — 이벤트를 stream으로 내보내는 주체 (시리즈 2편)
• AG-UI Package Structure — 4개 패키지 지도 (시리즈 1편)
• AG-UI Serialization — wire format 변환 (시리즈 4편)
• docs/concepts/events.mdx
• sdks/typescript/packages/core/src/events.ts
• Zod discriminated unions