Autenticazione dell'agente

Panoramica

Quando crei agenti conversazionali, potresti dover limitare l’accesso a determinati agenti o conversazioni. ElevenLabs offre diversi meccanismi di autenticazione per garantire che solo gli utenti autorizzati possano interagire con i tuoi agenti.

Metodi di autenticazione

ElevenLabs offre due metodi principali per proteggere i tuoi agenti conversazionali:

Utilizzare gli URL firmati

Gli URL firmati sono l’approccio consigliato per le applicazioni client. Questo metodo ti permette di autenticare gli utenti senza esporre la tua chiave API.

Come funzionano gli URL firmati

1. Il tuo server richiede un URL firmato a ElevenLabs usando la tua chiave API.
2. ElevenLabs genera un token temporaneo e restituisce un URL WebSocket firmato.
3. La tua applicazione client usa questo URL firmato per stabilire una connessione WebSocket.
4. L’URL firmato scade dopo 15 minuti.

Generare un URL firmato tramite l’API

Per ottenere un URL firmato, invia una richiesta all’endpoint get_signed_url con l’ID del tuo agente:

# 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

La risposta curl ha il seguente formato:

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

Connessione al tuo agente tramite un URL firmato

Recupera dal server l’URL firmato generato e usalo nel client per connetterti al websocket.

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

Scadenza dell’URL firmato

Gli URL firmati sono validi per 15 minuti. La sessione di conversazione può durare più a lungo, ma la conversazione deve essere avviata entro 15 minuti.

Utilizzare le liste di autorizzazione

Le liste di autorizzazione ti consentono di limitare l’accesso ai tuoi agenti conversazionali in base al dominio di origine. In questo modo, solo le richieste provenienti da domini approvati possono connettersi al tuo agente.

Come funzionano le liste di autorizzazione

1. Configuri un elenco di hostname approvati per il tuo agente.
2. Quando un client tenta di connettersi, ElevenLabs verifica se l’origine della richiesta corrisponde a un hostname consentito.
3. Se l’origine è nella lista di autorizzazione, la connessione è consentita; altrimenti, viene rifiutata.

Configurare le liste di autorizzazione

Le liste di autorizzazione vengono configurate nelle impostazioni di autenticazione del tuo agente. Puoi specificare fino a 10 hostname univoci autorizzati a connettersi al tuo agente.

Esempio: configurare una lista di autorizzazione

Scegliere un metodo di autenticazione

Configura un metodo di autenticazione per agente:

1. Usa gli URL firmati (enable_auth) per le sessioni client autenticate.
2. Usa le liste di autorizzazione (allowlist) per il controllo degli accessi basato sugli hostname.

Non configurare URL firmati e liste di autorizzazione insieme sullo stesso agente. Scegli il metodo più adatto al tuo modello di deployment.

Esempio: solo URL firmati

Usa enable_auth senza una 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
    )
  )
)

Esempio: solo lista di autorizzazione

Usa allowlist senza abilitare gli URL firmati:

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"),
      ]
    )
  )
)

Domande frequenti