클라이언트 이벤트

대화형 애플리케이션에서 클라이언트가 받는 실시간 이벤트를 이해하고 처리하세요.

클라이언트 이벤트는 실시간 통신을 지원하기 위해 서버에서 클라이언트로 전송되는 시스템 수준 이벤트입니다. 이 이벤트는 오디오, 전사, 에이전트 응답 및 기타 중요한 정보를 클라이언트 애플리케이션에 제공합니다.

클라이언트에서 서버로 보낼 수 있는 이벤트에 관한 자세한 내용은 클라이언트-서버 이벤트 문서를 참조하세요.

개요

클라이언트 이벤트는 대화의 실시간 특성을 유지하는 데 필수적입니다. 초기화 메타데이터부터 처리된 오디오와 에이전트 응답까지 모든 정보를 제공합니다.

이 이벤트는 WebSocket 통신 프로토콜의 일부이며 SDK에서 자동으로 처리됩니다. 고급 구현과 디버깅을 위해서는 이를 이해하는 것이 중요합니다.

클라이언트 이벤트 유형

conversation_initiation_metadata

대화 시작 시 자동으로 전송됨
대화 설정 및 매개변수 초기화

// Example initialization metadata
{
  "type": "conversation_initiation_metadata",
  "conversation_initiation_metadata_event": {
    "conversation_id": "conv_123",
    "agent_output_audio_format": "pcm_44100",  // TTS output format
    "user_input_audio_format": "pcm_16000"    // ASR input format
  }
}

queue_status

에이전트가 동시 실행 한도에 도달한 동안 통화 대기열에 있는 발신자에게만 전송됨
waiting은 conversation_initiation_metadata 이후, 보류 오디오 전에 한 번 전송됨
대기가 끝날 때 admitted 또는 timed_out이 한 번 전송됩니다. timed_out 다음에는 코드 4300으로 WebSocket이 닫힙니다.
대기 중인 발신자에게 항상 전송됩니다. 에이전트의 client_events 구성에서 활성화할 필요가 없습니다.

발신자가 대기열에 있는 동안 보류 오디오는 일반 audio 이벤트로 도착합니다. 보류 오디오를 에이전트 음성으로 처리하지 말고 이 이벤트를 사용해 대기 상태를 표시하세요.

// Example queue status event structure
{
  "type": "queue_status",
  "queue_status_event": {
    "status": "waiting"  // "waiting" | "admitted" | "timed_out"
  }
}

// Example queue status handler
websocket.on('queue_status', (event) => {
  const { status } = event.queue_status_event;
  if (status === 'waiting') {
    showWaitingState();
  } else if (status === 'admitted') {
    hideWaitingState();
  } else if (status === 'timed_out') {
    showAllAgentsBusyMessage();
  }
});

ping

즉각적인 응답이 필요한 상태 확인 이벤트
SDK에서 자동 처리됨
WebSocket 연결 유지에 사용됨

  // Example ping event structure
  {
    "ping_event": {
      "event_id": 123456,
      "ping_ms": 50  // Optional, estimated latency in milliseconds
    },
    "type": "ping"
  }

  // Example ping handler
  websocket.on('ping', () => {
    websocket.send('pong');
  });

audio

재생을 위한 base64 인코딩 오디오 포함
추적 및 순서 지정을 위한 숫자 이벤트 ID 포함
음성 출력 스트리밍 처리
문자 수준 타이밍 정보가 포함된 정렬 데이터 포함

WebRTC 연결에서는 LiveKit이 오디오를 직접 처리하므로 audio 이벤트가 전송되지 않습니다.

// Example audio event structure
{
  "audio_event": {
    "audio_base_64": "base64_encoded_audio_string",
    "event_id": 12345,
    "alignment": {  // Character-level timing data
      "chars": ["H", "e", "l", "l", "o"],
      "char_durations_ms": [50, 30, 40, 40, 60],
      "char_start_times_ms": [0, 50, 80, 120, 160]
    }
  },
  "type": "audio"
}

// Example audio event handler
websocket.on('audio', (event) => {
  const { audio_event } = event;
  const { audio_base_64, event_id, alignment } = audio_event;
  audioPlayer.play(audio_base_64);
  // Use alignment data for synchronized text display
  const { chars, char_start_times_ms } = alignment;
  chars.forEach((char, i) => {
    setTimeout(() => highlightCharacter(char, i), char_start_times_ms[i]);
  });
});

user_transcript

완료된 음성-텍스트 변환 결과 포함
완전한 사용자 발화를 나타냄
대화 기록에 사용됨

