For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme

추천

GPT-Live

Realtime API

음성 기능 개발

연결

오디오 처리

API 대시보드
ChatGPT 사용해 보기

GPT-Live의 위임과 도구 사용

백엔드 에이전트를 연결하고 검증된 결과를 실시간 대화에 전달하세요.

GPT-Live는 음성 대화를 진행하면서 추론과 도구 사용을 백엔드에 위임합니다. 백엔드 작업은 설정된 Responses 모델에서 실행할 수 있습니다. 클라이언트 위임을 사용하면 애플리케이션이 운영하는 어떤 모델, 에이전트 또는 서비스에서든 실행할 수 있습니다. 어느 모드에서든 권한, 사용자 확인, 업무 기록, 작업 상태는 애플리케이션이 관리합니다.

프롬프팅 가이드에서 실시간 모델의 위임과 도구 사용을 제어하는 방법을 자세히 알아보세요.

이 페이지의 이벤트 예제에서는 connection을 사용합니다. 이는 연결 가이드에 따라 연결한 기본 Live WebSocket 또는 사이드밴드 연결입니다. 기본 연결에서는 session.started를 받은 후 이벤트 헬퍼를 호출하세요. 연결된 사이드밴드는 이미 실행 중인 세션에 속합니다.

위임 모드 선택하기

Responses 위임 모드에서는 GPT-Live가 개발자가 지정한 Responses 모델을 호출하고 대화 컨텍스트를 제공한 뒤 백엔드 결과를 실시간 대화에 전달합니다. 클라이언트 위임 모드에서는 애플리케이션이 컨텍스트를 준비하고 에이전트나 워크플로우를 실행한 뒤 결과를 GPT-Live에 보냅니다.

GPT-Live가 요청을 관리하도록 하려면 Responses 위임으로 시작하세요. 자체 워크플로우를 실행하거나 결과를 GPT-Live에 보내기 전에 검토해야 한다면 클라이언트 위임을 선택하세요.

고려 사항 Responses 위임이 적합한 경우 클라이언트 위임이 적합한 경우
구현 부담 백엔드 요청 준비, 연결 관리, 대화에 결과 전달을 GPT-Live에 맡기고 싶습니다. 이 기능들을 직접 구현하고 운영하고 싶습니다.
백엔드 결과 검토 백엔드 출력을 GPT-Live에 바로 전달해도 됩니다. GPT-Live에 전달하기 전에 애플리케이션에서 결과를 검증하거나 민감한 내용을 가리거나 여러 결과를 합치거나 폐기해야 합니다.
백엔드 기능 GPT-Live가 지원하는 Responses 설정과 도구로 워크플로우를 실행할 수 있습니다. 다른 백엔드나 여러 모델이 필요하거나 관리형 설정에서 제공하는 범위를 넘어서는 API 기능이 필요합니다.
컨텍스트 관리 GPT-Live가 제공하는 대화 컨텍스트가 애플리케이션에 적합합니다. 각 백엔드 요청에 포함할 대화 기록, 메모리, 애플리케이션 상태를 직접 지정해야 합니다.
실행 정책 설정된 모델과 도구 호출 루프로 작업을 처리할 수 있습니다. 코드와 모델 간의 사용자 정의 라우팅, 대체 처리 경로, 체크포인트 또는 여러 백엔드 단계에 걸친 예산 관리가 필요합니다.

예를 들어 여행 어시스턴트는 항공편 운항 상태에 관한 질문을 항공사 서비스에 보내고 일정 변경 요청은 별도의 여행 계획 에이전트에 보낼 수 있습니다. 어느 백엔드를 호출하고 검증된 결과 중 무엇을 GPT-Live에 전달할지는 애플리케이션이 결정합니다.

두 모드 모두 애플리케이션이 작업 진행 상황을 추적하고, 사용자 정의 도구를 실행하기 전에 권한이 있는지, 필요한 사용자 확인을 받았는지 점검합니다. 애플리케이션이 백엔드 결과를 검토하는 동안에도 GPT-Live는 계속 말할 수 있습니다. 사용자가 음성을 듣는 시점을 애플리케이션에서 제어해야 한다면 재생 제어 기능을 추가하세요.

클라이언트 위임에서는 애플리케이션이 대화 컨텍스트도 유지해야 합니다. 위임 이벤트에는 메타데이터만 있고 작업 내용은 없습니다. 전사 이벤트와 애플리케이션 상태를 사용해 백엔드 요청을 준비하세요.

실제 워크로드에서 음성 에이전트를 평가할 때는 지연 시간, 작업 성공률, 비용을 비교하세요. 기존 아키텍처에 맞는 지침은 GPT-Live로 마이그레이션을 참고하세요.

세션을 생성할 때 모드를 선택하세요. 모드를 변경하려면 새 세션을 시작하세요.

위임 모드

