탐색으로 건너뛰기
가이드

채팅 모드

채팅 모드로 텍스트 전용 대화를 하도록 에이전트 구성하기

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

개요

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

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

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

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

에이전트와의 모든 대화에서 기본값으로 사용되도록 에이전트를 텍스트 전용 모드로 구성합니다.

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

전체 API 레퍼런스와 사용 가능한 모든 구성 옵션은 Create Agent 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 연결이 성공적으로 설정되었는지 확인합니다.

다음 단계