Trazas de OpenTelemetry

ElevenLabs Agents puede exportar conversaciones como trazas de OpenTelemetry codificadas como JSON de OTLP (resourceSpans). Reenvíalas a Datadog, Grafana Tempo, Honeycomb o cualquier backend que procese OTLP.

Resumen

Exporta trazas desde tres vías. Las tres comparten el mismo ID de traza por conversación y la nomenclatura de atributos elevenlabs.*. La forma y la temporización de los spans difieren entre post-llamada/GET (basado en transcripciones) y monitorización (basado en eventos).

Vías de exportación

Elegir una vía

• Todas las llamadas completadas en tu almacén de datos: webhook post-llamada
• Exportación puntual o reparación: GET de conversación con format=opentelemetry
• Interfaz de supervisión o alertas en directo: WebSocket de monitorización
• Cronología completa y detallada a posteriori: webhook post-llamada o GET de conversación
• Eventos de herramientas, MCP o medidas de protección a medida que ocurren: WebSocket de monitorización

Usa traceId o elevenlabs.conversation_id para unir datos entre vías. Combina la monitorización para operaciones en directo, los webhooks para análisis duradero y GET para rellenar datos.

Necesitas un recopilador o proveedor de observabilidad compatible con OTLP para cada vía. Los webhooks post-llamada requieren una ruta de webhook del espacio de trabajo. La API GET y el WebSocket de monitorización tienen cada uno sus propios ámbitos de clave de API y configuración; consulta las secciones siguientes.

Webhook post-llamada

Cuando termina una conversación, ElevenLabs envía una solicitud POST si hay configurado un webhook post-llamada, events incluye transcript y transcript_format es opentelemetry.

El type del webhook es post_call_transcription_otel (no post_call_transcription, que devuelve transcripciones JSON).

Carga útil del webhook

{
  "type": "post_call_transcription_otel",
  "event_timestamp": 1700000000,
  "data": {
    "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa",
    "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
    "otlp_traces": {
      "resourceSpans": []
    }
  }
}

Activar transcripciones de OpenTelemetry

Entrega

Forma de la traza

Cada entrega es una traza completa: un span raíz y sus elementos secundarios.

elevenlabs.conversation
├── elevenlabs.recv.user_transcript
├── elevenlabs.recv.agent_response
│   └── elevenlabs.tool.{name}
└── ...

Los spans de respuesta del agente incluyen elevenlabs.reasoning_content cuando la entrega contiene un resumen de razonamiento.

La temporización procede de time_in_call_secs de la transcripción y de los metadatos de la llamada. El span raíz establece elevenlabs.source = post_call_webhook y el estado ERROR cuando la llamada no terminó con una desconexión normal del cliente.

GET de conversación

Solicita el formato OpenTelemetry en Obtener conversación para recibir el mismo objeto otlp_traces que en el webhook post-llamada de OpenTelemetry, además del modelo completo de conversación.

GET /v1/convai/conversations/{conversation_id}?format=opentelemetry

Requiere una clave de API con CONVAI_READ. Con format=json (predeterminado), se omite otlp_traces.

{
  "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa",
  "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "status": "done",
  "transcript": [],
  "otlp_traces": {
    "resourceSpans": []
  }
}

import os
from dotenv import load_dotenv
from elevenlabs import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
conversation = elevenlabs.conversational_ai.conversations.get(
    conversation_id="conv_9001k1zph3fkeh5s8xg9z90swaqa",
    format="opentelemetry",
)
otlp_traces = conversation.otlp_traces

Los nombres de span esperados incluyen elevenlabs.conversation, elevenlabs.recv.user_transcript y elevenlabs.recv.agent_response.

WebSocket de monitorización

Transmite datos de trazas de OpenTelemetry como JSON de OTLP mientras hay una conversación en curso. Cada mensaje es un pequeño lote de resourceSpans, no una traza única al finalizar la llamada.

wss://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/monitor?events_format=opentelemetry

La autenticación requiere CONVAI_WRITE, xi-api-key (o Authorization) y acceso de EDITOR al espacio de trabajo del agente. Conéctate después de que empiece la conversación.

Protocolo de sesión

1. Conéctate con encabezados de autenticación.
2. Recibe {"type": "connected"}.
3. Recibe un lote de spans raíz (elevenlabs.conversation, elevenlabs.source = monitoring).
4. Recibe el historial almacenado en caché (aproximadamente los últimos 100 eventos) y, después, {"type": "history_complete"}.
5. Recibe lotes de spans en directo a medida que se producen los eventos.

Con events_format=json (predeterminado), el WebSocket devuelve eventos de cliente sin procesar en lugar de resourceSpans. Los comandos de control coinciden con los de Monitorización en tiempo real.

Forma de la traza

elevenlabs.conversation
├── elevenlabs.turn.0
│   ├── elevenlabs.event.user_transcript
│   └── elevenlabs.tool.{name}
└── elevenlabs.turn.1

Los eventos estructurados se asignan a atributos específicos (por ejemplo, elevenlabs.user.text, elevenlabs.agent.text). Los eventos desconocidos usan elevenlabs.event.data con JSON truncado.

Ejemplo de conexión

import WebSocket from "ws";
const ws = new WebSocket(
  "wss://api.elevenlabs.io/v1/convai/conversations/conv_9001k1zph3fkeh5s8xg9z90swaqa/monitor?events_format=opentelemetry",
  {
    headers: {
      "xi-api-key": process.env.ELEVENLABS_API_KEY!,
    },
  }
);
ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.type === "connected" || msg.type === "history_complete") return;
  if (msg.resourceSpans) {
    forwardToCollector({ resourceSpans: msg.resourceSpans });
  }
});

Estructura JSON de OTLP

Las trazas de OpenTelemetry de todas las vías comparten el mismo diseño de lote JSON de OTLP:

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "elevenlabs-convai" } },
          {
            "key": "elevenlabs.conversation_id",
            "value": { "stringValue": "conv_9001k1zph3fkeh5s8xg9z90swaqa" }
          }
        ]
      },
      "scopeSpans": [
        {
          "scope": { "name": "elevenlabs.convai", "version": "1.0.0" },
          "spans": [
            {
              "traceId": "32_hex_chars",
              "spanId": "16_hex_chars",
              "name": "elevenlabs.recv.agent_response",
              "startTimeUnixNano": "1700000000000000000",
              "endTimeUnixNano": "1700000001000000000",
              "status": { "code": 1 }
            }
          ]
        }
      ]
    }
  ]
}

Limitaciones

• No hay envío directo a tu ruta gRPC de OTLP.
• Las cargas útiles son JSON con formato de exportación de OTLP, no protobuf sin procesar en la transmisión.

Documentación relacionada

• Webhooks post-llamada
• Monitorización en tiempo real