AG-UI Messages

• AG-UI Messages는 에이전트와 사용자 간 대화 히스토리를 구성하는 영속 단위 객체
• role 필드를 discriminator로 삼는 tagged union 구조 (user/assistant/system/developer/tool/activity/reasoning)
• LLM 프로바이더(OpenAI/Anthropic/Bedrock 등)에 독립적인 벤더 중립 포맷
• 스트리밍 이벤트(TEXT_MESSAGE_*, TOOL_CALL_*, REASONING_*)를 누적하여 materialize되는 최종 상태 스냅샷
• Generative UI 스펙(A2UI/Open-JSON-UI/MCP-UI)을 실어 나르는 수송 경로

해당 개념이 필요한 이유

• LLM 프로바이더마다 메시지 포맷이 제각각 → 클라이언트 변경 없이 백엔드 모델 교체 가능해야 함
• 스트리밍 응답을 대화 히스토리로 누적해야 함 → 이벤트(흐름)와 메시지(상태)의 분리 필요
• 툴 호출 / 내부 추론 / UI 상태 / 멀티모달 입력 등 이질적 요소를 하나의 대화 타임라인에 통합 → 7가지 role로 의미 분리
• ZDR(Zero Data Retention) 같은 엔터프라이즈 컴플라이언스 환경에서 서버가 상태 저장 불가 → 클라이언트가 암호화된 상태를 캐리어로 운반

AS-IS: 벤더 종속적인 단일 포맷

sequenceDiagram
    autonumber
    participant UI as Frontend
    participant API as OpenAI API

    UI->>API: OpenAI 전용 포맷 요청
    API-->>UI: OpenAI 전용 스트리밍 응답
    Note over UI,API: Anthropic으로 갈아타려면<br/>클라이언트 전체 수정

TO-BE: AG-UI 추상화 레이어 (3계층 분리)

sequenceDiagram
    autonumber
    participant UI as Frontend
    participant AD as AG-UI Adapter
    participant FW as Framework
    participant LLM as Vendor LLM

    Note over UI,AD: Layer 1 - AG-UI Protocol 구간
    UI->>AD: AG-UI Message (벤더 중립)

    Note over AD: 변환 1 - Adapter 책임<br/>aguiMessagesToLangChain
    AD->>FW: Framework Format<br/>LangChain HumanMessage 등

    Note over FW: 변환 2 - Framework 책임<br/>AG-UI 무관
    FW->>LLM: Vendor API JSON<br/>OpenAI chat.completions 등

    LLM-->>FW: streaming chunks
    FW-->>AD: framework events
    AD-->>UI: AG-UI Events (표준 스트림)
    Note over UI,AD: 모델 변경 시 클라이언트 무변경

핵심: 프론트엔드는 Layer 1(AG-UI Protocol) 만 알면 되고, 내부의 프레임워크/벤더 변경은 Adapter 교체만으로 흡수된다.

Message 타입 7가지 — 역할과 가시성

Role	UI 표시	LLM 전달	용도
user	표시	전달	사용자 입력 (텍스트 or 멀티모달)
assistant	표시	전달 (다음 턴 컨텍스트)	AI 응답 + 툴 호출
system	숨김	전달	플랫폼 레벨 지시 (보안, 항상 적용)
developer	숨김	전달	앱 레벨 지시 (system보다 약함, user보다 강함)
tool	커스텀	전달	툴 실행 결과 (toolCallId로 링크)
reasoning	선택적 요약	전달 (encryptedValue로)	내부 chain-of-thought
activity	커스텀 UI	전달 안 함	프론트엔드 전용 상태

types.ts:161-169 에서 z.discriminatedUnion("role", [...])로 구현됨.

”Message 타입”이 의미하는 것

AG-UI에서 Message는 **“대화 히스토리에 누적되는 영속 객체”**를 의미하며, 사용자와 백엔드 사이를 오가는 트래픽 전부를 뜻하지는 않는다.

AG-UI 데이터 분류
│
├─ Message (상태/누적) — RunAgentInput.messages 배열에 쌓임
│   ├─ LLM 전달: user, assistant, system, developer, tool, reasoning
│   └─ 프론트엔드 전용: activity
│
├─ Event (흐름/일회성) — 통신 중 흘러가는 신호
│   ├─ TEXT_MESSAGE_START/CONTENT/END
│   ├─ TOOL_CALL_START/ARGS/END
│   ├─ STATE_SNAPSHOT/DELTA
│   └─ RUN_STARTED/FINISHED
│
└─ 기타
    ├─ Tool (LLM이 호출 가능한 함수 스키마)
    └─ Context (추가 컨텍스트 데이터)

Event는 Message를 구축하기 위한 스트림 조각이고, 이벤트 시퀀스가 누적되어 결국 하나의 Message 객체로 materialize된다.

system / developer의 의미

두 role 모두 사용자 UI에 노출되지 않으며, LLM 입력용 지시사항이다. OpenAI가 2024년말 도입한 instruction hierarchy 개념이 그대로 반영된 설계로, 우선순위는 다음과 같다.

