Estado da conversa e gestão de sessões
Nesta página
Estado da conversa e gestão de sessões
A API Responses suporta nativamente o estado da conversa, o que simplifica drasticamente a manutenção do contexto entre intervenções. Já não precisa de reconstruir o histórico em cada pedido: o servidor trata disso por si e você apenas passa um identificador.
Encadeamento com previous_response_id
O mecanismo resume-se a um único campo. Cada resposta possui um id; passe-o no parâmetro previous_response_id na chamada seguinte e o modelo terá acesso a tudo o que foi dito anteriormente. Na troca abaixo, a terceira pergunta — «Como é que os adiciono?» — não faria sentido isoladamente: o encadeamento permite ao modelo saber que estamos a falar de frações e que o utilizador é iniciante.
from openai import OpenAI
client = OpenAI()
# Primeira troca
r1 = client.responses.create(
model="gpt-5.6-terra",
instructions="You are a patient math teacher.",
input="I'd like to learn about fractions."
)
print(f"R1: {r1.output_text}")
# Segunda troca — o contexto é preservado automaticamente
r2 = client.responses.create(
model="gpt-5.6-terra",
input="Can you give me a concrete example?",
previous_response_id=r1.id
)
print(f"R2: {r2.output_text}")
# Terceira troca — toda a conversa está acessível
r3 = client.responses.create(
model="gpt-5.6-terra",
input="And how do I add them?",
previous_response_id=r2.id
)
print(f"R3: {r3.output_text}")
# O modelo sabe que temos falado sobre frações desde o início
Considere a diferença face à abordagem anterior. Com o Chat Completions, a conversa vivia numa lista que você mantinha e reenviava na íntegra a cada intervenção, com custos a crescer à medida que a troca se prolongava.
# ANTIGO — tinha de gerir tudo manualmente
history = [
{"role": "system", "content": "You are a math teacher."},
{"role": "user", "content": "I'd like to learn about fractions."},
{"role": "assistant", "content": "Sure! Fractions..."},
{"role": "user", "content": "A concrete example?"},
{"role": "assistant", "content": "Let's take a pizza..."},
{"role": "user", "content": "How do I add them?"},
]
# Enviado na íntegra em cada chamada = custos crescentes
A mesma troca reduz-se agora a uma única referência:
# NOVO — um único ID é suficiente
r = client.responses.create(
model="gpt-5.6-terra",
input="How do I add them?",
previous_response_id="previous_response_id"
)
# O servidor gere o histórico por si
Executar múltiplas conversas
Assim que a sua aplicação serve vários utilizadores, surge a questão: a qual utilizador pertence cada identificador? A resposta é uma tabela de mapeamento entre o utilizador e o último response.id da sua conversa. O gestor abaixo encapsula esta lógica: adiciona previous_response_id apenas se já existir uma sessão, guardando depois o novo identificador. A Alice e o Bob podem assim conversar em paralelo sem que os seus contextos se misturem, e «nova sessão» significa simplesmente esquecer o identificador atual.
class SessionManager:
"""Gestor de sessões de conversa."""
def __init__(self):
self.sessions: dict[str, str] = {} # user_id -> last_response_id
def send_message(self, user_id: str, message: str,
instructions: str = "") -> str:
"""Envia uma mensagem na sessão do utilizador."""
kwargs = {
"model": "gpt-5.6-terra",
"input": message,
}
# Adiciona instruções se fornecidas
if instructions:
kwargs["instructions"] = instructions
# Encadeia com a resposta anterior se existir
if user_id in self.sessions:
kwargs["previous_response_id"] = self.sessions[user_id]
response = client.responses.create(**kwargs)
# Guarda o ID para a próxima intervenção
self.sessions[user_id] = response.id
return response.output_text
def new_session(self, user_id: str):
"""Inicia uma nova conversa para o utilizador."""
if user_id in self.sessions:
del self.sessions[user_id]
# Utilização
manager = SessionManager()
# Utilizadora Alice
print(manager.send_message("alice", "Hello, tell me about Python."))
print(manager.send_message("alice", "What are its advantages?"))
# Utilizador Bob (conversa independente)
print(manager.send_message("bob", "Hello, tell me about Rust."))
# Alice continua a sua conversa sobre Python
print(manager.send_message("alice", "How do I get started?"))
Quando assumir o controlo do histórico
O encadeamento automático tem um limite: não pode modificar o que já foi dito. Se a sua aplicação precisar de resumir intervenções passadas, apagar uma mensagem com dados pessoais ou reinjetar um contexto reformulado, mude para entrada estruturada e gere a lista manualmente. Perde simplicidade, mas ganha controlo total — e a capacidade de monitorizar a inflação de tokens intervenção após intervenção.
def manual_conversation():
"""Conversa com gestão manual do histórico."""
history = []
while True:
user_input = input("You: ")
if user_input.lower() == "quit":
break
history.append({"role": "user", "content": user_input})
response = client.responses.create(
model="gpt-5.6-terra",
instructions="You are a concise assistant.",
input=history
)
assistant_msg = response.output_text
history.append({"role": "assistant", "content": assistant_msg})
print(f"Assistant: {assistant_msg}")
print(f" (Cumulative tokens: {response.usage.input_tokens})")
# manual_conversation()
Sobreviver a um reinício
Um dicionário em memória desaparece no primeiro redeploy, levando consigo todas as conversas ativas. Em produção, persista os identificadores — o ficheiro JSON abaixo ilustra o princípio, que pode adaptar à sua base de dados ou ao Redis. Note que registamos também o carimbo temporal e o uso de tokens, duas informações usadas respetivamente para expiração e rastreio de custos.
import json
from datetime import datetime
class PersistentSessionManager:
"""Sessões persistentes com cópia de segurança."""
def __init__(self, db_path: str = "sessions.json"):
self.db_path = db_path
self.sessions = self._load()
def _load(self) -> dict:
try:
with open(self.db_path, "r") as f:
return json.load(f)
except FileNotFoundError:
return {}
def _save(self):
with open(self.db_path, "w") as f:
json.dump(self.sessions, f, indent=2)
def send(self, session_id: str, message: str) -> str:
kwargs = {"model": "gpt-5.6-terra", "input": message}
if session_id in self.sessions:
kwargs["previous_response_id"] = self.sessions[session_id]["last_id"]
response = client.responses.create(**kwargs)
self.sessions[session_id] = {
"last_id": response.id,
"updated_at": datetime.now().isoformat(),
"total_tokens": response.usage.total_tokens
}
self._save()
return response.output_text
Por fim, implemente a expiração. Sem limpeza, a sua tabela de sessões só cresce e um utilizador que regresse três semanas depois retomaria uma conversa de que já não se lembra. Vinte e quatro horas é um ponto de partida razoável, ajustável consoante o seu caso de uso.
from datetime import datetime, timedelta
def clean_sessions(sessions: dict, max_age_hours: int = 24) -> dict:
"""Remove sessões expiradas."""
now = datetime.now()
active = {}
for sid, data in sessions.items():
updated = datetime.fromisoformat(data["updated_at"])
if now - updated < timedelta(hours=max_age_hours):
active[sid] = data
deleted = len(sessions) - len(active)
if deleted > 0:
print(f"{deleted} expired session(s) removed")
return active
Para resumir estas escolhas: use previous_response_id para conversas simples — é o mais eficiente; mude para entrada estruturada quando precisar de modificar o histórico; armazene response.id de forma fiável, numa base de dados e não em memória; limpe sessões inativas; e monitore os tokens cumulativos, ou a faturação acabar por o apanhar.
Pontos-chave
previous_response_idencadeia respostas automaticamente sem reenviar o histórico- Cada resposta tem um
idúnico utilizável para encadeamento - Gere múltiplas sessões com um dicionário
user_id -> response_id - A entrada estruturada (lista de mensagens) oferece mais controlo sobre o histórico
- Implemente persistência e expiração de sessões em produção