Cree sesiones de voz en tiempo real con la API MKA1 usando LiveKit. Configure opciones de LLM, herramientas, ajuste de STT y continuidad de conversación.
Use this file to discover all available pages before exploring further.
La API MKA1 proporciona una interfaz de voz en tiempo real a través de LiveKit. Esta guía cubre cómo obtener un token de sala, conectarse a una sesión de voz, enviar audio y texto como entrada, y capturar las respuestas del agente.
La integración de voz consta de tres componentes principales:
Token de Sala: Un JWT que otorga acceso a una sala de LiveKit
Conexión LiveKit: Comunicación en tiempo real basada en WebRTC
Agente de Voz: Procesa entrada de audio/texto y genera respuestas habladas
El flujo del agente funciona de la siguiente manera:
STT (Reconocimiento de Voz a Texto): El audio se transmite vía WebSocket a 16kHz y se transcribe
LLM: El texto transcrito es procesado por la API de Respuestas MKA1
TTS (Texto a Voz): La salida del LLM se sintetiza a audio a 24kHz
Cada solicitud que el agente de voz envía a la API de Respuestas incluye automáticamente "voice_mode": "true" en el metadata de la solicitud. Esto le permite distinguir respuestas originadas por voz de las basadas en texto al revisar el uso o el historial de respuestas.
Para iniciar una sesión de voz, primero solicite un token de sala a la API MKA1. El endpoint de token requiere una clave de API y acepta opcionalmente X-On-Behalf-Of para identificar usuarios finales. Consulte Autenticación para más detalles.
El objeto llm acepta los mismos campos que el cuerpo de la solicitud de la API de Respuestas, menos los campos gestionados por el agente de voz (input, stream, store, background).
Campo
Requerido
Descripción
model
Sí
Modelo LLM a utilizar (por ejemplo, meetkai:functionary-es-mini)
instructions
No
Instrucciones de sistema personalizadas para el agente
previous_response_id
No
Encadena esta sesión a una respuesta específica de una sesión anterior
conversation
No
Continúa una conversación existente — pase { "id": "conv_abc123..." } o el ID de la conversación como cadena
tools
No
Array de definiciones de herramientas (function, web_search, file_search, etc.)
tool_choice
No
Cómo el modelo selecciona herramientas ("auto", "none", "required", o una herramienta específica)
parallel_tool_calls
No
Permitir ejecución paralela de herramientas
max_tool_calls
No
Máximo de llamadas de herramientas por respuesta (por defecto: 30)
temperature
No
Temperatura de muestreo (por ejemplo, 0.7)
max_output_tokens
No
Máximo de tokens en la respuesta
reasoning
No
Configuración de razonamiento (por ejemplo, { "effort": "high" }). Establezca { "effort": "none" } para sesiones de voz para minimizar la latencia — vea la nota abajo.
top_p
No
Parámetro de muestreo nucleus
presence_penalty
No
Penalización de presencia para repetición de tokens
frequency_penalty
No
Penalización de frecuencia para repetición de tokens
truncation
No
"auto" o "disabled" — controla la truncación de contexto
context_management
No
Estrategias de gestión de contexto para truncar la conversación
service_tier
No
"auto", "default", "flex", o "priority"
prompt
No
Referencia a una plantilla de prompt y sus variables
text
No
Configuración de salida de texto (formato, verbosidad)
metadata
No
Metadatos clave-valor pasados a la API de Respuestas
No puede especificar ambos previous_response_id y conversation.
Los metadatos del token se incrustan en un JWT, que se pasa como encabezado HTTP. Mantenga el payload total de llm por debajo de ~8 KB — los arrays grandes de tools pueden necesitar ser recortados.
Para sesiones de voz, desactive el razonamiento configurando "reasoning": { "effort": "none" }. El razonamiento añade tiempo de pensamiento antes de que el modelo responda, lo que incrementa la latencia y crea pausas notables en la conversación. Desactivarlo mantiene las respuestas rápidas y naturales.
Al continuar una sesión, la clave de API y el encabezado X-On-Behalf-Of (si se usa) deben coincidir con la sesión original. El agente de voz cifra ambos en el token de sala y los pasa a todos los servicios MKA1 aguas abajo. Si no coinciden, el agente no tendrá acceso al contexto anterior.
Una vez que tenga un token, use el SDK de LiveKit para conectarse a la sala.
import { Room, RoomEvent, Track } from 'livekit-client';const room = new Room();// Conéctese a la salaawait room.connect(session.url, session.token);console.log('Conectado a la sala:', room.name);
El agente acepta entrada de audio a través de la pista de audio de la sala de LiveKit. El audio se procesa a una frecuencia de muestreo de 16kHz.
import { createLocalAudioTrack } from 'livekit-client';// Cree una pista de audio local desde el micrófonoconst audioTrack = await createLocalAudioTrack({ echoCancellation: true, noiseSuppression: true, autoGainControl: true});// Publique la pista en la salaawait room.localParticipant.publishTrack(audioTrack);
Detección de Actividad de Voz (VAD): El VAD se maneja en el servidor por el agente MKA1, no localmente. El agente detecta automáticamente cuando deja de hablar y comienza el procesamiento.
Frecuencia de muestreo: El audio se transmite a 16kHz al servicio de STT.
Finalización: El agente utiliza finalización en el servidor para determinar cuándo termina el habla. No hay retraso de finalización local.
También puede enviar mensajes de texto directamente al agente sin hablar.
// Envíe un mensaje de texto al agenteconst message = JSON.stringify({ type: 'user_message', content: 'What is the capital of France?'});await room.localParticipant.publishData( new TextEncoder().encode(message), { reliable: true, topic: 'lk.chat' });
El agente publica el response_id y conversation_id (si aplica) cuando comienza a generar una respuesta. Guarde el response_id para encadenar futuras sesiones usando previous_response_id.
room.on(RoomEvent.DataReceived, (payload, participant) => { if (participant.identity !== room.localParticipant.identity) { const data = JSON.parse(new TextDecoder().decode(payload)); if (data.response_id) { console.log('ID de respuesta:', data.response_id); console.log('ID de conversación:', data.conversation_id); // presente si se usa una conversación // Guarde response_id para encadenar futuras sesiones con previous_response_id } }});
El agente soporta conversaciones de varios turnos con memoria persistente. Cada respuesta recibe automáticamente un response_id, mientras que las conversaciones deben ser creadas y gestionadas explícitamente a través de la API de Conversaciones.Hay dos formas de continuar una conversación:llm.previous_response_id encadena una nueva sesión a una respuesta específica. El agente recibe el contexto de esa respuesta y todas las respuestas previas en la cadena. Use esto cuando:
Desea continuar desde un punto específico en una conversación
Está construyendo un flujo de conversación lineal
Desea ramificar desde una respuesta específica
llm.conversation referencia una conversación creada vía la API de Conversaciones. Use esto cuando:
Necesita gestionar metadatos de la conversación (títulos, etiquetas, etc.)
Desea listar o buscar conversaciones pasadas
Está construyendo una interfaz de chat con historial persistente de conversación
Múltiples clientes necesitan acceder a la misma conversación
import { Room, RoomEvent } from 'livekit-client';import { SDK } from '@meetkai/mka1';const mka1 = new SDK({ bearerAuth: `Bearer ${YOUR_API_KEY}`,});// 1. Obtenga un token para una nueva sesiónconst session = await mka1.llm.speech.livekitToken({ llm: { model: 'meetkai:functionary-es-mini' }}, { headers: { 'X-On-Behalf-Of': 'user-123' } }); // Opcional// 2. Conéctese a la salaconst room = new Room();await room.connect(session.url, session.token);// 3. Rastree el ID de respuesta cuando el agente respondalet lastResponseId: string;room.on(RoomEvent.DataReceived, (payload, participant) => { const data = JSON.parse(new TextDecoder().decode(payload)); if (data.response_id) { lastResponseId = data.response_id; }});// 4. Tenga una conversación...// 5. Desconéctese cuando termineroom.disconnect();
Use previous_response_id para encadenar una nueva sesión a la última respuesta, preservando el contexto de la conversación:
// Use la misma clave de API y X-On-Behalf-Of que la sesión originalconst mka1 = new SDK({ bearerAuth: `Bearer ${YOUR_API_KEY}`,});// 1. Obtenga un nuevo token encadenado a la respuesta anteriorconst session = await mka1.llm.speech.livekitToken({ llm: { model: 'meetkai:functionary-es-mini', previousResponseId: lastResponseId }}, { headers: { 'X-On-Behalf-Of': 'user-123' } }); // Opcional, pero debe coincidir si la sesión original lo usó// 2. Conéctese a la nueva salaconst room = new Room();await room.connect(session.url, session.token);// 3. El agente ahora tiene contexto de la sesión anterior// Usuario: "¿Qué te pregunté antes?"// Agente: "Me preguntaste sobre la capital de Francia..."
Use conversation_id para continuar una conversación existente creada vía la API de Conversaciones:
// Use la misma clave de API y X-On-Behalf-Of que la sesión originalconst mka1 = new SDK({ bearerAuth: `Bearer ${YOUR_API_KEY}`,});// 1. Obtenga un nuevo token con el ID de la conversaciónconst session = await mka1.llm.speech.livekitToken({ llm: { model: 'meetkai:functionary-es-mini', conversation: { id: conversationId } }}, { headers: { 'X-On-Behalf-Of': 'user-123' } }); // Opcional, pero debe coincidir si la sesión original lo usó// 2. Conéctese a la nueva salaconst room = new Room();await room.connect(session.url, session.token);// 3. El agente ahora tiene contexto de todo el historial de la conversación
Al continuar una conversación, la clave de API y el encabezado X-On-Behalf-Of (si se usa) deben coincidir con la sesión original. El contexto está limitado a la identidad autenticada.