FlowModels

Usar o Brain: salvar e continuar conversas por usuário final

Publicado em 11. novembro 2026

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.

A lista de usuários finais com chamadas e custos no mês em curso e o número de arquivos

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: o conversation não existe ou pertence a outro usuário final. Verifique se você está enviando a combinação certa de external_identifier e conversation.
  • 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_identifier no corpo JSON. Na biblioteca para Python, ele vai em extra_body. O campo user nã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ê.

Este artigo foi útil?

Voltar para Webhooks, usuários finais e MCP