핵심 아키텍처

핵심 아키텍처 (Core architecture)

AG-UI(Agent User Interaction Protocol)가 프런트엔드 애플리케이션과 AI 에이전트를 어떻게 연결하는지 이해하는 데 도움이 되는 핵심 아키텍처 문서예요. 이벤트 기반으로 설계된 유연한 구조가 어떤 구성 요소로 이뤄져 있는지 함께 살펴볼게요.

출처: 문서

본문

AG-UI(Agent User Interaction Protocol)는 유연하고 이벤트 주도적인 아키텍처 위에 구축되어, 프런트엔드 애플리케이션과 AI 에이전트 사이에 원활하고 효율적인 통신을 가능하게 해요. 이 문서는 핵심 아키텍처 구성 요소와 개념을 다룹니다.

설계 원칙 (Design Principles)

AG-UI는 가볍고 최소한의 의견만 담도록 설계되어, 다양한 에이전트 구현과 쉽게 통합할 수 있어요. 프로토콜의 유연성은 단순한 요구 사항에서 비롯됩니다:

1. 이벤트 주도 통신 (Event-Driven Communication): 에이전트는 실행 중에 16가지 표준 이벤트 타입 중 어느 것이든 내보낼 수 있어서, 클라이언트가 처리할 수 있는 업데이트 스트림을 만들어요.

2. 양방향 상호작용 (Bidirectional Interaction): 에이전트는 사용자로부터 입력을 받아들여, 인간과 AI가 원활하게 협력하는 워크플로를 가능하게 해요.

프로토콜에는 호환성을 최대화하는 두 가지 핵심 방식의 내장 미들웨어 레이어가 있습니다:

• 유연한 이벤트 구조 (Flexible Event Structure): 이벤트가 AG-UI 형식과 정확히 일치할 필요는 없어요 — AG-UI와 호환만 되면 됩니다. 덕분에 기존 에이전트 프레임워크가 자기 네이티브 이벤트 형식을 최소한의 노력으로 적응시킬 수 있어요.

• 전송 수단 비종속 (Transport Agnostic): AG-UI는 이벤트를 어떻게 전달할지 강제하지 않습니다. Server-Sent Events(SSE), 웹훅, WebSockets 등 다양한 전송 메커니즘을 지원해요. 이 유연성 덕분에 개발자는 자신의 아키텍처에 가장 잘 맞는 전송 수단을 고를 수 있어요.

이런 실용적인 접근 방식 덕분에 AG-UI는 기존 에이전트 구현이나 프런트엔드 애플리케이션을 크게 바꾸지 않고도 쉽게 채택할 수 있습니다.

아키텍처 개요 (Architectural Overview)

AG-UI는 에이전트와 애플리케이션 간의 통신을 표준화하는 클라이언트-서버 아키텍처를 따릅니다:

flowchart LR
    subgraph "Frontend"
        App["Application"]
        Client["AG-UI Client"]
    end

    subgraph "Backend"
        A1["AI Agent A"]
        P["Secure Proxy"]
        A2["AI Agent B"]
        A3["AI Agent C"]
    end

    App <--> Client
    Client <-->|"AG-UI Protocol"| A1
    Client <-->|"AG-UI Protocol"| P
    P <-->|"AG-UI Protocol"| A2
    P <-->|"AG-UI Protocol"| A3

    class P mintStyle;
    classDef mintStyle fill:#E0F7E9,stroke:#66BB6A,stroke-width:2px,color:#000000;

    style App rx:5, ry:5;
    style Client rx:5, ry:5;
    style A1 rx:5, ry:5;
    style P rx:5, ry:5;
    style A2 rx:5, ry:5;
    style A3 rx:5, ry:5;

• 애플리케이션 (Application): 사용자 대면 앱 — 예를 들어 채팅이나 어떤 AI 지원 애플리케이션이라면 해당돼요.
• AG-UI 클라이언트 (AG-UI Client): HttpAgent 같은 범용 통신 클라이언트나 기존 프로토콜에 연결하는 특화된 클라이언트예요.
• 에이전트 (Agents): 요청을 처리하고 스트리밍 응답을 생성하는 백엔드 AI 에이전트예요.
• 보안 프록시 (Secure Proxy): 추가 기능을 제공하고 보안 프록시 역할을 하는 백엔드 서비스예요.

핵심 구성 요소 (Core components)

프로토콜 레이어 (Protocol layer)

AG-UI의 프로토콜 레이어는 에이전트 통신을 위한 유연한 기반을 제공해요.

• 범용 호환성 (Universal compatibility): run(input: RunAgentInput) -> Observable<BaseEvent>을 구현하면 어떤 프로토콜에도 연결할 수 있어요.

