AG-UI Serialization

• AG-UI Serialization은 에이전트–UI 세션의 이벤트 스트림을 영속/복원하기 위한 표준 모델
• BaseEvent 시퀀스를 JSON 등 portable 포맷으로 저장·재생하는 이벤트 소싱(Event Sourcing) 기반 영속화 계약
• 새로고침·재접속·공유 시에도 대화·상태·UI를 그대로 복원하는 세션 재현 메커니즘
• parentRunId로 git-like 계보를 만드는 append-only branching 로그
• 의미를 보존하면서 스트림 길이를 줄이는 이벤트 압축(Compaction) 규약

해당 개념이 필요한 이유

• 새로고침/재접속 시 대화·UI 상태가 사라지는 문제 — 클라이언트/서버 어디서든 같은 스트림을 복원 가능해야 함
• 같은 thread 안에서 “다른 답을 시도해보고 비교”하는 워크플로우 — parentRunId 기반 분기 + 시간 여행 필요
• streaming delta(TEXT_MESSAGE_CONTENT, STATE_DELTA, TOOL_CALL_ARGS) 누적으로 인한 저장/네트워크 비용 폭증 — 의미를 보존한 압축 필요
• run 단위로 “에이전트에게 정확히 무엇이 입력되었는가”를 명시 기록 → 재현 가능성(reproducibility) 보장
• 실행 중 에이전트에 **재접속(attach)**하여 끊김 없이 이벤트를 이어 받기 위한 표준화된 백필(replay) 경로 필요

AS-IS — 휘발성 in-memory 스트림

sequenceDiagram
    autonumber
    participant UI
    participant Agent as AG-UI Agent
    participant Mem as In-Memory Stream
    UI->>Agent: runAgent(input)
    Agent-->>Mem: BaseEvent[] (휘발성)
    Note over Mem: 새로고침 / 크래시 / 탭 전환<br/>= 전체 스트림 손실
    UI--xMem: reload (히스토리 복구 불가)
    UI--xAgent: 재접속 시 mid-run 이벤트 받을 방법 없음

TO-BE — 직렬화된 append-only 스트림

sequenceDiagram
    autonumber
    participant UI
    participant Agent as AG-UI Agent
    participant Store as Append-Only Storage
    UI->>Agent: runAgent(input, parentRunId?)
    Agent-->>Store: BaseEvent append (JSON 직렬화)
    UI->>Store: load(threadId)
    Store-->>UI: serialized events
    UI->>UI: compactEvents() → snapshot 복원
    UI->>UI: 임의 runId 선택 → 시간 여행 / 분기

핵심 3가지 메커니즘

1. Stream Serialization — 이벤트 히스토리 영속화

• BaseEvent 배열 전체를 JSON 등 portable 포맷으로 저장 → DB·파일·로그 어디든 보관
• 핵심은 **“이벤트 자체가 진실(source of truth)“**이라는 이벤트 소싱 모델
• threadId, runId, timestamp 인덱스를 추가해 빠른 조회 가능
• 클라이언트 재로드 / 다른 디바이스 접속 / 공유 링크 모두 동일 메커니즘으로 처리

2. Event Compaction — 의미 보존 압축

streaming delta가 그대로 쌓이면 비용이 폭증한다. Compaction은 관찰 가능한 결과(observable outcome)는 유지하면서 이벤트 수를 줄인다.

대상	Before	After
메시지	TEXT_MESSAGE_START + N개 CONTENT(delta) + END	단일 MESSAGES_SNAPSHOT
도구 호출	TOOL_CALL_START + ARGS(delta)* + END + RESULT	압축된 단일 tool record (TOOL_CALL_RESULT 포함 형태)
상태	연속 STATE_DELTA (JSON Patch)	최종 STATE_SNAPSHOT
run 입력	RunStarted.input.messages에 중복된 메시지	이전 스트림에 이미 있는 메시지는 제거

자세한 Tool 이벤트 흐름과 Message 이벤트 흐름은 각 개념 문서를 참고.

3. Run Lineage — parentRunId 기반 git-like 계보

• 각 RUN_STARTED가 어떤 run에서 분기했는지 parentRunId로 명시
• 한 thread 안에 여러 분기를 동시에 보관 가능 (트리/DAG)
• 로그는 immutable & append-only — 결과적으로 결정적 시간 여행과 재현 가능한 세션 공유가 동시에 성립

