Conversas Persistentes
Nesta página
Lição atualizada em 3 de novembro de 2026 com base no SDK
mistralai3.7.0: recupere o histórico de uma conversa (as suasentries) utilizandoclient.beta.conversations.get_history;retrievenão existe egetdevolve apenas os metadados da conversa. Fonte: client-python.
Estado que Persiste Entre Trocas
Uma das principais vantagens da API de Agentes face às Conclusões de Chat (Chat Completions) é a persistência da conversa. Já não precisa de gerir manualmente o histórico de mensagens — a Mistral trata disso no lado do servidor. Especificamente, a lista de dicionários que costumava acumular numa variável, truncar quando o contexto transbordava e reconstruir em cada reinício do processo desaparece do seu código. Só precisa de acompanhar uma coisa: um identificador. E esse identificador segue uma regra que confunde toda a gente no primeiro projeto.
Iniciar uma Conversa
O método conversations.start() cria uma nova conversa e envia a primeira mensagem. O exemplo seguinte cria também o agente que a irá executar e fornece-lhe um contexto de projeto que pode consultar ao longo de várias intervenções.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Criar um agente
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="Assistente de Projeto",
description="Assistente de gestão de projetos.",
instructions="Ajuda a organizar e acompanhar projetos. Seja estruturado."
)
# Iniciar a conversa
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Vou lançar um novo projeto para redesenhar o nosso site. Orçamento: 50K €, prazo: setembro de 2026."
)
print(f"ID da Conversa: {response.conversation_id}")
O conversation_id devolvido é a sua chave para continuar esta conversa mais tarde. Guarde-o onde a sua aplicação o possa recuperar: numa sessão de utilizador, numa base de dados ou no ticket de suporte a que diz respeito.
Continuar uma Conversa
Para adicionar uma mensagem a uma conversa existente, passe o conversation_id para conversations.append(). Siga o fio condutor neste exemplo: a segunda pergunta não repete o orçamento nem o prazo, e a terceira pede um cronograma sem lembrar ao agente que se trata de um redesenho de site. No entanto, o agente tem todo esse contexto.
# Primeira troca
response1 = client.beta.conversations.start(
agent_id=agent.id,
inputs="Vou lançar um projeto de redesenho de site. Orçamento 50K €."
)
# Segunda troca — o agente lembra-se do contexto
response2 = client.beta.conversations.append(
conversation_id=response1.conversation_id,
inputs="Quais são os passos prioritários?"
)
# Terceira troca — ainda no mesmo contexto
response3 = client.beta.conversations.append(
conversation_id=response2.conversation_id,
inputs="Elabore um cronograma para os primeiros 3 meses."
)
Observe atentamente qual o identificador que alimenta cada chamada: response2 começa a partir do ID de response1, response3 a partir do de response2. Isto não é uma peculiaridade; é o mecanismo central da API.
O Mecanismo de Imutabilidade
Cada chamada a conversations.append() devolve um novo conversation_id. O antigo permanece legível, mas deve utilizar o ID mais recente para a próxima anexação.
# Cada append devolve um novo ID
id_1 = response1.conversation_id # "conv-aaa"
id_2 = response2.conversation_id # "conv-bbb"
id_3 = response3.conversation_id # "conv-ccc"
# Utilize SEMPRE o ID MAIS RECENTE para continuar
response4 = client.beta.conversations.append(
conversation_id=id_3, # Não id_1 nem id_2
inputs="Adicione marcos de validação do cliente."
)
O erro clássico consiste em guardar o identificador inicial na sua base de dados quando o utilizador abre o tópico e depois reutilizá-lo tal qual para cada mensagem. Nada falha: a API responde normalmente, mas cada pergunta reinicia a partir do contexto da primeira troca, e o seu agente parece ter amnésia sem qualquer erro que o alerte. Substitua sempre o identificador armazenado pelo que foi devolvido na resposta.
Ler o Histórico da Conversa
Pode ler o histórico a qualquer momento, o que ajuda tanto na depuração como na exibição de um tópico na sua interface.
conversation = client.beta.conversations.get_history(
conversation_id=response.conversation_id
)
for entry in conversation.entries:
print(f"[{entry.role}] {entry.type}: {entry.content[:100]}...")
Gerir o Armazenamento
Por predefinição, as conversas são armazenadas na nuvem da Mistral. O parâmetro store=False desativa este comportamento para trocas que a sua política interna proíba de deixar num servidor de terceiros.
# Conversa efémera — nada é guardado
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Dados confidenciais para analisar...",
store=False
)
A contrapartida corresponde ao objetivo: a conversa não é recuperável após a sessão e os dados não são mantidos nos servidores da Mistral. Perde a reprodução do histórico descrita acima e a sua aplicação deve tratar do acompanhamento das trocas por si própria, se necessário. Tome esta decisão de início, não como uma caixa de verificação de última hora.
Padrão de Conversa em Várias Intervenções
O esqueleto abaixo aplica tudo o que foi referido acima num ciclo interativo. O ponto chave é a variável conversation_id, inicializada como None: ela decide qual a chamada a fazer — start() na primeira intervenção, append() nas seguintes — e é reatribuída após cada resposta, seguindo a regra de imutabilidade.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Coach Técnico",
description="Coach para decisões técnicas.",
instructions="É um coach técnico sénior. Faça perguntas para compreender o contexto antes de aconselhar."
)
# Ciclo de conversa
conversation_id = None
while True:
user_input = input("Você: ")
if user_input.lower() in ["quit", "exit"]:
break
if conversation_id is None:
response = client.beta.conversations.start(
agent_id=agent.id,
inputs=user_input
)
else:
response = client.beta.conversations.append(
conversation_id=conversation_id,
inputs=user_input
)
conversation_id = response.conversation_id
for entry in response.outputs:
if hasattr(entry, "content"):
print(f"Agente: {entry.content}")
Adapte-o ao seu contexto substituindo input() pela sua fonte real de mensagens — pedido HTTP, mensagem de fila, evento de webhook — e persistindo o conversation_id onde a sua aplicação o possa encontrar na próxima intervenção.
Pontos-chave
conversations.start()cria uma nova conversa com uma primeira mensagemconversations.append()adiciona uma mensagem a uma conversa existente- Cada anexação devolve um novo
conversation_id— utilize sempre o mais recente store=Falsedesativa a persistência do lado da Mistral para dados sensíveis- O agente retém todo o contexto da conversa sem que precise de reenviar o histórico