GPT-Live로 마이그레이션하기

Realtime API에서 이전하기

먼저 GPT-Live 프롬프팅 가이드를 읽어 보세요. 기존 프롬프트를 session.instructions에 통째로 복사하지 말고 음성 모델과 백엔드의 역할에 맞게 나누세요. 대화 스타일과 위임 지침은 음성 프롬프트에 두고, 세부 워크플로우와 도구 사용 지침은 백엔드로 옮기세요.

이전 전: Realtime 모델이 음성 대화를 처리하고 check_availability, book_appointment 등의 함수를 선택합니다. 애플리케이션은 함수를 실행하고 결과를 반환합니다.

이전 후: GPT-Live가 음성 대화를 처리하고 작업을 위임합니다. 같은 함수를 이제 백엔드가 선택하며, 애플리케이션은 계속 함수 호출을 검증하고 실행합니다. 여기서는 Responses 위임을 사용합니다. 외부 에이전트를 유지한다면 클라이언트 어댑터를 사용하세요.

Responses 위임의 동작 방식

delegation.responses에서 백엔드 모델, 지침, 도구를 설정하세요. GPT-Live가 요청을 처리하는 데 백엔드 작업이 필요하다고 판단하면 Live 서비스가 해당 Responses 모델을 호출하고 관련 대화 컨텍스트를 제공합니다. 백엔드는 작업 처리 방법을 판단하고 도구를 선택합니다. 사용자 정의 함수 실행, 권한 검사, 실행 결과 반환은 계속 애플리케이션이 담당합니다.

예약 어시스턴트의 경우 다음과 같이 동작합니다.

1. 사용자가 금요일에 예약 가능한 시간을 물으면 GPT-Live가 요청을 위임합니다.
2. Responses 백엔드가 check_availability 호출을 요청합니다.
3. 애플리케이션이 함수를 실행하고 결과를 반환한 뒤 백엔드 응답을 이어갑니다.
4. GPT-Live가 백엔드의 답을 바탕으로 사용자와 예약 가능 시간을 논의합니다.

백엔드가 작업하는 동안에도 GPT-Live는 계속 말할 수 있습니다. 백엔드 작업과 오디오 재생은 별도로 추적하세요. 도구 결과로 작업 상태를 갱신하고 플레이어 상태에 따라 발화 중 표시를 갱신하세요. 설정과 전체 이벤트 플로우는 위임과 도구를 참고하세요.

연결과 오디오 수명 주기 조정하기

Realtime 세션 설정을 GPT-Live 연결 절차로 교체하세요. 전송 방식에 맞는 연결 시작 절차와 오디오 형식을 다시 확인하세요. WebRTC는 미디어 트랙으로 오디오를 전송하고 데이터 채널로 JSON 이벤트를 전송합니다. 기본 WebSocket 연결에서는 JSON 이벤트에 오디오를 담아 전송합니다.

Realtime 애플리케이션이 서버 연결을 사용해 통화를 모니터링하거나 가드레일을 적용한다면 GPT-Live 사이드밴드 연결에 맞게 조정하세요. 대화 검사와 재생 방식을 변경할 때는 가드레일 조정하기를 따르세요.

생성과 재생: 오디오 플레이어 상태에 따라 발화 중 표시를 제어하세요. 서버가 생성을 마쳤어도 플레이어에는 아직 재생할 오디오가 1초 분량 남아 있을 수 있습니다. Realtime에서는 response.output_audio.done이 생성 종료를 알리고 response.done이 응답 스트림을 끝냅니다. 중단이나 실패 여부는 response.status에서 확인하세요. GPT-Live에는 개별 음성 응답의 종료를 알리는 대응 이벤트가 없습니다.

자막: 입력 전사를 활성화하면 Realtime은 conversation.item.input_audio_transcription.delta로 텍스트 조각을 보내고 conversation.item.input_audio_transcription.completed로 최종 전사문을 보냅니다. GPT-Live에서는 각 조각을 발신자 또는 어시스턴트의 자막에 이어 붙이세요. 양쪽 자막이 동시에 바뀔 수 있습니다. 텍스트를 어떻게 묶을지는 애플리케이션이 결정하고, 재생 상태는 오디오 플레이어로 추적합니다. 자막 표시하기를 참고하세요.

위임된 Responses 작업을 시작하거나 이어가려면 response.create를 사용하세요. GPT-Live는 대화를 들으면서 언제 말할지 결정합니다. 세션 시작, 인사, 끼어들기, 세션 종료에 대해서는 세션 관리하기를 참고하세요.

대화 지침과 백엔드 지침 분리하기

Realtime 어시스턴트를 GPT-Live로 이전할 때는 기존 프롬프트에서 시작하세요. 말투와 발화 순서에 관한 지침을 Live 프롬프트로 옮기고 언제 작업을 위임할지에 관한 규칙을 추가하세요. 작업 지침과 도구 사용 절차는 백엔드 프롬프트에 두세요.