Responses 위임 설정하기

다음 위임 설정을 Live 세션을 생성할 때 추가하세요. Responses 모델은 음성 모델과 별도로 선택하세요.

export const session = {
  model: "gpt-live-1",
  delegation: {
    type: "responses",
    responses: {
      model: "gpt-6-luna",
      instructions: "[Your backend prompt]",
    },
  },
};

먼저 gpt-6-luna를 사용하거나, 더 복잡한 백엔드 작업에는 gpt-6-sol을 사용해 보세요. 백엔드 모델을 선택하기 전에 실제 작업에서 답변 품질과 지연 시간을 비교하세요.

지원되는 도구를 delegation.responses.tools에 등록하세요. delegation.responses.tool_choice를 "auto"로 설정하면 백엔드가 도구를 선택하고, "required"로 설정하면 도구 호출이 필수가 되며, "none"으로 설정하면 도구 호출이 비활성화됩니다. 이름으로 특정 함수를 선택할 수도 있습니다.

한 응답에서 도구 호출을 여러 번 허용하려면 delegation.responses.parallel_tool_calls를 true로 설정하세요. 순차적으로 호출하려면 false로 설정하세요. 사용자 정의 함수를 실행하고 종속성과 필요한 승인을 확인하는 일은 애플리케이션이 담당합니다. 이 설정은 GPT-Live가 작업을 위임한 후에 적용됩니다. 언제 위임해야 하는지는 실시간 모델의 프롬프트에 명시하세요.

Responses 설정에는 세션 생성 시 백엔드 model을 지정해야 합니다. 아래 도구 외에도 max_output_tokens(설정 시 최소 16), service_tier, 선택한 백엔드 모델이 지원하는 reasoning 및 text 설정을 사용할 수 있습니다. 조정할 수 있는 설정은 백엔드 지연 시간 줄이기를 참고하세요.

모델과 프로젝트에서 패스트 모드를 사용할 수 있다면 지연 시간에 민감한 호출에 적용해 보세요. GPT-Live에서는 delegation.responses.service_tier: "priority"로 선택합니다.

대화 중에 설정을 변경하려면 session.update를 보낼 때 변경 사항을 session.delegation.responses에 포함하세요. 백엔드 모델, 지침, 도구, tool_choice 또는 그 밖의 지원 설정을 업데이트할 수 있습니다. 생략한 설정은 현재 값을 유지합니다.

Responses 위임과 클라이언트 위임 간에 전환하려면 새 Live 세션을 생성하세요. delegation을 null로 업데이트하면 클라이언트 모드가 선택되므로 실행 중인 Responses 세션에 이 업데이트를 보내면 immutable_field_update 오류가 발생합니다.

이 설정에는 익숙한 Responses 개념이 사용되지만 Live는 독립형 Responses API 기능 중 일부만 지원합니다. 대화 컨텍스트를 제공하고 위임 작업을 시작하는 것은 Live입니다. 백엔드는 세션을 통해 설정하세요. Live의 response.create 명령어는 해당 설정을 사용하며 독립형 Responses 요청 본문을 받지 않습니다.

호스팅 도구 추가하기

호스팅 도구를 사용하려면 웹 검색, 파일 검색, 코드 인터프리터, 호스팅 셸 또는 이미지 생성을 delegation.responses.tools에 추가하세요. 각 가이드에서 설정 방법, 지원 모델, 필요한 리소스를 확인하세요. Responses가 이 도구들을 실행하고 결과를 자동으로 반환합니다.

셸에는 호스팅 컨테이너를 사용하세요. 필요에 따라 스킬을 함께 사용할 수 있습니다. 새로 업로드한 스킬은 참조한 버전을 읽을 수 있을 때까지 기다린 후 Live 세션을 시작하세요. 로컬 셸 호출은 애플리케이션이 실행해야 합니다. Live는 셸의 domain_secrets를 지원하지 않습니다.

MCP 및 기타 도구 추가하기

Responses 위임은 MCP, 도구 검색, 프로그래밍 방식의 도구 호출, 함수와 사용자 정의 도구, 컴퓨터 사용, 로컬 셸, 패치 적용도 지원합니다. 설정 방법은 각 가이드를 참고하세요. 애플리케이션의 실행 결과와 승인 결정은 Live 작업 재개 플로우를 통해 반환하세요.

Live는 제공된 MCP authorization과 headers를 Responses에 전달하지만, 애플리케이션에 돌려주는 세션 설정에는 해당 값을 포함하지 않습니다. 지침 등 다른 설정을 업데이트할 때는 이 값을 다시 보낼 필요가 없습니다. delegation.responses.tools를 교체할 때는 MCP 인증 정보를 다시 포함하세요.

설정 오류 처리하기

