# Processamento de eventos de saída com a API bidirecional
<a name="sonic-output-events"></a>

Quando o modelo Amazon Nova Sonic responde, ele segue uma sequência estruturada de eventos. O fluxo começa com um evento `completionStart` que contém identificadores exclusivos, como `sessionId`, `promptName` e `completionId`. Esses identificadores são consistentes em todo o ciclo de resposta e unem todos os eventos de resposta subsequentes.

## Visão geral
<a name="sonic-output-overview"></a>

Cada tipo de resposta segue um padrão consistente de três partes: `contentStart` define o tipo e o formato do conteúdo, o evento real do conteúdo e `contentEnd` conclui esse segmento. A resposta normalmente inclui vários blocos de conteúdo em sequência: transcrição do reconhecimento automático de fala (ASR) (o que o usuário disse), uso opcional de ferramentas (quando informações externas são necessárias), resposta de texto (o que o modelo planeja dizer) e resposta de áudio (a saída falada).

## Tipos de conteúdo de resposta
<a name="sonic-response-content-types"></a>

### Transcrição de ASR
<a name="sonic-asr-transcription"></a>

A transcrição do ASR aparece primeiro, fornecendo a compreensão do modelo sobre a fala do usuário com `role: "USER"` e `"additionalModelFields": "{\"generationStage\":\"FINAL\"}"` no `contentStart`.

### Uso de ferramentas
<a name="sonic-tool-use-response"></a>

Quando o modelo precisa de dados externos, ele envia eventos relacionados à ferramenta com nomes e parâmetros específicos da ferramenta.

### Resposta de texto
<a name="sonic-text-response"></a>

A resposta de texto fornece uma prévia do discurso planejado com `role: "ASSISTANT"` e `"additionalModelFields": "{\"generationStage\":\"SPECULATIVE\"}"`.

### Resposta de áudio
<a name="sonic-audio-response"></a>

A resposta de áudio então fornece trechos de fala codificados no Base64 que compartilham o mesmo `contentId` em todo o streaming.

## Compatibilidade com o barge-in
<a name="sonic-barge-in-support"></a>

Durante a geração de áudio, o Amazon Nova Sonic é compatível com o fluxo natural de conversação por meio de seu recurso de barge-in. Quando um usuário interrompe o Amazon Nova Sonic enquanto ele está falando, o Nova Sonic imediatamente para de gerar fala, muda para o modo de escuta e envia uma notificação de conteúdo indicando que a interrupção ocorreu. Como o Nova Sonic opera mais rápido do que em tempo real, o áudio pode já ter sido entregue, mas ainda não foi reproduzido. A notificação de interrupção permite que a aplicação cliente limpe sua fila de áudios e interrompa a reprodução imediatamente, criando uma experiência conversacional responsiva.

## Transcrição final
<a name="sonic-final-transcription"></a>

Depois que a geração de áudio é concluída (ou interrompida via barge-in), o Amazon Nova Sonic fornece uma resposta de texto adicional que contém uma transcrição em nível de frase do que foi realmente falado. Essa resposta de texto inclui um evento `contentStart` com `role: "ASSISTANT"` e `"additionalModelFields": "{\"generationStage\":\"FINAL\"}"`.

## Monitoramento de uso
<a name="sonic-usage-tracking"></a>

Durante todo o tratamento da resposta, eventos `usageEvent` são enviados para rastrear o consumo de tokens. Esses eventos contêm métricas detalhadas para tokens de entrada e de saída (tanto de fala quanto de texto) e seus totais acumulados. Cada `usageEvent` mantém o mesmo `sessionId`, `promptName` e `completionId` que outros eventos no fluxo da conversa. A seção de detalhes fornece as alterações incrementais (delta) e os totais acumulados do uso de tokens, permitindo o monitoramento preciso do uso durante a conversa.

## Conclusão
<a name="sonic-completion"></a>

O modelo envia um evento `completionEnd` com os identificadores originais e um `stopReason` que indica como a conversa terminou. Essa hierarquia de eventos garante que a aplicação possa rastrear quais partes da resposta estão associadas e processá-las adequadamente, mantendo o contexto em vários turnos.

O fluxo de eventos de saída começa entrando na fase de geração de resposta. Ele começa com o reconhecimento automático de fala, seleciona uma ferramenta para uso, transcreve a fala, gera áudio, finaliza a transcrição e encerra a sessão.

