탐색으로 건너뛰기

채팅 모드

채팅 모드로 에이전트를 텍스트 전용 대화에 맞게 구성하세요

채팅 모드를 사용하면 에이전트가 채팅 에이전트로 작동하여 오디오 입력/출력 없이 텍스트 전용 대화를 할 수 있습니다. 채팅 인터페이스를 구축하거나 에이전트를 테스트할 때 또는 오디오가 필요하지 않을 때 유용합니다.

개요

채팅 모드를 활성화하는 주요 방법은 두 가지입니다.

  1. 에이전트 구성: API를 통해 에이전트를 만들 때 텍스트 전용 모드로 구성
  2. 런타임 오버라이드: SDK 오버라이드를 사용하여 프로그래밍 방식으로 텍스트 전용 대화 강제 적용

이 가이드에서는 두 접근 방식과 다양한 SDK에서 채팅 모드를 구현하는 방법을 다룹니다.

텍스트 전용 에이전트 만들기

에이전트의 모든 대화에서 기본값으로 사용되도록 에이전트를 텍스트 전용 모드로 구성하세요.

대시보드에서 에이전트를 열고 고급 탭으로 이동한 다음 텍스트 전용 토글을 활성화하세요. 변경 사항을 저장하세요.

전체 API 레퍼런스 및 사용 가능한 모든 구성 옵션은 에이전트 생성 API 문서의 텍스트 전용 필드를 참조하세요.

텍스트 전용 모드 런타임 오버라이드

에이전트 수준에서 구성하는 대신 오버라이드를 사용하여 런타임에 채팅 모드를 활성화하려면 대화 구성에서 textOnly 오버라이드를 사용할 수 있습니다.

from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
# Configure for text-only mode with proper structure
conversation_override = {
"conversation": {
"text_only": True
}
}
config = ConversationInitiationData(
conversation_config_override=conversation_override
)
conversation = Conversation(
elevenlabs,
agent_id,
requires_auth=bool(api_key),
config=config,
# Important: Ensure agent_response callback is set
callback_agent_response=lambda response: print(f"Agent: {response}"),
callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
)
conversation.start_session()

이 구성은 다음을 보장합니다.

  • 오디오 입력/출력을 사용하지 않음
  • 모든 통신이 텍스트 메시지를 통해 이루어짐
  • 대화가 채팅과 유사한 인터페이스 모드에서 작동함

중요 참고 사항

중요: 채팅 모드를 사용할 때는 agent_response 이벤트/콜백이 활성화되고 올바르게 구성되었는지 반드시 확인해야 합니다. 그렇지 않으면 에이전트의 텍스트 응답이 사용자에게 전송되거나 표시되지 않습니다.

보안 오버라이드: 에이전트 수준 구성이 아닌 런타임 오버라이드를 사용할 때는 에이전트의 보안 설정에서 대화 오버라이드를 활성화해야 합니다. 에이전트의 보안 탭으로 이동하여 적절한 오버라이드를 활성화하세요. 자세한 내용은 오버라이드 문서를 참조하세요.

주요 요구 사항

  1. 에이전트 응답 이벤트: 에이전트의 텍스트 메시지를 수신하고 표시하려면 항상 agent_response 콜백 또는 이벤트 핸들러를 구성하세요.

  2. 에이전트 구성: 에이전트 설정에서 에이전트가 채팅 모드로 특별히 설정된 경우 오버라이드 없이 자동으로 텍스트 전용 대화를 사용합니다.

  3. 오디오 인터페이스 불필요: 텍스트 전용 모드를 사용할 때는 오디오 인터페이스를 구성하거나 마이크 권한을 요청할 필요가 없습니다.

예시: 에이전트 응답 처리

def handle_agent_response(response):
"""Critical handler for displaying agent messages"""
print(f"Agent: {response}") # Update your UI with the response
update_chat_ui(response)
config = ConversationInitiationData(
conversation_config_override={"conversation": {"text_only": True}}
)
conversation = Conversation(
elevenlabs,
agent_id,
config=config,
callback_agent_response=handle_agent_response,
)
conversation.start_session()

텍스트 메시지 보내기

채팅 모드에서는 오디오 대신 사용자 메시지를 프로그래밍 방식으로 전송해야 합니다.

# Send a text message to the agent
conversation.send_user_message("Hello, how can you help me today?")

동시성 이점

채팅 모드는 음성 대화보다 상당한 동시성 이점을 제공합니다.

  • 더 높은 한도: 채팅 전용 대화는 음성 대화보다 동시성 한도가 25배 더 높습니다.
  • 별도 풀: 텍스트 대화는 음성 대화 한도와 독립적인 전용 동시성 풀을 사용합니다.
  • 확장성: 고객 지원, 챗봇, 자동화 테스트와 같은 고처리량 애플리케이션에 적합합니다.
요금제음성 동시성채팅 전용 동시성
무료4100
스타터6150
크리에이터10250
프로20500
스케일30750
비즈니스30750
엔터프라이즈상향 조정됨상향 조정됨(25배)

트래픽에 필요한 채팅 전용 한도를 추정하려면 동시성 추정기를 사용하세요.

연결을 시작하는 동안 채팅 전용 대화는 핸드셰이크 과정에서 처음에 총 동시성 한도에 따라 확인된 후, 연결이 설정되면 별도의 채팅 전용 동시성 풀로 전송됩니다.

사용 사례

채팅 모드는 다음에 적합합니다.

  • 채팅 인터페이스: 음성 없는 기존 채팅 UI 구축
  • 테스트: 오디오 종속성 없이 에이전트 로직 테스트
  • 접근성: 사용자를 위한 텍스트 기반 대안 제공
  • 조용한 환경: 오디오 입력/출력이 적합하지 않은 경우
  • 통합 테스트: 에이전트 대화 자동화 테스트

문제 해결

에이전트가 응답하지 않음

에이전트의 응답이 표시되지 않는 경우:

  1. agent_response 콜백이 올바르게 구성되었는지 확인하세요.
  2. 에이전트가 채팅 모드로 구성되었거나 textOnly 오버라이드가 설정되었는지 확인하세요.
  3. WebSocket 연결이 성공적으로 설정되었는지 확인하세요.

다음 단계