우선순위 (높음 → 낮음)
1. system    — 플랫폼/OS 레벨 규칙 (항상 적용되는 안전장치)
2. developer — 앱 개발자가 추가하는 지시 (세션/시나리오별)
3. user      — 최종 사용자 입력

utils.ts:207에서 두 role을 동일하게 instruction 영역으로 처리한다.

“디버그 로그”나 “툴이 끝났음을 UI에 표시” 같은 시나리오는 developer가 아니라 activity 메시지 또는 STEP_FINISHED 이벤트의 영역이다.

UserMessage의 멀티모달 구조

types.ts:133-136:

export const UserMessageSchema = BaseMessageSchema.extend({
  role: z.literal("user"),
  content: z.union([z.string(), z.array(InputContentSchema)]),
});

content가 string | InputContent[] 유니온인 것이 핵심. 텍스트만 보내는 레거시 경로와 멀티모달 경로를 하나의 메시지 구조로 통합한다.

InputContent 2단 계층

InputContent (discriminatedUnion by "type")
├── TextInputContent      { type: "text",  text }
├── ImageInputContent     { type: "image", source, metadata? }
├── AudioInputContent     { type: "audio", source, metadata? }
├── VideoInputContent     { type: "video", source, metadata? }
└── DocumentInputContent  { type: "document", source, metadata? }

InputContentSource (discriminatedUnion by "type")
├── { type: "data", value: base64, mimeType }   — 인라인 데이터
└── { type: "url",  value: url,    mimeType? }  — 외부 참조

대용량 파일은 URL 참조, 작은 파일은 인라인 base64로 보내는 최적화 분기를 프로토콜 레벨에서 열어둔다.

멀티모달 요청이 모델까지 도달하는 전체 파이프라인

사용자가 [TextInputContent, VideoInputContent]를 업로드한 경우:

sequenceDiagram
    autonumber
    participant U as User
    participant FE as Frontend
    participant AD as AG-UI Adapter
    participant LC as LangChain Runtime
    participant API as OpenAI API

    U->>FE: 텍스트와 비디오 업로드
    FE->>AD: AG-UI UserMessage<br/>content - text + video 배열

    Note over AD: convertAguiMultimodalToLangchain<br/>mediaSourceToUrl
    AD->>LC: LangChain HumanMessage<br/>content - text + image_url 배열

    Note over LC: LangChain 내부에서<br/>OpenAI API 포맷으로 재변환
    LC->>API: OpenAI chat.completions<br/>content - text + image_url 배열

    API-->>LC: streaming response
    LC-->>AD: LangChain events
    AD-->>FE: AG-UI Events 표준화
    FE-->>U: 렌더링

utils.ts:119-151 의 convertAguiMultimodalToLangchain:

function convertAguiMultimodalToLangchain(content: InputContent[]) {
  for (const item of content) {
    if (item.type === "text") {
      langchainContent.push({ type: "text", text: item.text });
    }
    else if (MEDIA_CONTENT_TYPES.has(item.type)) {
      const url = mediaSourceToUrl(mediaItem.source);
      langchainContent.push({
        type: "image_url",  // LangChain은 전부 image_url로 통합
        image_url: { url },
      });
    }
  }
}

프로토콜 레벨과 어댑터 레벨의 타입 보존 차이

레벨	타입 구분	비고
AG-UI 프로토콜	image/audio/video/document 구분 보존	미래 대비 설계
LangChain 어댑터	모두 image_url로 뭉갬	utils.ts:71-73 주석이 명시
최종 모델 API	모델 지원 여부에 따라 다름	GPT-4o는 이미지, 비디오는 지원 제한적

AG-UI가 VideoInputContent, AudioInputContent를 미리 정의한 것은 모델/프레임워크가 따라올 때를 대비한 확장성 포석이다.

Adapter 레이어 — 프레임워크 포맷 변환의 책임 주체

AG-UI는 벤더 중립 포맷과 실제 프레임워크 사이의 변환을 공식적으로 제공하며, 그 구현체가 *Agent 클래스들이다.

핵심 원칙: 프론트엔드는 오직 AG-UI 프로토콜만 사용해 통신하고, Adapter가 프레임워크 포맷으로 변환하는 역할을 전담한다. 덕분에 모델/프레임워크를 교체해도 프론트엔드는 무변경이다.

⚠️ 헷갈리기 쉬운 지점 — “프레임워크”와 “벤더”는 다르다

이 섹션을 읽을 때 가장 많이 혼동되는 지점은 **“AG-UI가 벤더(OpenAI)에 직접 메시지를 보낸다”**고 생각하는 것이다. 실제로는 사이에 **“프레임워크”**라는 중간 계층이 하나 더 있다.

용어 구분:

