HTTP + Server-Sent Events

HTTP + Server-Sent Events (1.0) (HTTP + Server-Sent Events)

기본 바인딩을 다루는 페이지예요. 실행 입력을 담는 POST와 실행을 담는 text/event-stream. 애플리케이션이 실행 입력을 에이전트 엔드포인트로 POST하면, 응답은 실행을 운반하는 Server-Sent Events 스트림입니다.

출처: 문서

본문

기본 바인딩입니다. 애플리케이션이 실행 입력을 에이전트 엔드포인트로 POST합니다. 응답은 실행을 운반하는 Server-Sent Events 스트림입니다.

요청 (Request)

  • 클라이언트는 에이전트 엔드포인트로 POST를 보냅니다. 본문은 UTF-8로 인코딩된 단일 JSON 객체인 RunAgentInput이며, Content-Type: application/json입니다.
  • 클라이언트는 Accept: text/event-stream을 보냅니다(그 바인딩도 소비할 수 있을 때 protobuf 미디어 타입을 추가하면서).

응답 (Response)

  • 시작하는 실행은 Content-Type: text/event-stream과 함께 200으로 응답합니다.
  • 각 SSE 이벤트의 data 페이로드는 JSON 객체인 정확히 하나의 프로토콜 이벤트입니다 — 결코 둘 이상도, 조각도 아닙니다. 여러 줄의 data: 필드는 SSE가 지정하는 대로 이어집니다.
  • 생산자는 스트림을 LF(\n) 줄바꿈으로 프레임해야 합니다(MUST). SSE 문법은 CR과 CRLF도 허용하지만, 이 바인딩은 모든 소비자가 파싱한다고 알려진 한 형태로 고정합니다. 소비자는 추가로 전체 문법을 받아들일 수 있습니다(MAY).
  • 소비자는 data 외의 SSE 필드(event:, id:, retry:)를 무시해야 하며(MUST) SSE 주석 줄(: keep-alive)을 용인해야 합니다(MUST), 생산자는 어떤 박자로든 보낼 수 있습니다(MAY).
  • 생산자는 마지막 실행의 종료 이벤트 후에 응답 본문을 닫습니다. 하나의 POST는 하나의 요청을 담습니다. 그럼에도 응답은 생산자가 요청된 실행 앞에 스레드 내역을 재생할 때 여러 실행을 담을 수 있습니다(MAY) — 바인딩 계약에 따라 그들에게는 추가 입력이 이동하지 않습니다.

오류 (Errors)

  • 실행이 시작되기 전에 거부된 입력 — 잘못된 JSON, 검증 실패, 거부된 인증 — 은 이벤트 스트림이 없는 HTTP 오류 상태로 이어집니다. 실행은 결코 시작되지 않았어요.
  • 스트림이 열린 후의 실패는 RUN_ERROR로 스트림 안에서 이동합니다. HTTP 상태는 이미 보내졌고 바꿀 수 없습니다. 소비자는 200만으로 성공을 추론하면 안 됩니다(MUST NOT).
  • 종료 이벤트 없이 끊긴 연결은 잘린 실행입니다.

재개 없음 (No resumption)

바인딩에는 스트림 재개가 없습니다. SSE의 Last-Event-ID 메커니즘은 사용되지 않고, 끊긴 스트림은 다시 들어갈 수 없습니다. 다시 실행하는 것은 소비자가 보존한 무엇이든 입력으로 담는 새 runId의 새 실행입니다.

예시 (Example)

POST /agent HTTP/1.1
Content-Type: application/json
Accept: text/event-stream

{"threadId":"thr-1","runId":"run-1","messages":[…]}

HTTP/1.1 200 OK
Content-Type: text/event-stream

data: {"type":"RUN_STARTED","threadId":"thr-1","runId":"run-1"}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-1","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-1","delta":"Hello."}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-1"}

data: {"type":"RUN_FINISHED","threadId":"thr-1","runId":"run-1"}

더 알아보기 (Learn more)