Ragionamento negli agenti e nelle conversazioni
In questa pagina
Lezione riscritta il 2 novembre 2026 per Mistral Small 4 e Large 4. La documentazione di Mistral indica che
reasoning_effortè disponibile sugli endpoint Agents e Conversations all’interno del campocompletion_args. Fonti: Reasoning · Python SDK — Conversations.
Tre modi per chiamare un modello di ragionamento
Nelle lezioni precedenti hai utilizzato l’API Chat Completions: inviavi l’intera cronologia a ogni chiamata e reasoning_effort veniva inserito direttamente nella richiesta. Mistral offre altre due interfacce: le Agents API, che salvano una configurazione riutilizzabile (modello, istruzioni, strumenti, parametri), e le Conversations API, che mantengono la cronologia sul server. In queste due API, non imposti il ragionamento al livello superiore; lo annidi invece dentro completion_args, insieme agli altri parametri di generazione.
Un agente che ragiona
Impostare il livello di ragionamento nella definizione dell’agente evita di ripeterlo a ogni chiamata e garantisce che tutto il tuo team utilizzi la stessa configurazione:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
agent = client.beta.agents.create(
model="mistral-small-2603",
name="Financial Analyst",
instructions=(
"You analyze financial situations for SMEs. "
"End every response with a quantified recommendation and its assumptions."
),
completion_args={"reasoning_effort": "high"},
)
reponse = client.beta.conversations.start(
agent_id=agent.id,
inputs="Our working capital requirement has doubled in a year while revenue grew by 15%. What should we look at first?",
)
Leggere gli output delle conversazioni
Una conversazione non restituisce choices; restituisce una lista di voci (outputs). La risposta del modello si trova nelle voci di tipo message.output. Come per le Chat Completions, il contenuto è una stringa o una lista di chunk che può includere un ThinkChunk. La funzione separer della Lezione 3 funziona esattamente come prima:
for entry in reponse.outputs:
if entry.type == "message.output":
reflexion, texte = separer(entry.content)
print(texte)
Altre voci descrivono ciò che è accaduto durante il turno, come l’esecuzione di uno strumento (tool.execution) o una chiamata di funzione. Ignorale se ti interessa solo la risposta finale.
Una conversazione senza agente
Per compiti una tantum, le Conversations API accettano direttamente un modello, senza bisogno di configurare preventivamente un agente. Il server mantiene la cronologia e puoi proseguire lo scambio con conversations.append, aggiustando il livello di ragionamento per un turno specifico se necessario:
conv = client.beta.conversations.start(
model="mistral-large-4-0",
inputs="Propose a migration plan for a 2 TB PostgreSQL database with zero downtime.",
completion_args={"reasoning_effort": "high"},
)
suite = client.beta.conversations.append(
conversation_id=conv.conversation_id,
inputs="Summarize this plan in five steps for executive leadership.",
completion_args={"reasoning_effort": "low"}, # a summary doesn't need deep reflection
)
Questo è un vantaggio concreto rispetto alle Chat Completions, dove la documentazione richiede di reinviare l’intero messaggio dell’assistente, riflessione inclusa, a ogni nuovo turno (Lezione 7). Con le Conversations API, il server conserva la cronologia: non devi reinviarla a ogni chiamata.
Ragionamento e strumenti
Un agente può combinare ragionamento e strumenti: tools e completion_args sono campi indipendenti durante la creazione di un agente. Un agente di analisi può quindi disporre di ricerca web e ragionamento profondo:
agent_veille = client.beta.agents.create(
model="mistral-small-2603",
name="Competitive Intelligence",
instructions="You compare competitor offers using cited public sources.",
tools=[{"type": "web_search"}],
completion_args={"reasoning_effort": "high"},
)
Tieni d’occhio i costi, però: riflessione e chiamate di strumenti si accumulano nel conteggio per un singolo turno.
Confronto tra i tre approcci
| Criterio | Chat Completions | Agents | Conversations |
|---|---|---|---|
| Dove impostare il ragionamento | reasoning_effort nella richiesta | completion_args nell’agente | completion_args in start o append |
| Cronologia | Reinvio a ogni chiamata, riflessione inclusa | Gestita dalla conversazione | Conservata sul server |
Strumenti integrati (web_search…) | No | Sì | Sì |
| Uso tipico | Chiamate una tantum, controllo totale | Configurazione condivisa e riutilizzabile | Scambi multi-turno |
Migliori pratiche di integrazione
Imposta il livello di ragionamento nell’agente quando il compito è uniforme, e per turno quando varia: un turno di analisi iniziale a high, seguito da turni di riformulazione a low o none, a seconda del modello. Verifica che il valore sia adatto al modello dell’agente: Small 4 accetta high e none; Large 4 accetta low, medium e high. Infine, registra l’uso dei token per turno; è l’unico modo per sapere se il ragionamento vale la pena per il tuo caso d’uso.
Punti chiave
- Nelle API Agents e Conversations, passa
reasoning_effortdentrocompletion_args - Le risposte arrivano in
outputs; il testo si trova nelle vocimessage.output, riflessione inclusa - Le Conversations API mantengono la cronologia sul server: niente bisogno di reinviarla a ogni turno
- Puoi cambiare il livello a ogni turno con
conversations.append - Un agente può combinare strumenti integrati e ragionamento, al costo di un utilizzo cumulativo