![Diagrama de fluxo que mostra os estágios da conversa desde o início, passando por ASR, manuseio de ferramentas, respostas de texto e áudio até o fim com os eventos associados.](http://docs.aws.amazon.com/pt_br/nova/latest/nova2-userguide/images/Output-Event -Flow_3.png)


## Fluxo de eventos de saída
<a name="sonic-output-event-flow"></a>

A estrutura do fluxo de eventos de saída é fornecida nesta seção.

### 1. UsageEvent
<a name="sonic-usage-event"></a>

```
"event": {
    "usageEvent": {
        "completionId": "string", // unique identifier for completion
        "details": {
            "delta": { // incremental changes since last event
                "input": {
                    "speechTokens": number, // input speech tokens
                    "textTokens": number // input text tokens
                },
                "output": {
                    "speechTokens": number, // speech tokens generated
                    "textTokens": number // text tokens generated
                }
            },
            "total": { // cumulative counts
                "input": {
                    "speechTokens": number, // total speech tokens processed
                    "textTokens": number // total text tokens processed
                },
                "output": {
                    "speechTokens": number, // total speech tokens generated
                    "textTokens": number // total text tokens generated
                }
            }
        },
        "promptName": "string", // same unique identifier from promptStart event
        "sessionId": "string", // unique identifier
        "totalInputTokens": number, // cumulative input tokens
        "totalOutputTokens": number, // cumulative output tokens
        "totalTokens": number // total tokens in the session
    }
}
```

### 2. CompleteStartEvent
<a name="sonic-completion-start-event"></a>

```
"event": {
    "completionStart": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
    }
}
```

### 3. TextOutputContent
<a name="sonic-text-output-content"></a>

#### ContentStart
<a name="sonic-text-output-content-start"></a>

```
"event": {
    "contentStart": {
        "additionalModelFields": "{\"generationStage\":\"FINAL\"}" | "{\"generationStage\":\"SPECULATIVE\"}",
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // unique identifier for the content block
        "type": "TEXT",
        "role": "USER" | "ASSISTANT",
        "textOutputConfiguration": {
            "mediaType": "text/plain"
        }
    }
}
```

#### TextOutput
<a name="sonic-text-output"></a>

```
"event": {
    "textOutput": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "content": "string" // User transcribe or Text Response
    }
}
```

#### ContentEnd
<a name="sonic-text-output-content-end"></a>

```
"event": {
    "contentEnd": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "stopReason": "PARTIAL_TURN" | "END_TURN" | "INTERRUPTED",
        "type": "TEXT"
    }
}
```

### 4. ToolUse
<a name="sonic-tool-use-output"></a>

#### ContentStart
<a name="sonic-tool-use-content-start"></a>

```
"event": {
    "contentStart": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // unique identifier for the content block
        "type": "TOOL",
        "role": "TOOL",
        "toolUseOutputConfiguration": {
            "mediaType": "application/json"
        }
    }
}
```

#### ToolUse
<a name="sonic-tool-use-event"></a>

```
"event": {
    "toolUse": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "content": "json",
        "toolName": "string",
        "toolUseId": "string"
    }
}
```

#### ContentEnd
<a name="sonic-tool-use-content-end"></a>

```
"event": {
    "contentEnd": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "stopReason": "TOOL_USE",
        "type": "TOOL"
    }
}
```

### 5. AudioOutputContent
<a name="sonic-audio-output-content"></a>

#### ContentStart
<a name="sonic-audio-output-content-start"></a>

```
"event": {
    "contentStart": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // unique identifier for the content block
        "type": "AUDIO",
        "role": "ASSISTANT",
        "audioOutputConfiguration": {
            "mediaType": "audio/lpcm",
            "sampleRateHertz": 8000 | 16000 | 24000,
            "sampleSizeBits": 16,
            "encoding": "base64",
            "channelCount": 1
        }
    }
}
```

#### AudioOutput
<a name="sonic-audio-output-event"></a>

```
"event": {
    "audioOutput": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "content": "base64EncodedAudioData", // Audio
    }
}
```

#### ContentEnd
<a name="sonic-audio-output-content-end"></a>

```
"event": {
    "contentEnd": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "contentId": "string", // same unique identifier from its contentStart
        "stopReason": "PARTIAL_TURN" | "END_TURN",
        "type": "AUDIO"
    }
}
```

### 6. CompletionEndEvent
<a name="sonic-completion-end-event"></a>

```
"event": {
    "completionEnd": {
        "sessionId": "string", // unique identifier
        "promptName": "string", // same unique identifier from promptStart event
        "completionId": "string", // unique identifier
        "stopReason": "END_TURN" 
    }
}
```