Autenticación de agentes

Descripción general

Al crear agentes conversacionales, puede que necesites restringir el acceso a determinados agentes o conversaciones. ElevenLabs ofrece varios mecanismos de autenticación para garantizar que solo usuarios autorizados puedan interactuar con tus agentes.

Métodos de autenticación

ElevenLabs ofrece dos métodos principales para proteger tus agentes conversacionales:

Uso de URL firmadas

Las URL firmadas son el enfoque recomendado para aplicaciones del lado del cliente. Este método te permite autenticar usuarios sin exponer tu clave de API.

Cómo funcionan las URL firmadas

1. Tu servidor solicita una URL firmada a ElevenLabs mediante tu clave de API.
2. ElevenLabs genera un token temporal y devuelve una URL de WebSocket firmada.
3. Tu aplicación cliente usa esta URL firmada para establecer una conexión WebSocket.
4. La URL firmada caduca después de 15 minutos.

Generar una URL firmada mediante la API

Para obtener una URL firmada, realiza una solicitud al endpoint get_signed_url con el ID de tu 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 respuesta de curl tiene el siguiente formato:

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

Conectarte a tu agente mediante una URL firmada

Recupera del cliente la URL firmada generada por el servidor y úsala para conectarte 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}")

Caducidad de las URL firmadas

Las URL firmadas son válidas durante 15 minutos. La sesión de conversación puede durar más, pero debes iniciar la conversación dentro de ese plazo de 15 minutos.

Uso de listas de permitidos

Las listas de permitidos permiten restringir el acceso a tus agentes conversacionales según el dominio de origen. Esto garantiza que solo las solicitudes procedentes de dominios aprobados puedan conectarse a tu agente.

Cómo funcionan las listas de permitidos

1. Configuras una lista de nombres de host aprobados para tu agente.
2. Cuando un cliente intenta conectarse, ElevenLabs comprueba si el origen de la solicitud coincide con un nombre de host permitido.
3. Si el origen está en la lista de permitidos, se permite la conexión; de lo contrario, se rechaza.

Configurar listas de permitidos

Las listas de permitidos se configuran como parte de los ajustes de autenticación de tu agente. Puedes especificar hasta 10 nombres de host únicos autorizados para conectarse a tu agente.

Ejemplo: configurar una lista de permitidos

Elegir un método de autenticación

Configura un método de autenticación por agente:

1. Usa URL firmadas (enable_auth) para sesiones autenticadas del cliente.
2. Usa listas de permitidos (allowlist) para controlar el acceso según el nombre de host.

No configures URL firmadas y listas de permitidos a la vez para el mismo agente. Elige el método que se ajuste a tu modelo de implementación.

Ejemplo: solo URL firmadas

Usa enable_auth sin 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
    )
  )
)

Ejemplo: solo lista de permitidos

Usa allowlist sin habilitar las URL firmadas:

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

Preguntas frecuentes