Live는 시작 후와 설정 변경 시 Responses 설정을 비동기로 검증합니다. session.started와 session.updated는 검증이 끝나기를 기다리지 않습니다. error 이벤트의 코드가 responses_validation_failed이면 메시지에서 지원되지 않는 설정이나 접근할 수 없는 리소스를 확인하세요. 세션은 열린 상태로 유지되고 설정도 롤백되지 않으므로 session.update로 수정하세요.

예를 들어 스킬의 version에 1과 같은 숫자를 지정하면 responses_validation_failed 오류가 session.start 또는 session.update에서 발생하지만 세션은 종료되지 않습니다. 오류 메시지에서 잘못된 필드와 필요한 타입을 바로 확인할 수 있으므로 response.create를 기다릴 필요가 없습니다. error.client_event_id로 해당 설정 이벤트를 찾으세요. 같은 세션에서 복구하려면 session.update로 잘못된 도구 설정을 제거하세요. 버전은 "1"과 같은 문자열로 지정하세요.

검증을 통과해도 이후 도구 실행이 보장되지는 않습니다. 리소스 접근 권한이나 도구 가용성이 바뀔 수 있으므로 위임 작업 중에도 백엔드 오류를 계속 처리하세요. 호스팅 도구를 설정하면 검증 중에 컨테이너 등의 리소스가 초기화될 수 있습니다.

애플리케이션에서 실시간 대화 제어하기

Responses 위임이 백엔드 워크플로우를 관리하더라도 애플리케이션은 GPT-Live 모델에 컨텍스트를 직접 보낼 수 있습니다. 사이드밴드 WebSocket 또는 기본 이벤트 연결로 통화를 모니터링한다면 session.instructions.append, session.thinking.append 또는 session.commentary.append에 delegation_id: null을 지정해 사용할 수 있습니다. 예를 들어 전사 내용을 검사하는 가드레일에서 대화의 방향을 바꾸는 지침을 추가할 수 있습니다. 이 지침은 실시간 모델에 적용되며 Responses 백엔드 프롬프트를 변경하거나 진행 중인 작업을 취소하지 않습니다.

Responses 위임 처리하기

Responses가 처리하는 작업의 session.delegation.created 이벤트에는 target: "responses"와 response_id가 있습니다. 이후 Responses 이벤트는 response.event로 감싸져 전달됩니다.

{
  "type": "response.event",
  "event_id": "event_response_1",
  "delegation_id": "item_9tA2cB6n2V8c4X1z7Q5r9",
  "event": {
    "type": "response.output_text.delta",
    "sequence_number": 4,
    "item_id": "msg_123",
    "output_index": 0,
    "content_index": 0,
    "delta": "The forecast is",
    "logprobs": []
  }
}

최상위 이벤트 타입이 response.event이면 envelope.event.type에 따라 처리를 분기하세요. 백엔드 이벤트를 해당 위임과 연결할 수 있도록 바깥쪽 delegation_id를 저장하세요. 핸들러에는 여기서 소개한 것 외에도 Responses 수명 주기 이벤트가 중첩된 형태로 전달될 수 있습니다.

호스팅 도구의 진행 상황, 인용 출처, 파일, 생성된 이미지는 이 중첩 이벤트로 전달됩니다. 전달되는 수명 주기 스냅샷에는 출력 배열의 내용이 생략되므로 개별 출력 항목 이벤트와 부분 이미지 이벤트에서 결과를 수집하세요. 파일을 다운로드하려면 해당 Responses 파일 API 또는 컨테이너 API를 사용하세요. WebRTC 데이터 채널은 메시지 크기 제한이 더 작을 수 있으므로 대용량 이미지나 아티팩트 이벤트에는 WebSocket 또는 사이드밴드 연결을 사용하세요.

실시간 음성 출력과 위임 작업은 서로 독립적으로 진행됩니다. 백엔드 응답이 완료되었다고 해서 사용자가 답변을 들었다는 뜻은 아닙니다. 음성 답변의 내용은 Live 출력 전사와 오디오를 사용해 확인하세요.

도구 결과와 승인 결정 반환하기

애플리케이션 입력이 필요한 도구는 중첩된 response.output_item.done 이벤트에서 완료된 호출을 수집하세요. 권한이 있는 작업을 실행하거나 승인 여부를 확인한 뒤 response.item.create로 해당 결과 항목을 보내세요.

수신한 항목 결과 항목
function_call function_call_output
custom_tool_call custom_tool_call_output
computer_call computer_call_output
로컬 shell_call shell_call_output
apply_patch_call apply_patch_call_output
tool_search_call 중 execution: "client"인 항목 tool_search_output에 execution: "client"와 검색된 tools 포함
mcp_approval_request mcp_approval_response

