AG-UI State Management

• AG-UI State Management는 Agent와 Frontend 간 양방향 구조화 데이터 동기화 메커니즘
• JSON 객체 기반의 공유 상태(shared state) 채널
• STATE_SNAPSHOT, STATE_DELTA 이벤트로 전송되는 프로토콜 규격
• 프레임워크/트랜스포트에 독립적인 전송 계약

해당 개념이 필요한 이유

• 채팅 텍스트(TEXT_MESSAGE_*)만으로는 구조화된 UI 컴포넌트를 렌더링하기 어렵다
• Agent가 제안한 데이터를 사용자가 수정해서 다시 Agent에게 돌려보내는 양방향 채널이 필요하다
• 진행 중 상태(thinking, partial output 등)를 실시간 관찰할 수 있어야 한다
• Human-in-the-Loop 워크플로우(승인/거절/수정)의 핵심 전제 조건이다

AS-IS

대화 텍스트 하나에 모든 정보를 담았을 때:

sequenceDiagram
    autonumber
    participant U as User
    participant F as Frontend
    participant A as Agent
    U->>F: 이메일 보내줘
    F->>A: 메시지 전송
    A->>F: TEXT_MESSAGE 안내 문구만 전달
    Note over F: 텍스트만 받음. 버튼 UI 파싱 어려움. 재전송 플로우 없음
    F->>U: 그냥 텍스트 표시

TO-BE

구조화된 state로 주고받을 때:

sequenceDiagram
    autonumber
    participant U as User
    participant F as Frontend
    participant A as Agent
    U->>F: 이메일 보내줘
    F->>A: RunAgentInput with initial state
    A->>F: STATE_SNAPSHOT proposal 객체 전송
    F->>U: EmailProposalCard 렌더링
    U->>F: 내용 수정 후 승인
    F->>A: setState로 승인 상태 전송
    A->>F: TOOL_CALL send_email 최종 실행

State vs TEXT_MESSAGE의 역할 구분

이벤트 종류를 선택할 때의 기준은 “사용자가 그 정보에 반응할 수 있는가”이다.

TEXT_MESSAGE_*는 대화 로그의 일부로, 추가만 가능한(append-only) 텍스트 스트림이다. 사용자는 읽기만 하고 그 내용을 직접 수정하지 않는다.

STATE_SNAPSHOT / STATE_DELTA는 애플리케이션의 현재 상태를 표현하는 구조화된 데이터다. 커스텀 UI 컴포넌트로 렌더링되며, 사용자가 setState로 수정하면 그 변경이 Agent 쪽으로 다시 전파된다.

이메일 발송 제안을 예로 들면, "client@example.com에게 이메일을 보낼까요?"라는 안내 문구는 TEXT_MESSAGE로 보내되, 실제 수정 가능한 이메일 초안 객체({recipient, subject, body})는 STATE로 보내는 것이 자연스럽다. UI는 state를 보고 승인/수정 폼을 만들고, 사용자가 body를 수정하면 그 변경이 Agent에게 돌아간다.

구분	TEXT_MESSAGE	STATE_*
본질	대화 텍스트	구조화된 애플리케이션 데이터
변경 가능성	Append-only	양방향 수정
UI	채팅 풍선	커스텀 컴포넌트
목적	”말하기"	"상태 표현”

두 가지 동기화 방식: SNAPSHOT과 DELTA

AG-UI는 두 가지 보완적 이벤트로 state를 동기화한다.

STATE_SNAPSHOT 은 state 전체 객체를 담는 이벤트다. 수신 측은 기존 state를 완전히 교체한다.

interface StateSnapshotEvent {
  type: EventType.STATE_SNAPSHOT
  snapshot: any   // 전체 state 객체
}

STATE_DELTA 는 JSON Patch(RFC 6902) 연산 배열을 담는 이벤트다. 수신 측은 기존 state에 패치를 적용한다.

interface StateDeltaEvent {
  type: EventType.STATE_DELTA
  delta: JsonPatchOperation[]
}

축	SNAPSHOT	DELTA
데이터	전체	변경분만
적용 방식	교체	패치 적용
네트워크 비용	높음	낮음
주 용도	초기화, 재동기화, 대규모 변경	고빈도 증분 업데이트

