Voice agents

Voice agents (음성 에이전트)

음성 에이전트는 사용자가 애플리케이션과 말로 질문하고 작업을 완료하게 해줘요. 핵심 설계 선택은 음성이 reasoning과 도구에 어떻게 연결되는가예요: 별도 백엔드가 있는 연속 대화, 단일 음성 모델, 또는 단계별로 통제하는 파이프라인.

출처: 문서

본문

올바른 아키텍처 선택

아키텍처	가장 좋은 용도	선택 이유
GPT-Live	별도 백엔드와의 전이중(full-duplex) 대화	기존 텍스트 워크플로를 유지하고, 대화가 계속되는 동안 백엔드를 독립적으로 선택할 수 있어요.
Realtime API	하나의 세션에서 음성·reasoning·도구 사용	오디오를 해석하고, 무엇을 할지 결정하고, 음성으로 응답하기 위해 하나의 모델을 사용해요.
체인 음성 파이프라인	각 음성·텍스트 단계에 대한 통제	중간 텍스트를 검사·변환하고 각 컴포넌트를 독립적으로 교체할 수 있어요.

전이중 음성 에이전트 구축

GPT-Live는 듣고 말하기를 동시에 할 수 있는데, 이를 전이중(full duplex) 이라고 해요. 라이브 모델은 음성 상호작용을 처리하고 reasoning·도구 사용을 별도 백엔드에 위임해요. 백엔드 작업이 실행되는 동안 사용자는 계속 말할 수 있어요.

비즈니스 로직과 도구를 포함한 기존 텍스트 워크플로를 유지하고, 음성 인터페이스로 GPT-Live를 추가할 수 있어요. 여러분의 위임 모드(delegation mode) 가 누가 백엔드 작업을 실행하고 그 대화 컨텍스트를 공급하는지 결정해요.

클라이언트 위임 (Client delegation): 선택한 백엔드 모델과 프로바이더를 사용해 자신의 에이전트나 워크플로를 연결해요. 애플리케이션이 작업을 실행하고 결과를 GPT-Live로 반환해요.
Responses 위임 (Responses delegation): 백엔드 reasoning·도구 사용을 위해 OpenAI가 호스팅한 Responses 모델을 선택해요. GPT-Live가 대화 컨텍스트를 공급하고 그 모델에 대한 호출을 관리하며, 애플리케이션은 여전히 커스텀 함수를 실행해요.

두 모드 모두에서 애플리케이션이 권한과 비즈니스 기록을 통제해요. 말하기 동작은 라이브 모델의 프롬프트에, 비즈니스 규칙은 백엔드 프롬프트에 두세요.

GPT-Live 시작하기부터 시작하세요. 백엔드 설정은 위임과 도구, 말하기 동작은 음성 모델 프롬프팅을 참고하세요.

음성 대 음성 에이전트 구축

Realtime API의 경우 RealtimeAgent와 RealtimeSession이 브라우저 우선의 시작점을 제공해요. 세션은 오디오 턴, 도구, 방해(interruption), 핸드오프를 처리해요. 완전한 스타터는 이제 Realtime API 시작하기에 있으요.

체인 음성 워크플로 구축

음성 인식, 에이전트, 음성 생성 사이에서 텍스트를 검사하거나 변환하려면 체인 경로를 사용하세요. 애플리케이션이 세 단계를 관리해요.

음성-텍스트 (Speech-to-text)
에이전트 워크플로 자체
텍스트-음성 (Text-to-speech)

체인 음성 파이프라인 실행

import asyncio
import numpy as np

from agents import Agent, function_tool
from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline


@function_tool
def get_weather(city: str) -> str:
    """Get the weather for a given city."""
    return f"The weather in {city} is sunny."


agent = Agent(
    name="Assistant",
    instructions="You are a helpful voice assistant.",
    model="gpt-6-astra",
    tools=[get_weather],
)


async def main() -> None:
    pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
    audio_input = AudioInput(buffer=np.zeros(24000 * 3, dtype=np.int16))
    result = await pipeline.run(audio_input)
    async for event in result.stream():
        if event.type == "voice_stream_event_audio":
            print("Received audio bytes", len(event.data))


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

각 단계가 보이거나 교체 가능해야 할 때 이 경로를 사용하세요. 예를 들어 대본(transcript)을 저장하고, 텍스트 에이전트가 응답하기 전에 정책 검사를 실행하고, 내부 시스템을 호출한 다음, 워크플로가 승인된 답변에 도달한 후에만 음성을 생성할 수 있어요.

음성 에이전트 평가

대화와 완료된 작업을 모두 테스트하세요. 예약 어시스턴트라면 확인 음성을 듣고 올바른 예약이 저장됐는지 확인하세요.

예상 결과, 도구 호출, 권한이 있는 대표 시나리오를 선택하세요.
각 결과를 검증하는 데 필요한 오디오, 이벤트, 도구 결과, 애플리케이션 상태를 저장하세요. 실패한 평가 실행과, 에이전트가 작업을 실패하는 유효한 실행을 구분하세요.
시나리오를 반복하고 작업 완료, 들리는 응답 지연 시간, 방해, 원치 않는 침묵을 비교하세요. 변경을 비교할 때 호출자, 모델 구성, 도구, 전송을 일관되게 유지하세요.

