상태 관리

상태 관리 (State Management)

AG-UI에서 에이전트와 프론트엔드 간 상태 동기화를 이해하는 방법을 설명드릴게요.

출처: 문서

본문

상태 관리는 AG-UI 프로토콜의 핵심 기능으로, 에이전트와 프론트엔드 애플리케이션 간 실시간 동기화를 가능하게 해요. 상태를 공유하고 갱신하는 효율적인 메커니즘을 제공함으로써, AG-UI는 AI 에이전트와 인간 사용자가 매끄럽게 함께 작업하는 협업 경험의 기반을 만듭니다.

공유 상태 아키텍처 (Shared State Architecture)

AG-UI에서 상태는 다음과 같은 구조화된 데이터 객체입니다:

에이전트와의 상호작용 전반에 걸쳐 유지
에이전트와 프론트엔드 양쪽에서 접근 가능
상호작용이 진행됨에 따라 실시간으로 갱신
양쪽의 의사 결정을 위한 컨텍스트 제공

이 공유 상태 아키텍처는 양방향 통신 채널을 만들어요:

에이전트는 애플리케이션의 현재 상태에 접근해 정보에 기반한 결정을 내릴 수 있음
프론트엔드는 에이전트의 내부 상태 변화를 관찰하고 반응할 수 있음
양쪽 모두 상태를 수정할 수 있어 협업 워크플로를 만듦

상태 동기화 메서드 (State Synchronization Methods)

AG-UI는 상태 동기화를 위한 두 가지 상호 보완 메서드를 제공합니다:

상태 스냅샷 (State Snapshots)

STATE_SNAPSHOT 이벤트는 에이전트의 현재 상태 완전체 표현을 전달해요:

interface StateSnapshotEvent {
  type: EventType.STATE_SNAPSHOT
  snapshot: any // Complete state object
}

스냅샷은 일반적으로 다음에 사용돼요:

상호작용 시작 시 초기 상태를 설정
연결 중단 후 동기화 보장
완전한 새로고침이 필요한 큰 상태 변화 발생 시
향후 델타 업데이트를 위한 새 기준선(baseline) 설정

프론트엔드는 STATE_SNAPSHOT 이벤트를 받으면 기존 상태 모델을 스냅샷 내용으로 완전히 대체해야 해요.

상태 델타 (State Deltas)

STATE_DELTA 이벤트는 JSON Patch 형식(RFC 6902)으로 상태에 대한 증분 업데이트를 전달해요:

interface StateDeltaEvent {
  type: EventType.STATE_DELTA
  delta: JsonPatchOperation[] // Array of JSON Patch operations
}

델타는 전체 상태가 아닌 변경된 것만 보내므로 대역폭 효율적이에요. 이 접근 방식은 특히 다음과 같은 경우에 유용합니다:

스트리밍 상호작용 중 빈번한 작은 업데이트
대부분의 속성이 변하지 않는 큰 상태 객체
전체 스냅샷으로 보내기엔 비효율적인 고빈도 업데이트

JSON Patch 형식 (JSON Patch Format)

AG-UI는 상태 델타에 JSON Patch 형식(RFC 6902)을 사용하며, 이는 JSON 문서의 변경 사항을 표현하는 표준화된 방법을 정의합니다:

interface JsonPatchOperation {
  op: "add" | "remove" | "replace" | "move" | "copy" | "test"
  path: string // JSON Pointer (RFC 6901) to the target location
  value?: any // The value to apply (for add, replace)
  from?: string // Source path (for move, copy)
}

일반적인 연산에는 다음이 있어요:

add: 객체나 배열에 값 추가

{ "op": "add", "path": "/user/preferences", "value": { "theme": "dark" } }

replace: 값 교체

{ "op": "replace", "path": "/conversation_state", "value": "paused" }

remove: 값 제거

{ "op": "remove", "path": "/temporary_data" }

move: 값을 한 위치에서 다른 위치로 이동

{ "op": "move", "path": "/completed_items", "from": "/pending_items/0" }

프론트엔드는 정확한 상태 표현을 유지하기 위해 이 패치들을 순서대로 적용해야 해요. 패치 적용 후 불일치가 감지되면 프론트엔드는 새 STATE_SNAPSHOT을 요청할 수 있어요.

AG-UI에서의 상태 처리 (State Processing in AG-UI)

AG-UI 구현에서 상태 델타는 fast-json-patch 라이브러리를 사용해 적용됩니다:

case EventType.STATE_DELTA: {
  const { delta } = event as StateDeltaEvent;

  try {
    // Apply the JSON Patch operations to the current state without mutating the original
    const result = applyPatch(state, delta, true, false);
    state = result.newDocument;
    return emitUpdate({ state });
  } catch (error: unknown) {
    console.warn(
      `Failed to apply state patch:\n` +
      `Current state: ${JSON.stringify(state, null, 2)}\n` +
      `Patch operations: ${JSON.stringify(delta, null, 2)}\n` +
      `Error: ${errorMessage}`
    );
    return emitNoUpdate();
  }
}

