Vai alla navigazione
Guide

Modalità chat

Configura il tuo agente per conversazioni solo testuali con la modalità chat

La modalità chat consente ai tuoi agenti di agire come agenti chat, ovvero di avere conversazioni solo testuali senza input/output audio. È utile per creare interfacce chat, testare gli agenti o quando l’audio non è necessario.

Panoramica

Esistono due modi principali per abilitare la modalità chat:

  1. Configurazione dell’agente: Configura il tuo agente in modalità solo testo quando lo crei tramite l’API
  2. Override in fase di runtime: Usa gli override SDK per applicare programmaticamente conversazioni solo testuali

Questa guida illustra entrambi gli approcci e come implementare la modalità chat nei diversi SDK.

Creazione di agenti solo testuali

Configura un agente in modalità solo testo per renderla predefinita per ogni conversazione con quell’agente.

Apri il tuo agente nella dashboard, vai alla scheda Advanced e abilita l’interruttore Text only. Salva le modifiche.

Per il riferimento API completo e tutte le opzioni di configurazione disponibili, consulta il campo text only nella documentazione dell’API Create Agent .

Override in fase di runtime per la modalità solo testo

Per abilitare la modalità chat in fase di runtime usando gli override (anziché configurarla a livello di agente), puoi usare l’override textOnly nella configurazione della conversazione:

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

Questa configurazione garantisce che:

  • Non venga usato alcun input/output audio
  • Tutte le comunicazioni avvengano tramite messaggi di testo
  • La conversazione operi in una modalità di interfaccia simile a una chat

Note importanti

Importante: Quando usi la modalità chat, devi assicurarti che l’evento/callback agent_response sia attivato e configurato correttamente. In caso contrario, le risposte testuali dell’agente non verranno inviate né visualizzate all’utente.

Override di sicurezza: Quando usi override in fase di runtime (non la configurazione a livello di agente), devi abilitare gli override della conversazione nelle impostazioni di sicurezza dell’agente. Vai alla scheda Security del tuo agente e abilita gli override appropriati. Per maggiori dettagli, consulta la documentazione sugli override .

Requisiti principali

  1. Evento di risposta dell’agente: Configura sempre il callback agent_response o il gestore eventi per ricevere e visualizzare i messaggi testuali dell’agente.

  2. Configurazione dell’agente: Se il tuo agente è impostato specificamente in modalità chat nelle impostazioni dell’agente, userà automaticamente conversazioni solo testuali senza richiedere l’override.

  3. Nessuna interfaccia audio: Quando usi la modalità solo testo, non devi configurare interfacce audio né richiedere autorizzazioni per il microfono.

Esempio: gestione delle risposte dell’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()

Invio di messaggi di testo

In modalità chat, dovrai inviare programmaticamente i messaggi dell’utente anziché tramite l’audio:

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

Vantaggi di concorrenza

La modalità chat offre notevoli vantaggi di concorrenza rispetto alle conversazioni vocali:

  • Limiti più elevati: Le conversazioni solo chat hanno limiti di concorrenza 25 volte superiori rispetto alle conversazioni vocali
  • Pool separato: Le conversazioni testuali usano un pool di concorrenza dedicato, indipendente dai limiti delle conversazioni vocali
  • Scalabilità: Ideale per applicazioni ad alto throughput come assistenza clienti, chatbot o test automatizzati
PianoConcorrenza vocaleConcorrenza solo chat
Free4100
Starter6150
Creator10250
Pro20500
Scale30750
Business30750
EnterpriseAumentataAumentata (25x)

Durante l’avvio della connessione, le conversazioni solo chat vengono inizialmente controllate rispetto al limite totale di concorrenza durante il processo di handshake, quindi trasferite al pool di concorrenza separato per le conversazioni solo chat una volta stabilita la connessione.

Casi d’uso

La modalità chat è ideale per:

  • Interfacce chat: Creare UI chat tradizionali senza voce
  • Test: Testare la logica dell’agente senza dipendenze audio
  • Accessibilità: Fornire alternative basate sul testo agli utenti
  • Ambienti silenziosi: Quando l’input/output audio non è appropriato
  • Test di integrazione: Test automatizzati delle conversazioni degli agenti

Risoluzione dei problemi

L’agente non risponde

Se le risposte dell’agente non vengono visualizzate:

  1. Verifica che il callback agent_response sia configurato correttamente
  2. Controlla che l’agente sia configurato per la modalità chat o che l’override textOnly sia impostato
  3. Assicurati che la connessione WebSocket sia stata stabilita correttamente

Passaggi successivi