용어	정체	예시
AG-UI Protocol	벤더·프레임워크 중립 표준 포맷	types.ts의 MessageSchema
프레임워크 (Framework)	AI 오케스트레이션 라이브러리 (중간 계층)	LangChain, LangGraph, Mastra, Vercel AI SDK, LlamaIndex
벤더 (Vendor / Provider)	실제 LLM API 제공자 (최종 목적지)	OpenAI, Anthropic, AWS Bedrock, Google

왜 혼동되는가? “벤더사마다 이벤트가 다르다”는 말은 맞지만, AG-UI가 그걸 직접 해결하지는 않는다. 벤더 추상화는 프레임워크가 이미 해둔 일이고, AG-UI는 그 위에 한 층 더 얹힌 프론트엔드용 추상화다.

3계층 구조 — 데이터가 거치는 실제 경로

flowchart TB
    L1["Layer 1 - AG-UI Protocol<br/>벤더/프레임워크 중립 표준<br/>예시 - role assistant, toolCalls, camelCase"]
    L2["Layer 2 - Framework Format<br/>LangChain, ai-sdk, Mastra 등<br/>예시 - type ai, tool_calls, snake_case"]
    L3["Layer 3 - Vendor API Format<br/>OpenAI, Anthropic, Bedrock 등<br/>예시 - chat.completions JSON"]

    L1 <==>|"변환 1<br/>AG-UI Adapter가 담당"| L2
    L2 <==>|"변환 2<br/>Framework 내부 담당<br/>AG-UI 무관"| L3

    classDef agui fill:#b3d9ff,stroke:#0066cc,color:#000
    classDef framework fill:#ffd9b3,stroke:#cc6600,color:#000
    classDef vendor fill:#b3ffb3,stroke:#009900,color:#000

    class L1 agui
    class L2 framework
    class L3 vendor

AG-UI Message가 LLM에 도달하기까지 — 변환은 2회 일어난다

한 번의 사용자 요청이 LLM까지 도달하려면 총 2번의 포맷 변환이 필요하다.

flowchart LR
    A["AG-UI Message<br/>role assistant<br/>toolCalls array"]
    B["LangChain Message<br/>type ai<br/>tool_calls array"]
    C["OpenAI API JSON<br/>role assistant<br/>tool_calls array"]
    LLM(("LLM"))

    A ==>|"변환 1<br/>Adapter<br/>aguiMessagesToLangChain"| B
    B ==>|"변환 2<br/>Framework<br/>ChatOpenAI 내부"| C
    C ==>|"HTTP 전송<br/>Framework"| LLM

    classDef agui fill:#b3d9ff,stroke:#0066cc,color:#000
    classDef framework fill:#ffd9b3,stroke:#cc6600,color:#000
    classDef vendor fill:#b3ffb3,stroke:#009900,color:#000

    class A agui
    class B framework
    class C vendor

변환 횟수 요약:

변환	담당자	AG-UI 책임?
① AG-UI Message → 프레임워크 Message	Adapter (LangGraphAgent 등)	✅ Yes
② 프레임워크 Message → 벤더 API JSON	Framework 내부 (ChatOpenAI 등)	❌ No

실제 포맷 차이 — 코드로 확인

같은 “assistant 메시지”가 3계층에서 어떻게 다르게 생겼는지 비교하면 3계층의 존재가 확실히 보인다.

Layer 1: AG-UI Protocol 포맷 — types.ts:127-131

{
  id: "msg_1",
  role: "assistant",                    // 소문자 role
  content: "답변",
  toolCalls: [                          // camelCase
    { id, type: "function",
      function: { name, arguments: "{\"city\":\"tokyo\"}" }  // arguments는 JSON 문자열
    }
  ]
}

Layer 2: Framework (LangChain) 포맷 — utils.ts:241-253

{
  id,
  type: "ai",                           // "ai" (AG-UI는 "assistant")
  role: "assistant",
  content: "답변",
  tool_calls: [                         // snake_case
    { id,
      name: "weather",
      args: { city: "tokyo" },          // args는 파싱된 객체
      type: "tool_call",
    }
  ]
}

Layer 3: Vendor (OpenAI) API 포맷

{
  "role": "assistant",
  "content": "답변",
  "tool_calls": [
    { "id": "call_1",
      "type": "function",
      "function": {
        "name": "weather",
        "arguments": "{\"city\":\"tokyo\"}"
      }
    }
  ]
}

주요 차이점 요약:

필드	Layer 1 (AG-UI)	Layer 2 (LangChain)	Layer 3 (OpenAI)
role 표기	role: "assistant"	type: "ai"	role: "assistant"
툴 배열 이름	toolCalls	tool_calls	tool_calls
툴 인자	arguments: "{...}" (문자열)	args: {...} (객체)	arguments: "{...}" (문자열)
네이밍	camelCase	snake_case	snake_case

재미있는 점: Layer 1(AG-UI)과 Layer 3(OpenAI)은 묘하게 닮았지만 Layer 2(LangChain)는 다르다. LangChain이 자기만의 독자 포맷을 쓰기 때문이며, 이것이 “프레임워크 포맷”이라는 중간 계층이 실재하는 증거다.