결과와 호출은 call_id로 연결하세요. MCP 승인 결정의 경우에는 대신 approval_request_id를 승인 요청의 id로 설정하고 approve를 true 또는 false로 설정하세요. 완료된 mcp_call 자체에는 클라이언트 결과가 필요하지 않습니다. 프로그래밍 방식으로 호출한 함수의 caller 메타데이터와 컴퓨터 사용에 필요한 안전 확인을 포함해 각 도구의 결과 스키마를 따르세요.

대기 중인 모든 호출의 결과를 제출한 후 response.create를 보내세요. 항목을 추가하는 것만으로는 백엔드가 작업을 재개하지 않습니다. 결과가 누락되면 tool_outputs_required 오류가 발생하고, 함수 결과만 누락되면 function_call_outputs_required 오류가 발생합니다. 중복 결과나 호출과 타입이 맞지 않는 결과는 거부됩니다.

현재 백엔드 응답이 완료되기 전에도 결과를 제출하고 작업 재개를 요청할 수 있습니다. 수락된 response.create는 현재 응답이 완료될 때까지 기다리므로 다시 보내지 마세요. 이후 백엔드가 추가 호출을 생성하면 그 결과를 제출한 뒤 response.create를 다시 보내세요.

사용자 정의 함수를 실행하고 결과 반환하기

중첩된 response.output_item.done 이벤트에서 완료된 함수 호출을 읽으세요. 완성된 함수 항목에는 call_id, name, arguments가 들어 있습니다. 인수 생성이 끝났음을 알리는 이벤트만으로는 호출을 식별할 수 없습니다.

중첩된 response.created의 응답 ID와 바깥쪽 delegation_id를 함께 추적하세요. response.output_item.done에서 해당 응답의 함수 호출을 수집한 뒤, 이 목록을 기준으로 작업을 재개하기 전에 제출할 도구 결과를 결정하세요.

전달되는 수명 주기 이벤트에는 response.completed를 포함해 함수 호출에 결과가 필요한 경우에도 response.output: []가 들어 있습니다. 이 이벤트에서는 tools 배열도 비어 있고 instructions: null이며 input 필드는 없습니다. 함수 호출은 개별 출력 항목 이벤트에서 읽으세요.

권한이 있는 작업을 실행한 후 결과를 Responses 항목으로 추가하세요.

export function sendUpdate(connection) {
  connection.send({
    type: "response.item.create",
    event_id: "tool_result_1",
    item: {
      type: "function_call_output",
      call_id: "call_123",
      output: '{"status":"confirmed","order_id":"order_123"}',
    },
  });
}

그런 다음 응답 재개를 명시적으로 요청하세요.

export function sendUpdate(connection) {
  connection.send({
    type: "response.create",
    event_id: "continue_1",
  });
}

대기 중인 함수 호출마다 response.item.create로 결과를 보내고, 이어서 response.create를 보내 백엔드 응답을 재개하세요. response.item.create에는 별도의 성공 확인 이벤트가 없으므로 오류와 중첩된 Responses 수명 주기 이벤트를 계속 처리하세요.

두 명령어 모두 Responses 위임이 필요합니다. Live의 response.create 명령어는 세션에 저장된 백엔드 설정을 사용합니다. 위에 나온 이벤트 페이로드를 사용하고 백엔드 모델과 기타 설정은 세션을 통해 지정하세요.

기존 백엔드 프롬프트로 시작하기

기존 텍스트 에이전트의 프롬프트를 출발점으로 삼으세요. 작업 지침과 업무 규칙은 백엔드에 유지하고, 텍스트 채팅이나 음성 출력의 직접 제어를 전제로 한 지침은 수정하세요. 음성 전사를 처리하고 유용한 결과를 반환하는 방법을 설명하세요. 권한 검사와 필수 사용자 확인은 애플리케이션에서 강제하세요.

## 음성 대화 컨텍스트
실시간 음성 대화를 진행하는 어시스턴트를 도와주세요. 전사 내용에는 오류나
끝맺지 않은 문구가 있을 수 있고, 사용자가 앞선 발언을 나중에 정정할 수도 있습니다.
최신 컨텍스트와 검증된 기록을 사용하세요. 필요한 정보가 여전히 불분명하다면
추측하지 말고 해당 정보를 물어보세요.

## 작업 지침
[Your task instructions, business rules, available tools,
and confirmation requirements.]

## 결과 반환
관련 사실, 현재 작업 상태, 다음 단계를 반환하세요.
도구나 서비스에서 성공을 확인한 후에 작업이 완료되었다고 알리세요.
결과가 불분명하다면 그 사실을 밝히고 무엇을 확인해야 하는지 설명하세요.

대용량 구조화 페이로드, 긴 도구 출력, 화면 표시용 Markdown은 백엔드에 보관하세요. GPT-Live에는 관련 사실을 전달하고 표현 방식은 모델에 맡기세요. 도구 결과가 간결하다면 음성에 맞게 다시 작성하기 위해 모델을 추가로 호출할 필요가 없습니다.