이 구현은 다음을 보장합니다:

패치는 원자적으로 적용됨(전부 또는 전무)
적용 과정에서 원래 상태는 변경되지 않음
오류는 포착되어 우아하게 처리됨

인간-개입 협업 (Human-in-the-Loop Collaboration)

공유 상태 시스템은 AG-UI의 인간-개입 워크플로의 기초입니다. 다음을 가능하게 해요:

실시간 가시성: 사용자가 에이전트의 사고 과정과 현재 상태를 관찰
컨텍스트 인지: 에이전트가 사용자 행동, 선호도, 애플리케이션 상태에 접근
협업적 의사 결정: 인간과 AI가 진화하는 상태에 모두 기여
피드백 루프: 인간이 상태 속성을 수정해 에이전트를 교정하거나 안내

예를 들어, 에이전트가 제안된 행동으로 상태를 업데이트할 수 있어요:

{
  "proposal": {
    "action": "send_email",
    "recipient": "[email protected]",
    "content": "Draft email content..."
  }
}

프론트엔드는 이 제안을 사용자에게 표시할 수 있고, 사용자는 실행 전에 승인·거부·수정할 수 있어요.

CopilotKit 구현 (CopilotKit Implementation)

AI 어시스턴트 구축을 위한 인기 프레임워크인 CopilotKit은 "shared state" 기능을 통해 AG-UI의 상태 관리 시스템을 활용해요. 이 구현은 에이전트(특히 LangGraph 에이전트)와 프론트엔드 애플리케이션 간 양방향 상태 동기화를 가능하게 합니다.

CopilotKit의 공유 상태 시스템은 다음을 통해 구현됩니다:

// In the frontend React application
const { state: agentState, setState: setAgentState } = useCoAgent({
  name: "agent",
  initialState: { someProperty: "initialValue" },
})

이 훅은 에이전트의 상태에 대한 실시간 연결을 만들어 다음을 가능하게 해요:

프론트엔드에서 에이전트의 현재 상태 읽기
프론트엔드에서 에이전트 상태 업데이트
에이전트 상태에 기반한 UI 컴포넌트 렌더링

백엔드에서 LangGraph 에이전트는 다음을 사용해 상태 업데이트를 발행할 수 있어요:

# In the LangGraph agent
async def tool_node(self, state: ResearchState, config: RunnableConfig):
    # Update state with new information
    tool_state = {
        "title": new_state.get("title", ""),
        "outline": new_state.get("outline", {}),
        "sections": new_state.get("sections", []),
        # Other state properties...
    }

    # Emit updated state to frontend
    await copilotkit_emit_state(config, tool_state)

    return tool_state

이 상태 업데이트는 AG-UI의 상태 스냅샷과 델타 메커니즘을 사용해 전송되어 에이전트와 프론트엔드 사이에 매끄러운 공유 컨텍스트를 만듭니다.

모범 사례 (Best Practices)

AG-UI에서 상태 관리를 구현할 때:

스냅샷을 신중히 사용: 전체 스냅샷은 기준선을 세울 필요가 있을 때만 보내기.
증분 변경에는 델타 선호: 작은 상태 업데이트는 데이터 전송을 최소화하기 위해 델타 사용.
상태를 신중히 구조화: 부분 업데이트를 지원하고 패치 복잡성을 최소화하도록 상태 객체 설계.
상태 충돌 처리: 에이전트와 프론트엔드의 충돌 업데이트를 해결하는 전략 구현.
오류 복구 포함: 불일치 감지 시 상태를 재동기화하는 메커니즘 제공.
보안 고려: 공유 상태에 민감한 정보를 저장하지 않기.

결론 (Conclusion)

AG-UI의 상태 관리 시스템은 인간과 AI 에이전트가 함께 작업하는 협업 애플리케이션 구축을 위한 강력한 기반을 제공해요. 스냅샷과 JSON Patch 델타를 통해 프론트엔드와 백엔드 간 상태를 효율적으로 동기화함으로써, AG-UI는 인간 직관과 AI 기능의 장점을 결합한 정교한 인간-개입 워크플로를 가능하게 합니다.

CopilotKit 같은 프레임워크의 구현은 이 공유 상태 접근 방식이 완전 자율 시스템이나 전통적인 사용자 인터페이스보다 더 효과적인 협업 경험을 만들 수 있음을 보여줍니다.

더 알아보기 (Learn more)

Interrupts — 인간-개입 일시중지·재개
Capabilities — 상태 관련 기능 선언 STATE_SNAPSHOT/STATE_DELTA