Leitfäden

Chat-Modus

Konfigurieren Sie Ihren Agent für reine Textgespräche im Chat-Modus

Im Chat-Modus können Ihre Agents als Chat-Agents agieren, also reine Textgespräche ohne Audioein- oder -ausgabe führen. Das ist nützlich, um Chat-Oberflächen zu erstellen, Agents zu testen oder wenn Audio nicht erforderlich ist.

Überblick

Es gibt zwei Hauptwege, um den Chat-Modus zu aktivieren:

  1. Agent-Konfiguration: Konfigurieren Sie Ihren Agent beim Erstellen über die API für den reinen Textmodus
  2. Laufzeitüberschreibungen: Verwenden Sie SDK-Überschreibungen, um reine Textgespräche programmatisch zu erzwingen

Dieser Leitfaden behandelt beide Ansätze und die Implementierung des Chat-Modus in verschiedenen SDKs.

Reine Text-Agents erstellen

Konfigurieren Sie einen Agent für den reinen Textmodus, um ihn als Standard für jedes Gespräch mit diesem Agent festzulegen.

Öffnen Sie Ihren Agent im Dashboard, navigieren Sie zum Tab Advanced und aktivieren Sie den Schalter Text only. Speichern Sie Ihre Änderungen.

Die vollständige API-Referenz und alle verfügbaren Konfigurationsoptionen finden Sie im Feld text only der Create-Agent-API- Dokumentation.

Laufzeitüberschreibungen für den reinen Textmodus

Um den Chat-Modus zur Laufzeit über Überschreibungen zu aktivieren, statt ihn auf Agent-Ebene zu konfigurieren, können Sie die Überschreibung textOnly in Ihrer Gesprächskonfiguration verwenden:

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

Diese Konfiguration stellt Folgendes sicher:

  • Es wird keine Audioein- oder -ausgabe verwendet
  • Die gesamte Kommunikation erfolgt über Textnachrichten
  • Das Gespräch läuft im Modus einer chatähnlichen Oberfläche

Wichtige Hinweise

Kritisch: Bei Verwendung des Chat-Modus müssen Sie sicherstellen, dass das Ereignis bzw. der Callback agent_response aktiviert und korrekt konfiguriert ist. Andernfalls werden die Textantworten des Agents nicht an den Benutzer gesendet oder angezeigt.

Sicherheitsüberschreibungen: Bei Verwendung von Laufzeitüberschreibungen, nicht einer Konfiguration auf Agent-Ebene, müssen Sie die Gesprächsüberschreibungen in den Sicherheitseinstellungen Ihres Agents aktivieren. Navigieren Sie zum Tab Security Ihres Agents und aktivieren Sie die passenden Überschreibungen. Weitere Informationen finden Sie in der Dokumentation zu Überschreibungen .

Zentrale Anforderungen

  1. Agent-Antwortereignis: Konfigurieren Sie stets den Callback oder Event-Handler agent_response, um die Textnachrichten des Agents zu empfangen und anzuzeigen.

  2. Agent-Konfiguration: Wenn Ihr Agent in den Agent-Einstellungen speziell auf Chat-Modus eingestellt ist, verwendet er automatisch reine Textgespräche, ohne dass eine Überschreibung erforderlich ist.

  3. Keine Audiooberfläche: Bei Verwendung des reinen Textmodus müssen Sie keine Audiooberflächen konfigurieren oder Mikrofonberechtigungen anfordern.

Beispiel: Agent-Antworten verarbeiten

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

Textnachrichten senden

Im Chat-Modus müssen Sie Benutzernachrichten programmatisch statt über Audio senden:

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

Vorteile bei der Parallelität

Der Chat-Modus bietet gegenüber Sprachgesprächen deutliche Vorteile bei der Parallelität:

  • Höhere Limits: Reine Chat-Gespräche haben 25-mal höhere Parallelitätslimits als Sprachgespräche
  • Separater Pool: Textgespräche verwenden einen dedizierten Parallelitätspool, unabhängig von den Limits für Sprachgespräche
  • Skalierbarkeit: Ideal für Anwendungen mit hohem Durchsatz wie Kundensupport, Chatbots oder automatisierte Tests
PlanSprachparallelitätReine Chat-Parallelität
Free4100
Starter6150
Creator10250
Pro20500
Scale30750
Business30750
EnterpriseErhöhtErhöht (25x)

Während des Verbindungsaufbaus werden reine Chat-Gespräche zunächst während des Handshake-Prozesses anhand Ihres gesamten Parallelitätslimits geprüft und nach Herstellung der Verbindung in den separaten Pool für reine Chat-Gespräche übertragen.

Anwendungsfälle

Der Chat-Modus ist ideal für:

  • Chat-Oberflächen: Klassische Chat-UIs ohne Sprache erstellen
  • Tests: Agent-Logik ohne Audioabhängigkeiten testen
  • Barrierefreiheit: Textbasierte Alternativen für Benutzer bereitstellen
  • Stille Umgebungen: Wenn Audioein- oder -ausgabe nicht geeignet ist
  • Integrationstests: Automatisierte Tests von Agent-Gesprächen

Fehlerbehebung

Agent antwortet nicht

Wenn die Antworten des Agents nicht angezeigt werden:

  1. Prüfen Sie, ob der Callback agent_response korrekt konfiguriert ist
  2. Prüfen Sie, ob der Agent für den Chat-Modus konfiguriert ist oder die Überschreibung textOnly festgelegt wurde
  3. Stellen Sie sicher, dass die WebSocket-Verbindung erfolgreich hergestellt wurde

Nächste Schritte