Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Ragionamento negli agenti e nelle conversazioni

Lezione 4 di 12 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Tre modi per chiamare un modello di ragionamento
  2. Un agente che ragiona
  3. Leggere gli output delle conversazioni
  4. Una conversazione senza agente
  5. Ragionamento e strumenti
  6. Confronto tra i tre approcci
  7. Migliori pratiche di integrazione
  8. Punti chiave

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 campo completion_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

CriterioChat CompletionsAgentsConversations
Dove impostare il ragionamentoreasoning_effort nella richiestacompletion_args nell’agentecompletion_args in start o append
CronologiaReinvio a ogni chiamata, riflessione inclusaGestita dalla conversazioneConservata sul server
Strumenti integrati (web_search…)NoSìSì
Uso tipicoChiamate una tantum, controllo totaleConfigurazione condivisa e riutilizzabileScambi 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_effort dentro completion_args
  • Le risposte arrivano in outputs; il testo si trova nelle voci message.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