스펙

스펙 (Specification)

AG-UI 프로토콜 1.0의 공식 행동 스펙이에요. 에이전트가 사용자 대면 애플리케이션과 어떻게 대화하는지 표준화하는 개방형 프로토콜의 권위 있는 요구사항을 정의해요.

출처: 문서

본문

AG-UI는 에이전트가 사용자 대면 애플리케이션과 말하는 방식을 표준화하는 개방형 프로토콜이에요: 요청 하나가 들어오면, 사용자가 에이전트에서 보는 모든 것 — 텍스트, 도구 호출, 추론, 공유 상태, 진행 — 을 담은 정렬된 타입 이벤트 스트림 하나가 나갑니다.

이 스펙은 schema.json의 JSON Schema에 기반해 권위 있는 프로토콜 요구사항을 정의하며, Schema Reference로 읽기 쉽게 렌더링됩니다.

구현 가이드, 개념, 예시는 documentation을 참고하세요.

이 문서의 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", "OPTIONAL" 키워드는 BCP 14[RFC2119][RFC8174]에 설명된 대로, 여기에 보이는 것처럼 전부 대문자일 때에만 해석됩니다.

이 문서가 무엇인가

JSON Schema는 이벤트가 어떻게 생겼는지 말해 줘요. 하지만 이벤트가 어떤 순서로 도착할 수 있는지, 구현이 인식하지 못하는 무엇으로 무엇을 하는지, 언제 경고를 내보내야 하는지는 말할 수 없어요. 그 규칙들이 바로 프로토콜이고, 이 문서가 그것들을 명시합니다.

권한 분할은 의도적이고 절대적이에요.

schema은 구조에 대해 권위가 있어요. 어떤 필드가 존재하는지, 무엇이 필수인지, 각각이 어떤 타입을 담는지, 판별자가 어떤 값을 가질 수 있는지. 이 문서가 필드를 언급할 때는 규칙에 의미를 주기 위해서지, 필드의 형태를 다시 말하기 위해서가 아니에요. 둘이 구조에 대해 다르면, 스키마가 이기고 이 문서에 버그가 있는 겁니다.
이 문서는 행동에 대해 권위가 있어요. 순서, 라이프사이클, 귀속, 오류 처리, 호환성. 스키마는 그 어느 것도 표현할 수 없어요. 구현이 여기 규칙과 다르면, 구현에 버그가 있는 겁니다.

역할 (Roles)

모든 규칙은 누구를 묶는지 이름을 붙여요. 두 역할이 의무를 집니다.

프로듀서(producer) 는 이벤트 스트림을 내보내는 무엇이든이에요 — 에이전트, 프록시, 브리지, 테스트 더블.
컨슈머(consumer) 는 그것을 읽는 무엇이든이에요 — 클라이언트 SDK, UI, 레코더, 다른 프록시.

둘 다 하는 참여자는 두 규칙 집합에 각각 방향별로 묶여요.

적합성 (Conformance)

구현은 그것이 맡는 역할에 적용되는 모든 MUST와 MUST NOT을 만족할 때 적합해요. SHOULD 수준 규칙은 좋은 구현이 하는 일을 서술해요; 그것에서 벗어나는 것은 위반이 아니라 이유가 필요한 결정이에요.

적합성은 스트림별로 판정돼요. 형식이 잘못된 실행을 하나 내보내는 프로듀서는, 다른 실행에서 무엇을 하든 적합하지 않아요.

개요 (Overview)

프로토콜은 모든 구현이 말하는 기반(base)과, 프로듀서가 말할 것이 있을 때 내보내는 기능들로 분해돼요:

이벤트 모델 — 봉투(envelope), 일반 필드, 식별자.
실행 입력 (Run input) — 애플리케이션에서 에이전트로 오는 유일한 메시지.
메타데이터 (Metadata) — 모든 것 위의 열린 채널, 그리고 그것이 병합되는 방식.
이벤트 패턴 (Event patterns) — 스트리밍, 스냅샷–델타, 인터럽트–재개.
전송 (Transports) — HTTP + SSE, HTTP + Protobuf, 그리고 커스텀 바인딩이 충족해야 할 계약.
처리 모델 (Processing model) — 강제(enforcement) 앞의 미들웨어; 인식되지 않은 자료는 살아남고, 형식이 잘못된 알려진 값은 치명적.
버전 관리와 호환성 (Versioning and compatibility) — 더 오래되고 더 새로운 피어와 대화하기, 그리고 콘텐츠 손실이 무엇을 의무화하는지.
이벤트 스트림 (Event streams) — 여덟 개의 이벤트 패밀리.

보안과 신뢰·안전 (Security and Trust & Safety)

AG-UI는 모델 출력을 애플리케이션이 하는 일로 바꿔요: 도구 호출은 행동이 되고, 상태 이벤트는 쓰기가 되며, 스트리밍된 콘텐츠는 사용자가 읽는 것이 됩니다. 그것과 함께, 프로토콜이 와이어 레벨에서 강제할 수 없지만 구현자가 다뤄야 할 의무가 따라옵니다.

핵심 원칙

사용자 동의와 통제. 애플리케이션이 무엇을 실행할지 결정해요. 부작용이 있는 도구 호출을 실행하기 전에 명시적 사용자 동의를 얻어야 하고(SHOULD), 승인되지 않은 행동을 사용자가 승인한 것으로 표현해서는 안 됩니다(MUST NOT).
모델 출력은 신뢰할 수 없는 입력이다. 도구 인자, 도구 결과, 상태 콘텐츠와 passthrough 페이로드는 신뢰 경계를 건너요. 애플리케이션은 행동할 것을 검증해야 하고(MUST), 스트리밍된 콘텐츠를 실행 가능한 마크업으로 렌더링해서는 안 됩니다(MUST NOT).
데이터는 양방향으로 흘러요. 상태와 메시지는 모든 실행에서 컨슈머를 왕복하고 돌아옵니다. 프로듀서는 그것들에 비밀을 넣지 말아야 하고(SHOULD NOT), 컨슈머는 추론과 암호화된 산출물을 대화와 동등한 기밀성으로 취급해야 해요(SHOULD).

구현 지침

프로토콜 자체는 이 원칙들을 강제할 수 없어요. 구현자는 중요한 행동에 대한 동의 흐름을 만들고, 모든 신뢰 경계에서 스키마와 의미론을 검증하고, 렌더링을 실행과 분리하고, 에이전트가 사용자 대신 무엇을 했는지 감사할 만큼 로그를 남겨야 해요(SHOULD).

범위 (Scope)

이 문서는 프로토콜을 명시해요: 이벤트 스트림, 실행 입력, 그것들을 교환하는 당사자들의 의무. 특정 통합이 이벤트를 받은 후 그것으로 무엇을 하는지, 에이전트 프레임워크가 어떻게 구조화되어야 하는지, UI가 무엇을 어떻게 렌더링해야 하는지는 명시하지 않아요.

AG-UI는 3개의 일급 SDK — TypeScript, Python, .NET — 로 유지되며, 여기 있는 모든 규칙은 그것들 모두에 동등하게 적용됩니다. 다른 언어 바인딩은 커뮤니티 관리이고, 적합성을 주장할 때 이 문서에 묶이지만, 여기에 있는 어떤 것도 그것들에서 파생되지 않아요.

Learn More

Architecture — 구성 요소, 실행, 설계 원칙.
Base Protocol — 이벤트 모델, 실행 입력, 패턴, 전송, 처리, 버전 관리.
Event Streams — 여덟 개의 이벤트 패밀리와 그 규칙.
Key Changes — 1.0이 0.x 계열에 비해 바꾸는 것.

더 알아보기 (Learn more)

스펙 1.0 개요 — 이벤트 모델과 실행 입력 같은 기본 구조를 확인해 보세요.
이벤트 스트림 — 프로토콜의 여덟 이벤트 패밀리를 살펴보세요.
Key Changes — 1.0에서 바뀐 내용을 확인해 보세요.