// Example transcript event structure
{
  "type": "user_transcript",
  "user_transcription_event": {
    "user_transcript": "Hello, how can you help me today?"
  }
}

// Example transcript handler
websocket.on('user_transcript', (event) => {
  const { user_transcription_event } = event;
  const { user_transcript } = user_transcription_event;
  updateConversationHistory(user_transcript);
});

agent_response

완전한 에이전트 메시지 포함
메시지가 완료되면 한 번 전송되므로, 음성 대화에서는 대개 메시지 오디오 스트리밍이 이미 시작된 후에 도착합니다.
표시 및 기록에 사용됨

생성되는 대로 에이전트 텍스트를 표시하려면 이 이벤트를 기다리지 말고 아래 설명된 agent_chat_response_part 이벤트를 사용하세요.

// Example response event structure
{
  "type": "agent_response",
  "agent_response_event": {
    "agent_response": "Hello, how can I assist you today?"
  }
}

// Example response handler
websocket.on('agent_response', (event) => {
  const { agent_response_event } = event;
  const { agent_response } = agent_response_event;
  displayAgentMessage(agent_response);
});

agent_response_correction

중단 후 잘린 응답 포함
표시된 메시지 업데이트
대화 정확성 유지

// Example response correction event structure
{
  "type": "agent_response_correction",
  "agent_response_correction_event": {
    "original_agent_response": "Let me tell you about the complete history...",
    "corrected_agent_response": "Let me tell you about..."  // Truncated after interruption
  }
}

// Example response correction handler
websocket.on('agent_response_correction', (event) => {
  const { agent_response_correction_event } = event;
  const { corrected_agent_response } = agent_response_correction_event;
  displayAgentMessage(corrected_agent_response);
});

agent_response_metadata

맞춤 LLM 응답의 임의 메타데이터 포함
맞춤 LLM을 사용할 때만 전송됨
에이전트의 client_events 구성에서 명시적으로 활성화해야 함

이 이벤트는 맞춤 LLM 통합에 특화되어 있습니다. 맞춤 LLM 서버가 응답과 함께 추가 메타데이터를 전달하고, 클라이언트 애플리케이션이 이를 사용할 수 있습니다.

// Example agent response metadata event structure
{
  "type": "agent_response_metadata",
  "agent_response_metadata_event": {
    "metadata": {
      // Any key-value pairs returned by your custom LLM
      "key": "value"
    },
    "event_id": 12345
  }
}

// Example metadata handler
websocket.on('agent_response_metadata', (event) => {
  const { agent_response_metadata_event } = event;
  const { metadata, event_id } = agent_response_metadata_event;
  // Use metadata for UI updates, logging, or analytics
  console.log(`Response ${event_id} metadata:`, metadata);
  updateResponseDetails(metadata);
});

client_tool_call

에이전트가 클라이언트에서 실행하기를 원하는 함수 호출을 나타냄
도구 이름, 도구 호출 ID 및 매개변수 포함
클라이언트 측에서 함수를 실행하고 결과를 서버로 다시 전송해야 함

SDK를 사용하는 경우 결과를 서버로 다시 보내는 처리를 위한 콜백이 제공됩니다.

// Example tool call event structure
{
  "type": "client_tool_call",
  "client_tool_call": {
    "tool_name": "search_database",
    "tool_call_id": "call_123456",
    "parameters": {
      "query": "user information",
      "filters": {
        "date": "2024-01-01"
      }
    }
  }
}

// Example tool call handler
websocket.on('client_tool_call', async (event) => {
  const { client_tool_call } = event;
  const { tool_name, tool_call_id, parameters } = client_tool_call;
  try {
    const result = await executeClientTool(tool_name, parameters);
    // Send success response back to continue conversation
    websocket.send({
      type: "client_tool_result",
      tool_call_id: tool_call_id,
      result: result,
      is_error: false
    });
  } catch (error) {
    // Send error response if tool execution fails
    websocket.send({
      type: "client_tool_result",
      tool_call_id: tool_call_id,
      result: error.message,
      is_error: true
    });
  }
});

agent_tool_response

에이전트가 도구 함수를 실행했을 때를 나타냄
도구 메타데이터 및 실행 상태 포함
대화 중 에이전트의 도구 사용 현황을 확인할 수 있음

// Example agent tool response event structure
{
  "type": "agent_tool_response",
  "agent_tool_response": {
    "tool_name": "skip_turn",
    "tool_call_id": "skip_turn_c82ca55355c840bab193effb9a7e8101",
    "tool_type": "system",
    "is_error": false
  }
}

