AG-UI(Agent-User Interaction) 프로토콜 매핑 (트렌드 보고서 Tier 1).
에이전트 실행을 사용자 인터페이스로 스트리밍하기 위한 순수 변환 계층이다.
ElGraph 스트림 이벤트(ElGraph.stream/3의 %{thread_id, step, node, event} 원소)를
AG-UI 표준 이벤트(타입 + camelCase 필드)로 변환한다. HTTP/SSE 서버는 이 매핑 위의
얇은 계층으로 별도 패키지가 담당한다 — ElGraph.A2A와 동일한 패턴.
AG-UI 이벤트 타입 (구현 범위):
RUN_STARTED / RUN_FINISHED / RUN_ERROR — 실행 생명주기
STEP_STARTED / STEP_FINISHED — 노드(=step) 경계 (:node_start/:node_end)
TEXT_MESSAGE_START / _CONTENT / _END — 토큰 스트림 ({:token, delta})
TOOL_CALL_START / _ARGS / _END — 툴 호출 ({:tool_call, id, name, args})
STATE_SNAPSHOT — 최종/중단 상태 ({:done, result})
토큰 메시지는 노드 단위로 프레이밍한다(노드 1개 = assistant 메시지 1개). transform/3이
열린 메시지를 추적해 :node_end나 종료 이벤트 시 자동으로 닫는다.
Summary
Functions
CUSTOM 이벤트 — 프레임워크 밖 임의 이벤트(메트릭 등).
단일 ElGraph 스트림 원소를 AG-UI 이벤트로 무상태 매핑한다(best-effort). 메시지 프레이밍이
필요 없는 경우용 — 완전한 시퀀스(START/END 프레이밍 포함)는 transform/3을 쓴다.
매핑 불가 원소는 :ignore.
MESSAGES_SNAPSHOT 이벤트 — 전체 메시지 목록 스냅샷.
RUN_ERROR 이벤트.
RUN_FINISHED 이벤트.
RUN_STARTED 이벤트.
STATE_DELTA 이벤트 — JSON Patch(RFC 6902) 연산 목록.
STATE_SNAPSHOT 이벤트 — 임의 상태 스냅샷.
ElGraph 스트림(Enumerable of %{event: ...})을 AG-UI 이벤트 시퀀스로 변환한다.
Types
Functions
CUSTOM 이벤트 — 프레임워크 밖 임의 이벤트(메트릭 등).
iex> ElGraph.AGUI.custom("metric", 5)["value"]
5단일 ElGraph 스트림 원소를 AG-UI 이벤트로 무상태 매핑한다(best-effort). 메시지 프레이밍이
필요 없는 경우용 — 완전한 시퀀스(START/END 프레이밍 포함)는 transform/3을 쓴다.
매핑 불가 원소는 :ignore.
MESSAGES_SNAPSHOT 이벤트 — 전체 메시지 목록 스냅샷.
RUN_ERROR 이벤트.
iex> ElGraph.AGUI.run_error("boom")["message"]
"boom"RUN_FINISHED 이벤트.
RUN_STARTED 이벤트.
iex> ElGraph.AGUI.run_started("t1", "r1")["type"]
"RUN_STARTED"STATE_DELTA 이벤트 — JSON Patch(RFC 6902) 연산 목록.
STATE_SNAPSHOT 이벤트 — 임의 상태 스냅샷.
@spec transform(Enumerable.t(), String.t(), String.t()) :: Enumerable.t()
ElGraph 스트림(Enumerable of %{event: ...})을 AG-UI 이벤트 시퀀스로 변환한다.
앞에 RUN_STARTED를 붙이고, 토큰을 메시지로 프레이밍하며, 종료(:done 또는 :down) 이벤트
시 STATE_SNAPSHOT + RUN_FINISHED(또는 RUN_ERROR)로 마감한다. 입력이 lazy 스트림이면
결과도 lazy다.