Sessões

Use memória de conversa no servidor por HTTP e WebSocket.

Sessões: com estado vs sem estado

Por padrão, a API é sem estado: cada requisição precisa carregar o histórico completo de mensagens, exatamente como na OpenAI. Você manda tudo, o Pepe responde, nada é lembrado.

O Pepe também oferece um modo com estado que a maioria dos servidores da OpenAI não tem. Anexe um id de sessão e o servidor guarda a conversa para você. Em cada chamada seguinte você envia apenas a mensagem mais nova do usuário; o Pepe a acrescenta ao histórico guardado, executa o agente e lembra do resultado. Isso é conveniente para interfaces de chat e bots de mensageria em que você não quer enviar a transcrição inteira toda vez.

CLI vs API

pepe run é sempre avulso: ele não aceita session_id e não lembra do comando anterior. Para manter contexto no terminal, use o console:

pepe chat assistant --session minha-sessao

A API HTTP monta a chave de sessão a partir de dois campos, e eles se combinam.

user identifica quem está falando. É o campo padrão da OpenAI, então qualquer SDK oficial ganha memória no servidor sem sair do formato padrão. É por ele que você deve começar.
session_id, no corpo JSON ou num cabeçalho x-session-id, identifica qual conversa daquela pessoa. Use quando a mesma pessoa pode ter várias conversas separadas.

Como eles se combinam:

Enviado	Chave de sessão
só `user`	`user`
só `session_id`	`session_id`
os dois	`user:session_id` (conversas independentes por pessoa)
os dois, mesmo valor	vira uma só
nenhum (ou vazio)	sem estado

Assim, no WhatsApp você passa user = o telefone e session_id = um id de conversa, e cada conversa de cada contato é independente, isolada das outras.

# Turno 1: só a mensagem nova é necessária; o servidor guarda o histórico.
curl http://localhost:4000/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{
    "model": "assistant",
    "user": "user-42",
    "messages": [{"role": "user", "content": "Meu nome é Ada."}]
  }'

# Turno 2: mesmo id de sessão, só a pergunta nova. O agente lembra de "Ada".
curl http://localhost:4000/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{
    "model": "assistant",
    "user": "user-42",
    "messages": [{"role": "user", "content": "Qual é meu nome?"}]
  }'

No modo com estado a resposta inclui o session_id que você usou, para que você possa devolvê-lo na próxima chamada. Sessões com estado também funcionam com streaming; basta adicionar "stream": true.

Recuperação depois de um reinício

Se o Pepe cair no meio de um turno (um deploy, um crash) com a persistência de sessões ativada, a conversa interrompida não é simplesmente perdida. Na próxima subida, o Pepe detecta qualquer sessão cujo último turno não terminou, reexecuta esse turno internamente e entrega a resposta para onde a conversa estava acontecendo (Telegram, o painel, qualquer que seja o canal). A mensagem interrompida ainda recebe resposta em vez de simplesmente sumir. Isso só vale para sessões persistidas (serve/gateway), não para chamadas avulsas de pepe run.

Isolamento entre projetos. As chaves de sessão são internamente delimitadas por projeto. O mesmo id de sessão usado sob dois tokens diferentes (dois projetos diferentes) nunca chega à mesma conversa, de modo que um projeto nunca consegue ler a sessão de outro.

Para voltar ao modo sem estado, simplesmente omita as três fontes de id e envie você mesmo o array completo de messages. Esse é o comportamento comum da OpenAI.

← API HTTP Autenticação →