// Example agent tool response handler
websocket.on('agent_tool_response', (event) => {
  const { agent_tool_response } = event;
  const { tool_name, tool_call_id, tool_type, is_error } = agent_tool_response;
  if (is_error) {
    console.error(`Agent tool ${tool_name} failed:`, tool_call_id);
  } else {
    console.log(`Agent executed ${tool_type} tool: ${tool_name}`);
  }
});

agent_tool_response_full_payload

agent_tool_response를 반영하며, 도구의 전체 결과 페이로드를 full_tool_result에 문자열로 추가 스트리밍합니다.
표시 또는 후속 처리를 위해 클라이언트에 도구 출력을 제공합니다.
에이전트의 client_events 구성에서 명시적으로 활성화해야 합니다.

이 이벤트는 전체 도구 결과를 클라이언트에 노출하며 민감한 데이터를 포함할 수 있습니다. 클라이언트가 페이로드를 안전하게 처리할 수 있을 때만 활성화하세요. 64KB보다 큰 결과는 자동으로 잘립니다.

// Example agent tool response full payload event structure
{
  "type": "agent_tool_response_full_payload",
  "agent_tool_response_full_payload": {
    "tool_name": "lookup_order",
    "tool_call_id": "lookup_order_c82ca55355c840bab193effb9a7e8101",
    "tool_type": "webhook",
    "is_error": false,
    "full_tool_result": "{\"order_id\": \"ORD-789\", \"status\": \"shipped\"}",
    "truncated": false
  }
}

React

JavaScript

// Example agent tool response full payload handler (using @elevenlabs/react)
import { ConversationProvider } from '@elevenlabs/react';
function App() {
  return (
    <ConversationProvider
      onAgentToolResponse={(response) => {
        if (!('full_tool_result' in response)) return;
        const { tool_name, tool_call_id, is_error, full_tool_result, truncated } = response;
        if (is_error) {
          console.error(`Agent tool ${tool_name} failed:`, tool_call_id);
        } else {
          console.log(`Tool ${tool_name} returned:`, full_tool_result);
        }
        if (truncated) {
          console.warn(`Tool ${tool_name} result was truncated (exceeded 64 KB).`);
        }
      }}
    >
      <Agent />
    </ConversationProvider>
  );
}

vad_score

음성 활동 감지 점수 이벤트
사용자가 말하고 있을 확률을 나타냄
값의 범위는 0~1이며, 값이 높을수록 음성에 대한 신뢰도가 높음

// Example VAD score event
{
  "type": "vad_score",
  "vad_score_event": {
    "vad_score": 0.95
  }
}

mcp_tool_call

에이전트가 MCP 도구 함수를 실행했을 때를 나타냄
도구 이름, 도구 호출 ID 및 매개변수 포함
loading, awaiting_approval, success, failure의 네 가지 상태 중 하나로 호출됨

{
  "type": "mcp_tool_call",
  "mcp_tool_call": {
    "service_id": "xJ8kP2nQ7sL9mW4vR6tY",
    "tool_call_id": "call_123456",
    "tool_name": "search_database",
    "tool_description": "Search the database for user information",
    "parameters": {
      "query": "user information",
    },
    "timestamp": "2024-09-30T14:23:45.123456+00:00",
    "state": "loading",
    "approval_timeout_secs": 10
  }
}

agent_chat_response_part

에이전트의 응답 텍스트를 생성되는 대로 start, delta, stop 메시지로 스트리밍함
텍스트 전용 모드에서는 항상 전송되며, 음성 대화에서는 에이전트의 client_events 구성에서 명시적으로 활성화해야 함
에이전트 또는 활성 프로시저가 응답 전체를 평가한 후에야 공개할 수 있는 차단 가드레일을 사용할 때는 전송되지 않음
response_id는 스트리밍되는 메시지를 식별하며, 이후 이를 확정하는 agent_response의 response_id와 일치함

