Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Conversazioni persistenti

Lezione 5 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Uno stato che persiste tra gli scambi
  2. Avviare una conversazione
  3. Continuare una conversazione
  4. Il meccanismo di immutabilità
  5. Leggere la cronologia della conversazione
  6. Gestire l’archiviazione
  7. Schema di conversazione multi-turno
  8. Punti chiave

Lezione aggiornata il 3 novembre 2026 in base all’SDK mistralai 3.7.0: recupera la cronologia di una conversazione (i suoi entries) usando client.beta.conversations.get_history; retrieve non esiste e get restituisce solo i metadati della conversazione. Fonte: client-python.

Uno stato che persiste tra gli scambi

Uno dei principali vantaggi dell’API Agents rispetto alle Chat Completions è la persistenza delle conversazioni. Non devi più gestire manualmente la cronologia dei messaggi: se ne occupa Mistral lato server. Nello specifico, la lista di dizionari che accumulavi in una variabile, troncavi quando il contesto superava il limite e ricostruivi a ogni riavvio del processo scompare dal tuo codice. Devi solo tenere traccia di una cosa: un identificatore. E questo identificatore segue una regola che manda in confusione tutti al primo progetto.

Avviare una conversazione

Il metodo conversations.start() crea una nuova conversazione e invia il primo messaggio. L’esempio seguente crea anche l’agente che la gestirà, fornendogli un contesto di progetto su cui potrai interrogarti in più turni.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Crea un agente
agent = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Assistente di Progetto",
    description="Assistente per la gestione dei progetti.",
    instructions="Aiuti a organizzare e tracciare i progetti. Sii strutturato."
)

# Avvia la conversazione
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Sto lanciando un nuovo progetto per ridisegnare il nostro sito web. Budget: 50.000 €, scadenza: settembre 2026."
)

print(f"ID conversazione: {response.conversation_id}")

L’conversation_id restituito è la tua chiave per continuare questa conversazione in seguito. Salvalo dove la tua applicazione può recuperarlo: in una sessione utente, in un database o nel ticket di supporto a cui si riferisce.

Continuare una conversazione

Per aggiungere un messaggio a una conversazione esistente, passa il conversation_id a conversations.append(). Segui il filo di questo esempio: la seconda domanda non ripete il budget né la scadenza, e la terza chiede una pianificazione senza ricordare all’agente che si tratta di un ridisegno del sito web. Eppure l’agente ha tutto quel contesto.

# Primo scambio
response1 = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Sto lanciando un progetto di ridisegno del sito web. Budget 50.000 €."
)

# Secondo scambio — l'agente ricorda il contesto
response2 = client.beta.conversations.append(
    conversation_id=response1.conversation_id,
    inputs="Quali sono i passaggi prioritari?"
)

# Terzo scambio — sempre nello stesso contesto
response3 = client.beta.conversations.append(
    conversation_id=response2.conversation_id,
    inputs="Redigi una pianificazione per i primi 3 mesi."
)

Osserva attentamente quale identificatore alimenta ogni chiamata: response2 parte dall’ID di response1, response3 da quello di response2. Non è un capriccio dell’API, è il meccanismo centrale.

Il meccanismo di immutabilità

Ogni chiamata a conversations.append() restituisce un nuovo conversation_id. Quello vecchio rimane leggibile, ma devi usare l’ID più recente per il prossimo append.

# Ogni append restituisce un nuovo ID
id_1 = response1.conversation_id  # "conv-aaa"
id_2 = response2.conversation_id  # "conv-bbb"
id_3 = response3.conversation_id  # "conv-ccc"

# Usa sempre l'ID più RECENTE per continuare
response4 = client.beta.conversations.append(
    conversation_id=id_3,  # Non id_1 o id_2
    inputs="Aggiungi le tappe di validazione del cliente."
)

L’errore classico consiste nel salvare l’identificatore iniziale nel database quando l’utente apre il thread, per poi riutilizzarlo così com’è per ogni messaggio. Nulla va in crash: l’API risponde normalmente, ma ogni domanda riparte dal contesto del primo scambio e il tuo agente sembra avere l’amnesia, senza alcun errore che ti avvisi. Sovrascrivi sempre l’identificatore memorizzato con quello restituito nella risposta.

Leggere la cronologia della conversazione

Puoi leggere la cronologia in qualsiasi momento, il che aiuta sia per il debug sia per visualizzare un thread nella tua interfaccia.

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]}...")

Gestire l’archiviazione

Per impostazione predefinita, le conversazioni sono archiviate nel cloud di Mistral. Il parametro store=False disabilita questo comportamento per gli scambi che la tua politica interna vieta di lasciare su un server di terze parti.

# Conversazione effimera — nulla viene salvato
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Dati confidenziali da analizzare...",
    store=False
)

Il compromesso corrisponde all’obiettivo: la conversazione non è recuperabile dopo la sessione e i dati non vengono conservati sui server di Mistral. Perdi la riproduzione della cronologia descritta sopra e la tua applicazione deve gestire il tracciamento degli scambi da sola, se necessario. Prendi questa decisione a monte, non come una spunta dell’ultimo minuto.

Schema di conversazione multi-turno

Lo scheletro seguente applica tutto quanto sopra in un ciclo interattivo. Il punto chiave è la variabile conversation_id, inizializzata a None: decide quale chiamata effettuare—start() al primo turno, append() in seguito—e viene riassegnata dopo ogni risposta, seguendo la regola di immutabilità.

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 Tecnico",
    description="Coach per le decisioni tecniche.",
    instructions="Sei un coach tecnico senior. Fai domande per comprendere il contesto prima di dare consigli."
)

# Ciclo di conversazione
conversation_id = None

while True:
    user_input = input("Tu: ")
    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}")

Adattalo al tuo contesto sostituendo input() con la tua fonte reale di messaggi—richiesta HTTP, messaggio in coda, evento webhook—e persistendo conversation_id dove la tua applicazione può trovarlo al turno successivo.

Punti chiave

  • conversations.start() crea una nuova conversazione con un primo messaggio
  • conversations.append() aggiunge un messaggio a una conversazione esistente
  • Ogni append restituisce un nuovo conversation_id: usa sempre l’ultimo
  • store=False disabilita la persistenza lato Mistral per i dati sensibili
  • L’agente mantiene l’intero contesto della conversazione senza che tu debba reinviare la cronologia