RunStarted 확장 필드

AG-UI Event의 lifecycle 이벤트 중 RUN_STARTED가 직렬화/분기를 위해 다음 필드를 추가로 갖는다.

type RunStartedEvent = BaseEvent & {
  type: EventType.RUN_STARTED
  threadId: string
  runId: string
  /** 같은 thread 안에서 어떤 run을 부모로 가지치기 했는지 */
  parentRunId?: string
  /** 이번 run에 Agent에게 정확히 전달된 입력
   *  (이미 히스토리에 있는 메시지는 생략 가능 — Normalized Input) */
  input?: AgentInput
}

핵심은 **“run 입력의 명시 기록”**이다. 메시지가 누적되는 환경에서, “이번 run에 정확히 무엇이 들어갔는가”를 사후에 알기 어렵기 때문.

이벤트 압축(Compaction) 예시

Before — streaming raw events

[
  { type: "TEXT_MESSAGE_START",   messageId: "msg1", role: "user" },
  { type: "TEXT_MESSAGE_CONTENT", messageId: "msg1", delta: "Hello " },
  { type: "TEXT_MESSAGE_CONTENT", messageId: "msg1", delta: "world" },
  { type: "TEXT_MESSAGE_END",     messageId: "msg1" },
  { type: "STATE_DELTA", patch: { op: "add",     path: "/foo", value: 1 } },
  { type: "STATE_DELTA", patch: { op: "replace", path: "/foo", value: 2 } },
]

After — compacted snapshots

[
  {
    type: "MESSAGES_SNAPSHOT",
    messages: [{ id: "msg1", role: "user", content: "Hello world" }],
  },
  {
    type: "STATE_SNAPSHOT",
    state: { foo: 2 },
  },
]

압축 후에도 관찰자가 보는 최종 결과는 동일하다. 다만 중간 streaming의 시각적 효과(타이핑 애니메이션 등)는 사라지므로, “live 재생” 용도에는 raw, “장기 보관”용에는 compacted를 선택적으로 사용한다.

분기(Branching)와 시간 여행

parentRunId만으로 git-like 그래프가 자연 발생한다.

gitGraph
    commit id: "run1"
    commit id: "run2"
    branch alternative
    checkout alternative
    commit id: "run3 (parent run2)"
    commit id: "run4"
    checkout main
    commit id: "run5 (parent run2)"
    commit id: "run6"

분기 사용 사례

• 같은 질문에 대한 대안 응답 비교 — A/B 비교, “Regenerate” UX의 근간
• Human-in-the-Loop 워크플로우에서 사용자가 다른 결정을 내렸을 때의 what-if 탐색
• 디버깅 시 “버그 발생 직전 run으로 되돌아가서 다시 실행” — 결정적 재현

시간 여행이 가능한 이유

• 로그가 append-only이므로 임의 시점의 스냅샷을 결정적으로 재구성 가능
• run 입력이 RunStarted.input에 명시되어 있어, 그 시점의 컨텍스트를 정확히 복원

// 분기 예시
{ type: "RUN_STARTED", threadId: "t1", runId: "run1",
  input: { messages: ["Tell me about Paris"] } }
 
// run1에서 분기
{ type: "RUN_STARTED", threadId: "t1", runId: "run2",
  parentRunId: "run1",
  input: { messages: ["Actually, tell me about London instead"] } }

정규화된 입력 (Normalized Input)

같은 thread에서 run을 거듭하면 메시지가 누적된다. 두 번째 run에서 첫 run의 메시지를 또 input.messages에 담으면 중복 저장이 된다. 따라서 이미 스트림에 존재하는 메시지는 생략한다.

// run1: 첫 메시지를 풀로 기록
{ type: "RUN_STARTED", runId: "run1",
  input: { messages: [{ id: "msg1", role: "user", content: "Hello" }] } }
 
// run2: msg1은 이미 history에 있으므로 input에서 제외
{ type: "RUN_STARTED", runId: "run2",
  input: { messages: [{ id: "msg2", role: "user", content: "How are you?" }] } }

이 규칙은 메시지 모델의 “이벤트(흐름) ≠ 메시지(상태) 분리” 철학과 맞물린다 — 메시지는 독립된 영속 단위이므로 동일 메시지가 여러 run의 input에 중복될 필요가 없다.