클라이언트 위임에서는 결과를 GPT-Live에 직접 반환하세요. Responses 위임에서는 필요한 도구 결과나 승인 결정을 반환해 백엔드 작업을 재개하세요. 호스팅 도구는 애플리케이션에서 결과를 보내지 않아도 계속 실행됩니다.

용도에 맞는 업데이트 보내기

GPT-Live가 내용을 어떻게 사용해야 하는지에 따라 이벤트를 선택하세요.

보낼 내용 이벤트
고지 사항을 알리거나 말을 멈추도록 하는 등 진행 중인 실시간 대화에 적용할 지침 session.instructions.append
추가하는 즉시 말하지 않고 이후 관련 질문을 받으면 내부 추론에 활용할 정보 session.thinking.append
모델이 추가된 텍스트를 자신의 표현으로 바꾸어 소리 내어 전달할 정보 session.commentary.append

세 이벤트 모두 content에 일반 문자열을 사용하며 한 번에 추가할 수 있는 내용은 500토큰까지입니다. delegation_id를 포함하세요. 특정 작업의 업데이트에는 원래 클라이언트 위임 ID를 사용하고, 일반적인 세션 컨텍스트에는 null을 사용하세요. null이 아닌 ID는 이미 존재하는 클라이언트 위임을 가리켜야 합니다. ID를 지정해도 지침은 실시간 세션에 적용되며 별도의 백엔드 프롬프트가 되지 않습니다.

첫인사를 하려면 세션 생성 시 developer 메시지를 session.input에 포함하고 그 메시지에 인사 지침을 넣으세요. session.started 이후 오디오 입력이 활성화된 상태에서 session.commentary.append로 같은 지침을 한 번만 보내세요. 이때 고유한 event_id와 delegation_id: null을 사용하세요. 모델이 표현을 바꾸어 말할 수 있으며, 확인 이벤트를 받더라도 음성이 생성되거나 재생되었다는 보장은 없습니다. 전체 이벤트 순서와 정확한 문구나 전달 확인이 필요할 때 애플리케이션에서 재생을 제어하는 방법은 통화 상대가 말하기 전에 인사하기를 참고하세요.

지침을 추가하면 모델이 하던 말이나 행동이 중단될 수 있습니다. 대화 방향을 바꿔야 할 때 사용하세요. 관련 도구나 작업을 차단해야 한다면 애플리케이션 상태에서 차단을 강제하세요.

클라이언트가 관리하는 작업의 진행 상황을 음성 안내 없이 전달하려면 다음과 같이 하세요.

export function sendUpdate(connection) {
  connection.send({
    type: "session.thinking.append",
    event_id: "availability_progress",
    delegation_id: "item_123",
    content: "Checking Thursday availability. No appointment has been booked.",
  });
}

예약이 확정되면 사용자가 들어야 할 결과를 보내세요.

export function sendUpdate(connection) {
  connection.send({
    type: "session.commentary.append",
    event_id: "appointment_result",
    delegation_id: "item_123",
    content: "Your appointment is confirmed for Thursday at 2:00 PM",
  });
}

예약이 실제로 성공한 후에만 이 결과를 보내세요. 세션 전체에 적용할 지침에는 session.instructions.append와 delegation_id: null을 사용하세요.

예를 들어 애플리케이션의 가드레일에 따라 요청을 차단한 후 다음과 같이 대화 방향을 바꿀 수 있습니다.

export function sendUpdate(connection) {
  connection.send({
    type: "session.instructions.append",
    event_id: "guardrail_block_17",
    delegation_id: null,
    content:
      "Stop speaking about that request. Briefly explain that you cannot help with it, then wait for the user.",
  });
}

지침을 보내도 백엔드 작업은 취소되지 않습니다. 애플리케이션에서 해당 작업을 차단하고 이미 실행 중인 작업을 처리하세요.

각 업데이트에 대응하는 확인 이벤트는 session.thinking.appended, session.commentary.appended, session.instructions.appended입니다. 확인 이벤트의 client_event_id를 보낸 이벤트의 event_id와 대조하세요. 확인 이벤트는 컨텍스트가 모델에 반영되었을 것으로 추정되는 시점까지 기다리지만 음성 생성이나 재생이 끝날 때까지 기다리지는 않습니다. 시점과 오류 처리에 관한 자세한 내용은 컨텍스트가 모델에 전달되는 시점을 참고하세요.

GPT-Live가 대화에 활용할 수 있는 사실과 간략한 진행 상황을 보내세요. session.thinking.append로 보낸 내용은 이후 음성 답변에 영향을 줄 수 있으므로 비밀 정보와 비공개 백엔드 추론 내용은 애플리케이션에 보관하세요.

도구 실행 중 자동 확인 응답 억제하기

클라이언트 위임에서는 대기 중인 자동 확인 응답이 생성되기 전에 음성 출력을 요청하지 않는 컨텍스트 업데이트를 보내 해당 응답을 취소할 수 있습니다.