// Example start event
{
  "type": "agent_chat_response_part",
  "text_response_part": {
    "type": "start",
    "text": "",
    "event_id": 12345,
    "response_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

// Example delta event with text chunk
{
  "type": "agent_chat_response_part",
  "text_response_part": {
    "type": "delta",
    "text": "Hello, how can I",
    "event_id": 12345,
    "response_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

// Example stop event
{
  "type": "agent_chat_response_part",
  "text_response_part": {
    "type": "stop",
    "text": "",
    "event_id": 12345,
    "response_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

// Example handler
websocket.on('agent_chat_response_part', (event) => {
  const { text_response_part } = event;
  const { type: partType, text, response_id } = text_response_part;
  if (partType === 'start') {
    initializeResponseBuffer(response_id);
  } else if (partType === 'delta') {
    appendToResponseBuffer(response_id, text);
  } else if (partType === 'stop') {
    finalizeResponse(response_id);
  }
});

agent_reasoning_response_part

agent_reasoning_response_part는 텍스트 전용 대화 중 모델이 제공하는 추론을 스트리밍합니다. 에이전트의 client_events에서 이벤트를 활성화하고 추론 요약을 켜세요. 서버는 start, delta, stop 메시지를 전송합니다. 음성 대화 중이거나 에이전트 또는 활성 프로시저가 차단 가드레일을 사용하는 동안에는 이 이벤트를 전송하지 않습니다.

이 이벤트와 해당 SDK 콜백은 실험적 기능입니다. 동작과 형태는 모든 릴리스에서 변경될 수 있습니다.

이벤트 페이로드

{
  "type": "agent_reasoning_response_part",
  "reasoning_response_part": {
    "type": "delta",
    "text": "The user asked to cancel, so I should verify the account before continuing.",
    "event_id": 123456
  }
}

시작 및 중지 이벤트는 빈 text 값을 사용합니다.

추론 이벤트 처리

import { Conversation } from '@elevenlabs/client';
const conversation = await Conversation.startSession({
  agentId: 'agent_7101k5zvyjhmfg983brhmhkd98n6',
  textOnly: true,
  onAgentReasoningResponsePart: ({ type, text, event_id }) => {
    if (type === 'start') {
      initializeReasoningBuffer(event_id);
    } else if (type === 'delta') {
      appendToReasoningBuffer(text);
    } else if (type === 'stop') {
      finalizeReasoning();
    }
  },
});

agent_response_complete

보류 중인 도구 호출을 포함해 에이전트가 응답을 완료하면 발생합니다. 이 이벤트 이후에는 사용자가 새 입력을 제공하거나 턴 제한 시간이 새 턴을 트리거하는 경우에만 에이전트가 추가 출력을 생성합니다.
에이전트의 client_events 구성에서 명시적으로 활성화해야 함

// Example agent response complete event structure
{
  "type": "agent_response_complete",
  "agent_response_complete_event": {
    "event_id": 12345
  }
}

// Example handler
websocket.on('agent_response_complete', (event) => {
  const { agent_response_complete_event } = event;
  const { event_id } = agent_response_complete_event;
  console.log(`Agent response ${event_id} complete`);
});

guardrail_triggered

가드레일 위반으로 대화가 종료되면 발생합니다. 성공한 재시도를 가드레일이 트리거한 경우에는 전송되지 않습니다.
이벤트 자체가 신호이며 type 필드 외에 페이로드를 포함하지 않습니다.
에이전트의 client_events 구성에서 명시적으로 활성화해야 합니다.

// Example guardrail triggered event structure
{
  "type": "guardrail_triggered"
}

// Example guardrail triggered handler (using @elevenlabs/client)
import { Conversation } from '@elevenlabs/client';
const conversation = await Conversation.startSession({
  agentId: 'agent_7101k5zvyjhmfg983brhmhkd98n6',
  onGuardrailTriggered: () => {
    console.warn('Guardrail triggered — conversation will end.');
  },
});

이벤트 흐름

다음은 대화 중 발생하는 일반적인 이벤트 순서입니다:

에이전트가 동시 처리 한도에 도달했고 통화 대기열이 활성화된 경우, 서버는 conversation_initiation_metadata와 첫 번째 audio 이벤트 사이에 queue_status 이벤트를 전송합니다. 발신자가 연결될 때까지 대기 음악은 audio 이벤트로 전달됩니다.

모범 사례

오류 처리
- 각 이벤트 유형에 적절한 오류 처리 구현
- 디버깅을 위해 중요한 이벤트 기록
- 연결 중단을 원활하게 처리
오디오 관리
- 오디오 청크를 적절히 버퍼링
- 중단 시 적절한 정리 작업 구현
- 오디오 리소스 관리 처리
연결 관리
- PING 이벤트에 신속하게 응답
- 재연결 로직 구현
- 연결 상태 모니터링

문제 해결

연결 문제

WebSocket 연결이 올바르게 설정되었는지 확인
PING/PONG 응답 확인
API 자격 증명 확인

오디오 문제

오디오 청크 처리 확인
오디오 형식 호환성 확인
메모리 사용량 모니터링

이벤트 처리

디버깅을 위해 모든 이벤트 기록
오류 경계 구현
이벤트 핸들러 등록 확인

자세한 구현 예시는 SDK 문서를 확인하세요.