스펙들 3
탐색 1.0.1 문서
버전
문서 변경 이력
섹션 20
현재 페이지 5
1.0.1 ko public

스펙

RAWP-DPS

Data processing specification for RAWP integrations.

변경 이력 전체 Markdown 목차 Markdown

2. Envelope 구조 (Frame Envelope)

2.1. 공통 Envelope

송수신되는 모든 WSS 프레임은 다음 JSON 구조를 준수해야 한다 (MUST).

{
  "v": 1,
  "type": "String (필수, 네임스페이스 기반 이벤트 타입)",
  "message_id": "String (필수, UUID v4)",
  "timestamp": "String (필수, ISO 8601, 밀리초 정밀도 권장)",
  "session_id": "String (필수, 소속 세션 식별자)",
  "turn_id": "String (선택, 현재 Turn 식별자, UUID v4)",
  "parent_id": "String (선택, 이 메시지가 응답하는 대상 message_id)",
  "metadata": {},
  "payload": {}
}

필드 상세

필드 필수 설명
v MUST Envelope 버전. 본 규격에서는 항상 정수 1. 수신자는 자신이 지원하지 않는 v 값을 수신하면 해당 프레임을 무시하고 session.error로 응답해야 한다 (MUST).
type MUST 네임스페이스 기반 이벤트 타입. §3에서 정의.
message_id MUST 프레임 고유 식별자. 중복 수신 시 멱등성(Idempotency) 판단 기준.
timestamp MUST 발신 시각. ISO 8601. 밀리초 정밀도 권장 (SHOULD).
session_id MUST Agent Session 식별자 (UUID v4). RAWP 1.0.2 §5.1에서 발급. WSS Connection이 아닌 Agent Session을 식별한다.
turn_id SHOULD 현재 에이전트 Turn의 식별자. 동일 Turn 내 모든 프레임은 같은 turn_id를 공유.
parent_id OPTIONAL 요청-응답 상관 관계. agent.prompt.request에 대한 agent.prompt.delta는 해당 요청의 message_id를 parent_id로 참조.
metadata OPTIONAL 확장 및 디버깅용 자유 형식 객체. 빈 객체 {} 허용.
payload MUST 이벤트 타입별 페이로드. §3에서 각 타입별로 정의.

2.2. 파싱 규약

  • Postel's Law: 수신자는 payload 내 알 수 없는 키를 무시해야 한다 (MUST).
  • Unknown Type: 수신자는 자신이 처리할 수 없는 type을 수신하면 해당 프레임을 무시하고, 로그에 기록해야 한다 (MUST). 에러를 발생시키거나 연결을 종료해서는 안 된다 (MUST NOT).
  • Envelope 버전: v 필드가 지원 범위를 벗어나면 프레임을 무시하고 session.error를 발송해야 한다 (MUST).

2.3. 프레임 순서 보장

WSS는 메시지 순서를 보장하므로, 동일 연결 내 프레임은 발신 순서대로 수신됨을 전제한다. 단, 재연결(reattach) 후 session.history 프레임을 통해 과거 이력이 재전송될 때는 timestamp와 message_id 기준으로 순서를 재구성해야 한다 (MUST).

2.4. 다중 마스터 환경 (Multi-Master Fan-out)

클라이언트가 복수의 마스터 서버에 동시 등록된 환경(RAWP 1.0.2 §3 참조)에서의 DPS 프레임 분배 규칙을 정의한다.

브로드캐스트 원칙: 클라이언트는 하나의 Agent Session에서 발생하는 모든 DPS 프레임을 해당 세션에 연결된 모든 WSS Connection으로 브로드캐스트해야 한다 (MUST). 여기에는 세션을 생성한 마스터의 WSS뿐 아니라, 다른 마스터가 동일 세션에 연결한 WSS도 포함된다.

  • 에이전트 출력 프레임(agent.*, tool.*, session.*)은 해당 세션에 바인딩된 모든 WSS Connection에 전송해야 한다 (MUST).
  • 마스터가 발송한 control.* 프레임(예: control.prompt.request)도 해당 세션에 바인딩된 다른 모든 WSS Connection에 중계해야 한다 (MUST). 이를 통해 마스터 A가 전송한 프롬프트를 마스터 B도 수신하여 사용자에게 표시할 수 있다.
  • 로컬 UI WSS Connection(RAWP 1.0.2 §10.6)도 브로드캐스트 대상에 포함된다 (MUST).
  • 로컬 세션(RAWP 1.0.2 §10, origin: "local")의 DPS 프레임은 마스터에 전송하지 않는다 (MUST NOT). 로컬 UI WSS에만 전달한다.
  • control.* 프레임의 중계 시 message_id 기반 멱등성 처리를 수행하여 발신자에게 자신의 프레임이 되돌아오는 것을 방지해야 한다 (MUST). 즉, 프레임을 발송한 WSS Connection에는 해당 프레임을 재전송하지 않는다.

참조