GPT-Live의 경우 이 차원들을 독립적으로 측정하세요.

작업 및 도구 결과: 의도 보존, 위임된 작업, 도구 인자, 권한, 최종 애플리케이션 상태를 확인하세요. 음성 확인이 완료된 액션과 일치하는지 검증하세요.
대화 타이밍: 들리는 응답 타이밍, 원치 않는 침묵, 겹침, 백엔드 작업 실행 중 수정을 포함한 방해에 양보하는지를 측정하세요.
음성 및 언어: 억양, 배경 소음, 언어 전환, 이름, 숫자에 걸쳐 입력 인식을 테스트하세요. 출력 명료성과 언어 선택을 인식과 별도로 평가하세요.
세션 신뢰성: 연결 실패, 드롭된 오디오, 타임아웃, 불완전한 세션을 작업 점수와 별도로 추적하세요.

Crawl, Walk, Run을 사용해 단계적으로 복잡도를 추가하세요.

Crawl: 통제된 단일 턴 요청에 합성 음성을 사용하세요. 반복 가능한 비교를 위해 생성된 오디오, 애플리케이션 컨텍스트, 예상 결과를 고정하세요.
Walk: 단일 턴 요청의 대표적인 인간 녹음을 재생해 목소리, 마이크, 멈춤, 음향 조건이 동작에 어떤 영향을 주는지 테스트하세요.
Run: 독립적인 시뮬레이션 호출자를 사용해 연속 다중 턴 대화를 수행하세요. 대화와 백엔드 작업이 겹치는 동안 명확화, 요구 변경, 방해, 복구를 테스트하세요.

자동 점수를 인간 청취로 보완해 발음, 자연스러움, 대화가 적절하게 진행되는지 평가하세요.

GPT-Live 평가 하네스는 음성 에이전트 평가 Cookbook을 참고하세요.

Realtime 평가 하네스와 실제 예시는 OpenAI Cookbook의 Realtime 평가 가이드를 사용하세요.

지연 시간 측정

호출자가 유용한 음성 답변을 기다리는 시간을 측정하세요. 지연을 찾기 위해 백엔드 시간을 별도로 추적하고, 유사한 호출에 걸쳐 중앙값과 95번째 백분위수를 비교하세요.

프론트엔드 모델을 비교할 때 호출자, 녹음, 백엔드 모델, 프롬프트, 전송, 오디오 케이던스, 그래더를 고정하세요.

GPT-Live의 경우 애플리케이션이 관찰할 수 있는 단계를 기록하세요: 위임 수신, 백엔드 요청 시작, 첫 유용한 결과, 도구 시작과 종료, 결과 제출, 오디오 도착, 클라이언트 재생. 클라이언트 위임은 애플리케이션에 백엔드 요청에 대한 직접적인 가시성을 주고, Responses 위임은 중첩 응답 이벤트와 애플리케이션이 실행하는 커스텀 도구를 노출해요.

이 타이밍을 사용해 연결 설정, 모델 작업, 도구, 버퍼링, 재생의 지연을 찾으세요. "확인 중이에요" 같은 확인 신호를 호출자가 필요한 답변과 별도로 측정하세요.

한 번에 한 요소씩 바꾸고 같은 시나리오를 반복하세요. 더 빠른 응답이 작업 성공, 도구 정확성, 방해에도 영향을 주는지 확인하세요. 백엔드 지연 줄이기를 참고하세요.

음성 에이전트는 여전히 같은 핵심 에이전트 빌딩 블록을 사용해요

음성 표면은 전송과 오디오 루프를 바꾸지만, 핵심 워크플로 결정은 같아요.

음성 에이전트가 외부 기능이 필요할 때 도구 사용을 사용하세요.
음성 워크플로가 스트리밍, 연속, 내구성 있는 상태가 필요할 때 에이전트 실행을 사용하세요.
음성 워크플로가 전문가 간에 분기할 때 오케스트레이션과 핸드오프를 사용하세요.
음성 워크플로가 안전 검사나 승인이 필요할 때 가드레일과 인간 검토를 사용하세요.
MCP 기반 기능이 필요하거나 음성 워크플로가 어떻게 동작했는지 검사하고 싶을 때 통합과 관찰성을 사용하세요.

실용적인 규칙: 먼저 오디오 아키텍처를 선택하고, 나머지 에이전트 워크플로는 텍스트와 같은 방식으로 설계하세요.

다음 단계

오디오·음성 개요 — 사용 사례에 맞는 올바른 실시간 또는 오디오 가이드를 선택합니다.
대화 관리 — Realtime 세션 생애 주기와 이벤트 모델 작업.
WebRTC 연결 — 브라우저·모바일 오디오를 Realtime 세션에 직접 연결.
Realtime 프롬프팅 가이드 — reasoning, 전조, 도구, 엔티티 캡처, 음성 동작 튜닝.

더 알아보기 (Learn more)

GPT-Live 시작하기와 위임과 도구를 참고하세요.
Realtime 시작하기를 참고하세요.