텍스트 에이전트에 음성을 추가한다면 기존 백엔드 프롬프트를 재사용하고 음성 대화용 Live 프롬프트를 작성하세요.

일관된 대화 경험 유지하기

어시스턴트의 역할, 대상 사용자, 목적을 유지하고 대화의 특성을 결정하는 다음 세부 사항을 보존하세요.

• 인사, 자기소개, 음성으로 전달하는 고지 사항과 필수 문구 또는 전달 순서.
• “영어로 말하세요”와 같은 언어 및 발음 요건.
• 성격, 따뜻함, 공감 표현, 격식 수준, 말하는 속도와 호흡.
• 음성 답변의 상세도와 의도한 말투를 보여 주는 예시.
• 사용자의 말을 듣고 있다는 표시를 하는 방식, 말을 멈추고 듣는 방식, 사용자가 끼어들 때 대응하는 방식.

Live 프롬프트가 짧아도 자세한 음성 답변을 요청할 수 있습니다.

Live 프롬프트 작성하기

어시스턴트의 정체성, 말투, 대화 방식을 정할 때는 권장 프롬프트 구조를 사용하세요. Backchannel policy와 Interruption policy를 유지해 상대의 말을 듣고 있다는 표시를 어떻게 하고, 어시스턴트가 말하는 도중 상대가 끼어들면 어떻게 대응할지 설명하세요.

Live가 정확하게 위임하려면 백엔드에서 어떤 일을 할 수 있는지 알아야 합니다. 이러한 기능을 일상적인 표현으로 설명하세요. 함수 이름과 도구 스키마는 도구 호출을 처리하는 백엔드에 두세요.

Delegation policy 아래의 다음 항목을 애플리케이션에 맞게 조정하세요.

• Backend tools: 기존 프롬프트와 같은 용어를 사용해 애플리케이션이 지원하는 기능을 나열하세요. 예를 들어 “예약 가능 시간을 확인하고 회신 전화를 예약합니다”라고 작성할 수 있습니다.
• Delegate to the backend when: “사용자가 회신 전화를 예약해 달라고 하면 위임하세요”와 같이 해당 기능을 언제 사용할지 명시하세요. 이미 진행 중인 작업에 필요한 정정, 확인, 새로운 정보도 포함하세요.
• Do not delegate to the backend when: 인사, 요청을 이해하기 위한 짧은 질문, 대화에서 이미 나온 정보나 여전히 유효한 백엔드 결과를 다시 말하는 경우 등 Live가 직접 처리할 수 있는 상황을 설명하세요.

Live가 진행 상황을 어떻게 알리고, 백엔드의 다음 질문을 어떻게 사용자에게 묻고, 검증된 결과를 어떻게 전달해야 하는지 설명하세요.

어시스턴트가 통화를 종료하는 경우 Live에 마무리 인사와 통화 종료 요청 위임에 관한 지침을 제공하세요. 실제 통화 종료 도구와 실행 순서는 백엔드에 두세요. 예를 들어 애플리케이션에서 마무리 인사 재생을 마친 뒤 연결을 끊고, 대기 중인 계산을 취소하고, 이후 저장을 차단해야 할 수 있습니다. Live는 인사와 위임을 담당하고 백엔드와 애플리케이션은 나머지 단계를 처리합니다.

백엔드 프롬프트 조정하기

원래 프롬프트에서 시작하세요. 여전히 적용되는 문구, 순서, 예시, 구조는 유지하세요. 프롬프트가 주로 작업을 설명한다면 대부분 그대로 사용할 수 있습니다.

다음 지침은 백엔드 프롬프트에 두세요.

• 사용자 요청 해석, 정정 사항 반영, 누락된 정보 수집, 작업 진행 상황 추적.
• 도메인 지식 활용, 자격 요건 확인, 답의 근거가 되는 기록이나 서비스 조회.
• 검색, 업데이트, 확인, 라우팅, 통화 전환, 회신 전화 등 지원하는 동작의 절차 준수.
• 안전, 개인정보 보호, 권한 규칙 적용, 실패 처리, 통화 전환 또는 종료 후 동작 제한.
• Live가 전달할 정확한 사실, 작업 상태, 다음 질문 준비.

음성, 인사, 발화 순서, 위임 시점에 관한 지침은 Live 프롬프트로 옮기세요. 백엔드가 사용자에게 직접 말한다고 가정한 지침은 백엔드가 Live에 정보를 반환하도록 조정하세요. 안전 및 개인정보 보호 제한이 각 모델의 발언, 질문, 동작에 영향을 준다면 두 프롬프트 모두에 해당 제한을 두세요.