⚠️ 헷갈리기 쉬운 지점 — “왜 프레임워크를 거쳐 가나? 바로 벤더로 보내면 안 되나?”

이론적으로는 Adapter가 AG-UI → OpenAI JSON으로 바로 변환할 수도 있다. 하지만 그러지 않는 이유:

문제	프레임워크 경유 시
벤더 추상화를 누가 하나?	LangChain이 이미 20+ 벤더 지원 → 공짜로 상속
새 LLM 추가되면?	LangChain이 지원하기만 하면 AG-UI Adapter 수정 불필요
복잡한 기능(RAG, 멀티스텝)?	프레임워크가 이미 구현 → AG-UI가 재발명 안 해도 됨
코드 단순성	Adapter는 “LangChain과만” 대화하면 됨

즉 AG-UI가 “프레임워크 레벨”에서 멈추는 건 설계적 타협이 아니라 전략적 선택이다. 이미 LangChain/ai-sdk/Mastra가 벤더 추상화를 완성해뒀기 때문에, AG-UI는 그 추상화를 프론트엔드까지 연장하는 역할만 하면 된다.

전체 통신 흐름 (Adapter가 포맷 변환을 전담)

sequenceDiagram
    autonumber
    participant FE as Frontend
    participant AD as AG-UI Adapter
    participant FW as Framework Runtime
    participant LLM as LLM API

    rect rgba(100, 180, 255, 0.15)
        Note over FE,AD: AG-UI 프로토콜 구간<br/>프론트엔드는 이 포맷만 알면 됨
        FE->>AD: AG-UI Message - role, content, toolCalls
    end

    rect rgba(255, 180, 100, 0.15)
        Note over AD: Adapter가 포맷 변환 전담<br/>aguiMessagesToLangChain
        AD->>AD: AG-UI to Framework Native<br/>포맷 변환
    end

    rect rgba(180, 255, 180, 0.15)
        Note over AD,LLM: 프레임워크/모델 구간<br/>프론트엔드는 알 필요 없음
        AD->>FW: Framework-native Message<br/>LangChain HumanMessage 등
        FW->>LLM: Vendor-specific JSON<br/>OpenAI chat.completions 등
        LLM-->>FW: streaming chunks
        FW-->>AD: framework events
    end

    rect rgba(255, 180, 100, 0.15)
        Note over AD: Adapter가 역변환 전담<br/>framework event to AG-UI Event
        AD->>AD: Framework Native to AG-UI<br/>포맷 역변환
    end

    rect rgba(100, 180, 255, 0.15)
        AD-->>FE: AG-UI Events<br/>TEXT_MESSAGE_*, TOOL_CALL_* 등
        Note over FE,AD: AG-UI 프로토콜 구간
    end

구간별 책임 분리:

구간	포맷	책임 주체
Frontend ↔ Adapter	AG-UI Message / Events (표준)	AG-UI Protocol
Adapter 내부	AG-UI ↔ Framework 변환	Adapter (LangGraphAgent 등)
Adapter → Framework Runtime	LangChain/ai-sdk 네이티브 포맷	Framework
Framework → LLM API	OpenAI/Anthropic JSON	Framework 내부

즉 LLM 교체(OpenAI → Claude) 시 Framework 내부에서만 변경이 일어나고, 프레임워크 교체(LangChain → Mastra) 시에도 Adapter 구현체만 바꾸면 프론트엔드는 무변경이다.

Adapter의 두 가지 베이스 클래스

① HttpAgent 상속 — 단순 중계 (백엔드가 이미 AG-UI 포맷으로 응답):

// integrations/crew-ai/typescript/src/index.ts
export class CrewAIAgent extends HttpAgent {}
export class AgnoAgent extends HttpAgent { ... }
export class PydanticAIAgent extends HttpAgent { ... }

② AbstractAgent 상속 — 풀 커스텀 (네이티브 포맷 양방향 변환 필요):

// integrations/langgraph/typescript/src/agent.ts:124
export class LangGraphAgent extends AbstractAgent {
  run(input: RunAgentInput): Observable<ProcessedEvents> {
    // input.messages (AG-UI) → LangChain messages 변환
    // LangChain 실행
    // LangChain 이벤트 → AG-UI Events 역변환 스트리밍
  }
}

책임 범위의 경계

데이터가 3번 모양을 바꾸며 LLM까지 도달하는데, 각 변환 단계를 누가 책임지는지가 핵심이다.

flowchart LR
    A["AG-UI Message"]
    B["LangChain Message"]
    C["OpenAI API JSON"]

    A -->|"변환 1 - LangGraphAgent<br/>AG-UI Adapter"| B
    B -->|"변환 2 - LangChain ChatOpenAI<br/>프레임워크 내부"| C

    classDef format fill:#f5f5f5,stroke:#666,color:#000

    class A,B,C format

AG-UI가 책임지는 것 / 아닌 것:

flowchart LR
    subgraph AGUI_SCOPE["AG-UI Adapter 책임 범위"]
        direction LR
        A2["AG-UI Message"] ==>|"변환 1"| B2["LangChain Message"]
    end

    subgraph FW_SCOPE["Framework 내부 책임 - AG-UI 무관"]
        direction LR
        B3["LangChain Message"] ==>|"변환 2"| C2["OpenAI API JSON"]
    end

    AGUI_SCOPE -.경계.-> FW_SCOPE

    classDef adapter fill:#ffd9b3,stroke:#cc6600,color:#000
    classDef framework fill:#b3ffb3,stroke:#009900,color:#000

    class A2,B2 adapter
    class B3,C2 framework

한 줄 요약: Adapter는 “AG-UI ↔ 프레임워크 포맷”까지만 책임진다. 그 이후 프레임워크가 어떤 LLM API를 쓰든(OpenAI/Anthropic/Bedrock) 그건 프레임워크의 몫이지 AG-UI가 관여할 일이 아니다.

VercelAISDKAgent처럼 프레임워크 자체가 멀티 프로바이더를 통합 지원하는 경우, 변환 ②가 프레임워크 내부에 이미 녹아 있어 Adapter는 변환 ①만 신경 쓰면 된다.

병렬 Tool Calls의 순서 보존

N개의 툴이 병렬 실행될 때 완료 순서와 상관없이 시작(START) 순서로 배열 위치가 고정된다.

핵심 원리: TOOL_CALL_START가 슬롯을 선점

default.ts:293-315:

case EventType.TOOL_CALL_START: {
  const { toolCallId, toolCallName, parentMessageId } = event;
  const targetMessage = resolveOrCreateAssistantMessage(...);
  targetMessage.toolCalls ??= [];
 
  // 배열에 push — 이 시점에 순서가 결정됨
  targetMessage.toolCalls.push({
    id: toolCallId,
    type: "function",
    function: { name: toolCallName, arguments: "" },
  });
}

타임라인 예시

시간  이벤트                          toolCalls 배열 상태
──────────────────────────────────────────────────────────
t=0   TOOL_CALL_START(id:1)           [1(비어있음)]
t=1   TOOL_CALL_START(id:2)           [1, 2(비어있음)]
t=2   TOOL_CALL_START(id:3)           [1, 2, 3(비어있음)]
t=3   TOOL_CALL_START(id:4)           [1, 2, 3, 4(비어있음)]
t=4   TOOL_CALL_ARGS(id:3, "...")     [1, 2, 3(채워짐), 4]
t=5   TOOL_CALL_END(id:3)             [1, 2, 3(완료), 4]
t=10  TOOL_CALL_ARGS(id:1, "...")     [1(채워짐), 2, 3, 4]
t=11  TOOL_CALL_END(id:1)             [1(완료), 2, 3, 4]

3번이 먼저 완료되어도 배열 위치는 그대로 3번째 슬롯을 지킨다. TOOL_CALL_ARGS와 TOOL_CALL_END는 toolCallId로 자기 슬롯을 찾을 뿐 위치를 변경하지 않는다(default.ts:336).

설계 의도

1. LLM 응답 순서 보존: LLM이 의도한 순서가 UI에도 반영되어야 함
2. 재정렬 시 UI 깜빡임 방지: React 배열 키 순서 변경이 리렌더 폭풍 유발
3. toolCallId로 정합성 보장: 순서 유지해도 결과 매칭(ToolMessage.toolCallId)은 id 기반이므로 무결

예외: 많은 통합이 순차 실행을 강제

agent.ts:87 등 대부분의 LangGraph 예제는:

parallel_tool_calls: false,  // 레이스 컨디션 회피

로 기본값을 설정해 실제로는 병렬 실행 자체가 조심스럽게 사용된다.

Tool Call Linking 패턴

세 개의 ID가 서로 다른 역할을 하며 병렬 실행 결과를 정확히 매칭한다.

flowchart LR
    subgraph AM["AssistantMessage"]
        AM_ID["id - msg_2<br/>메시지 자체의 ID"]
        TC_ID["toolCalls 0번째 id - call_1<br/>호출 요청 ID"]
    end

    subgraph TM["ToolMessage"]
        TM_ID["id - result_1<br/>결과 메시지 ID"]
        TC_REF["toolCallId - call_1<br/>참조"]
    end

    TC_ID -. "링크 - ID 매칭" .-> TC_REF

    classDef request fill:#ffe6cc,stroke:#d79b00,color:#000
    classDef result fill:#d5e8d4,stroke:#82b366,color:#000
    class AM_ID,TC_ID request
    class TM_ID,TC_REF result

순서 독립적으로 매칭되므로 assistant가 N개 툴을 병렬 발행해도 결과 충돌 없이 처리 가능하다.

encryptedValue — ZDR/store: false 환경의 상태 캐리어

encryptedValue는 UI 렌더링용이 아니라 LLM 서버에 다시 입력하기 위한 불투명 토큰이다.

표시/저장/전달의 3축 분리