SNAPSHOT은 최초에만 사용되는가

일반적 흐름은 “최초 SNAPSHOT → 이후 DELTA”가 맞지만, SNAPSHOT은 중간에도 필요에 따라 다시 나올 수 있다. 공식 문서는 네 가지 경우를 명시한다.

1. 인터랙션 시작 시 baseline 수립
2. 연결 끊김 후 재동기화
3. 패치 적용에 실패해 불일치가 감지된 경우
4. 대규모 변경으로 delta보다 snapshot이 효율적인 경우

예를 들어 네트워크가 잠시 끊겨 일부 delta가 유실되면 클라이언트의 state가 서버와 어긋난다. 이때 다음 delta 적용이 실패하고, Agent는 새 SNAPSHOT을 내려 baseline을 다시 잡는다. 사용자가 “주제를 바꿔 다시 시작하자”고 요청하는 것처럼 기존 state가 전부 무의미해질 때도 SNAPSHOT을 다시 사용한다.

JSON Patch 형식 (RFC 6902)

DELTA 이벤트는 표준 JSON Patch 연산 배열로 표현된다.

interface JsonPatchOperation {
  op: "add" | "remove" | "replace" | "move" | "copy" | "test"
  path: string    // JSON Pointer (RFC 6901)
  value?: any     // add, replace용
  from?: string   // move, copy용
}

대표 연산 예시:

{ "op": "add", "path": "/user/preferences", "value": { "theme": "dark" } }
{ "op": "replace", "path": "/conversation_state", "value": "paused" }
{ "op": "remove", "path": "/temporary_data" }
{ "op": "move", "path": "/completed_items", "from": "/pending_items/0" }

Path는 / 구분자로 객체 경로를 나타내는 JSON Pointer이며, 배열 인덱스도 /0, /1 식으로 표현한다.

AG-UI 클라이언트는 fast-json-patch 라이브러리로 이 연산들을 원자적으로 적용하고, 실패 시에는 조용히 업데이트를 포기한 뒤 필요하면 새 SNAPSHOT을 요청한다. 원본 코드는 sdks/typescript/packages/client/src/apply/default.ts에서 확인할 수 있다.

case EventType.STATE_DELTA: {
  const { delta } = event as StateDeltaEvent;
  try {
    const result = jsonpatch.applyPatch(state, delta, true, false);
    state = result.newDocument;
  } catch (error) {
    console.warn(`Failed to apply state patch: ...`);
  }
}

State 전달의 주체별 역할

“Agent는 어떻게 state를 전달해야 할지 아는가? LLM에 지침이 있는가?”라는 질문은 층위를 섞었을 때 생기는 혼동이다. 실제로는 다섯 주체가 각자 다른 책임을 진다.

주체	담당	한 줄 요약
Frontend	initialState 정의, UI 렌더, setState	암묵적 스키마의 출발점
AG-UI 프로토콜	이벤트 타입 정의, 전송 규격	”HOW to transmit”만 담당
Agent 프레임워크(+Adapter)	LLM 출력을 state 이벤트로 변환	”WHEN to emit” 결정
LLM	Tool Call 또는 Structured Output 생성	”state”라는 개념을 모름
개발자	시스템 프롬프트 + 비즈니스 로직 작성	세 번째와 네 번째를 연결

중요한 점은 LLM이 “state를 보내야겠다”고 결정하는 게 아니라는 것이다. LLM은 언제나처럼 도구를 호출할 뿐이고, 그 도구 호출을 Agent 프레임워크 또는 Adapter 코드가 state 이벤트로 변환한다. 즉, 프롬프트에 적힌 지침은 LLM에게 “이런 도구를 이런 형식으로 호출해 달라”는 안내이지, “state를 보내 달라”는 직접 지시가 아니다.

Agent 프레임워크별 State emit 패턴

같은 목표(state 동기화)를 프레임워크마다 다른 전략으로 구현한다. 이 다양성이 바로 integrations/ 디렉토리가 존재하는 이유다.

패턴 A — 자동 Tool 주입 (Claude Agent SDK). Adapter가 ag_ui_update_state라는 특수 도구를 MCP 서버에 자동 등록하고, 시스템 프롬프트에 사용 지침을 자동 추가한다. Claude는 이 도구를 평범한 MCP 도구로 인식하고 호출한다.

