Realtime transport

Realtime transport (Realtime 전송)

이 페이지는 realtime 에이전트가 Python 애플리케이션에 어떻게 들어맞는지 결정하는 데 써요.

Python SDK 경계: Python SDK는 브라우저 WebRTC transport를 포함하지 않아요. 이 페이지는 Python SDK transport 선택(서버 측 WebSocket과 SIP 연결 흐름)만 다뤄요. 브라우저 WebRTC는 별개 플랫폼 주제로, 공식 Realtime API with WebRTC 가이드에 문서화돼 있어요.

출처: 문서

본문

결정 가이드

목표 시작 이유
서버 관리 realtime 앱 만들기 Quickstart 기본 Python 경로는 RealtimeRunner가 관리하는 서버 측 WebSocket 세션이에요.
어떤 transport·배포 형태를 고를지 이해하기 이 페이지 transport이나 배포 형태를 확정하기 전에 이것을 보세요.
에이전트를 전화·SIP 호출에 연결하기 Realtime guide, examples/realtime/twilio_sip 이 저장소는 call_id로 구동되는 SIP 연결 흐름을 제공해요.

서버 측 WebSocket이 기본 Python 경로

RealtimeRunner는 커스텀 RealtimeModel을 넘기지 않는 한 OpenAIRealtimeWebSocketModel을 사용해요. 즉 표준 Python 토폴로지는 이렇게 생겼어요.

  • Python 서비스가 RealtimeRunner를 만들어요.
  • await runner.run()이 RealtimeSession을 반환해요.
  • RealtimeSession을 async 컨텍스트 매니저로 진입한 뒤 텍스트·구조화 메시지·오디오를 보내요.
  • RealtimeSessionEvent 항목을 소비하고 오디오·대본을 애플리케이션으로 전달해요.

코어 데모 앱·CLI 예제·Twilio Media Streams 예제가 이 토폴로지를 사용해요.

  • examples/realtime/app
  • examples/realtime/cli
  • examples/realtime/twilio

서버가 오디오 파이프라인·도구 실행·승인 흐름·기록 처리를 소유할 때 이 경로를 쓰세요.

저수준 WebSocket 튜닝

기본 서버 측 WebSocket 연결을 튜닝해야 한다면 OpenAIRealtimeWebSocketModel에 transport_config를 넘기세요.

from agents.realtime import (
    OpenAIRealtimeWebSocketModel,
    RealtimeAgent,
    RealtimeRunner,
)

agent = RealtimeAgent(name="Assistant")
model = OpenAIRealtimeWebSocketModel(
    transport_config={
        "ping_interval": 20.0,
        "ping_timeout": 60.0,
        "handshake_timeout": 30.0,
        "max_size": 8 * 1024 * 1024,
    }
)
runner = RealtimeRunner(starting_agent=agent, model=model)

지원되는 옵션은:

  • ping_interval — 클라이언트 keepalive ping 사이의 초. 핑을 끄려면 None으로 설정.
  • ping_timeout — 연결 해제 전 pong을 기다리는 초. 하트비트 타임아웃 없이 지연된 pong을 허용하려면 None으로 설정.
  • handshake_timeout — 초기 연결 핸드셰이크를 기다리는 초.
  • max_size — 최대 수신 WebSocket 메시지 크기(바이트). SDK 기본은 None이라 수신 메시지 크기가 무제한이에요. 메시지별 메모리 사용량을 제한해야 할 때 명시적 한도를 설정하세요.

이 설정들은 Realtime API 세션이 아니라 클라이언트 연결을 구성해요. 엔드포인트·인증·호출 연결·재생 설정은 계속 RealtimeModelConfig를 사용하세요.

SIP 연결이 텔레포니 경로

이 저장소에 문서화된 텔레포니 흐름에서 Python SDK는 call_id로 기존 realtime 호출에 연결해요.

이 토폴로지는 이렇게 생겼어요.

  • OpenAI가 realtime.call.incoming 같은 웹훅을 서비스에 보내요.
  • 서비스가 Realtime Calls API로 호출을 수락해요.
  • Python 서비스가 RealtimeRunner(..., model=OpenAIRealtimeSIPModel())을 시작해요.
  • 세션이 model_config={"call_id": ...}으로 연결된 뒤 다른 realtime 세션처럼 이벤트를 처리해요.

이건 examples/realtime/twilio_sip에 나타난 토폴로지예요. 더 넓은 Realtime API도 일부 서버 측 제어 패턴에 call_id를 쓰지만, 이 저장소가 제공하는 연결 예제는 SIP예요.

브라우저 WebRTC는 이 SDK 범위 밖

앱의 주요 클라이언트가 Realtime WebRTC를 쓰는 브라우저라면:

  • 이 저장소의 Python SDK 문서 범위 밖으로 취급하세요.
  • 클라이언트 측 흐름과 이벤트 모델은 공식 Realtime API with WebRTC와 Realtime conversations 문서를 쓰세요.
  • 브라우저 WebRTC 클라이언트에 더해 대역 외(사이드밴드) 서버 연결이 필요하면 공식 Realtime server-side controls 가이드를 쓰세요.
  • 이 저장소가 브라우저 측 RTCPeerConnection 추상화나 바로 쓸 수 있는 브라우저 WebRTC 샘플을 제공하길 기대하지 마세요.

이 저장소는 현재 브라우저 WebRTC + Python 사이드밴드 예제도 제공하지 않아요.

커스텀 엔드포인트와 연결 지점

RealtimeModelConfig의 transport 구성 표면은 기본 transport 동작을 커스터마이즈하게 해줘요.

  • url — WebSocket 엔드포인트 재정의
  • headers — Azure 인증 헤더 같은 명시적 헤더 제공
  • api_key — API 키를 직접 또는 콜백으로 전달
  • call_id — 기존 realtime 호출에 연결. 이 저장소에서 문서화된 예제는 SIP예요.
  • playback_tracker — 중단 처리용 실제 재생 진행 보고

토폴로지를 정한 뒤 상세 lifecycle·기능 표면은 Realtime agents 가이드를 참고하세요.

더 알아보기 (Learn more)