Vai alla navigazione

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 agenti o quando l’audio non è necessario.

Panoramica

Esistono due modi principali per abilitare la modalità chat:

  1. Configurazione dell’agente: Configura l’agente in modalità solo testuale quando lo crei tramite l’API
  2. Override runtime: Usa gli override dell’SDK per imporre conversazioni solo testuali a livello di codice

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

Creare agenti solo testuali

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

Apri l’agente nella dashboard, vai alla scheda Avanzate e abilita l’interruttore Solo testo. 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 runtime per la modalità solo testuale

Per abilitare la modalità chat in fase di runtime usando gli override (invece della configurazione 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
  • Tutta la comunicazione avvenga tramite messaggi di testo
  • La conversazione funzioni in 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. Senza di esso, le risposte testuali dell’agente non verranno inviate né mostrate all’utente.

Override di sicurezza: Quando usi gli override runtime (non la configurazione a livello di agente), devi abilitare gli override della conversazione nelle impostazioni di sicurezza dell’agente. Vai alla scheda Sicurezza dell’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 o il gestore eventi agent_response per ricevere e mostrare i messaggi di testo dell’agente.

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

  3. Nessuna interfaccia audio: Quando usi la modalità solo testuale, 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()

Inviare messaggi di testo

In modalità chat, dovrai inviare i messaggi dell’utente a livello di codice invece che tramite audio:

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

Vantaggi in termini di concorrenza

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

  • Limiti più alti: 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 a throughput elevato come assistenza clienti, chatbot o test automatizzati
PianoConcorrenza vocaleConcorrenza solo chat
Free4100
Starter6150
Creator10250
Pro20500
Scale30750
Business30750
EnterpriseAumentataAumentata (25x)

Per stimare il limite solo chat necessario per il tuo traffico, usa lo stimatore di concorrenza.

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

Casi d’uso

La modalità chat è ideale per:

  • Interfacce chat: Creare UI di 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 in modalità chat oppure che sia impostato l’override textOnly
  3. Assicurati che la connessione WebSocket sia stabilita correttamente

Passaggi successivi