함수 이름, 인수 요건, 도구 사용 절차는 백엔드 지침에 두세요. 도구 정의는 백엔드의 도구 설정에 넣으세요. 애플리케이션은 도구를 실행하며, 현재 작업 상태를 기준으로 권한과 인수를 검증하고 필수 확인을 받았는지 검사합니다.

대화에 담긴 요청, 정정, 확인의 의미는 백엔드 모델이 파악하도록 하세요. 정규식, 키워드 목록, 문구의 정확한 일치에 의존하는 규칙은 앞서 한 말이나 정정 내용에 따라 달라지는 의미를 놓칩니다. 예를 들어 “네”라는 답은 예약 시간을 확인한다는 뜻일 수도, 질문을 들었다는 뜻일 수도, 앞서 나온 제안에 대한 답일 수도 있습니다.

발신자가 끼어들거나 통화가 전환 또는 종료될 때 이미 실행 중인 작업을 어떻게 처리할지에 관한 규칙을 유지하세요. 발화를 멈춰도 백엔드 작업은 계속 실행됩니다. 발신자가 취소를 요청하면 백엔드와 애플리케이션이 취소를 처리하고 결과를 Live에 알려야 합니다.

충돌하는 지침 해결하기

원래 프롬프트와 새 프롬프트 두 개를 검토해 서로 어긋나는 지침을 찾으세요. 반복되는 지침은 합치고 구체적인 조건과 예외는 해당 규칙과 함께 두세요. 권한, 질문 횟수 제한, 확인 요건, 통화 종료 후 허용되는 동작을 점검하세요.

사용자가 원하는 일과 이미 일어난 일을 구분하세요. 발신자가 금요일을 목요일로 바꾸면 백엔드는 최신 요청에 따라 목요일을 대상으로 작업합니다. 금요일 예약이 이미 완료됐는지는 예약 기록에서 확인합니다. 그다음 어떤 변경이 가능한지는 기존 확인 및 권한 규칙이 결정합니다.

프롬프트를 사용하기 전에 제품 동작에 관한 결정은 담당자와 합의하세요. 예를 들어 한 지침에서는 예약을 계속하라고 하고 다른 지침에서는 발신자가 끼어들면 모든 작업을 중단하라고 한다면 애플리케이션이 어떻게 동작해야 하는지 결정하세요. 합의한 동작을 프롬프트와 이를 실행하는 애플리케이션 로직에 반영하세요.

필수 동작이 각각 구현되어 있는지 확인하세요. 통화를 종료하려면 통화 종료 기능이 필요합니다. 말로만 인사를 마치면 연결은 계속 열려 있습니다. 기능이 없다면 직접 구현할지, 해당 워크플로우를 담당하는 팀과 지원 가능한 대안을 정할지 결정하세요.

두 프롬프트 검토하기

두 프롬프트를 원본과 비교해 필요한 모든 동작이 적절한 곳에 반영되었는지 확인하세요.

• Live 프롬프트가 어시스턴트의 정체성, 어휘, 말투, 고지 사항, 사용자가 끼어들 때의 대응 방식을 유지합니다.
• 백엔드 프롬프트가 작업 절차, 사실, 조건, 예시, 권한, 실패 처리 방식을 유지합니다.
• 위임 규칙이 새 요청, 정정, 확인, 대화와 작업 정보가 함께 담긴 요청을 포괄합니다.
• 두 프롬프트에서 질문 횟수 제한, 동작이 확인된 것으로 보는 시점, 작업 계속 진행, 취소, 통화 전환 및 종료 처리 방식이 일치합니다.

Live 프롬프트는 session.instructions에 넣으세요. Responses 위임을 사용할 때는 백엔드 프롬프트를 session.delegation.responses.instructions에 넣고, 클라이언트 위임을 사용할 때는 기존 에이전트 설정에 두세요. 도구 정의는 백엔드에 두세요. 설정과 결과 처리에 대해서는 위임과 도구를 참고하세요.

You are Rowan, the appointment assistant for Northstar Repairs.
Speak English, calmly and briefly. Greet the caller once with:
"Hello, this is Rowan from Northstar Repairs. How can I help?"
Use brief listening acknowledgments. Stop speaking when interrupted.

Help callers find and book appointments. Ask for the preferred date
and time zone if missing, then use check_availability.
Offer only returned slots. Ask the caller to confirm the exact slot
before calling book_appointment.
If the caller changes the date, time zone, or slot, discard the earlier
confirmation and check availability again.
Report a booking only after the tool confirms success. If the outcome
is unclear, say it is unconfirmed and do not retry automatically.

You are Rowan, the appointment assistant for Northstar Repairs.
Speak English, calmly and briefly. Greet the caller once with:
"Hello, this is Rowan from Northstar Repairs. How can I help?"

Backchannel policy: Use brief listening acknowledgments.

