HTTP + Protobuf 전송

이진 바인딩에 대해 설명해 드릴게요 — 같은 POST 요청, 길이 프리픽스가 붙은 protobuf 프레임 스트림이 응답으로 돌아옵니다 — 1.0 기준이에요. 컴팩트한 와이어를 원하는 컨슈머를 위한 이진 바인딩이에요.

출처: 문서

본문

이진 바인딩은 컴팩트한 와이어를 원하는 컨슈머를 위한 것이에요. SSE 바인딩의 요청 절반을 완전히 공유해요 — 실행 입력은 같은 JSON POST예요 — 응답에서만 다릅니다.

협상 (Negotiation)

이 바인딩을 원하는 클라이언트는 Accept 헤더에 text/event-stream과 함께 application/vnd.ag-ui.event+proto를 포함합니다. 허용(admission)이 옵트인하는 것입니다 — 와일드카드 범위(*/*, application/*)도 미디어 타입을 허용해요 — 그래서 protobuf를 소비할 수 없는 클라이언트는 와일드카드나 다운랭크된 항목 대신, 자기가 할 수 있는 것을 이름 붙이는 명시적 Accept를 보내야 합니다(MUST): 두 미디어 타입 사이의 상대 품질 값은 참고되지 않아요.
바인딩을 지원하는 프로듀서는 클라이언트의 Accept가 양수 품질로 미디어 타입을 허용할 때마다 그것으로 답해야 하고(SHOULD), 그렇지 않으면 SSE로 답해야 합니다(MUST). 그것을 지원하지 않는 프로듀서는 미디어 타입을 무시해요 — 그래서 클라이언트는 항상 SSE를 받을 준비가 되어 있어야 하는 이유입니다.
응답의 Content-Type은 정확히 application/vnd.ag-ui.event+proto예요; 컨슈머는 이 헤더로 자기 파서를 선택합니다.

프레이밍 (Framing)

응답 본문은 프레임의 시퀀스이고, 각각 하나의 프로토콜 이벤트예요:

프레임은 4바이트 길이 헤더 — 부호 없는 32비트 빅엔디언 정수 — 뒤에 정확히 그만큼의 바이트의 인코딩된 이벤트 하나입니다.
프레임은 구분자 없이 붙어 있어요. 컨슈머는 전송 청크에 걸쳐 쪼개진 프레임과 한 청크 안의 여러 프레임을 견뎌야 해요(MUST).
프레임 중간에서 끝나는 본문은 truncated run이에요.

와이어 스키마

protobuf 메시지 정의는 SDK들이 생성되는 같은 JSON Schema에서 생성됩니다; 와이어 스키마는 두 번째 진실 원천이 아니에요. 구현 간 패리티는 적합성 표면의 일부예요: 정규 이벤트 코퍼스(corpus)가 인코딩된 바이트를 고정하고, 모든 일급 인코더는 코퍼스를 바이트 단위로 재현해야 해요(MUST). (코퍼스가 보장입니다 — 같은 의미 값을 받은 두 인코더는 여전히 열린 JSON 객체의 항목을 다르게 정렬할 수 있고, protobuf 맵 인코딩이 그것을 보이게 만들어요.)

의미론은 이진 와이어가 허용하는 만큼 SSE 바인딩에 가깝게 유지돼요:

프레임에서 디코딩된 이벤트는 SSE에서 파싱된 이벤트와 같은 처리 파이프라인에 들어갑니다 — 미들웨어가 먼저, 강제가 그다음, 동일하게.
와이어 스키마가 열린 페이로드로 담는 자료 — RUN_FINISHED.outcome, 메타데이터, 상태, rawEvent — 은 디코딩에서 살아남아 그 파이프라인에 닿아요: 이 바인딩으로 도착한 인식되지 않은 outcome은 SSE에서처럼 강제가 경고와 함께 떼어내고, 바인딩은 디코드 시점에 그것을 거부해서는 안 됩니다(MUST NOT).
이진 와이어는 나머지에 대해 본질적으로 더 좁아요. 이 빌드의 와이어 스키마보다 앞선 필드는 protobuf 디코딩 자체가 조용히 건너뜁니다 — 경고와 함께 떼어내는 행동은 오직 JSON 와이어에서만 완전히 관찰 가능해요. 같은 좁아짐이 와이어 스키마가 모델링하지 않는 프로토콜 법적 열린 멤버를 덮어요: JSON 와이어가 보존해야 하는 JSON Patch 연산의 확장 멤버는 이 와이어에서는 살아남지 못합니다. 이 빌드가 앞서는 봉투 가지를 가진 이벤트는 넘겨줄 타입 문자열이 없으므로, 바인딩은 경고와 함께 프레임을 버립니다 — 강제가 주는 같은 답을 전송에서 철자한 것이에요.
바이트가 메시지로 디코딩되지 않는 프레임은 형식이 잘못된 전송 자료이며 스트림에 치명적이에요. 프레임 중간에서 그냥 끝나는 본문은 그렇지 않아요: 그것은 truncated run이에요.

오류

SSE 바인딩과 동일해요: 스트림 전의 거부는 HTTP 오류 상태이고, 스트림 안의 실패는 다른 프레임처럼 프레임 하나인 RUN_ERROR예요.

더 알아보기 (Learn more)

스펙 개요 — AG-UI 1.0 프로토콜의 공식 요구사항을 확인해 보세요.
전송 (Transports) — 전송 바인딩 전반과 계약 규칙을 살펴보세요.
처리 모델 (Processing) — 이진 디코딩된 이벤트가 어떤 파이프라인을 거치는지 확인해 보세요.