전송

전송 (Transports)

AG-UI를 운반하기 위해 transport가 제공해야 하는 것과 표준 바인딩 — 1.0 버전을 설명드릴게요.

출처: 문서

본문

프로토콜 의미론은 모든 transport에서 동일해요. transport는 바인딩(binding) 입니다: run input이 어떻게 전달되는지, 이벤트가 어떻게 프레이밍·인코딩되는지, 스트림이 어떻게 종료되거나 실패하는지를 정의해요. 이벤트가 무엇을 뜻하는지는 정의하지 않아요 — 이벤트 패턴과 처리 모델은 모든 바인딩에서 동일합니다.

바인딩 계약 (The binding contract)

바인딩은 다음을 반드시 제공해야 해요(MUST):

  • 순서 있고 완전한 전달 — 실행의 이벤트를 프로듀서가 발행한 순서대로. 프로토콜의 순서는 도착 순서입니다; 이벤트를 재정렬하거나 드롭할 수 있는 transport는 둘 다 복원하는 계층 없이는 AG-UI를 운반할 수 없어요.
  • 교환을 여는 RunAgentInput의 전달 — 어떤 이벤트보다 먼저. 계속해서 추가 실행 — 재생된 스레드 — 을 운반하는 스트림은 그것들을 위해 추가 입력을 전달하지 않아요: 그 실행들은 프로듀서가 역사를 다시 진술하는 것이며, 각 RUN_STARTED는 자신의 input 에코를 담을 수 있어요(MAY).
  • 소비자가 절단(truncation)과 구분할 수 있는 종료 신호 — 종료 이벤트 뒤에 깔끔하게 끝나는 스트림은 닫힌 실행이고, 종료 이벤트 없이 죽는 연결은 절단된 실행입니다.
  • 거부된 입력을 위한 오류 경로 — 구조적으로 유효하지 않은 RunAgentInput은 RUN_STARTED 전에, 스트림 밖에서 거부돼요.

인증과 권한 부여는 프로토콜이 아니라 바인딩과 애플리케이션의 속성입니다: AG-UI는 자격 증명을 정의하지 않으며, 바인딩은 채널이 사용하는 것을 담아요(HTTP 인증, 주변 프로세스 신원, 또는 아무것도).

표준 바인딩 (Standard bindings)

  1. HTTP + Server-Sent Events: run input은 HTTP POST입니다; 이벤트는 JSON을 담는 SSE 프레임으로 다시 스트리밍돼요.
  2. HTTP + Protobuf: 동일한 POST가 길이 프리픽스 protobuf 프레임의 이진 응답으로 협상됩니다.

두 바인딩 모두 요청 절반을 공유해요; 콘텐츠 협상으로 선택되는 응답 인코딩에서만 다릅니다. HTTP를 말하는 구현은 SSE 바인딩을 반드시 지원해야 하며(MUST); protobuf 바인딩은 선택(OPTIONAL)입니다.

절단 (Truncation)

종료 이벤트 없이 스트림이 끝나는 소비자는 절단된 실행을 갖게 돼요: 프로듀서는 계속 갔을지 몰라도, 이 소비자는 나머지를 결코 볼 수 없을 거예요. 절단된 실행에는 결과(outcome)가 없어요. 소비자는 그것을 위해 RUN_FINISHED를 합성해선 안 되고(MUST NOT), 성공했다고 보고해선 안 돼요(MUST NOT); 실행이 끊김 전에 전달한 모든 것은 전달된 채 남아요. 그 너머로 절단을 어떻게 표면화할지 — 실행을 미해결로 두거나, 합성 실패를 일으키거나 — 는 소비자의 몫입니다; 재실행은 새 runId를 가진 새 실행이에요.

커스텀 전송 (Custom transports)

구현은 다른 채널 — WebSockets, 메시지 버스, 프로세스 내 파이프 — 위에 AG-UI를 운반할 수 있어요(MAY). 커스텀 transport는 이벤트 모델, 이벤트 패턴, 처리 규칙을 보존해야 하고, 위의 바인딩 계약을 충족해야 해요. 상호운용성을 돕기 위해 프레이밍, 입력 전달, 종료·오류 신호를 문서화해야 해요(SHOULD).

JSON을 운반하는 커스텀 transport는 새 봉투를 지어내기보다 SSE 바인딩과 정확히 이벤트를 프레이밍해야 해요(SHOULD) — 프레임당 하나의 이벤트 객체로: SSE 바인딩의 프레이밍이 프로토콜의 JSON 프레이밍이며, HTTP 메커니즘만 HTTP에 특정적이에요.

더 알아보기 (Learn more)