패턴 B — 선언적 반환 (Pydantic AI). 개발자가 정의한 도구의 반환 타입이 StateSnapshotEvent이면 프레임워크가 자동으로 AG-UI 스트림에 흘려보낸다.

@agent.tool_plain
async def display_recipe(recipe: Recipe) -> StateSnapshotEvent:
    return StateSnapshotEvent(
        type=EventType.STATE_SNAPSHOT,
        snapshot={'recipe': recipe},
    )

패턴 C — 명시적 dispatch (LangGraph). 개발자가 노드 코드 안에서 adispatch_custom_event("manually_emit_intermediate_state", state, config=config)를 호출하면, Adapter가 이 커스텀 이벤트를 StateSnapshotEvent로 변환한다.

패턴 D — 스트리밍 가로채기 (LangGraph Predictive State). config["metadata"]["predict_state"]로 “어느 도구의 어느 인자를 어느 state 키에 복사할지”를 선언해두면, LLM이 그 도구 호출을 스트리밍하는 도중에도 실시간으로 state가 업데이트된다. “문서가 타이핑되는 모습”이 실시간 렌더링되는 데모의 원리다.

공통점은 모두 LLM 출력(주로 도구 호출)을 중간 레이어가 AG-UI 이벤트로 번역한다는 것이다.

Agent가 state를 emit하는 코드 흐름

LangGraph 기준으로 “LLM 출력 → state 이벤트”의 완전한 경로는 다음과 같다.

sequenceDiagram
    autonumber
    participant LLM
    participant Node as LangGraph Node
    participant Adapter as AG-UI Adapter
    participant FE as Frontend

    Note over Node: predict_state 메타데이터 설정
    Node->>LLM: invoke messages
    LLM-->>Node: tool_call chunks 스트리밍
    Node->>Node: 내부 state 업데이트
    Node->>Adapter: adispatch_custom_event 호출
    Adapter->>Adapter: get_state_snapshot 필터링
    Adapter-->>FE: StateSnapshotEvent
    FE->>FE: state 교체 및 UI 리렌더

ClaudeAgentAdapter의 자동 주입 메커니즘

“개발자가 프롬프트에 ag_ui_update_state를 직접 쓰는 게 아니라면, 그걸 감싸는 컴포넌트가 있을 것이다”라는 추론은 정확하다. 실제로 ClaudeAgentAdapter가 다섯 가지 일을 자동으로 수행한다.

1단계 — 도구 동적 생성. state가 들어오면 create_state_management_tool()이 @tool 데코레이터로 ag_ui_update_state를 즉석에서 만든다. 실제 구현은 스텁이며, 나중에 “State updated successfully”를 반환할 뿐이다. 원본은 ag_ui_claude_sdk/utils.py.

@tool(
    "ag_ui_update_state",
    "Update the shared application state...",
    {"state_updates": dict}   # 스키마는 그냥 dict (구조 강제 없음)
)
async def update_state_tool(args: dict) -> dict:
    return {"content": [{"type": "text", "text": "State updated successfully"}]}

2단계 — MCP 서버 등록. 생성된 도구를 create_sdk_mcp_server()로 동적 MCP 서버에 등록하고, ClaudeAgentOptions.mcp_servers에 주입한다. Claude에게는 mcp__ag_ui__ag_ui_update_state라는 이름의 평범한 MCP 도구로 보인다.

3단계 — 시스템 프롬프트 자동 append. build_state_context_addendum()이 현재 state를 JSON으로 직렬화하고 사용 지침을 포함한 markdown 블록을 생성해, 개발자의 원본 system_prompt 뒤에 이어 붙인다.

[개발자가 작성한 원본 system_prompt]
 
