Uwierzytelnianie agenta

Omówienie

Podczas tworzenia agentów konwersacyjnych możesz chcieć ograniczyć dostęp do niektórych agentów lub rozmów. ElevenLabs oferuje kilka mechanizmów uwierzytelniania, które zapewniają, że z twoimi agentami wchodzą w interakcję tylko uprawnieni użytkownicy.

Metody uwierzytelniania

ElevenLabs oferuje dwie główne metody zabezpieczania agentów konwersacyjnych:

Korzystanie z podpisanych adresów URL

Podpisane adresy URL to zalecane rozwiązanie dla aplikacji po stronie klienta. Ta metoda pozwala uwierzytelniać użytkowników bez ujawniania klucza API.

Jak działają podpisane adresy URL

1. Twój serwer żąda podpisanego adresu URL od ElevenLabs, używając klucza API.
2. ElevenLabs generuje tymczasowy token i zwraca podpisany adres WebSocket URL.
3. Twoja aplikacja kliencka używa tego podpisanego adresu URL, aby nawiązać połączenie WebSocket.
4. Podpisany adres URL wygasa po 15 minutach.

Generowanie podpisanego adresu URL przez API

Aby uzyskać podpisany adres URL, wyślij żądanie do endpointu get_signed_url z identyfikatorem agenta:

# 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

Odpowiedź curl ma następujący format:

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

Łączenie z agentem za pomocą podpisanego adresu URL

Pobierz z serwera wygenerowany podpisany adres URL w kliencie i użyj go, aby połączyć się z WebSocketem.

# 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}")

Wygasanie podpisanego adresu URL

Podpisane adresy URL są ważne przez 15 minut. Sesja rozmowy może trwać dłużej, ale musi zostać rozpoczęta w ciągu tych 15 minut.

Korzystanie z list dozwolonych

Listy dozwolonych pozwalają ograniczyć dostęp do agentów konwersacyjnych na podstawie domeny źródłowej. Dzięki temu z agentem mogą łączyć się tylko żądania z zatwierdzonych domen.

Jak działają listy dozwolonych

1. Konfigurujesz listę zatwierdzonych nazw hostów dla swojego agenta.
2. Gdy klient próbuje się połączyć, ElevenLabs sprawdza, czy źródło żądania odpowiada dozwolonej nazwie hosta.
3. Jeśli źródło jest na liście dozwolonych, połączenie jest dozwolone; w przeciwnym razie zostaje odrzucone.

Konfigurowanie list dozwolonych

Listy dozwolonych konfigurujesz w ustawieniach uwierzytelniania agenta. Możesz podać maksymalnie 10 unikalnych nazw hostów, które mogą łączyć się z agentem.

Przykład: konfiguracja listy dozwolonych

Wybór metody uwierzytelniania

Skonfiguruj jedną metodę uwierzytelniania na agenta:

1. Użyj podpisanych adresów URL (enable_auth) dla uwierzytelnionych sesji klienta.
2. Użyj list dozwolonych (allowlist) do kontroli dostępu na podstawie nazwy hosta.

Nie konfiguruj jednocześnie podpisanych adresów URL i list dozwolonych dla tego samego agenta. Wybierz metodę pasującą do twojego modelu wdrożenia.

Przykład: tylko podpisane adresy URL

Użyj enable_auth bez 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
    )
  )
)

Przykład: tylko lista dozwolonych

Użyj allowlist bez włączania podpisanych adresów URL:

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