경로	UI 노출	클라이언트 저장	LLM 재전송
content (평문 요약)	보임	가능	가능
encryptedValue (암호문)	안 보임	그대로 보관	그대로 왕복

reasoning.mdx:315:

// Client stores only:
// - The encrypted blob (cannot decrypt)
// - The summary text (no sensitive details)
// Full reasoning is never persisted in plaintext

왜 필요한가: 일반 상태 vs ZDR 정책

일반 (서버가 reasoning 저장 가능):

[1턴] User: "복잡한 문제"
      LLM: reasoning 1000 토큰 생성 → Answer
      서버 저장 ✅
[2턴] User: "왜?"
      LLM: 저장된 reasoning 참조 → 답변

ZDR / store: false (서버 저장 금지):

[1턴] User: "복잡한 문제"
      LLM: reasoning → 암호화(자기 키) → encryptedValue
      클라이언트에 전송 (내용 모름, 저장만)
      서버 저장 안 함 ✅
[2턴] User: "왜?"
      클라이언트: encryptedValue 그대로 재전송
      LLM: 복호화 → 원본 reasoning 복원 → 답변 ✅

encryptedValue 없이 2턴을 보내면 LLM이 reasoning을 처음부터 재계산 → 비용 2배 + 결과 불일치 가능.

세 주체의 역할

• LLM 서버: 암호화/복호화 키 소유 (상태는 저장 안 함)
• 클라이언트: 암호문 보관만 (내용 이해 불가)
• AG-UI Protocol: 양쪽을 중계

3단계 라이프사이클

sequenceDiagram
    autonumber
    participant A as Agent
    participant C as Client

    Note over A,C: Turn 1
    A->>C: REASONING_MESSAGE_START - msg-456
    A->>C: REASONING_MESSAGE_CONTENT - 요청 분석 중 - UI 요약
    A->>C: REASONING_MESSAGE_END
    A->>C: REASONING_ENCRYPTED_VALUE<br/>subtype message<br/>entityId msg-456<br/>encryptedValue eyJhbG...

    Note over C: UI에는 요약만 렌더<br/>encryptedValue는 객체 필드에만 저장

    Note over A,C: Turn 2
    C->>A: RunAgentInput.messages에 reasoning 메시지 포함<br/>id msg-456, role reasoning,<br/>content 요약, encryptedValue eyJhbG...
    Note over A: encryptedValue 복호화하여<br/>원본 CoT 복원
    A->>C: 맥락 이어서 응답

default.ts:1092-1100 의 클라이언트 측 처리:

// subtype is "message"
const message = messages.find((m) => m.id === entityId);
if (message?.role !== "activity" && message) {
  message.encryptedValue = encryptedValue;  // 객체 필드에만 저장, 렌더 안 함
}

언제 실제로 써야 하는가

상황	필요?
일반 챗봇	불필요
OpenAI store: true (기본값)	불필요
OpenAI store: false + reasoning 모델 (o1/o3)	필요
금융/의료/법률 엔터프라이즈	필요
ZDR 계약 고객	필요

일반 개발자는 대부분 신경 쓸 필요 없고, 컴플라이언스 환경 전용 기능이다. 다만 AG-UI 프로토콜 설계상 필드가 상시 노출되어 있으므로 존재 이유를 이해해두는 것이 중요하다.

유사 패턴: Tool Call에도 encryptedValue

types.ts:8-13:

export const ToolCallSchema = z.object({
  id: z.string(),
  type: z.literal("function"),
  function: FunctionCallSchema,
  encryptedValue: z.string().optional(),  // 툴 선택 이유를 암호화 보존
});

“왜 이 툴을 이 인자로 호출했는지”의 근거를 ZDR 환경에서도 보존 가능.

ActivityMessage — 프론트엔드 전용 Generative UI 슬롯

types.ts:147-152:

export const ActivityMessageSchema = z.object({
  id: z.string(),
  role: z.literal("activity"),
  activityType: z.string(),       // 프론트엔드가 컴포넌트 선택
  content: z.record(z.any()),     // 자유 스키마
});

왜 LLM에 보내지 않는가

“검색 중…”, “3단계 중 2단계 진행” 같은 UI 상태를 LLM 히스토리에 넣으면:

1. 토큰 낭비 — 다음 턴에 재입력
2. LLM 혼란 — “이 JSON은 뭐지?” 해석 시도

default.ts:578-582 에서 명시적으로 서버 전송 제외:

const isClientOnlyRole = (role: string) =>
  role === "activity" || role === "reasoning";

Custom UI Schema 예시 3가지

패턴 A: 체크리스트 (PLAN)

{
  id: "activity_plan_1",
  role: "activity",
  activityType: "PLAN",
  content: {
    title: "리서치 작업",
    tasks: [
      { id: "t1", label: "논문 검색", status: "pending" },
      { id: "t2", label: "요약 작성", status: "pending" },
    ]
  }
}

진행 중 ACTIVITY_DELTA로 JSON Patch 업데이트:

{
  type: EventType.ACTIVITY_DELTA,
  messageId: "activity_plan_1",
  activityType: "PLAN",
  patch: [
    { op: "replace", path: "/tasks/0/status", value: "done" }
  ]
}

패턴 B: 검색 진행 상태 (SEARCH)

{
  id: "activity_search_1",
  role: "activity",
  activityType: "SEARCH",
  content: {
    query: "AG-UI protocol spec",
    status: "running",
    results: [
      { title: "AG-UI Docs", url: "...", snippet: "..." },
    ],
    metrics: { totalFound: 2, searchTimeMs: 342 }
  }
}

패턴 C: 멀티 스텝 진행 (SCRAPE)

{
  id: "activity_scrape_1",
  role: "activity",
  activityType: "SCRAPE",
  content: {
    url: "https://example.com",
    currentStep: 2,
    totalSteps: 4,
    steps: [
      { label: "페이지 로드", status: "done", duration: 120 },
      { label: "DOM 파싱", status: "done", duration: 45 },
      { label: "데이터 추출", status: "running" },
      { label: "정제 및 저장", status: "pending" },
    ]
  }
}

프론트엔드 디스패치 패턴

function ActivityRenderer({ message }: { message: ActivityMessage }) {
  switch (message.activityType) {
    case "PLAN":    return <PlanActivity content={message.content} />;
    case "SEARCH":  return <SearchActivity content={message.content} />;
    case "SCRAPE":  return <ScrapeActivity content={message.content} />;
    default:        return <GenericActivity content={message.content} />;
  }
}

Record<string, any>의 자유도는 activityType 단위로 팀이 자율적으로 스키마를 설계하고, JSON Patch로 증분 업데이트를 받는 프로토콜에 묶이지 않은 확장점이다.

Generative UI — JSON/HTML 직접 전달

AG-UI는 “렌더링 스펙”이 아니라 **“수송 경로”**다. JSON을 그대로 나르는 것이 기본 기능이며, generative-ui-specs.mdx:18-20:

AG-UI is not a generative UI specification — it’s a User Interaction protocol… AG-UI natively supports all of the above generative UI specs and allows developers to define their own custom generative UI standards as well.

4가지 전달 방식 비교

방법	무손실 전달	보안	유연성	사용 패턴
ActivityMessage + JSON	가능	안전 (프론트가 렌더)	컴포넌트 필요	권장 표준
Tool Call 기반	가능	안전	LLM이 호출해야	tool-based generative UI
Raw HTML	가능	XSS 위험	완전 자유	비권장
MCP-UI (iframe)	가능	샌드박스	웹페이지급	Microsoft+Shopify 스펙

공식 Generative UI 스펙

generative-ui-specs.mdx:12-16:

스펙	유지보수	특징
A2UI	Google	JSONL 기반 스트리밍, 플랫폼 무관
Open-JSON-UI	OpenAI	내부 declarative UI 스키마 표준화
MCP-UI	Microsoft + Shopify	iframe 기반 완전 개방 스펙

AG-UI는 이 모든 스펙을 네이티브 지원하며, ActivityMessage.content의 Record<string, any>가 각 스펙의 JSON을 그대로 실어 나른다.

Tool-based Generative UI 예시

agent.ts:27-29:

const systemMessage = new SystemMessage({
  content: 'Help the user with writing Haikus. If the user asks for a haiku,
            use the generate_haiku tool to display the haiku to the user.'
});

LLM이 generate_haiku({title, lines}) 툴 호출 → 실제 실행 없음 → 툴 호출 자체가 UI 지시. 프론트엔드가 tool call의 arguments를 받아 컴포넌트로 렌더링.

Raw HTML 전달 시 주의

// 보안 주의: dangerouslySetInnerHTML 패턴
yield {
  type: "ACTIVITY_SNAPSHOT",
  messageId: "html-1",
  activityType: "RAW_HTML",
  content: { html: "<div class='card'>...</div>" }
}

LLM이 생성한 HTML을 그대로 렌더하면 <script> 주입 가능. 실무에서는 JSON 스키마를 쓰고 프론트엔드가 안전하게 컴포넌트로 렌더하는 것이 표준이며, 웹페이지급 자유도가 필요하면 MCP-UI의 iframe 샌드박스를 쓴다.

전체 시퀀스 — 툴 호출 포함 end-to-end 흐름

사용자가 “도쿄 날씨 알려줘”를 물었을 때의 전 구간 흐름.