모델 교체와 컨텍스트 보존

메시지가 벤더 중립 영속 단위라는 사실의 직접적 귀결: 같은 thread 안에서 LLM 모델을 바꿔도 히스토리는 날아가지 않는다. AG-UI 공식 문서가 이 시나리오를 명시적 설계 목표로 삼는다.

“AG-UI messages are designed to be vendor-neutral… a common interface regardless of the underlying AI service.” — messages.mdx

시나리오 — 같은 thread에서 모델 A → B 전환

회원 상담 thread에서 첫 5턴은 OpenAI GPT-4o로 처리하다가, 6턴부터 비용 문제로 Anthropic Claude로 라우팅을 바꾸는 상황. 6턴째에 사용자가 “지금까지 대화 요약해줘”라고 묻는다.

flowchart TD
    subgraph Persist["영속 계층 — 벤더 무관"]
        Thread["threadId t-1<br/>MESSAGES_SNAPSHOT (1~5턴)<br/>STATE_SNAPSHOT"]
    end

    subgraph Run5["Run 5 — 모델 A"]
        IN5[RunAgentInput] --> ADP_A[OpenAI 어댑터<br/>aguiToOpenAI]
        ADP_A --> LLM_A[GPT-4o]
    end

    subgraph Run6["Run 6 — 모델 B 같은 thread"]
        IN6[RunAgentInput<br/>같은 messages 배열] --> ADP_B[Anthropic 어댑터<br/>aguiToAnthropic]
        ADP_B --> LLM_B[Claude]
    end

    Thread --> IN5
    Thread --> IN6
    LLM_A -- "RUN_FINISHED 후 누적" --> Thread
    LLM_B -- "이전 5턴을 컨텍스트로 받아 요약 가능" --> Thread

핵심은 RunAgentInput.messages가 모델 독립적인 동일 배열이라는 점이다. 모델별 변환은 어댑터가 매번 다르게 적용할 뿐이다.

# 핵심 수도 코드 — AbstractAgent 내부 라우팅
def run(input: RunAgentInput):
    messages = input.messages          # 벤더 중립 AG-UI 메시지
    if route_to_b(input):
        vendor_msgs = agui_to_anthropic(messages)
        stream = anthropic.stream(vendor_msgs)
    else:
        vendor_msgs = agui_to_openai(messages)
        stream = openai.stream(vendor_msgs)
    yield from to_agui_events(stream)  # 결과는 다시 AG-UI 이벤트로 환원

보존되는 것 vs 유실되는 것

항목	모델 교체 시	이유
user / assistant / tool 메시지 본문	보존	벤더 중립 포맷
STATE_SNAPSHOT / STATE_DELTA	보존	JSON 객체, 모델 무관
threadId / runId / parentRunId lineage	보존	AG-UI 레이어가 관리
Reasoning 메시지	부분 보존	role: "reasoning"은 표준화되나, 모델별 reasoning 서명·세부 구조는 손실 가능
Prompt cache key	무효화	캐시는 모델별 — 새 모델에서 hit 불가
벤더 전용 tool 메타	변환 필요	AG-UI Tools는 JSON Schema 기반이라 대부분 호환

따라서 모델 전환은 “컨텍스트 유실”보다는 “캐시·미세 메타 리셋” 관점으로 이해해야 한다.

장기 기억과 RAG 통합

thread 내부 히스토리는 위 메커니즘으로 보존되지만, 수개월·수년치 대화를 모두 매 run의 messages에 넣는 건 비현실적이다. AG-UI는 thread 외부의 long-term memory를 capability flag로 인지한다.

interface StateCapabilities {
  /** Set `true` if the agent has long-term memory beyond the current thread 
   *  (e.g., vector store, knowledge base, or cross-session recall). */
  memory?: boolean
  persistentState?: boolean
}

— docs/concepts/capabilities.mdx

즉 vector DB는 AG-UI 프로토콜이 직접 제공하지는 않지만, “에이전트가 이런 능력을 가짐”을 클라이언트에 선언하는 표준이 있다. 직렬화된 이벤트 스트림을 RAG 백본으로 재활용하는 것은 설계 의도와 정확히 부합한다.