Interruption policy: Stop speaking when interrupted and listen.

Delegation policy:
Backend tools:
- Appointments: check available times and book appointments.

Delegate to the backend when:
- The caller wants to find or book an appointment.
- The caller supplies or corrects a date, time zone, or slot, or
  answers a booking question, including confirming a slot.

Do not delegate to the backend when:
- The caller greets you or asks you to repeat a still-current result.
- You need a brief clarification to understand what they are asking.

Relay the backend's questions and results. Offer only slots it returns.
Do not claim a booking is complete until the backend confirms success.
If the backend reports an unclear outcome, say it is unconfirmed.

Help callers find and book appointments for Northstar Repairs.
Ask for the preferred date and time zone if missing, then use
check_availability. Offer only returned slots.
Ask the caller to confirm the exact slot before calling book_appointment.
If the caller changes the date, time zone, or slot, discard the earlier
confirmation and check availability again.
Report a booking only after the tool confirms success. If the outcome
is unclear, report it as unconfirmed and do not retry automatically.

Return the available slots, booking outcome, or next question for the
voice assistant to communicate. Interpret the caller's latest answers
and corrections using the conversation and current task state.

함수 핸들러 조정하기

check_availability와 book_appointment의 구현은 유지하세요. 함수 정의는 Responses 함수 스키마에 맞춰 Realtime의 session.tools 또는 response.tools에서 delegation.responses.tools로 옮기세요. 도구 선택 설정은 delegation.responses.tool_choice와 delegation.responses.parallel_tool_calls로 옮기세요. Responses 위임 설정하기를 참고하세요.

함수는 이전과 마찬가지로 원래 call_id에 대한 결과를 반환합니다. 달라지는 것은 핸들러가 호출을 수신하고 결과를 보내는 경로입니다.

예를 들어 check_availability가 확인된 예약 가능 시간을 반환하면 연결된 세션에서 다음 이벤트를 보내세요. call_availability를 수신한 호출 ID로 바꾸세요.

이전 전: Realtime 결과

12345678{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_availability",
    "output": "{\"available\":true,\"slot_id\":\"slot_friday_14\",\"booked\":false}"
  }
}

이전 후: GPT-Live 결과

