Realtime Quickstart

Realtime Quickstart (Realtime 퀵스타트)

Python SDK의 Realtime 에이전트는 WebSocket transport 위의 OpenAI Realtime API를 기반으로 한 서버 측 저지연 에이전트예요.

Python SDK 경계: Python SDK는 브라우저 WebRTC transport를 제공하지 않아요. 이 페이지는 서버 측 WebSocket을 통한 Python 관리 realtime 세션만 다뤄요. 이 SDK는 서버 측 오케스트레이션·도구·승인·텔레포니 통합에 쓰세요. Realtime transport도 함께 보세요.

출처: 문서

본문

사전 요구사항

  • Python 3.10 이상
  • OpenAI API 키
  • OpenAI Agents SDK에 대한 기본적인 익숙함

설치

아직 안 했다면 OpenAI Agents SDK를 설치하세요.

pip install openai-agents

서버 측 realtime 세션 만들기

1. realtime 구성 요소 가져오기

import asyncio

from agents.realtime import RealtimeAgent, RealtimeRunner

2. 시작 에이전트 정의

agent = RealtimeAgent(
    name="Assistant",
    instructions="You are a helpful voice assistant. Keep responses short and conversational.",
)

3. 러너 구성

새 코드에는 중첩된 audio.input / audio.output 세션 설정 형태를 선호하세요. 새 realtime 에이전트는 gpt-realtime-2.1로 시작하세요.

runner = RealtimeRunner(
    starting_agent=agent,
    config={
        "model_settings": {
            "model_name": "gpt-realtime-2.1",
            "audio": {
                "input": {
                    "format": "pcm16",
                    "transcription": {"model": "gpt-4o-mini-transcribe"},
                    "turn_detection": {
                        "type": "semantic_vad",
                        "interrupt_response": True,
                    },
                },
                "output": {
                    "format": "pcm16",
                    "voice": "ash",
                },
            },
        }
    },
)

4. 세션 시작하고 입력 보내기

runner.run()은 RealtimeSession을 반환해요. 세션 컨텍스트에 들어가면(enter) 연결이 열려요.

async def main() -> None:
    session = await runner.run()

    async with session:
        await session.send_message("Say hello in one short sentence.")

        async for event in session:
            if event.type == "audio":
                # Forward or play event.audio.data.
                pass
            elif event.type == "history_added":
                print(event.item)
            elif event.type == "agent_end":
                # One assistant turn finished.
                break
            elif event.type == "error":
                print(f"Error: {event.error}")

if __name__ == "__main__":
    asyncio.run(main())

session.send_message()은 일반 문자열이나 구조화된 realtime 메시지를 받아요. 원시 오디오 청크에는 session.send_audio()를 쓰세요.

이 퀵스타트가 포함하지 않는 것

  • 마이크 캡처와 스피커 재생 코드 — examples/realtime의 realtime 예제를 보세요.
  • SIP / 텔레포니 연결 흐름 — Realtime transport와 SIP 섹션을 보세요.

핵심 설정

기본 세션이 동작하면, 그다음으로 대부분의 사람들이 손대는 설정은 이쪽이에요.

  • model_name
  • audio.input.format, audio.output.format
  • audio.input.transcription
  • audio.input.noise_reduction
  • 자동 턴 감지용 audio.input.turn_detection
  • audio.output.voice
  • tool_choice, prompt, tracing
  • async_tool_calls, tool_execution.pre_approval_tool_input_guardrails, guardrails_settings.debounce_text_length, tool_error_formatter

input_audio_format, output_audio_format, input_audio_transcription, turn_detection 같은 더 오래된 평평한 별칭은 여전히 동작하지만, 새 코드에는 중첩 audio 설정이 권장돼요.

수동 턴 제어를 하려면 Realtime agents 가이드에 설명된 저수준 session.update / input_audio_buffer.commit / response.create 흐름을 쓰세요. 전체 스키마는 RealtimeRunConfig와 RealtimeSessionModelSettings를 참고하세요.

연결 옵션

환경 변수에 API 키를 설정하세요.

export OPENAI_API_KEY="your-api-key-here"

또는 세션을 시작할 때 직접 넘기세요.

session = await runner.run(model_config={"api_key": "your-api-key"})

model_config는 다음도 지원해요.

  • url — 커스텀 WebSocket 엔드포인트
  • headers — 커스텀 요청 헤더
  • call_id — 기존 realtime 호출에 연결. 이 저장소에서 문서화된 연결 흐름은 SIP예요.
  • playback_tracker — 사용자가 실제로 들은 오디오 양을 보고

headers를 명시적으로 넘기면 SDK가 당신을 위해 Authorization 헤더를 주입하지 않아요.

Azure OpenAI에 연결할 때는 model_config["url"]을 GA Realtime 엔드포인트 URL로 설정하고 headers를 명시적으로 넘기세요. realtime 에이전트에는 레거시 베타 경로(/openai/realtime?api-version=...)를 피하세요. 자세한 내용은 Realtime agents 가이드를 참고하세요.

다음 단계

  • 서버 측 WebSocket과 SIP 중 고르려면 Realtime transport를 읽으세요.
  • lifecycle·구조화 입력·승인·handoff·guardrail·저수준 제어는 Realtime agents 가이드를 읽으세요.
  • examples/realtime의 예제를 둘러보세요.

더 알아보기 (Learn more)