RAG 파이프라인

flowchart LR
    Stream[직렬화된 BaseEvent 로그] -->|compactEvents| Snap[MESSAGES_SNAPSHOT]
    Snap -->|user/assistant 추출 + 큐레이션| Chunk[텍스트 청크]
    Chunk -->|embedding model| Emb[벡터]
    Emb --> VDB[(Vector DB<br/>pgvector / Pinecone /<br/>Weaviate / Qdrant)]

    NewQ[새 user 메시지] -->|query embedding| VDB
    VDB -->|top-K 유사 청크| Inject[RunAgentInput.context]
    Inject --> Agent[AG-UI Agent]

핵심은 검색 결과를 messages에 직접 prepend하지 않고 Context 슬롯에 주입한다는 것이다. AG-UI에 이미 표준 슬롯이 있다.

# 핵심 수도 코드 — RAG 컨텍스트 주입
hits = vector_db.search(embed(latest_user_msg), top_k=5)
input = RunAgentInput(
    thread_id="t-1",
    run_id="r-42",
    messages=current_thread_messages,        # 정규화된 짧은 히스토리
    context=[
        Context(description=f"recall_{i}", value=h.text)
        for i, h in enumerate(hits)          # ← 장기 기억 주입
    ],
    state={}, tools=[], forwarded_props={},
)

시나리오 — 1년치 고객 상담 RAG

같은 사용자가 6개월 전 환불 문의를 했고, 오늘 다시 비슷한 케이스로 접속. compaction된 과거 이벤트 로그에서 user/assistant 메시지만 추출해 임베딩한 상태라면:

• 오늘 새 메시지의 임베딩으로 vector DB 질의
• 유사도 top-3 청크가 Context로 주입
• 에이전트는 6개월 전 결정 사유까지 파악한 채로 응답 생성

큐레이션 가이드

메시지 role	임베딩 대상
user, assistant	권장 — 의도/결정의 핵심
tool	선택적 — 짧은 결과만, 긴 raw payload는 노이즈
reasoning	선택적 — 의사결정 추적용으로만
activity	비권장 — UI 진행 상황은 검색 가치 낮음
system, developer	비권장 — 정적 프롬프트, 매번 별도 주입

Storage 백엔드 — 프로토콜의 경계

위 두 메커니즘(컨텍스트 보존 + RAG)은 모두 “어딘가에 직렬화된 이벤트가 저장돼 있다”를 전제한다. 그 “어딘가”는 AG-UI가 제공하지 않는다.

“Conversation history is stored only in memory. If the application restarts, all history is lost. For persistence, you must implement your own storage solution by retrieving conversations using getHistory() and saving them externally.” — docs/sdk/kotlin/client/stateful-agui-agent.mdx

즉 SQLite·Postgres·Redis 같은 특정 DB가 SDK에 박혀 있지 않다. 프로토콜은 직렬화 형식과 권장사항만 제공하고, storage 어댑터는 사용자/integration이 붙인다.

어댑터 패턴

flowchart LR
    Bus[Event Bus] -->|"save(threadId, events)"| Adapter[StorageAdapter<br/>인터페이스]
    Adapter --> A[(Postgres<br/>JSONB events 컬럼)]
    Adapter --> B[(S3<br/>append-only 파일)]
    Adapter --> C[(Redis Streams<br/>실시간 + 짧은 보관)]
    Adapter --> D[(ClickHouse<br/>분석/집계)]
    Adapter --> E[(Vector DB<br/>RAG용 사이드카)]

# 핵심 수도 코드 — 사용자가 구현하는 어댑터 계약
class StorageAdapter(Protocol):
    async def append(self, thread_id: str, event: BaseEvent) -> None: ...
    async def load(self, thread_id: str) -> list[BaseEvent]: ...
    async def compact(self, thread_id: str) -> None: ...

백엔드 선택 가이드

백엔드	적합한 경우	트레이드오프
Postgres + JSONB	트랜잭션·관계형 조인 필요, 중규모	인덱스 설계 필요, 매우 긴 스트림은 row 비대
S3 / 파일 append	장기 보관·저비용 cold storage	부분 조회 어려움 → compaction 후 snapshot으로 별도 보관
Redis Streams	실시간 attach·재접속, 짧은 보관	영속성은 보조용, 장기 보관에는 부적합
ClickHouse / BigQuery	분석·집계·시계열 질의	단건 트랜잭션 부적합
Vector DB (사이드카)	RAG 전용 — 위 RAG 섹션 패턴	원본 이벤트 저장은 못 함, 다른 backend와 병행 필요