sequenceDiagram
    autonumber
    participant U as User
    participant FE as Frontend
    participant AD as AG-UI Adapter
    participant LG as LangGraph
    participant API as OpenAI API

    U->>FE: 도쿄 날씨 알려줘
    FE->>AD: POST /run<br/>AG-UI UserMessage 포함

    Note over AD: aguiMessagesToLangChain 변환
    AD->>LG: graph.stream with LangChain messages
    LG->>API: OpenAI chat.completions - LC 내부 변환
    API-->>LG: streaming - choice.delta.tool_calls

    LG-->>AD: LangGraph events
    Note over AD: LangGraph event를 AG-UI Event로 변환

    AD-->>FE: SSE - RUN_STARTED
    AD-->>FE: SSE - TEXT_MESSAGE_START
    AD-->>FE: SSE - TOOL_CALL_START - weather
    AD-->>FE: SSE - TOOL_CALL_ARGS - city tokyo
    AD-->>FE: SSE - TOOL_CALL_END

    FE->>FE: 프론트엔드 툴 실행<br/>또는 서버 재호출
    FE->>AD: 툴 결과 포함 재요청

    AD->>LG: 툴 결과와 누적 메시지
    LG->>API: 2차 추론
    API-->>LG: 최종 응답
    LG-->>AD: streaming
    AD-->>FE: SSE - TEXT_MESSAGE_CONTENT<br/>delta - 오늘 도쿄는
    AD-->>FE: SSE - TEXT_MESSAGE_END
    AD-->>FE: SSE - RUN_FINISHED
    FE->>U: 오늘 도쿄는 15도

동기화 메커니즘 — Snapshot vs Streaming

MESSAGES_SNAPSHOT (완전 교체)

전체 대화 배열을 한 번에 교체. 초기화 / 재연결 / 대규모 변경 시 사용.

default.ts:551-596 의 병합 로직이 주목할 만함:

// activity / reasoning 메시지는 서버 스냅샷에 없어도 유지
const isClientOnlyRole = (role: string) =>
  role === "activity" || role === "reasoning";
 
messages = messages
  .filter((m) => isClientOnlyRole(m.role) || snapshotMap.has(m.id))
  .map((m) => (isClientOnlyRole(m.role) ? m : snapshotMap.get(m.id)!));

클라이언트 전용 role은 스냅샷이 덮어쓰지 않는다 — 프론트엔드 상태 보존을 위한 설계.

Streaming (점진 구축)

TEXT_MESSAGE_START    → { messageId, role }
TEXT_MESSAGE_CONTENT  → { messageId, delta }  (N회)
TEXT_MESSAGE_END      → { messageId }

TOOL_CALL_START → TOOL_CALL_ARGS (JSON 조각들) → TOOL_CALL_END

주의: TOOL_CALL_ARGS.delta는 JSON 문자열의 조각이라 중간 파싱 시 깨진다. END까지 쌓고 JSON.parse가 원칙이며 default.ts:405-410 구현도 그렇게 되어 있다.

벤더 중립성의 구체적 이득

flowchart LR
    CLIENT["Client"]
    PROTO["AG-UI<br/>(표준 포맷)"]
    ADAPTER["Adapter"]
    F1["OpenAI format"]
    F2["Anthropic format"]
    F3["Custom format"]
    M1(("OpenAI<br/>모델"))
    M2(("Claude<br/>모델"))
    M3(("Custom<br/>모델"))

    CLIENT <--> PROTO
    PROTO <--> ADAPTER
    ADAPTER <--> F1
    ADAPTER <--> F2
    ADAPTER <--> F3
    F1 <--> M1
    F2 <--> M2
    F3 <--> M3

    classDef agui fill:#b3d9ff,stroke:#0066cc,color:#000
    classDef adapter fill:#ffd9b3,stroke:#cc6600,color:#000
    classDef vendor fill:#e1d5e7,stroke:#9673a6,color:#000
    classDef model fill:#f8cecc,stroke:#b85450,color:#000

    class CLIENT,PROTO agui
    class ADAPTER adapter
    class F1,F2,F3 vendor
    class M1,M2,M3 model

클라이언트는 AG-UI 포맷만 알면 되므로 모델 스위칭이 어댑터 교체로 끝난다. MCP/A2A와 구분되는 AG-UI만의 포지션이 여기에 구체적으로 구현되어 있다.

체크 포인트

1. AssistantMessage.content가 optional인 이유 — toolCalls만으로도 의미가 성립
2. ToolMessage에 name 필드가 없는 이유 — BaseMessage를 extend 안 하고 독립 스키마. role+toolCallId로 충분
3. ActivityMessage.content가 Record<string, any>인 이유 — 커스텀 UI 스키마를 자유롭게 수용
4. Streaming 중 연결 끊김 복구 — 재연결 후 MESSAGES_SNAPSHOT으로 동기화
5. encryptedValue 수명 — 다음 턴 요청 시 원본 그대로 재전송, 클라이언트는 내용 무관
6. 문서 ↔ 코드 네이밍 불일치 — encryptedContent(문서)는 실제로 encryptedValue(코드). 코드가 정답

참고 문서

• AG-UI Messages 공식 문서
• AG-UI Reasoning (encryptedValue 상세)
• AG-UI Generative UI Specs
• types.ts — Zod 스키마 정의
• default.ts — 클라이언트 이벤트 적용 로직
• utils.ts — 멀티모달 변환 레퍼런스
• agent.ts — Adapter 구현 레퍼런스