프로토콜의 핵심 추상화는 애플리케이션이 에이전트를 실행하고 이벤트 스트림을 받을 수 있게 해 줍니다:

// Core agent execution interface
type RunAgent = () => Observable<BaseEvent>

class MyAgent extends AbstractAgent {
  run(input: RunAgentInput): RunAgent {
    const { threadId, runId } = input
    return () =>
      from([
        { type: EventType.RUN_STARTED, threadId, runId },
        {
          type: EventType.MESSAGES_SNAPSHOT,
          messages: [
            { id: "msg_1", role: "assistant", content: "Hello, world!" }
          ],
        },
        { type: EventType.RUN_FINISHED, threadId, runId },
      ])
  }
}

표준 HTTP 클라이언트 (Standard HTTP client)

AG-UI는 RunAgentInput 타입의 본문을 받는 POST 요청을 수용하고 BaseEvent 객체 스트림을 보내는 모든 엔드포인트에 연결할 수 있는 표준 HTTP 클라이언트 HttpAgent를 제공해요.

HttpAgent는 다음 전송 수단을 지원합니다:

• HTTP SSE (Server-Sent Events)

  • 넓은 호환성을 위한 텍스트 기반 스트리밍
  • 읽고 디버깅하기 쉬움

• HTTP 바이너리 프로토콜 (HTTP binary protocol)

  • 성능이 높고 공간 효율적인 커스텀 전송
  • 프로덕션 환경을 위한 견고한 바이너리 직렬화

메시지 타입 (Message types)

AG-UI는 에이전트 통신의 다양한 측면을 위한 여러 이벤트 범주를 정의합니다:

• 수명주기 이벤트 (Lifecycle events)

  • RUN_STARTED, RUN_FINISHED, RUN_ERROR
  • STEP_STARTED, STEP_FINISHED

• 텍스트 메시지 이벤트 (Text message events)

  • TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END

• 도구 호출 이벤트 (Tool call events)

  • TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END

• 상태 관리 이벤트 (State management events)

  • STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT

• 특수 이벤트 (Special events)

  • RAW, CUSTOM

에이전트 실행 (Running Agents)

에이전트를 실행하려면 클라이언트 인스턴스를 만들고 실행하면 돼요:

// Create an HTTP agent client
const agent = new HttpAgent({
  url: "https://your-agent-endpoint.com/agent",
  agentId: "unique-agent-id",
  threadId: "conversation-thread"
});

// Start the agent and handle events
agent.runAgent({
  tools: [...],
  context: [...]
}).subscribe({
  next: (event) => {
    // Handle different event types
    switch(event.type) {
      case EventType.TEXT_MESSAGE_CONTENT:
        // Update UI with new content
        break;
      // Handle other event types
    }
  },
  error: (error) => console.error("Agent error:", error),
  complete: () => console.log("Agent run complete")
});

상태 관리 (State Management)

AG-UI는 특화된 이벤트를 통해 효율적인 상태 관리를 제공해요:

• STATE_SNAPSHOT: 특정 시점의 완전한 상태 표현
• STATE_DELTA: JSON Patch 형식(RFC 6902)을 사용한 증분 상태 변경
• MESSAGES_SNAPSHOT: 완전한 대화 내역

이 이벤트들은 최소한의 데이터 전송으로 클라이언트 측 효율적인 상태 관리를 가능하게 해 줍니다.

도구와 핸드오프 (Tools and Handoff)

AG-UI는 표준화된 이벤트를 통해 에이전트 간 핸드오프와 도구 사용을 지원해요:

• 도구 정의는 runAgent 파라미터로 전달됩니다
• 도구 호출은 TOOL_CALL_START → TOOL_CALL_ARGS → TOOL_CALL_END 이벤트 시퀀스로 스트리밍됩니다
• 에이전트는 다른 에이전트에게 핸드오프할 수 있고, 컨텍스트 연속성을 유지해요

이벤트 (Events)

AG-UI의 모든 통신은 타입이 지정된 이벤트에 기반해요. 모든 이벤트는 BaseEvent를 상속합니다:

interface BaseEvent {
  type: EventType
  timestamp?: number
  rawEvent?: any
}

이벤트는 엄격하게 타입이 지정되고 검증되어, 구성 요소 간의 안정적인 통신을 보장합니다.

더 알아보기 (Learn more)

• 아키텍처 (1.0 스펙) — 스펙 버전의 아키텍처 정의
• Generative UI — AG-UI와 생성형 UI 스펙의 관계
• 이벤트 — 여덟 가지 이벤트 패밀리