실전에서는 2-tier 조합이 흔하다 — hot tier(Redis/Postgres)에 raw events, cold tier(S3/ClickHouse)에 compacted snapshots, 사이드카로 vector DB.

공식 integration 사례

• ADK middleware — POST /agents/state 엔드포인트로 thread별 messages/state 조회. 내부 storage는 ADK 측 자유 선택.
• ADK + VertexAIMemoryService — 세션 만료 시 memory_service.add_session_to_memory() 자동 호출 → 사실상 자동 RAG 백필
• Kotlin getHistory(threadId) — 메모리 전용. 영속화 책임은 호출자.

직렬화 흐름 — End-to-End

sequenceDiagram
    autonumber
    participant UI
    participant Store as Storage (append-only)
    participant Bus as Event Bus
    participant Agent as AbstractAgent

    Agent-->>Bus: RUN_STARTED (threadId, runId, parentRunId?, input?)
    Agent-->>Bus: TEXT_MESSAGE_START / CONTENT(delta)*  / END
    Agent-->>Bus: STATE_DELTA (JSON Patch) ...
    Agent-->>Bus: TOOL_CALL_START / ARGS / END / RESULT
    Agent-->>Bus: RUN_FINISHED

    Bus->>Store: append events (JSON.stringify)

    Note over Store: 정책에 따라 주기적으로 compactEvents() 적용

    UI->>Store: load(threadId)
    Store-->>UI: serialized events
    UI->>UI: compactEvents → MESSAGES_SNAPSHOT / STATE_SNAPSHOT 복원
    UI->>UI: 임의 runId 선택 → 시간 여행

기본 코드 예시

// 직렬화 (저장)
const events: BaseEvent[] = [...];
const serialized = JSON.stringify(events);
await storage.save(threadId, serialized);
 
// 복원 + 압축
const restored = JSON.parse(await storage.load(threadId));
const compacted = compactEvents(restored);
 
// compacted 스트림으로 UI 다시 그리기
ui.render(compacted);

다른 AG-UI 개념과의 관계

• AG-UI Event — Serialization은 결국 이벤트 시퀀스의 영속화다. 28개 이벤트 타입 자체가 직렬화의 단위.
• AG-UI Messages — TEXT_MESSAGE_* 스트림이 압축되어 MESSAGES_SNAPSHOT이 된다. 메시지는 영속 상태, 이벤트는 흐름.
• AG-UI State Management — STATE_DELTA(JSON Patch RFC 6902)가 누적되어 최종 STATE_SNAPSHOT으로 압축된다.
• AG-UI Tools — TOOL_CALL_START/ARGS/END/RESULT 흐름이 단일 tool record로 압축 가능.
• AG-UI Agents / AbstractAgent — 직렬화 대상은 runAgent(input) 결과 이벤트 스트림. RunStarted.input 필드가 입력의 정확한 기록을 가능하게 한다.

구현 시 고려사항

• SDK 헬퍼 제공: (de)serialize, compactEvents 같은 유틸을 SDK 차원에서 제공해야 일관성 확보
• append-only 저장: 가능하면 incremental write — 한 run이 끝날 때마다 append, 도중 수정 금지
• 압축 정책: 실시간 보기 = raw, 장기 보관 = compacted, 또는 [hot=raw, cold=compacted] 2-tier 정책
• 인덱싱: threadId, runId, parentRunId, timestamp에 인덱스 — 분기 그래프 탐색과 부분 로드 성능 확보
• 압축 알고리즘: 장기 보관 시 gzip/zstd 등 페이로드 압축 추가 고려
• PII / ZDR: 메시지에 민감 정보가 포함될 수 있으므로 저장 전 redaction 또는 클라이언트 보관 정책 고려

참고 문서

• AG-UI 공식 문서 — Serialization
• JSON Patch — RFC 6902
• 관련 개념: AG-UI Event, AG-UI Messages, AG-UI State Management, AG-UI Tools, AG-UI Agents, AbstractAgent, Human-in-the-Loop