Normalmente, sua aplicação envia em cada requisição todo o histórico do chat até ali. Com o Brain do FlowModels, isso não é necessário. Você informa apenas para qual usuário final é a requisição e qual conversa está continuando. O histórico, as memórias e os documentos dessa pessoa ficam por nossa conta.
Sem e com o Brain
- Sem
external_identifier, o histórico é seu. Você envia todas as mensagens necessárias, e nós não salvamos nenhum histórico de conversa. - Com
external_identifier, você ativa o Brain. Salvamos a conversa, recorremos às memórias e aos trechos de arquivos relevantes dessa pessoa e ajustamos o contexto à janela de entrada do modelo.
As duas formas funcionam em /chat/completions e /responses, inclusive com streaming.
A primeira mensagem
{
"model": "groq/openai/gpt-oss-120b",
"external_identifier": "cliente-1042",
"messages": [{"role": "user", "content": "Estou planejando relançar nosso site. Por onde eu começo?"}]
}
external_identifier é o seu próprio identificador estável da pessoa, com 1 a 255 caracteres. Um número de cliente também deve ser enviado como texto, ou seja, "1042" em vez de 1042. Se ainda não conhecermos o identificador, criamos o usuário final automaticamente na primeira chamada.
A resposta contém também o campo conversation com um UUID. Salve esse valor junto com o chat na sua aplicação.
Continuar a conversa
Na próxima mensagem, envie o mesmo identificador, o conversation e somente a nova mensagem:
{
"model": "groq/openai/gpt-oss-120b",
"external_identifier": "cliente-1042",
"conversation": "018f1234-5678-7abc-9def-0123456789ab",
"messages": [{"role": "user", "content": "Me dê três próximos passos concretos para isso."}]
}
Se você enviar o histórico antigo mesmo assim, ele aparece em dobro no contexto. Isso custa mais tokens e confunde o modelo. Se você omitir conversation, começa uma nova conversa com o mesmo usuário final. As memórias e os arquivos dele também ficam disponíveis nela.
Não confunda os três identificadores
| Identificador | De onde vem | Para que serve |
|---|---|---|
external_identifier |
do seu sistema | associa requisições a uma pessoa |
id do usuário final |
de POST /end-users |
gerenciamento, arquivos, exclusão |
conversation |
da resposta | continua uma conversa específica |
Se quiser criar um usuário final antecipadamente, por exemplo para já associar documentos a ele, use POST /v1/end-users com external_identifier e, opcionalmente, metadata. Se o usuário final já existir, você simplesmente recebe o registro existente.
O que acontece em conversas longas
Quando uma conversa ultrapassa a janela de entrada do modelo, resumimos os trechos mais antigos e salvamos o resumo. As mensagens mais recentes são mantidas na íntegra. Cada trecho é resumido e pago apenas uma vez. Esses resumos também fazem parte do seu consumo. Mais detalhes em Histórico longo demais: context_length_exceeded e compactação do histórico.
Usuários finais na interface
Em Usuários finais, você vê todos os usuários finais com o identificador, as chamadas e os custos no mês em curso, além do número de arquivos e memórias. Como usar a lista está em Gerenciar os usuários finais da sua aplicação.

Memórias automáticas
O Brain guarda automaticamente, como memórias, informações importantes das conversas, por exemplo “prefere respostas curtas”. Para novos usuários finais, isso vem ativado. Você pode desativar por usuário final com PATCH /end-users/{id} e "memory_extraction_enabled": false. Como criar e editar memórias por conta própria está em Criar, buscar e alterar memórias de um usuário final pela API.
Quando algo não funciona
404 conversation_not_found: oconversationnão existe ou pertence a outro usuário final. Verifique se você está enviando a combinação certa deexternal_identifiereconversation.409 conversation_in_progress: já há uma requisição em andamento para a mesma conversa. Espere a resposta dela antes de enviar a próxima.- O Brain não se lembra: verifique se você está mesmo enviando
external_identifierno corpo JSON. Na biblioteca para Python, ele vai emextra_body. O campousernão basta: ele serve apenas para rastrear abuso e não ativa o Brain.
Bom saber
Use como identificador um ID neutro do seu sistema, e não um endereço de e-mail ou um nome. Assim, os dados pessoais ficam com você.