세션 생성 시 delegation.acknowledgement_delay_ms를 설정해 애플리케이션이 업데이트를 보낼 시간을 확보하세요. 예를 들어 다음과 같이 클라이언트 위임을 설정할 수 있습니다.

{
  "delegation": {
    "type": "client",
    "acknowledgement_delay_ms": 800
  }
}

위임 이벤트인 session.delegation.created를 받는 즉시 session.thinking.append를 보내고 content는 빈 문자열로 설정하세요. 고유한 event_id를 사용하고 event.delegation.id를 delegation_id에 복사하세요. 백엔드 결과를 기다리기 전에 이 이벤트를 보내세요.

{
  "type": "session.thinking.append",
  "event_id": "event_quiet_progress_1",
  "delegation_id": "item_9tA2bF3h7K9m2P5q8R1s4",
  "content": ""
}

백엔드 작업을 계속 진행하고 검증된 결과를 음성으로 안내할 준비가 되면 같은 위임 ID로 session.commentary.append를 보내세요. 진행 상황을 컨텍스트로 제공하려면 추론용 업데이트에 "Lookup in progress."처럼 사실을 담은 메시지를 넣어도 됩니다. 이 경우에도 모델에 해당 내용을 말하도록 요청하지 않으면서 대기 중인 확인 응답을 취소할 수 있습니다.

추론용 업데이트나 음성 안내용 업데이트를 추가하면 다른 위임에 대한 응답까지 포함해 세션에서 대기 중인 모든 자동 확인 응답이 취소됩니다. 이미 생성된 오디오를 중지하거나 모델이 별도로 말하는 것까지 막지는 않습니다. 지연 설정은 자동 확인 응답을 요청하는 시점을 제어하므로 모델이 그보다 먼저 말할 수도 있습니다. 이벤트 규약은 클라이언트 위임 설정 및 추론용 업데이트 레퍼런스를 참고하세요.

컨텍스트 전달 여부를 확인하려면 session.thinking.appended 이벤트의 client_event_id를 보낸 이벤트의 ID와 대조하세요. 실제로 음성이 나오지 않는지는 해당 워크로드에서 오디오를 테스트하세요. 무음을 보장해야 한다면 애플리케이션에서 재생을 제어하세요.

정확하고 유용한 업데이트 보내기

시간이 오래 걸리는 작업에서는 한 단계가 끝났거나, 지연을 알려야 하거나, 사용자에게 질문해야 하는 등 의미 있는 변화가 있을 때 업데이트를 보내세요.

클라이언트 모드에서 백그라운드 진행 상황에는 session.thinking.append를 사용하세요. 사용자에게 음성으로 알려 줄 만한 내용에는 session.commentary.append를 사용하세요.

음성 안내에는 session.commentary.append를 사용하고 확인된 작업 상태와 일치하는 내용을 보내세요.

상태 예시 문구
진행 중 “예약 가능한 시간을 확인하고 있습니다.”
완료 “목요일 오후 2시로 예약되었습니다.”
실패 “해당 시간은 더 이상 예약할 수 없습니다.”
취소 확인 “예약이 취소되었습니다.”

사용자가 요청을 변경하면 애플리케이션에서 진행 중인 작업을 업데이트하세요. 예를 들어 금요일을 목요일로 바꾸면 이후 작업에는 목요일을 사용하고 이전 금요일 요청의 결과는 무시하세요. 취소는 백엔드에서 처리하고 취소에 성공한 것을 확인한 후 사용자에게 알리세요. 음성 대화를 중단해도 백엔드 작업은 계속 실행됩니다.

실패한 도구 호출을 재시도하기 전에 원래 작업이 이미 실행되었는지 확인하세요. 예를 들어 응답이 유실되었다는 이유로 같은 예약을 두 번 생성해서는 안 됩니다. 결과가 불분명하면 그 사실을 알리고 다음에 할 수 있는 일을 제안하세요.

UI 컨텍스트 공유하기

현재 페이지나 작업, 관련 선택 항목, “이 옵션” 같은 표현이 무엇을 가리키는지 이해하는 데 필요한 사실을 간략히 정리해 GPT-Live에 전달하세요. 애플리케이션 상태에서 직접 요약을 구성하면 됩니다. 형식을 다듬기 위해 모델을 추가로 호출할 필요는 없습니다.

세션 시작 시점과 관련 상태가 변경될 때 UI 컨텍스트를 보내세요. 상태가 그대로라면 업데이트를 생략하고, 빠르게 연속으로 변경되면 최신 상태를 짧게 요약해 한 번에 보내세요. 이전 선택에서 무엇이 바뀌었는지 명확히 밝히세요.

  • 초기 컨텍스트: “사용자가 8월 6일 오후 7시, 2인 식당 예약을 검토하고 있습니다. 아직 예약하지 않았습니다.”
  • 정정: “선택한 시간이 오후 8시로 바뀌었습니다. 이전에 선택한 시간은 오후 7시였습니다.”

