# Processamento de eventos de entrada com a API bidirecional
A API de streaming bidirecional usa uma arquitetura orientada por eventos com eventos estruturados de entrada e saída. Compreender a ordem correta dos eventos é crucial para implementar aplicações de conversação bem-sucedidas e manter o estado adequado da conversa durante as interações.
## Visão geral
A conversa do Nova Sonic segue uma sequência estruturada de eventos. Você começa enviando um evento `sessionStart` que contém os parâmetros de configuração de inferência, como temperatura e limites de token. Em seguida, você envia `promptStart` para definir o formato de saída de áudio e as configurações de ferramentas, atribuindo um identificador `promptName` exclusivo que deve ser incluído em todos os eventos subsequentes.
Para cada tipo de interação (prompt do sistema, áudio etc.), você segue um padrão de três partes: use `contentStart` para definir o tipo de conteúdo e o perfil do conteúdo (`SYSTEM`, `USER`, `ASSISTANT`, `TOOL`, `SYSTEM_SPEECH`), depois forneça o evento de conteúdo real e finalize com `contentEnd` para concluir o segmento. O evento `contentStart` especifica se você está enviando resultados de ferramentas, transmitindo áudio ou se é um prompt do sistema. O evento `contentStart` inclui um identificador `contentName` exclusivo.
## Histórico da conversa
Um histórico de conversa pode ser incluído apenas uma vez, após o prompt do sistema e antes do início do streaming de áudio. Ele segue o mesmo padrão `contentStart`/`textInput`/`contentEnd`. Os perfis `USER` e `ASSISTANT` devem ser definidos no evento `contentStart` para cada mensagem histórica. Isso fornece um contexto essencial para a conversa atual, mas deve ser concluído antes que qualquer nova entrada do usuário comece.
## Streaming de áudio
O streaming de áudio opera com amostragem contínua de microfone. Depois de enviar um `contentStart` inicial, os quadros de áudio (aproximadamente 32 ms cada) são capturados diretamente do microfone e enviados imediatamente como eventos `audioInput` usando o mesmo `contentName`. Essas amostras de áudio devem ser transmitidas em tempo real à medida que são capturadas, mantendo a cadência natural de amostragem do microfone durante toda a conversa. Todos os quadros de áudio compartilham um único contêiner de conteúdo até que a conversa termine e seja explicitamente concluída.
## Conclusão da sessão
Depois que a conversa terminar ou precisar ser encerrada, é essencial fechar adequadamente todos os streamings abertos e encerrar a sessão na sequência correta. Para encerrar adequadamente uma sessão e evitar vazamentos de recursos, você deve seguir uma sequência de fechamento específica:
+ Feche todos os streamings de áudio abertos com o evento `contentEnd`.
+ Envie um evento `promptEnd` que faça referência ao `promptName` original.
+ Envie o evento `sessionEnd`.
Ignorar qualquer um desses eventos de encerramento pode resultar em conversas incompletas ou em recursos órfãos.
Esses identificadores criam uma estrutura hierárquica: o `promptName` une todos os eventos da conversa, enquanto cada `contentName` marca os limites de blocos de conteúdo específicos. Essa hierarquia garante que o modelo mantenha o contexto adequado durante toda a interação.
## Fluxo de eventos de entrada
A estrutura do fluxo de eventos de entrada é fornecida nesta seção.
### 1. RequestStartEvent (Início da sessão)
O evento de início da sessão inicializa a conversa com a configuração de inferência e as configurações de detecção de turnos.
**Configuração da inferência:**
+ `maxTokens`: número máximo de tokens a serem gerados na resposta
+ `topP`: parâmetro de amostragem de núcleo (0,0 a 1,0) para controlar a randomização
+ `temperature`: controla a randomização na geração (0,0 a 1,0)
**Configuração de detecção de turnos:** o parâmetro `endpointingSensitivity` controla a rapidez com que o Nova Sonic detecta quando um usuário termina de falar:
+ `HIGH`: detecta pausas rapidamente, permitindo respostas mais rápidas, mas pode interromper quem fala mais devagar
+ `MEDIUM`: sensibilidade balanceada para a maioria dos cenários de conversação (padrão recomendado)
+ `LOW`: espera mais antes de detectar o final da fala, melhor para falantes atenciosos ou hesitantes
```
{
"event": {
"sessionStart": {
"inferenceConfiguration": {
"maxTokens": "int",
"topP": "float",
"temperature": "float"
},
"turnDetectionConfiguration": {
"endpointingSensitivity": "HIGH" | "MEDIUM" | "LOW"
}
}
}
}
```
**Exemplo:**
```
{
"event": {
"sessionStart": {
"inferenceConfiguration": {
"maxTokens": 2048,
"topP": 0.9,
"temperature": 0.7
},
"turnDetectionConfiguration": {
"endpointingSensitivity": "MEDIUM"
}
}
}
}
```
### 2. PromptStartEvent
O evento de início do prompt define a configuração da conversa, incluindo os formatos de saída, a seleção de voz e as ferramentas disponíveis.
Para obter uma lista de IDs de voz disponíveis, consulte [Suporte a idiomas e recursos multilíngues](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
O evento de início do conteúdo de texto é usado para prompts do sistema, histórico de conversas e entrada de texto intermodal.
**Parâmetro interativo:**
+ `true`: habilita a entrada intermodal, possibilitando mensagens de texto durante uma sessão de voz ativa
+ `false`: entrada de texto padrão para prompts do sistema e histórico de conversas
**Tipos de perfil:**
+ `SYSTEM`: instruções e prompts do sistema
+ `USER`: mensagens do usuário no histórico de conversas ou na entrada intermodal
+ `ASSISTANT`: respostas do assistente no histórico de conversas
+ `SYSTEM_SPEECH`: controla a formatação da transcrição para troca de código em hindi (scripts latino/devanagari/mistos)
```
{
"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"
}
}
}
}
```
**Exemplo - Prompt do sistema:**
```
{
"event": {
"contentStart": {
"promptName": "conv-12345",
"contentName": "system-prompt-1",
"type": "TEXT",
"interactive": false,
"role": "SYSTEM",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
**Exemplo - Entrada intermodal:**
```
{
"event": {
"contentStart": {
"promptName": "conv-12345",
"contentName": "user-text-1",
"type": "TEXT",
"interactive": true,
"role": "USER",
"textInputConfiguration": {
"mediaType": "text/plain"
}
}
}
}
```
#### Áudio
```
{
"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"
}
}
}
}
```
#### Ferramenta
```
{
"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": {}
}
}
```