1
2
3
4
5
6
7
8
9
10
11export function sendUpdate(connection) {
  connection.send({
    type: "response.item.create",
    event_id: "availability_result_1",
    item: {
      type: "function_call_output",
      call_id: "call_availability",
      output: '{"available":true,"slot_id":"slot_friday_14","booked":false}',
    },
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection
from openai.types.responses.response_input_item_param import ResponseInputItemParam


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    item: ResponseInputItemParam = {
        "type": "function_call_output",
        "call_id": "call_availability",
        "output": '{"available":true,"slot_id":"slot_friday_14","booked":false}',
    }
    await connection.response.item.create(
        event_id="availability_result_1",
        item=item,
    )

1
2
3
4
5
6
7
8
9
10
11
12
13
14import (
	"context"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/live"
	"github.com/openai/openai-go/v3/responses"
)

// SendUpdate requires a started Live session.
func SendUpdate(ctx context.Context, connection *live.LiveConnection) error {
	return connection.Send(ctx, live.ClientEventUnionParam{OfResponseItemCreate: &live.ResponseItemCreateEventParam{
		EventID: openai.String("availability_result_1"),
		Item:    responses.ResponseInputItemUnionParam{OfFunctionCallOutput: &responses.ResponseInputItemFunctionCallOutputParam{CallID: openai.String("call_availability"), Output: responses.ResponseInputItemFunctionCallOutputOutputUnionParam{OfString: openai.String("{\"available\":true,\"slot_id\":\"slot_friday_14\",\"booked\":false}")}}},
	}})
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.helpers.LiveConnection;
import com.openai.models.live.*;
import com.openai.models.responses.*;

public static void sendUpdate(LiveConnection connection) {
  connection.send(
      ClientEvent.ofResponseItemCreate(
          ResponseItemCreateEvent.builder()
              .eventId("availability_result_1")
              .item(
                  ResponseInputItem.FunctionCallOutput.builder()
                      .callId("call_availability")
                      .output(
                          "{\"available\":true,\"slot_id\":\"slot_friday_14\",\"booked\":false}")
                      .build())
              .build()));
}

1
2
3
4
5
6
7
8
9def send_update(connection)
  connection.send_event(
    type: "response.item.create", event_id: "availability_result_1", item: {
      type: "function_call_output",
      call_id: "call_availability",
      output: "{\"available\":true,\"slot_id\":\"slot_friday_14\",\"booked\":false}"
    }
  )
end

필요한 함수 결과를 모두 제출한 뒤 백엔드 작업을 이어가세요.

1
2
3
4
5
6export function sendUpdate(connection) {
  connection.send({
    type: "response.create",
    event_id: "continue_availability_1",
  });
}

1
2
3
4
5
6
7
8
9
10from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    await connection.response.create(
        event_id="continue_availability_1",
    )

1
2
3
4
5
6
7
8
9
10
11
12import (
	"context"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/live"
)

// SendUpdate requires a started Live session.
func SendUpdate(ctx context.Context, connection *live.LiveConnection) error {
	return connection.Send(ctx, live.ClientEventUnionParam{OfResponseCreate: &live.ResponseCreateEventParam{
		EventID: openai.String("continue_availability_1"),
	}})
}

1
2
3
4
5
6
7
8import com.openai.helpers.LiveConnection;
import com.openai.models.live.*;

public static void sendUpdate(LiveConnection connection) {
  connection.send(
      ClientEvent.ofResponseCreate(
          ResponseCreateEvent.builder().eventId("continue_availability_1").build()));
}

1
2
3def send_update(connection)
  connection.send_event(type: "response.create", event_id: "continue_availability_1")
end

마이그레이션 초기에는 parallel_tool_calls를 false로 설정해 도구 호출을 한 번에 하나씩 처리하세요. 내부 response.output_item.done 이벤트에서 각 함수 호출을 수집하고 함수 이름, 인수, call_id를 보관하세요. 이후 완료 이벤트에 output: []가 포함되어 있어도 이 기록을 유지하세요. 인수 수신 완료 이벤트만으로는 함수 이름과 call_id를 알 수 없으므로 항목이 완성될 때까지 기다린 뒤 핸들러를 실행하세요. 호출 수집, 출력 제출, 오류 처리는 전체 함수 결과 처리 절차를 따르세요.

컨텍스트 유지 및 정정 사항 반영하기

Responses 위임은 음성 대화에서 관련 컨텍스트를 추려 백엔드에 제공합니다. 예약 판단의 기준이 되는 상태는 애플리케이션에 보관하세요. 여기에는 선택한 시간, 사용자가 확인한 시간, 권한, 진행 중인 동작, 결과가 포함됩니다. Live 대화 기록은 압축될 수 있으므로 예약 기록을 대신할 수 없습니다.

사용자가 “아, 금요일로 바꿀게요”라고 하면 금요일을 현재 요청으로 기록하고 목요일에 대해 받은 확인은 지우세요. 애플리케이션이 이전 요청의 결과를 구분할 수 있도록 작업에 리비전 2와 같은 새 버전 번호를 부여하세요.

예약하기 전에 날짜, 시간, 사용자가 확인한 내용이 여전히 현재 요청과 일치하는지 확인하세요. 사용자가 요청을 변경해 대기 중인 함수 호출을 거절한다면 실제 처리 내용에 맞게 호출을 건너뛰었거나 취소했다는 결과를 반환하세요. 백엔드 작업을 이어가기 전에 필요한 모든 호출에 대해 결과를 제출하세요.

목요일 예약이 이미 성공했다면 새 예약을 시도하기 전에 기존 예약의 현재 상태를 확인하고 요청된 변경을 처리하세요.

각 전사 조각을 수신한 그대로 화자, start_ms, end_ms와 함께 보관하세요. 조각이 늦게 도착하거나 두 사람이 동시에 말하는 경우에도 이 정보를 사용해 해당 발신자 또는 어시스턴트의 자막이나 채팅 말풍선을 갱신하세요. 메시지를 어디서 나눌지는 애플리케이션에서 정하고 오디오 재생은 플레이어에서 추적하세요. 전사 타임스탬프만으로는 각 단어의 정확한 재생 시점을 알 수 없습니다. 의도가 불확실하면 중요한 날짜, 이름, 숫자는 다시 물어 확인하세요. 전사와 컨텍스트 처리에 대해서는 세션 관리하기를 참고하세요.

이미지와 화면 컨텍스트: Realtime 애플리케이션이 이미지를 입력받는다면 이미지를 처리할 수 있는 백엔드로 보내고 관련 텍스트를 GPT-Live에 반환하세요. 클라이언트 위임과 Responses 위임 모두 이 방식을 지원합니다. 이미지와 시각적 컨텍스트 추가하기를 참고하세요.

오디오에 의존하는 판단 유지하기

음성 사서함의 신호음을 감지하거나 재생 타이밍을 바탕으로 녹음된 인사말을 식별하는 등 소리 자체를 들어야 하는 판단이 있습니다. GPT-Live는 통화 오디오를 듣지만 위임 시 오디오가 백엔드로 자동 전송되지는 않습니다. 클라이언트 모드에서 session.delegation.created에는 ID와 타이밍 정보가 들어 있습니다. 요청 컨텍스트와 백엔드에 필요한 오디오는 애플리케이션이 제공합니다.

자동 응답기를 감지하려면 수신 오디오를 오디오 처리 기능이 있는 감지기로 명시적으로 보내세요. 애플리케이션이 관리하는 구성으로, 통화의 일부 구간에서 GPT-Live와 별도의 Realtime 세션을 함께 실행하는 방식을 검토할 수 있습니다.

1. 수신한 통화 오디오의 복사본을 두 세션 모두에 보내세요.
2. 감지기가 구조화된 함수 호출로 분류 결과를 보고하도록 하세요. 각 결과가 스키마에 맞는지 확인하고, 더 이상 유효하지 않은 결과는 거부하고, 근거가 부족하면 미확인 상태로 두세요. 나중에 추가 근거가 들어오면 판단을 수정할 수 있게 하세요.
3. 관련성이 있고 신뢰할 수 있는 컨텍스트를 GPT-Live에 보내고 송신 오디오 재생에 애플리케이션 정책을 적용하세요.

두 가지를 따로 추적하세요. 상대가 사람인지 기계인지, 그리고 수신 측에서 메시지를 녹음할 준비가 되었는지입니다. 안내 음성이 아직 재생 중이어도 감지기가 음성 사서함을 식별할 수 있습니다. 애플리케이션이 요구하는 근거를 확보한 뒤에 송신 오디오를 허용하세요. 컨텍스트 수신 확인은 업데이트가 수락되었다는 기록입니다. 재생 여부는 여전히 애플리케이션이 결정합니다. 가드레일 조정하기와 재생 제어를 참고해 애플리케이션이 제어하는 오디오 경로에서 그 결정을 적용하세요.

짧게 “여보세요”라고 한 뒤 음성 사서함 안내가 이어지는 경우, 통화 연결 전에 발신자를 확인하는 안내가 나오는 경우, 음성 사서함 작동 중에 사람이 전화를 받는 경우를 테스트하세요. 통화가 끝나기 전에 감지기를 중지할 계획이라면 중지한 뒤 사람이 전화를 받을 때의 동작도 테스트하세요. 테스트 결과와 감지기 실행에 드는 추가 비용을 고려해 실행 시간을 정하세요. 오디오를 더 수신하면서 처음의 “사람” 분류가 바뀌는 경우도 포함하세요.

텍스트 에이전트 또는 다단계 파이프라인에서 이전하기

이전 전: 텍스트 에이전트가 텍스트 요청을 받아 자체 도구와 저장된 상태를 사용합니다. 여러 단계를 직렬로 연결한 음성 파이프라인은 에이전트 앞에 음성 인식 단계를, 뒤에 음성 합성 단계를 추가합니다.

이전 후: GPT-Live가 음성 인터페이스를 제공하고 기존 에이전트에 작업을 위임합니다. 다단계 파이프라인에서는 별도로 두었던 음성 인식과 음성 합성 단계를 대체합니다. 기존 모델, 지침, 도구, 워크플로우, 영속 상태가 여전히 작업에 적합하다면 백엔드에 유지하세요.

기존 에이전트 연결하기

delegation을 {"type":"client"}로 설정하세요. 이 작업은 세션 설정 단계에서 수행합니다. 애플리케이션은 다음과 같은 알림을 받습니다.

123456789{
  "type": "session.delegation.created",
  "offset_ms": 1000,
  "delegation": {
    "id": "item_appointment_1",
    "type": "delegation",
    "target": "client"
  }
}

이 알림을 받으면 애플리케이션의 위임 핸들러를 시작하세요. 같은 요청에 결과를 연결할 수 있도록 delegation.id를 보관하세요. 핸들러는 발신자와 어시스턴트의 전사문, 애플리케이션이 보관하는 작업 기록을 바탕으로 에이전트 입력을 준비합니다. 알림 자체에는 요청 텍스트나 도구 인수가 없습니다.

예를 들어 예약 에이전트는 다음과 같은 입력을 받을 수 있습니다.

발신자: “아, 금요일로 바꿀게요.”

현재 요청: 발신자의 시간대를 기준으로 금요일에 예약 가능한 시간을 찾습니다.

이전 결과: 목요일 오후 2시를 제안했습니다.

확인 여부: 발신자가 확인한 금요일 예약 시간은 없습니다.

작업 리비전: 2.

문장 전체가 전사되기 전에 알림이 도착할 수 있습니다. 컨텍스트가 충분해질 때까지 알림을 보관하거나, 동작을 실행하기 전에 발신자에게 요청 내용을 다시 물어보세요.

텍스트 애플리케이션에서는 사용자의 최신 메시지를 에이전트에 바로 전달할 수 있습니다. GPT-Live를 사용할 때는 해당 컨텍스트를 제공하고 검증된 결과를 간결하게 반환하는 어댑터를 추가하세요.

어댑터를 호출하기 전에 위임 ID를 기록해 해당 위임의 작업을 시작하는 핸들러가 하나뿐이도록 하세요. 요청이 불분명하다면 컨텍스트가 준비된 뒤 어댑터를 다시 호출하세요.

권한 검사, 사용자 확인, 작업 ID, 재시도는 계속 백엔드가 담당합니다. 예약을 변경하기 전에 작업의 현재 리비전을 확인하세요. 나중에 어댑터가 리비전을 검사하는 것은 오래된 결과가 안내되는 것을 막을 뿐입니다. 이미 이루어진 예약을 되돌릴 수는 없습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25async function handleDelegation(event, app) {
  if (
    event.type !== "session.delegation.created" ||
    event.delegation?.target !== "client"
  )
    return;

  const context = app.readContext();
  if (!context) return; // Retain the notice; resolve the request before acting.

  const summary = await app.runAgent({
    revision: context.revision,
    recentConversation: context.recentConversation,
    task: context.task,
  });

  if (app.currentRevision() !== context.revision) return;

  app.send({
    type: "session.commentary.append",
    event_id: crypto.randomUUID(),
    delegation_id: event.delegation.id,
    content: summary,
  });
}

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
32
33
34
35
36
37
38
39
40from collections.abc import Awaitable, Callable
from dataclasses import dataclass
from uuid import uuid4

from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection
from openai.types.live.server_event import ServerEvent


@dataclass(frozen=True)
class Context:
    revision: int
    recent_conversation: str
    task: str


async def handle_delegation(
    event: ServerEvent,
    connection: AsyncLiveConnection | AsyncSidebandConnection,
    *,
    read_context: Callable[[], Context | None],
    run_agent: Callable[[Context], Awaitable[str]],
    current_revision: Callable[[], int],
) -> None:
    if (
        event.type != "session.delegation.created"
        or event.delegation.target != "client"
    ):
        return
    context = read_context()
    if context is None:
        return  # Retain the notice; resolve the request before acting.
    summary = await run_agent(context)
    if current_revision() != context.revision:
        return
    await connection.session.commentary.append(
        event_id=str(uuid4()),
        delegation_id=event.delegation.id,
        content=summary,
    )

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
32
33
34import (
	"context"
	"crypto/rand"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/live"
)

type Context struct {
	Revision           int
	RecentConversation string
	Task               string
}

func handleDelegation(ctx context.Context, event live.ServerEventUnion, connection *live.LiveConnection,
	readContext func() *Context, runAgent func(context.Context, Context) (string, error), currentRevision func() int) error {
	if event.Type != "session.delegation.created" || event.AsDelegationCreatedEvent().Delegation.Target != "client" {
		return nil
	}
	snapshot := readContext()
	if snapshot == nil {
		return nil
	} // Retain the notice; resolve the request before acting.
	saved := *snapshot
	summary, err := runAgent(ctx, saved)
	if err != nil {
		return err
	}
	if currentRevision() != saved.Revision {
		return nil
	}
	return connection.Send(ctx, live.ClientEventUnionParam{OfSessionCommentaryAppend: &live.CommentaryAppendEventParam{
		EventID: openai.String(rand.Text()), DelegationID: openai.String(event.AsDelegationCreatedEvent().Delegation.ID), Content: summary,
	}})
}

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
32
33
34import com.openai.helpers.LiveConnection;
import com.openai.models.live.*;
import java.util.UUID;
import java.util.concurrent.CompletionStage;
import java.util.function.*;

public record Context(int revision, String recentConversation, String task) {}

public static CompletionStage<Void> handleDelegation(
    ServerEvent event,
    LiveConnection connection,
    Supplier<Context> readContext,
    Function<Context, CompletionStage<String>> runAgent,
    IntSupplier currentRevision) {
  if (!event.isSessionDelegationCreated()
      || !event.asSessionDelegationCreated().delegation().target().toString().equals("client"))
    return java.util.concurrent.CompletableFuture.completedFuture(null);
  var snapshot = readContext.get();
  // Retain the notice; resolve the request before acting.
  if (snapshot == null) return java.util.concurrent.CompletableFuture.completedFuture(null);
  return runAgent
      .apply(snapshot)
      .thenAccept(
          summary -> {
            if (currentRevision.getAsInt() != snapshot.revision()) return;
            connection.send(
                ClientEvent.ofSessionCommentaryAppend(
                    CommentaryAppendEvent.builder()
                        .eventId(UUID.randomUUID().toString())
                        .delegationId(event.asSessionDelegationCreated().delegation().id())
                        .content(summary)
                        .build()));
          });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18require "openai"
require "securerandom"
Context = Data.define(:revision, :recent_conversation, :task)

def handle_delegation(event, connection, read_context:, run_agent:, current_revision:)
  return unless event.type == :"session.delegation.created" && event.delegation.target == :client

  context = read_context.call
  return if context.nil? # Retain the notice; resolve the request before acting.

  summary = run_agent.call(context)
  return unless current_revision.call == context.revision

  connection.send_event(
    type: :"session.commentary.append", event_id: SecureRandom.uuid,
    delegation_id: event.delegation.id, content: summary
  )
end

애플리케이션에서 컨텍스트 콜백과 에이전트 콜백을 구현하세요. 컨텍스트 콜백은 최근 대화와 현재 작업을 반환하고, 요청이 여전히 불분명하면 값을 반환하지 않습니다. 에이전트 콜백은 기존 백엔드를 실행하고 최대 500토큰의 검증된 요약을 반환합니다. JavaScript에서는 애플리케이션이 제공하는 send 콜백이 Live 연결로 JSON 이벤트를 보냅니다. Python에서는 어댑터가 SDK의 connection을 통해 직접 업데이트를 보냅니다.

예약 어시스턴트의 컨텍스트에는 요청한 날짜와 시간대, 이전에 제안한 예약 가능 시간, 사용자가 확인한 시간, 가장 최근의 정정 사항이 명확히 드러나야 합니다. 예약 가능 시간 조회 결과에는 해당 시간에 예약할 수 있으며 아직 예약이 이루어지지 않았다는 점을 명시하세요. 예약에 성공한 뒤에만 예약 완료 확인을 반환하세요. 전체 설정과 결과 처리 플로우는 클라이언트 위임을 참고하세요.

업데이트와 정정 사항 전달하기

구조화된 도구 출력과 워크플로우 세부 정보는 백엔드에 두세요. GPT-Live에는 사실에 근거한 짧은 업데이트를 반환하세요.

• 조회가 아직 진행 중이라는 알림처럼 백그라운드 작업의 진행 상황에는 session.thinking.append를 사용하세요.
• 사용자가 들어야 하는 검증된 결과에는 session.commentary.append를 사용하세요.
• 애플리케이션에서 작성한 행동 지침에는 session.instructions.append를 사용하세요.

세 이벤트 모두 content에 최대 500토큰의 일반 문자열을 받으며 delegation_id가 필요합니다. 관련 작업에는 원래 클라이언트 위임 ID를 사용하고, 일반적인 세션 컨텍스트에는 null을 사용하세요. client_event_id를 사용해 각 수신 확인을 해당 명령과 연결하세요. 이 확인은 업데이트가 수락되었음을 뜻합니다. 생성된 발화는 어시스턴트 전사 이벤트로 확인하고 실제 재생 상태는 플레이어에서 추적하세요. 용도에 맞는 업데이트 보내기를 참고하세요.

사용자가 “아, 금요일로 바꿀게요”라고 하면 금요일을 현재 요청으로 저장하고 버전 번호를 올린 뒤 목요일에 대해 받은 확인은 지우세요. 기존 에이전트에 정정 사항을 보내세요. 목요일 조회의 취소를 요청할지, 조회 내용을 바꿀지, 완료될 때까지 기다린 뒤 결과를 버릴지 결정하세요.

조회가 취소되었다고 알리기 전에 실제 상태를 추적하세요. 사용자가 끼어들어 어시스턴트의 발화가 이미 멈췄더라도 백엔드에서는 해당 조회를 어떻게 처리할지 결정하고 조치하세요.

음성 세션이 끝난 뒤에도 백엔드 작업이 계속될 수 있습니다. 애플리케이션에 작업 상태를 영속적으로 저장하세요. 나중에 다시 음성으로 대화할 때는 저장된 관련 컨텍스트로 새 세션을 시작하세요. 세션 관리하기를 참고하세요.

직접 입력한 텍스트를 에이전트에 계속 전달하기

직접 입력한 텍스트는 계속 기존 백엔드로 보내세요. 텍스트로 정정한 내용도 같은 작업의 업데이트로 처리하고, 검증된 관련 컨텍스트를 음성 세션에 보내세요. 텍스트 입력 받기와 정확하고 유용한 업데이트 제공하기를 참고하세요.

텍스트와 음성 보호 조치 조정하기

텍스트 에이전트나 다단계 파이프라인은 완성된 답변을 화면에 표시하거나 음성으로 재생하기 전에 검증할 수 있습니다. GPT-Live에서는 대화와 백엔드 작업이 동시에 진행됩니다. 사용자가 듣기 전에 모든 음성 응답이 검사를 통과해야 한다면 애플리케이션이 제어하는 오디오 재생 경로에 검사를 넣으세요. 백엔드 결과 전달을 보류해도 GPT-Live는 계속 말할 수 있습니다.

가드레일 조정하기에 따라 기존 검사를 유지하면서 발화가 계속될 수 있다는 점을 반영하세요.