어느 위임 모드에서든 session.thinking.append와 delegation_id: null을 사용해 백그라운드 컨텍스트 업데이트를 보내세요. HTML 전문, DOM 트리, 대용량 JSON 페이로드, 상호작용 로그는 애플리케이션이나 백엔드에 보관하세요. 페이지 콘텐츠는 지침으로 실행하지 말고 참고 데이터로 취급하세요.

텍스트 입력 받기

주문 번호처럼 사용자가 직접 입력한 값은 사용자 제공 데이터로 백엔드에 보내세요. 그러면 백엔드에서 입력한 텍스트를 그대로 사용할 수 있습니다.

Responses 위임에서는 백엔드가 처리할 사용자 메시지를 대기열에 추가하세요.

export function sendUpdate(connection) {
  connection.send({
    type: "response.item.create",
    event_id: "typed_order_number",
    item: {
      type: "message",
      role: "user",
      content: [
        {
          type: "input_text",
          text: "My order number is A0042.",
        },
      ],
    },
  });
}

백엔드를 실행하거나 작업을 재개할 준비가 되면 response.create를 보내세요. 백엔드가 함수 결과를 기다리고 있다면 필요한 결과를 모두 먼저 반환하세요. 텍스트를 대기열에 추가해도 이미 실행 중인 작업은 취소되지 않습니다.

이미지와 시각적 컨텍스트 추가하기

통화 상대가 사진이나 화면에 관해 대화할 수 있도록 애플리케이션에서 이미지와 관련 컨텍스트를 이미지 입력을 지원하는 백엔드에 보내세요. 백엔드가 이미지를 해석하고 GPT-Live가 대화에 활용할 텍스트를 반환합니다. Live 오디오 프런트엔드는 이미지를 직접 받지 않습니다.

Responses 위임에서는 이미지 입력을 지원하는 백엔드 모델을 설정하세요. response.item.create로 Responses가 지원하는 이미지 입력 항목을 대기열에 추가한 뒤 response.create를 보내 백엔드 작업을 실행하거나 재개하세요. 재개하기 전에 대기 중인 필수 도구 결과와 승인 결정을 모두 반환하세요. Responses 위임 처리하기를 참고하세요.

백엔드 이미지 입력은 session.input과 구분하세요. 이 필드는 시작 시 Live 프런트엔드에 초기 텍스트 대화 기록을 제공합니다. 지원되는 이미지 형식과 모델의 제한 사항은 이미지와 비전을 참고하세요.

백엔드 지연 시간 줄이기

백엔드 작업을 요청한 시점부터 대화에 활용할 수 있는 결과가 나올 때까지 걸리는 시간을 줄이세요. 단계별 지연 시간을 측정해 지연이 발생하는 지점을 찾으세요. 같은 시나리오에서 유용한 음성 답변이 나오기까지 걸리는 시간과 작업 성공률을 비교하세요. 평가 방법은 음성 에이전트 평가 Cookbook을 참고하세요.

Responses 위임

Live는 Responses와의 지속적인 WebSocket 연결을 관리하고 미리 알 수 있는 요청 설정을 준비합니다. 현재 연결과 상태가 허용하면 이전 응답 상태도 재사용할 수 있습니다. 실제 워크로드에서 응답 시간과 보고된 캐시 사용량을 측정해 효과를 확인하세요.

백엔드 설정은 delegation.responses에서 조정하세요.

  • model: 추론과 도구 선택을 담당할 모델을 음성 모델과 별도로 선택하세요.
  • reasoning.effort: 해당 모델이 지원하는 값으로 추론 시간과 작업 품질의 균형을 맞추세요.
  • service_tier: 모델 지원 여부와 프로젝트 접근 권한에 따라 auto, default, flex, priority 중 하나를 사용하세요. auto는 프로젝트 설정을 따릅니다. 선택한 서비스 등급의 성능과 비용을 평가하세요.

세션 중에는 session.update로 지원되는 설정을 변경하세요. 사용자 정의 도구는 여전히 애플리케이션에서 실행됩니다. 따라서 Live가 Responses 연결을 관리하더라도 느린 서비스 호출, 대기열, 도구 결과 버퍼링 때문에 답변이 늦어질 수 있습니다. 필요한 도구 결과를 각각 신속하게 반환하고 백엔드 응답을 재개하세요.

전사 조각에 대응하기

애플리케이션에서 전사 조각을 처리하는 것은 선택 사항이며 두 위임 모드 모두에서 가능합니다. 사용자와 어시스턴트의 전사 조각은 WebSocket 또는 WebRTC 데이터 채널로 전달됩니다. 애플리케이션 로직이나 경량 모델로 전사 조각을 처리해 위임 이벤트가 도착하기 전에 작업을 시작하거나, 전사 내용 자체를 계기로 애플리케이션이 관리하는 작업을 시작할 수 있습니다.

