Guias

Modo de chat

Configure seu agente para conversas apenas por texto com o modo de chat

O modo de chat permite que seus agentes atuem como agentes de chat, ou seja, tenham conversas apenas por texto, sem entrada ou saída de áudio. Isso é útil para criar interfaces de chat, testar agentes ou quando não é necessário usar áudio.

Visão geral

Há duas formas principais de ativar o modo de chat:

  1. Configuração do agente: Configure seu agente para o modo apenas texto ao criá-lo pela API
  2. Substituições em tempo de execução: Use substituições do SDK para impor conversas apenas por texto de forma programática

Este guia aborda as duas abordagens e como implementar o modo de chat em diferentes SDKs.

Criando agentes apenas de texto

Configure um agente para o modo apenas texto a fim de torná-lo o padrão para todas as conversas com esse agente.

Abra seu agente no painel, acesse a aba Advanced e ative a opção Text only. Salve suas alterações.

Para ver a referência completa da API e todas as opções de configuração disponíveis, consulte o campo text only na documentação da API Create Agent .

Substituições em tempo de execução para o modo apenas texto

Para ativar o modo de chat em tempo de execução usando substituições (em vez de configurá-lo no nível do agente), você pode usar a substituição textOnly na configuração da conversa:

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()

Essa configuração garante que:

  • Nenhuma entrada ou saída de áudio seja usada
  • Toda a comunicação ocorra por mensagens de texto
  • A conversa funcione no modo de interface semelhante a um chat

Observações importantes

Crítico: Ao usar o modo de chat, você deve garantir que o evento/callback agent_response esteja ativado e configurado corretamente. Sem isso, as respostas de texto do agente não serão enviadas nem exibidas ao usuário.

Substituições de segurança: Ao usar substituições em tempo de execução (e não uma configuração no nível do agente), você deve ativar as substituições de conversa nas configurações de segurança do seu agente. Acesse a aba Security do seu agente e ative as substituições apropriadas. Para mais detalhes, consulte a documentação sobre substituições .

Requisitos principais

  1. Evento de resposta do agente: Sempre configure o callback ou manipulador de eventos agent_response para receber e exibir as mensagens de texto do agente.

  2. Configuração do agente: Se seu agente estiver definido especificamente para o modo de chat nas configurações do agente, ele usará automaticamente conversas apenas por texto sem exigir a substituição.

  3. Sem interface de áudio: Ao usar o modo apenas texto, não é necessário configurar interfaces de áudio nem solicitar permissões de microfone.

Exemplo: como lidar com respostas do agente

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()

Enviando mensagens de texto

No modo de chat, você precisará enviar mensagens do usuário de forma programática, em vez de enviá-las por áudio:

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

Benefícios de concorrência

O modo de chat oferece vantagens significativas de concorrência em relação às conversas por voz:

  • Limites maiores: Conversas apenas por chat têm limites de concorrência 25 vezes maiores que conversas por voz
  • Pool separado: Conversas por texto usam um pool de concorrência dedicado, independente dos limites de conversas por voz
  • Escalabilidade: Ideal para aplicações de alto volume, como suporte ao cliente, chatbots ou testes automatizados
PlanoConcorrência de vozConcorrência apenas por chat
Grátis4100
Starter6150
Creator10250
Pro20500
Scale30750
Business30750
EnterpriseMaiorMaior (25x)

Durante o início da conexão, as conversas apenas por chat são verificadas inicialmente em relação ao seu limite total de concorrência durante o processo de handshake e, após o estabelecimento da conexão, são transferidas para o pool separado de concorrência apenas por chat.

Casos de uso

O modo de chat é ideal para:

  • Interfaces de chat: Criar UIs de chat tradicionais sem voz
  • Testes: Testar a lógica do agente sem dependências de áudio
  • Acessibilidade: Oferecer alternativas baseadas em texto aos usuários
  • Ambientes silenciosos: Quando entrada ou saída de áudio não é apropriada
  • Testes de integração: Testes automatizados de conversas de agentes

Solução de problemas

Agente não responde

Se as respostas do agente não estiverem aparecendo:

  1. Verifique se o callback agent_response está configurado corretamente
  2. Verifique se o agente está configurado para o modo de chat ou se a substituição textOnly está definida
  3. Certifique-se de que a conexão WebSocket foi estabelecida com sucesso

Próximas etapas