## Current Shared State
This state is shared with the frontend UI and can be updated.
```json
{ "recipe": { "title": "", "ingredients": [], "instructions": "" } }

4단계 — 초기 SNAPSHOT 발송. run() 시작 시점에 input_data.state가 있으면 즉시 StateSnapshotEvent를 emit해 Frontend가 초기 state를 가지고 시작할 수 있게 한다.

5단계 — tool call 가로채기. Claude가 ag_ui_update_state를 호출하면 Adapter가 그 호출을 감지해 일반 TOOL_CALL_* 이벤트 대신 STATE_SNAPSHOT 이벤트를 emit한다(상세는 아래 별도 섹션).

개발자 입장에서는 이 다섯 단계가 모두 블랙박스이며, ClaudeAgentAdapter(name=..., options=...)만 인스턴스화하면 자동으로 동작한다.

State의 스키마는 누가 정의하는가

“state 키가 서비스마다 다를 수 있는가? 누가 구조를 정하는가?”에 대한 답은 프레임워크마다 다르다.

claude-agent-sdk 통합에서는 Frontend가 사실상의 스키마 정의자다. useCoAgent({ initialState: {...} })로 넘기는 초기 state의 JSON 구조가 암묵적 계약이 된다. 백엔드 Adapter에는 어떤 스키마 검증도 없고, 받은 dict를 얕은 병합({**prev, **updates})으로 합칠 뿐이다. Claude는 시스템 프롬프트에 주입된 JSON 예시를 보고 구조를 유추해 같은 키 구조로 업데이트를 생성한다.

즉, 서비스마다 키가 완전히 다를 수 있다.

서비스 종류	예시 state 구조
레시피 어시스턴트	{ "recipe": { "title": ..., "ingredients": [...] } }
작업 승인 워크플로우	{ "steps": [{"description": ..., "status": "pending"}] }
이메일 드래프트 에이전트	{ "email_draft": { "recipient": ..., "body": ... } }
쇼핑 카트	{ "user_profile": {...}, "cart": [...] }

반면 Pydantic AI는 명시적 Pydantic BaseModel을 강제하고, LangGraph는 TypedDict 기반 StateGraph로 스키마를 선언한다. 이런 통합에서는 백엔드에도 스키마가 존재한다.

claude-agent-sdk 통합이 느슨한 이유는 설계 선택이다. 스키마를 Frontend 한 곳에만 두면 Frontend/Backend 동기화 문제가 사라진다는 장점과, Claude의 JSON 구조 유추 능력을 신뢰하기 때문이다. 트레이드오프는 백엔드 타입 안전성의 포기다.

Adapter의 가로채기 동작 원리

“Claude에게 스텁이 ok를 반환하는데 Adapter는 어떻게 state를 처리하는가? 가로채는 주체는 누구인가?”에 대한 답은 두 개의 평행한 흐름이 동시에 진행된다는 것이다.

sequenceDiagram
    autonumber
    participant Claude
    participant SDK as Claude SDK CLI
    participant Stub as Stub Tool
    participant Adapter
    participant FE as Frontend

    Claude->>SDK: tool_use ag_ui_update_state
    SDK->>Stub: execute
    Stub-->>SDK: State updated successfully
    SDK-->>Claude: tool_result success
    Note over Claude: 정상 tool 호출로 인식. 추론 계속
    SDK->>Adapter: 메시지 스트림 관찰
    Adapter->>Adapter: tool_name 검사 후 특수 분기
    Note over Adapter: TOOL_CALL 이벤트 스킵하고 state 병합
    Adapter-->>FE: StateSnapshotEvent 전송

흐름 A (Claude ↔ Stub). Claude Agent SDK의 MCP 인프라가 스텁 도구를 실제로 실행한다. 스텁은 "State updated successfully"를 반환하고, Claude는 이것을 정상 tool_result로 받아 다음 동작을 결정한다. 이 흐름은 AG-UI와 무관하게 완결된다.

흐름 B (Adapter의 도청). 그와 동시에 Adapter는 client.receive_response()로 Claude SDK 메시지 스트림을 관찰하고 있다. 이 스트림을 AG-UI 이벤트로 번역하는 과정에서 tool_name이 ag_ui_update_state인 경우만 특수 분기한다. 원본은 ag_ui_claude_sdk/handlers.py.

if _is_state_management_tool(tool_name):
    state_updates = tool_input.get("state_updates", {})
    if isinstance(current_state, dict) and isinstance(state_updates, dict):
        current_state = {**current_state, **state_updates}
    yield StateSnapshotEvent(
        type=EventType.STATE_SNAPSHOT,
        snapshot=current_state
    )
    return   # 일반 TOOL_CALL_* 이벤트 emit 스킵

“가로채기”의 본질은 도구 실행을 막는 것이 아니라, Claude SDK 메시지 → AG-UI 이벤트 변환 단계에서 특수 경로로 보내는 것이다. 통역사가 “같은 말을 다르게 번역”하는 것에 가깝다.

가로채는 주체는 명확히 Adapter(ClaudeAgentAdapter), 구체적으로는 스트리밍 경로의 _stream_claude_sdk() 메서드와 비스트리밍 경로의 handle_tool_use_block() 함수다.

Agent와 Claude 간 통신 스택

“ClaudeAgentAdapter는 API 호출 방식인가, CLI + NDJSON인가?”에 대한 답은 후자다.

의존성 체인은 다음과 같다.

Python 서버 (FastAPI)
 └─ ag-ui-claude-sdk (PyPI, 이 레포의 통합 패키지)
      └─ claude-agent-sdk (PyPI, Anthropic 공식)
           └─ subprocess spawn
                └─ `claude` CLI 바이너리 (npm @anthropic-ai/claude-code)
                     └─ HTTPS → api.anthropic.com

Adapter 자체가 Anthropic API를 직접 호출하지는 않는다. 대신 claude-agent-sdk 라이브러리에 위임하고, 이 라이브러리가 Claude Code CLI를 subprocess로 띄워 stdio 기반 NDJSON 프로토콜로 통신한다. CLI가 최종적으로 Anthropic API와 HTTPS로 통신하는 부분은 Adapter 관점에서 블랙박스다.

증거는 README의 Session Persistence 항목에 드러난다. Claude SDK가 .claude/ 디렉토리에 세션 상태를 저장한다는 점은 순수 API 클라이언트로는 불가능한 동작으로, CLI가 로컬 파일시스템을 다루는 특성 때문이다.

따라서 이 통합을 배포하려면 단순히 Python 패키지 하나로는 부족하고, Node.js 환경 + @anthropic-ai/claude-code CLI 바이너리가 PATH에 있어야 한다.

npm install -g @anthropic-ai/claude-code
pip install ag-ui-claude-sdk
export ANTHROPIC_API_KEY=sk-ant-xxx

통신 스택 전체에는 세 개의 독립된 스트림이 중첩되어 있다.

구간	프로토콜	내용
Claude API ↔ CLI	HTTPS + SSE	Anthropic Messages API 토큰 스트림
CLI ↔ Python SDK	stdio + NDJSON	Claude SDK 메시지 객체
FastAPI ↔ Frontend	HTTP + SSE	AG-UI 이벤트(RUN_STARTED, STATE_SNAPSHOT 등)

각 레이어는 자기 단의 스트림을 파싱하고 다음 레이어 형식으로 변환해서 내보낸다. ClaudeAgentAdapter의 본질은 이 중간 번역기다.

Codex CLI용 어댑터는 존재하는가

현재 AG-UI 공식 integrations/ 디렉토리에는 18개 통합이 있지만, OpenAI Codex CLI 전용 어댑터는 없다.

전체 통합 목록:

a2a                      langroid
adk-middleware           llama-index
ag2                      mastra
agent-spec               microsoft-agent-framework
agno                     pydantic-ai
aws-strands              server-starter
claude-agent-sdk         server-starter-all-features
community/genkit         vercel-ai-sdk
community/spring-ai
crew-ai
langchain
langgraph

CLI subprocess 방식이 Claude에만 있는 것은, Claude Code CLI가 공식 claude-agent-sdk로 라이브러리화되어 stdio/NDJSON 프로토콜이 안정적으로 공개되었기 때문이다. Codex CLI는 주로 터미널 UX 중심이라 프로그래매틱 제어를 위한 표준 SDK 배포가 아직 Claude만큼 성숙하지 않다.

OpenAI 모델을 AG-UI와 붙이려면 현실적으로는 API 기반 통합을 사용한다: vercel-ai-sdk, langchain, langgraph(LLM provider로 OpenAI 선택), llama-index, pydantic-ai 등이 모두 HTTPS API 경로로 OpenAI를 지원한다.

직접 Codex CLI 어댑터를 만들고 싶다면 claude-agent-sdk 통합이 좋은 템플릿이 된다. adapter.py(AbstractAgent 구현), session.py(subprocess 관리), handlers.py(tool call 번역), utils.py(프롬프트 augmentation)의 네 가지 파일 구조를 그대로 따르되, Codex CLI의 stdio 메시지 포맷을 AG-UI 이벤트로 매핑하는 로직만 새로 작성하면 된다. 난이도는 Codex CLI의 프로토콜 문서화 수준에 크게 좌우된다.

통합별 비교 요약

같은 AG-UI 프로토콜에 붙는 다양한 방식:

통합	Agent ↔ LLM 통신 방식	state 스키마 정의 위치
claude-agent-sdk	CLI subprocess + stdio/NDJSON	Frontend (암묵적)
langchain	anthropic / openai SDK → HTTPS API	개발자 코드
langgraph	내부 LLM 추상화 → HTTPS API	TypedDict / Pydantic
vercel-ai-sdk	@ai-sdk/* → HTTPS API	TypeScript 타입
pydantic-ai	다중 provider → HTTPS API	Pydantic BaseModel
crew-ai	내부 LLM 추상화	Flow state (Pydantic)
mastra	내부 메모리 시스템	Working memory

AG-UI 프로토콜은 어떤 방식이든 상관하지 않는다. 프로토콜은 Frontend ↔ Agent 사이의 규격만 정의하고, 그 뒤는 각 통합이 자유롭게 선택한다. 이것이 AG-UI가 “transport agnostic”이라고 불리는 실제 이유다.

Best Practices

• SNAPSHOT은 아껴 쓰기: 초기화, 재동기화, 대규모 리셋 등 baseline이 필요한 순간에만 사용한다
• DELTA를 기본으로: 증분 변경은 항상 delta로 보내 네트워크 비용을 줄인다
• State 구조 설계: 부분 업데이트가 쉽도록 중첩을 얕게, 키를 안정적으로 설계한다
• 충돌 처리 정책 마련: Agent와 Frontend가 동시에 같은 필드를 수정할 때 어느 쪽이 이기는지 미리 정한다
• 에러 복구 경로 확보: delta 적용 실패 시 SNAPSHOT 재요청 메커니즘을 두어 클라이언트가 영구적으로 어긋나지 않게 한다
• 민감 정보 배제: 공유 state에는 인증 토큰, 개인정보 등을 담지 않는다
• 프레임워크별 규약 준수: 각 통합이 가진 state emit 패턴(Claude SDK의 도구 주입, Pydantic AI의 반환 타입, LangGraph의 dispatch 등)을 따른다

참고 문서

• AG-UI State Management (공식)
• JSON Patch (RFC 6902)
• JSON Pointer (RFC 6901)
• Claude Agent SDK (Python)
• CopilotKit useCoAgent
• 레포 내부 구현
  • sdks/typescript/packages/core/src/events.ts — StateSnapshotEvent, StateDeltaEvent 스키마 정의
  • sdks/typescript/packages/client/src/apply/default.ts — 클라이언트 측 fast-json-patch 적용 로직
• 통합 구현 예 (claude-agent-sdk)
  • adapter.py — 메인 오케스트레이션, build_options, _stream_claude_sdk
  • handlers.py — 비스트리밍 경로의 tool 가로채기
  • utils.py — create_state_management_tool, build_state_context_addendum
• 통합 구현 예 (langgraph Python)
  • ag_ui_langgraph/agent.py — LangGraph 노드 이벤트를 AG-UI 이벤트로 변환
  • examples/agents/shared_state/agent.py — adispatch_custom_event 사용 예시
  • examples/agents/predictive_state_updates/agent.py — predict_state 메타데이터 설정 예시
• 통합 구현 예 (기타 프레임워크)
  • integrations/pydantic-ai/python/examples/server/api/shared_state.py — Pydantic AI 선언적 반환 패턴
  • integrations/mastra/typescript/src/mastra.ts — Mastra working memory snapshot 방식
  • integrations/crew-ai/python/ag_ui_crewai/endpoint.py — CrewAI 이벤트 버스 리스너 방식
• 전체 통합 목록: integrations/