음성 에이전트

음성 에이전트를 사용하면 사용자가 애플리케이션과 대화하면서 질문하고 작업을 완료할 수 있습니다. 설계할 때 가장 먼저 정할 것은 음성 대화를 추론 및 도구 사용과 연결하는 방식입니다. 별도의 백엔드가 작업을 처리하는 동안 대화를 이어 가거나, 하나의 음성 모델에 모두 맡기거나, 파이프라인의 각 단계를 직접 제어할 수 있습니다.

적합한 아키텍처 선택하기

전이중 음성 에이전트 구축하기

GPT-Live는 들으면서 동시에 말할 수 있습니다. 이를 전이중 방식이라고 합니다. 실시간 모델은 음성 대화를 담당하고 추론과 도구 사용은 별도의 백엔드에 위임합니다. 백엔드가 작업하는 동안에도 사용자는 계속 말할 수 있습니다.

비즈니스 로직과 도구를 포함한 기존 텍스트 워크플로우를 유지하면서 GPT-Live를 음성 인터페이스로 추가할 수 있습니다. 백엔드 작업을 누가 실행하고 그 작업에 필요한 대화 컨텍스트를 누가 제공하는지는 위임 모드에 따라 달라집니다.

• 클라이언트 위임: 원하는 백엔드 모델과 제공업체를 선택해 자체 에이전트나 워크플로우를 연결하세요. 애플리케이션이 작업을 실행하고 결과를 GPT-Live에 반환합니다.
• Responses 위임: OpenAI가 호스팅하는 Responses 모델 중에서 백엔드 추론과 도구 사용을 담당할 모델을 선택하세요. GPT-Live가 대화 컨텍스트를 제공하고 해당 모델 호출을 관리합니다. 사용자 정의 함수는 애플리케이션이 계속 실행합니다.

두 모드 모두 애플리케이션이 권한과 업무 기록을 관리합니다. 말하는 방식은 실시간 모델의 프롬프트에, 비즈니스 규칙은 백엔드 프롬프트에 정의하세요.

먼저 GPT-Live 시작하기를 참고하세요. 백엔드 설정은 위임과 도구에서, 모델이 말하는 방식을 설정하는 방법은 음성 모델 프롬프트 작성하기에서 확인할 수 있습니다.

음성-음성 변환 에이전트 구축하기

Realtime API를 사용하면 RealtimeAgent와 RealtimeSession으로 브라우저 환경에서 구현을 시작할 수 있습니다. 세션이 음성 대화 턴, 도구, 끼어들기, 핸드오프를 처리합니다. 전체 시작 예제는 이제 Realtime API 시작하기에서 확인할 수 있습니다.

단계별 음성 워크플로우 구축하기

음성 인식, 에이전트 실행, 음성 생성 단계 사이에서 텍스트를 검사하거나 변환하려면 단계별 파이프라인을 사용하세요. 애플리케이션이 다음 세 단계를 관리합니다.

1. 음성을 텍스트로 변환
2. 에이전트 워크플로우 실행
3. 텍스트를 음성으로 변환

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import 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", event.data.nbytes)


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

각 단계의 처리 내용을 확인하거나 구성 요소를 교체해야 할 때 이 방식을 사용하세요. 예를 들어 대화 기록을 텍스트로 저장하고, 텍스트 에이전트가 응답하기 전에 정책 준수 여부를 검사하고, 내부 시스템을 호출한 뒤, 워크플로우에서 답변이 승인된 후에만 음성을 생성할 수 있습니다.

음성 에이전트 평가하기

대화 내용과 실제 작업 결과를 모두 테스트하세요. 예약 어시스턴트라면 예약 확인 안내를 듣고 올바른 일정이 저장되었는지 확인하세요.

1. 대표적인 시나리오를 선택하고 각 시나리오에서 기대하는 결과, 도구 호출, 권한을 정하세요.
2. 각 결과를 검증하는 데 필요한 오디오, 이벤트, 도구 실행 결과, 애플리케이션 상태를 저장하세요. 평가 실행 자체가 실패한 경우와 평가가 정상적으로 실행됐지만 에이전트가 작업에 실패한 경우를 구분하세요.
3. 시나리오를 반복 실행해 작업 완료 여부, 음성 응답이 들릴 때까지의 지연 시간, 끼어들기, 의도하지 않은 무음을 비교하세요. 변경 전후를 비교할 때는 통화 상대, 모델 설정, 도구, 전송 방식을 동일하게 유지하세요.

GPT-Live에서는 다음 항목을 개별적으로 측정하세요.

