# Gerenciamento do histórico do chat
<a name="sonic-chat-history"></a>

As respostas do Amazon Nova 2 Sonic incluem transcrições de ASR (reconhecimento automático de voz) para vozes de usuários e assistentes. Armazenar o histórico do chat é uma prática recomendada, não apenas para fins de registro em log, mas também para retomar as sessões quando a conexão é fechada inesperadamente. Isso possibilita o reenvio de contexto pelo cliente ao Nova Sonic, permitindo a continuidade do diálogo de forma fluida.

Consulte os seguintes recursos para obter mais informações sobre o gerenciamento de histórico do chat:

1. [Registro em log do histórico do chat](https://github.com/aws-samples/amazon-nova-samples/tree/main/speech-to-speech/amazon-nova-2-sonic/repeatable-patterns/chat-history-logger)

1. [Retomada das conversas](https://github.com/aws-samples/amazon-nova-samples/tree/main/speech-to-speech/repeatable-patterns/resume-conversation)

## Envio do histórico do chat
<a name="sonic-chat-history-sending"></a>

Um histórico de conversa pode ser incluído apenas uma vez, após o prompt de sistema/fala e antes do início do streaming de áudio. O histórico geral do chat não pode ser maior que 40 KB. O seguinte diagrama mostra quando o histórico do chat é transmitido durante o ciclo de vida do evento:

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/nova/latest/nova2-userguide/images/Sending-Chat-History_4.png)


Cada mensagem do histórico requer três eventos: `contentStart`, `textInput` e `contentEnd`.

**Esquema do evento por mensagem:**
+ `contentStart`: define o perfil e a configuração da mensagem

  ```
  {
    "event": {
      "contentStart": {
        "promptName": "<prompt-id>",
        "contentName": "<content-id>",
        "type": "TEXT",
        "interactive": true,
        "role": "ASSISTANT",
        "textInputConfiguration": {
          "mediaType": "text/plain"
        }
      }
    }
  }
  ```
+ `textInput`: contém o conteúdo real da mensagem. Um textInput não pode ser maior que 1 KB. Em caso afirmativo, divida em vários textInputs no mesmo bloco de conteúdo. Se a conversa exceder 40 K, reduza o histórico total do chat.

  ```
  {
    "event": {
      "textInput": {
        "promptName": "<prompt-id>",
        "contentName": "<content-id>",
        "content": "Take your time, Don. I'll be here when you're ready."
      }
    }
  }
  ```
+ `contentEnd`: marca o fim da mensagem

  ```
  {
    "event": {
      "contentEnd": {
        "promptName": "<prompt-id>",
        "contentName": "<content-id>"
      }
    }
  }
  ```

Repita esses três eventos para cada mensagem em seu histórico do chat, alternando entre os perfis de USER e ASSISTANT.

**Considerações importantes:**
+ O histórico do chat só pode ser incluído **uma vez** por sessão
+ O histórico do chat deve ser enviado **após o prompt do sistema** e **antes do início do streaming de áudio**
+ Todas as mensagens do histórico devem ser enviadas antes do início do streaming de áudio
+ Cada mensagem deve especificar o perfil de USER ou ASSISTANT
+ Use o conteúdo da transcrição armazenado dos eventos textOutput como o valor do conteúdo em textInput

## Recebimento de transcrições de ASR
<a name="sonic-chat-history-receiving"></a>

Durante uma conversa, o Amazon Nova 2 Sonic envia transcrições de ASR por meio de eventos de saída. Cada transcrição é entregue como uma sequência de três eventos: contentStart, textOutput e contentEnd.

**Exemplo: transcrição da fala do usuário:**

1. contentStart - indica o início de uma transcrição:

```
{
  "event": {
    "contentStart": {
      "additionalModelFields": "{\"generationStage\":\"FINAL\"}",
      "completionId": "<completion-id>",
      "contentId": "<content-id>",
      "promptName": "<prompt-id>",
      "role": "USER",
      "sessionId": "<session-id>",
      "textOutputConfiguration": {
        "mediaType": "text/plain"
      },
      "type": "TEXT"
    }
  }
}
```

2. textOutput – contém o conteúdo real da transcrição:

```
{
  "event": {
    "textOutput": {
      "completionId": "<completion-id>",
      "content": "hello how are you",
      "contentId": "<content-id>",
      "promptName": "<prompt-id>",
      "role": "USER",
      "sessionId": "<session-id>"
    }
  }
}
```

3. contentEnd - marca o fim da transcrição:

```
{
  "event": {
    "contentEnd": {
      "completionId": "<completion-id>",
      "contentId": "<content-id>",
      "promptName": "<prompt-id>",
      "sessionId": "<session-id>",
      "stopReason": "PARTIAL_TURN",
      "type": "TEXT"
    }
  }
}
```

 O mesmo padrão de três eventos se aplica aos perfis de USER e ASSISTANT. Extraia o campo `content` do evento `textOutput` e o campo `role` do evento `contentStart` para criar seu histórico de chat.

## Práticas recomendadas
<a name="sonic-chat-history-best-practices"></a>

Sempre armazene o histórico do chat para habilitar:
+ Retomadas de sessões em diferentes dispositivos
+ Registro em log e auditoria de conversas
+ Preservação do contexto para interações de acompanhamento

Importante: ao salvar o histórico do chat, use saídas de texto com base no generationStage:
+ Speculative: uma prévia do que Nova 2 Sonic planeja dizer, gerada antes do início da síntese de áudio
+ Final: a transcrição real em nível de frase do que foi falado na resposta de áudio

Sempre salve a saída de texto FINAL em seu histórico de chat, pois ela representa o registro preciso da conversa.

Exemplo de saída FINAL (salve no histórico do chat):

```
ContentStart event: { 
  "additionalModelFields": "{\"generationStage\":\"FINAL\"}", 
  "completionId": "<completion-id>", 
  "contentId": "<content-id>", 
  "role": "ASSISTANT", 
  "sessionId": "<session-id>", 
  "type": "TEXT" 
}
```

Exemplo de saída SPECULATIVE (visualização opcional, não para histórico):

```
ContentStart event: { 
  "additionalModelFields": "{\"generationStage\":\"SPECULATIVE\"}", 
  "completionId": "<completion-id>", 
  "contentId": "<content-id>", 
  "role": "ASSISTANT", 
  "sessionId": "<session-id>", 
  "type": "TEXT" 
}
```