이 패턴은 다음과 같이 활용할 수 있습니다.

  • 대기 시간을 줄이세요. 정보가 충분히 모이면 필요할 것으로 예상되는 조회를 미리 시작하세요. 예를 들어 사용자가 원하는 조건을 계속 설명하는 동안 예약 가능 여부를 확인할 수 있습니다.
  • 가드레일을 실행하세요. 누적되는 전사 내용에서 개입이 필요한 요청이나 응답이 있는지 확인하세요. 대화 가드레일 적용하기를 참고하세요.
  • 대화 방식을 조정하세요. 혼란이나 답답함이 드러나는 표현을 감지하면 사용자 경험을 조정하거나 해당 상황에 맞는 구체적인 지침을 보내세요.
  • 인터페이스를 업데이트하세요. 관련 컨트롤을 강조하거나, 추천 값으로 필드를 채우거나, 결과가 준비되는 대로 표시하세요.

브라우저 애플리케이션에서는 자막과 로컬 UI 업데이트에 WebRTC 데이터 채널을 사용하세요. 가드레일 적용, 경량 모델을 이용한 검사, 도구 선제 호출 등을 위해 서버에서 전사를 처리한다면 사이드밴드 WebSocket으로 이벤트를 수신하고 같은 GPT-Live 세션을 직접 제어하세요.

의미 있는 새 정보가 들어올 때 누적된 텍스트를 처리하세요. 전사 조각은 불완전할 수 있고 이후 발언으로 요청이 바뀔 수 있습니다. 더 이상 유효하지 않은 결과는 폐기하고, 같은 작업을 두 번 실행하지 않도록 뒤이어 위임되는 작업과 조율하세요. 중요한 결과를 수반하는 작업을 실행하기 전에는 평소와 같이 권한과 필요한 사용자 확인을 점검하세요.

확인한 내용이나 지침은 업데이트에 맞는 추가 이벤트로 GPT-Live에 보내세요. 클라이언트 위임과 별개로 시작한 작업에는 delegation_id: null을 사용하세요. UI 변경 적용과 도구 실행 및 취소는 애플리케이션이 관리합니다.

두 모드에 공통으로 적용할 수 있는 최적화

다음 백엔드 개선 방법은 두 위임 모드 모두에 효과가 있습니다.

  • 작업에 맞는 모델과 추론 수준을 선택하세요. 정확도 요구 사항을 충족하는 설정을 비교하세요. 낮은 추론 수준에서도 작업을 안정적으로 완료한다면 그 수준을 사용하세요.
  • 답변을 간결하게 유지하세요. GPT-Live가 대화를 이어 가는 데 필요한 사실과 상태를 반환하세요. 긴 설명은 피하고, 결과를 음성에 맞게 다시 쓰기 위한 용도로만 모델을 추가 호출하지 마세요.
  • 도구 지연과 불필요한 호출을 줄이세요. 입력이 준비되면 권한이 있는 작업을 시작하고, 결과가 유효한 동안에는 재사용하며, 완료된 조회를 반복하지 마세요.
  • 서로 독립적인 작업은 동시에 실행하세요. 독립적인 조회 호출은 함께 실행할 수 있습니다. 작업 간 종속성을 지키고 필요한 사용자 확인을 받으세요. parallel_tool_calls를 사용하면 모델이 여러 호출을 요청할 수 있지만 사용자 정의 함수의 실행 일정과 실제 실행은 애플리케이션이 담당합니다.

Responses에 관한 일반적인 지침은 지연 시간 최적화를, 변경되지 않는 입력을 재사용하는 방법은 프롬프트 캐싱을 참고하세요.

전체 상호작용 검증하기

백엔드가 의도한 작업을 완료했는지, 클라이언트가 예상한 결과를 음성으로 재생했는지 확인하세요. 예를 들어 예약에 성공했다면 예약 기록과 그 후 재생된 오디오를 모두 확인하세요. 백엔드 작업은 완료되어도 음성 답변은 도중에 끊길 수 있으므로 두 결과를 별도로 테스트하세요.

GPT-Live 위임 ID와 함께 애플리케이션의 각 작업에는 고유한 작업 ID를, 변경된 요청마다 해당 작업 버전을 기록하세요. 이 기록을 사용해 재연결이나 재시도 후 이미 완료된 작업을 식별하고 이전 요청에 대한 결과를 폐기하세요.

반복 가능한 테스트를 구성하려면 음성 에이전트 평가를 참고하세요. 기존 Realtime 도구 호출 루프나 여러 단계를 연결한 백엔드를 사용한다면 GPT-Live로 마이그레이션을 따르세요.