Agenten-Authentifizierung

Übersicht

Beim Erstellen von Conversational Agents müssen Sie möglicherweise den Zugriff auf bestimmte Agents oder Unterhaltungen beschränken. ElevenLabs bietet mehrere Authentifizierungsmechanismen, damit nur autorisierte Nutzer mit Ihren Agents interagieren können.

Authentifizierungsmethoden

ElevenLabs bietet zwei primäre Methoden zum Absichern Ihrer Conversational Agents:

Signierte URLs verwenden

Signierte URLs sind der empfohlene Ansatz für clientseitige Anwendungen. Mit dieser Methode können Sie Nutzer authentifizieren, ohne Ihren API-Schlüssel offenzulegen.

So funktionieren signierte URLs

1. Ihr Server fordert mit Ihrem API-Schlüssel eine signierte URL von ElevenLabs an.
2. ElevenLabs generiert ein temporäres Token und gibt eine signierte WebSocket-URL zurück.
3. Ihre Client-Anwendung verwendet diese signierte URL, um eine WebSocket-Verbindung herzustellen.
4. Die signierte URL läuft nach 15 Minuten ab.

Eine signierte URL über die API generieren

Um eine signierte URL zu erhalten, senden Sie eine Anfrage an den get_signed_url-Endpunkt mit Ihrer Agent-ID:

# Server-side code using the Python SDK
from elevenlabs.client import ElevenLabs
async def get_signed_url():
    try:
        elevenlabs = ElevenLabs(api_key="your-api-key")
        response = await elevenlabs.conversational_ai.conversations.get_signed_url(agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6")
        return response.signed_url
    except Exception as error:
        print(f"Error getting signed URL: {error}")
        raise

Die curl-Antwort hat folgendes Format:

{
  "signed_url": "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&conversation_signature=your-token"
}

Mit einer signierten URL eine Verbindung zu Ihrem Agent herstellen

Rufen Sie die vom Server generierte signierte URL im Client ab und verwenden Sie sie, um eine Verbindung zum WebSocket herzustellen.

# Client-side code using the Python SDK
from elevenlabs.conversational_ai.conversation import (
    Conversation,
    AudioInterface,
    ClientTools,
    ConversationInitiationData
)
import os
from elevenlabs.client import ElevenLabs
api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)
conversation = Conversation(
  client=elevenlabs,
  agent_id=os.getenv("AGENT_ID"),
  requires_auth=True,
  audio_interface=AudioInterface(),
  config=ConversationInitiationData()
)
async def start_conversation():
  try:
    signed_url = await get_signed_url()
    conversation = Conversation(
      client=elevenlabs,
      url=signed_url,
    )
    conversation.start_session()
  except Exception as error:
    print(f"Failed to start conversation: {error}")

Ablauf signierter URLs

Signierte URLs sind 15 Minuten lang gültig. Die Unterhaltungssitzung kann länger dauern, aber die Unterhaltung muss innerhalb des 15-Minuten-Fensters gestartet werden.

Zulassungslisten verwenden

Zulassungslisten ermöglichen es, den Zugriff auf Ihre Conversational Agents anhand der Ursprungsdomain zu beschränken. So können sich nur Anfragen von genehmigten Domains mit Ihrem Agent verbinden.

So funktionieren Zulassungslisten

1. Sie konfigurieren eine Liste genehmigter Hostnamen für Ihren Agent.
2. Wenn ein Client versucht, eine Verbindung herzustellen, prüft ElevenLabs, ob der Ursprung der Anfrage mit einem zugelassenen Hostnamen übereinstimmt.
3. Wenn sich der Ursprung auf der Zulassungsliste befindet, wird die Verbindung erlaubt, andernfalls abgelehnt.

Zulassungslisten konfigurieren

Zulassungslisten werden als Teil der Authentifizierungseinstellungen Ihres Agent konfiguriert. Sie können bis zu 10 eindeutige Hostnamen angeben, die sich mit Ihrem Agent verbinden dürfen.

Beispiel: Eine Zulassungsliste einrichten

Eine Authentifizierungsmethode wählen

Konfigurieren Sie pro Agent eine Authentifizierungsmethode:

1. Verwenden Sie signierte URLs (enable_auth) für authentifizierte Client-Sitzungen.
2. Verwenden Sie Zulassungslisten (allowlist) für die zugriffssteuerung nach Hostnamen.

Konfigurieren Sie signierte URLs und Zulassungslisten nicht gemeinsam für denselben Agent. Wählen Sie die Methode, die zu Ihrem Bereitstellungsmodell passt.

Beispiel: Nur signierte URLs

Verwenden Sie enable_auth ohne allowlist:

from elevenlabs.client import ElevenLabs
import os
from elevenlabs.types import *
api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)
agent = elevenlabs.conversational_ai.agents.create(
  conversation_config=ConversationalConfig(
    agent=AgentConfig(
      first_message="Hi. I require a signed URL.",
    )
  ),
  platform_settings=AgentPlatformSettingsRequestModel(
    auth=AuthSettings(
      enable_auth=True
    )
  )
)

Beispiel: Nur Zulassungsliste

Verwenden Sie allowlist, ohne signierte URLs zu aktivieren:

from elevenlabs.client import ElevenLabs
import os
from elevenlabs.types import *
api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)
agent = elevenlabs.conversational_ai.agents.create(
  conversation_config=ConversationalConfig(
    agent=AgentConfig(
      first_message="Hi. I only accept approved hostnames.",
    )
  ),
  platform_settings=AgentPlatformSettingsRequestModel(
    auth=AuthSettings(
      allowlist=[
        AllowlistItem(hostname="example.com"),
        AllowlistItem(hostname="app.example.com"),
      ]
    )
  )
)

FAQ