아키텍처

아키텍처 (1.0) (Architecture)

1.0 스펙의 아키텍처를 다루는 페이지예요. 구성 요소, 상호작용의 단위로서의 실행(run), 그리고 그 배후의 원칙을 설명합니다. 에이전트가 사용자 대면 애플리케이션과 통신하는 통로는 타입이 지정된 이벤트의 순서 있는 스트림 하나뿐이라는 점이 핵심이에요.

출처: 문서

본문

AG-UI는 에이전트를 사용자 대면 애플리케이션에 한 가지 통로로 연결합니다: 단일 요청에 응답하는, 타입이 지정된 이벤트의 순서 있는 스트림이죠. 사용자가 에이전트에서 보는 모든 것 — 텍스트, 도구 호출, 추론(reasoning), 상태, 진행 — 은 스트림 안에 있습니다. 사이드 채널은 없어요.

핵심 구성 요소 (Core Components)

graph LR
    subgraph "Application"
        UI[User Interface]
        C[AG-UI Client<br/>middleware · enforcement · verification]
        UI --- C
    end
    subgraph "Agent side"
        E[Agent Endpoint]
        B[Framework Bridge]
        A[Agent / LLM framework]
        E --- B
        B --- A
    end
    C -- "RunAgentInput" --> E
    E -- "event stream" --> C

애플리케이션 (The application)

사용자를 소유합니다. 스트림을 렌더링하고, 광고한 도구 호출을 실행하며, 에이전트가 공유하는 상태를 유지하고, 무엇이 사용자의 동의를 요구하는지 결정합니다.

클라이언트 (The client)

소비자의 프로토콜 기계장치로, 보통 SDK입니다. 실행 입력을 보내고, 돌아오는 것에 처리 파이프라인을 돌립니다 — 호환성 번역, 미들웨어, enforcement, 청크 확장, 검증 — 그리고 애플리케이션에 신뢰할 수 있는 스트림을 건네줍니다.

에이전트 엔드포인트와 그 브리지 (The agent endpoint and its bridge)

생산자입니다. 브리지는 프레임워크의 네이티브 이벤트를 프로토콜 이벤트로 번역합니다. 엔드포인트는 전송 바인딩을 말합니다. 프로토콜은 프레임워크 개념을 담지 않으므로, 한 클라이언트가 어떤 프레임워크든 마주할 수 있습니다.

미들웨어 (Middleware)

어느 쪽이든 클라이언트 파이프라인에 설치하는 코드입니다. 그것은 enforcement가 아무것도 떼어내기 전에 모든 이벤트를 봅니다. 그래서 호환성 시미(shim)는 폐기된 형태를 번역할 수 있고, 확장은 현재 버전이 정의하지 않는 자료에 작용할 수 있습니다.

실행 (The run)

상호작용의 단위입니다. 소비자는 하나의 RunAgentInput으로 교환을 엽니다. 생산자는 실행 수명주기로 괄호로 묶인 이벤트로 응답합니다 — 요청된 실행이, 어쩌면 재생된 내역이 앞에 오죠. 대화는 그러한 실행들의 스레드이며, 메시지와 상태를 쌓아갑니다.

sequenceDiagram
    participant Application
    participant Agent

    Application->>Agent: RunAgentInput (threadId, runId, messages, tools, state)
    Agent->>Application: RUN_STARTED
    Agent->>Application: … messages, tool calls, state, activity …
    Agent->>Application: RUN_FINISHED (outcome, usage)
    Note over Application: renders, executes, stores
    Application->>Agent: next RunAgentInput (same threadId)

설계 원칙 (Design Principles)

  1. 에이전트를 노출하기가 매우 쉬워야 한다. 브리지는 구현이 아니라 번역입니다. 프레임워크가 내보내는 것은 무엇이든 작은 이벤트 패밀리 집합에 매핑되고, 모든 선택사항은 선택입니다. 필수 표면은 실행 수명주기뿐이고 그 외는 없어요.

  2. 관찰 가능한 모든 것이 교환 안에 있다. 에이전트의 가시적 행동 중 어떤 것도 대역 밖으로 나가지 않습니다. 교환 — 각 실행 입력과 그에 응답한 이벤트 — 을 보관하는 레코더는 UI가 매 순간 알았던 것을 재구성합니다. 이것이 프로토콜을 테스트 가능하고, 재생 가능하며, 전송 비종속적으로 만드는 이유입니다.

  3. 관대한 읽기, 엄격한 쓰기. 생산자는 스키마가 정의하는 것만 내보내야 합니다. 소비자는 인식하지 못하는 것을 견뎌야 하며, 실패 대신 경고와 함께 떼어냅니다. 완전한 비대칭성 — 그리고 잘못된 알려진 값이 왜 반대로 취급되는지 — 는 처리 모델입니다.

  4. 미들웨어는 enforcement보다 먼저 실행된다. 아무것도 떼어내기 전에 번역이 기회를 얻으므로, 프로토콜은 어느 쪽도 버려두지 않고 진화할 수 있습니다. 어제의 형태는 경계에서 번역되고, 내일의 것은 그것을 아는 누구에게나 통과합니다.

  5. 전송은 바인딩이다. 의미론은 결코 유선에 따라 달라지지 않습니다. SSE 텍스트로 묶든 protobuf 프레임으로 묶든 같은 이벤트, 같은 규칙 — 공유 바이트 코퍼스로 크로스 구현 패리티가 고정됩니다.

더 알아보기 (Learn more)