• 작업 및 도구 실행 결과: 사용자의 의도가 유지되었는지 확인하고 위임한 작업, 도구 인수, 권한, 애플리케이션의 최종 상태를 점검하세요. 음성으로 안내한 내용이 실제로 완료된 작업과 일치하는지 확인하세요.
• 대화 타이밍: 음성 응답이 들릴 때까지 걸리는 시간, 의도하지 않은 무음, 양쪽이 동시에 말하는 구간을 측정하세요. 백엔드가 작업하는 도중 사용자가 내용을 정정하는 경우를 포함해, 사용자가 끼어들면 에이전트가 발화를 멈추고 차례를 넘기는지도 확인하세요.
• 음성 및 언어: 억양, 배경 소음, 대화 중 언어 전환, 이름, 숫자 등 다양한 조건에서 음성 입력을 제대로 인식하는지 테스트하세요. 출력 음성을 알아듣기 쉬운지, 적절한 언어로 응답하는지는 입력 인식과 별도로 평가하세요.
• 세션 안정성: 연결 실패, 오디오 누락, 시간 초과, 완료되지 않은 세션을 작업 점수와 별도로 추적하세요.

기기, 걷기, 달리기의 세 단계로 테스트의 복잡도를 높여 가세요.

1. 기기: 통제된 조건에서 합성 음성으로 단일 턴 요청을 테스트하세요. 비교를 반복할 수 있도록 생성한 오디오, 애플리케이션 컨텍스트, 기대 결과를 고정하세요.
2. 걷기: 사람이 직접 말한 대표적인 단일 턴 요청의 녹음본을 재생해 목소리, 마이크, 말 사이의 쉼, 음향 환경이 에이전트 동작에 어떤 영향을 주는지 테스트하세요.
3. 달리기: 독립적으로 동작하는 모의 통화 상대와 여러 턴에 걸쳐 연속으로 대화하세요. 대화와 백엔드 작업이 동시에 진행되는 동안 에이전트가 불분명한 요청을 어떻게 확인하고, 요구사항 변경이나 끼어들기에 어떻게 대응하며, 중단된 대화를 어떻게 이어 가는지 테스트하세요.

자동 평가 점수와 함께 사람이 직접 음성을 듣고 발음, 자연스러움, 대화 속도가 적절하게 느껴지는지도 평가하세요.

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

Realtime 평가 하네스와 상세한 예제는 OpenAI Cookbook의 Realtime 평가 가이드를 참고하세요.

지연 시간 측정하기

통화 상대가 필요한 답변을 음성으로 듣기까지 얼마나 기다리는지 측정하세요. 지연 원인을 찾을 수 있도록 백엔드 처리 시간은 별도로 추적하고, 유사한 통화끼리 중앙값과 95번째 백분위수를 비교하세요.

프런트엔드 모델을 비교할 때는 통화 상대, 녹음본, 백엔드 모델, 프롬프트, 전송 방식, 오디오 전송 주기, 평가기를 동일하게 유지하세요.

GPT-Live에서는 애플리케이션이 관측할 수 있는 각 단계의 시점을 기록하세요. 여기에는 위임 요청 수신, 백엔드 요청 시작, 첫 유용한 결과 수신, 도구 실행 시작과 종료, 결과 제출, 오디오 도착, 클라이언트 재생이 포함됩니다. 클라이언트 위임에서는 애플리케이션이 자체 백엔드 요청을 직접 관측할 수 있습니다. Responses 위임에서는 중첩된 응답 이벤트와 애플리케이션이 실행하는 사용자 정의 도구를 관측할 수 있습니다.

이렇게 기록한 시간을 바탕으로 연결 설정, 모델 처리, 도구 실행, 버퍼링, 재생 중 어디에서 지연이 발생하는지 찾으세요. “확인 중입니다”와 같은 중간 안내가 들리기까지의 시간과 통화 상대가 필요한 답변을 듣기까지의 시간은 따로 측정하세요.

한 번에 하나의 요인만 변경하고 같은 시나리오를 반복하세요. 응답 속도가 빨라졌을 때 작업 성공 여부, 도구 사용의 정확성, 끼어들기 처리에도 영향이 있는지 확인하세요. 백엔드 지연 시간 줄이기를 참고하세요.

음성 에이전트에 공통으로 쓰이는 핵심 구성 요소

음성 인터페이스에서는 전송 방식과 오디오 처리 루프가 달라지지만, 워크플로우를 설계할 때 고려할 사항은 같습니다.

• 음성 에이전트에 외부 기능이 필요하면 도구 사용하기를 참고하세요.
• 음성 워크플로우에 스트리밍, 실행 재개, 영구 상태가 필요하면 에이전트 실행하기를 참고하세요.
• 음성 워크플로우가 여러 전문 에이전트로 분기하면 오케스트레이션과 핸드오프를 참고하세요.
• 음성 워크플로우에 안전성 검사나 승인이 필요하면 가드레일과 사람의 검토를 참고하세요.
• MCP 기반 기능이 필요하거나 음성 워크플로우가 어떻게 동작했는지 살펴보려면 통합과 관측 가능성을 참고하세요.

먼저 오디오 아키텍처를 선택한 뒤, 나머지 에이전트 워크플로우는 텍스트를 사용할 때와 같은 방식으로 설계하세요.

다음 단계