# Gestión de eventos de entrada con la API bidireccional
La API de transmisión bidireccional utiliza una arquitectura basada en eventos con eventos de entrada y salida estructurados. Comprender el orden correcto de los eventos es fundamental para implementar aplicaciones conversacionales que funcionen y mantener el estado de conversación adecuado durante todas las interacciones.
## Descripción general
La conversación de Nova Sonic sigue una secuencia de eventos estructurada. Se empieza por enviar un evento `sessionStart` que contenga los parámetros de configuración de la inferencia, como la temperatura y los límites de tokens. A continuación, se envía `promptStart` para definir el formato de salida de audio y las configuraciones de las herramientas, y se asigna un identificador único `promptName` que se debe incluir en todos los eventos posteriores.
Para cada tipo de interacción (petición del sistema, audio, etc.), se sigue un patrón de tres partes: se utiliza `contentStart` para definir el tipo de contenido y el rol del contenido (`SYSTEM`, `USER`, `ASSISTANT`, `TOOL`, `SYSTEM_SPEECH`), luego se proporciona el evento de contenido real y se termina con `contentEnd` para cerrar ese segmento. El evento `contentStart` especifica si se están enviando los resultados de la herramienta, si se está transmitiendo audio o una petición al sistema. El evento `contentStart` incluye un identificador único `contentName`.
## Historial de la conversación
El historial de conversaciones solo se puede incluir una vez, después de darle la petición al sistema y antes de que comience la transmisión de audio. Sigue el mismo patrón `contentStart`/`textInput`/`contentEnd`. Los roles `USER` y `ASSISTANT` deben definirse en el evento `contentStart` para cada mensaje histórico. Esto proporciona un contexto esencial para la conversación actual, pero debe completarse antes de que comience cualquier nueva entrada del usuario.
## Transmisión de audio
La transmisión de audio funciona con un muestreo continuo del micrófono. Tras enviar un `contentStart` inicial, se capturan las tramas del audio (aproximadamente de 32 ms cada una) directamente desde el micrófono y se envían inmediatamente como eventos `audioInput` utilizando el mismo `contentName`. Estas muestras de audio deben transmitirse en tiempo real a medida que se capturan, manteniendo la cadencia de muestreo natural del micrófono durante toda la conversación. Todas las tramas de audio comparten un único contenedor de contenido hasta que la conversación finaliza y se cierra explícitamente.
## Cierre de la sesión
Una vez que la conversación finalice o deba terminarse, es esencial cerrar correctamente todas las transmisiones abiertas y finalizar la sesión en la secuencia correcta. Para finalizar correctamente una sesión y evitar la pérdida de recursos, se debe seguir una secuencia de cierre específica:
+ Cierre todas las transmisiones de audio abiertas con el evento `contentEnd`.
+ Envíe un evento `promptEnd` que haga referencia al `promptName` original.
+ Envíe el evento `sessionEnd`.
Omitir cualquiera de estos eventos de cierre puede provocar conversaciones incompletas o recursos huérfanos.
Estos identificadores crean una estructura jerárquica: el `promptName` une todos los eventos de la conversación, mientras que cada `contentName` marca los límites de bloques de contenido específicos. Esta jerarquía garantiza que el modelo mantenga el contexto adecuado durante toda la interacción.
## Flujo de eventos de entrada
En esta sección, se proporciona la estructura del flujo de eventos de entrada.
### 1. RequestStartEvent (inicio de la sesión)
El evento de inicio de la sesión inicializa la conversación con la configuración de inferencias y de detección de turnos.
**Configuración de inferencias:**
+ `maxTokens`: número máximo de tokens que se generarán en la respuesta
+ `topP`: parámetro de muestreo del núcleo (de 0,0 a 1,0) para el control de la aleatoriedad
+ `temperature`: control de la asignación al azar en la generación (de 0,0 a 1,0)
**Configuración de detección de turnos:** el parámetro `endpointingSensitivity` controla la rapidez con la que Nova Sonic detecta cuándo ha terminado de hablar un usuario.
+ `HIGH`: detecta las pausas rápidamente, lo que permite respuestas más rápidas, pero puede interrumpir a hablantes más lentos.
+ `MEDIUM`: tiene una sensibilidad equilibrada para la mayoría de los escenarios de conversación (se recomienda de forma predeterminada).
+ `LOW`: espera más tiempo antes de detectar el final del habla, lo que es mejor para hablantes reflexivos o indecisos.
```
{
"event": {
"sessionStart": {
"inferenceConfiguration": {
"maxTokens": "int",
"topP": "float",
"temperature": "float"
},
"turnDetectionConfiguration": {
"endpointingSensitivity": "HIGH" | "MEDIUM" | "LOW"
}
}
}
}
```
**Ejemplo:**
```
{
"event": {
"sessionStart": {
"inferenceConfiguration": {
"maxTokens": 2048,
"topP": 0.9,
"temperature": 0.7
},
"turnDetectionConfiguration": {
"endpointingSensitivity": "MEDIUM"
}
}
}
}
```
### 2. PromptStartEvent
El evento de inicio de la petición define la configuración de la conversación, lo que incluye los formatos de salida, la selección de voz y las herramientas disponibles.
Para obtener una lista de los ID de voz disponibles, consulte [Soporte lingüístico y capacidades multilingües](https://docs.aws.amazon.com/nova/latest/nova2-userguide/sonic-language-support.html).
```
{
"event": {
"promptStart": {
"promptName": "string", // unique identifier same across all events i.e. UUID
"textOutputConfiguration": {
"mediaType": "text/plain"
},
"audioOutputConfiguration": {
"mediaType": "audio/lpcm",
"sampleRateHertz": 8000 | 16000 | 24000,
"sampleSizeBits": 16,
"channelCount": 1,
"voiceId": "matthew" | "tiffany" | "amy" | "olivia" | "lupe" | "carlos" | "ambre" | "florian" | "lennart" | "beatrice" | "lorenzo" |
"tina" | "carolina" | "leo" | "kiara" | "arjun",
"encoding": "base64",
"audioType": "SPEECH"
},
"toolUseOutputConfiguration": {
"mediaType": "application/json"
},
"toolConfiguration": {
"tools": [
{
"toolSpec": {
"name": "string",
"description": "string",
"inputSchema": {
"json": "{}"
}
}
}
]
}
}
}
}
```
### 3. InputContentStartEvent
#### Texto
El evento de inicio del contenido de texto se utiliza para las peticiones del sistema, el historial de conversaciones y la entrada de texto multimodal.
**Parámetro interactivo:**
+ `true`: habilita la entrada multimodal, lo que permite enviar mensajes de texto durante una sesión de voz activa
+ `false`: entrada de texto estándar para las peticiones del sistema y el historial de conversaciones
**Tipos de roles:**
+ `SYSTEM`: peticiones e instrucciones del sistema
+ `USER`: mensajes del usuario en el historial de conversaciones o la entrada multimodal
+ `ASSISTANT`: respuestas del asistente en el historial de conversaciones
+ `SYSTEM_SPEECH`: controla el formato de transcripción para cambios de código en hindi (alfabetos latino, devanagari o mixto)
```
{
"event": {
"contentStart": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // unique identifier for the content block
"type": "TEXT",
"interactive": "boolean", // true for cross-modal input
"role": "SYSTEM" | "USER" | "ASSISTANT" | "TOOL" | "SYSTEM_SPEECH",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
**Ejemplo, petición del sistema:**
```
{
"event": {
"contentStart": {
"promptName": "conv-12345",
"contentName": "system-prompt-1",
"type": "TEXT",
"interactive": false,
"role": "SYSTEM",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
**Ejemplo, entrada multimodal:**
```
{
"event": {
"contentStart": {
"promptName": "conv-12345",
"contentName": "user-text-1",
"type": "TEXT",
"interactive": true,
"role": "USER",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
#### Audio
```
{
"event": {
"contentStart": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // unique identifier for the content block
"type": "AUDIO",
"interactive": true,
"role": "USER",
"audioInputConfiguration": {
"mediaType": "audio/lpcm",
"sampleRateHertz": 8000 | 16000 | 24000,
"sampleSizeBits": 16,
"channelCount": 1,
"audioType": "SPEECH",
"encoding": "base64"
}
}
}
}
```
#### Herramienta
```
{
"event": {
"contentStart": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // unique identifier for the content block
"interactive": false,
"type": "TOOL",
"role": "TOOL",
"toolResultInputConfiguration": {
"toolUseId": "string", // existing tool use id
"type": "TEXT",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
}
```
### 4. TextInputContent
```
{
"event": {
"textInput": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // unique identifier for the content block
"content": "string"
}
}
}
```
### 5. AudioInputContent
```
{
"event": {
"audioInput": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // same unique identifier from its contentStart
"content": "base64EncodedAudioData"
}
}
}
```
### 6. ToolResultContentEvent
```
"event": {
"toolResult": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string", // same unique identifier from its contentStart
"content": "{\"key\": \"value\"}" // stringified JSON object as a tool result
}
}
```
### 7. InputContentEndEvent
```
{
"event": {
"contentEnd": {
"promptName": "string", // same unique identifier from promptStart event
"contentName": "string" // same unique identifier from its contentStart
}
}
}
```
### 8. PromptEndEvent
```
{
"event": {
"promptEnd": {
"promptName": "string" // same unique identifier from promptStart event
}
}
}
```
### 9. RequestEndEvent
```
{
"event": {
"sessionEnd": {}
}
}
```