Architettura dell'API Mistral Agents
In questa pagina
Aggiornato il 3 novembre 2026. Il precedente esempio completo di agente passava
guardrails={"enabled": True}, un formato inesistente: il parametro ufficiale è una lista di configurazionimoderation_llm_v2. L’inputtool.executionespone il nome dello strumento inentry.name, non inentry.tool_name, cosa che in precedenza generava unAttributeError. Fonti: Agents & Conversations · Moderation & Guardrailing · SDKmistralai3.7.0.
I tre oggetti fondamentali
L’API Mistral Agents si basa su tre oggetti interconnessi: Agent, Conversation ed Entry. La maggior parte degli errori di progettazione riscontrati all’inizio di un progetto—ricreare un agente per ogni richiesta, riutilizzare un conversation_id scaduto o un’analisi della risposta che va in crash su un entry inaspettato—deriva dalla confusione tra questi tre livelli. Comprendere i loro ruoli e le loro relazioni è un prerequisito per scrivere anche una sola riga di codice.
L’oggetto Agent
Un Agent è un insieme di configurazioni che definisce il comportamento del modello. Non contiene dati di conversazione: è un modello riutilizzabile che crei una volta e a cui migliaia di conversazioni possono fare riferimento.
La creazione richiede come minimo un modello, un nome e una descrizione.
agent = client.beta.agents.create(
model="mistral-large-latest", # Modello LLM da utilizzare
name="My Agent", # Identificatore leggibile dall'uomo
description="Agent for financial analysis" # Descrizione orientata al compito
)
Il parametro model designa il modello che alimenterà l’agente, scelto tra i modelli di completamento chat disponibili come mistral-medium-latest o mistral-large-latest. Il name è un identificatore leggibile dall’uomo che usi per trovare e riferirti all’agente: in un progetto con venti agenti, è ciò che ti salva dallo scavare nei log per capire quale sta rispondendo ai clienti. La description, invece, è orientata al compito e serve a più della semplice documentazione interna: aiuta il modello a comprendere il ruolo che ci si aspetta da lui, il che spiega la dicitura “agent for financial analysis” piuttosto che un vago “agent number 3”.
Il resto viene configurato opzionalmente ed è qui che prende forma la vera personalità dell’agente.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Complete Agent",
description="Agent with all parameters",
instructions="You are a finance expert. Always respond with sources.",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"}
],
completion_args={"temperature": 0.3, "top_p": 0.95},
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"jailbreaking": 0.2, "financial": 1},
"action": "block",
},
}
],
)
instructions— Il prompt di sistema dell’agente (definisce la sua personalità, le regole e lo stile)tools— Lista degli strumenti disponibili:web_search,web_search_premium,code_interpreter,image_generation,document_libraryo funzioni personalizzatecompletion_args— Parametri del campionatore (temperature, top_p, max_tokens, ecc.)guardrails— Una lista di configurazioni di moderazione (moderation_llm_v2) applicate al messaggio in entrata di ciascuna conversazione dell’agente; qui, il jailbreaking viene bloccato sopra 0.2 e la categoriafinancialè disabilitata (soglia1), poiché l’agente è costruito per discutere di finanza. I dettagli sono nel corso AI Moderation and Security with Mistral.
Nell’esempio sopra, l’agente finanziario eredita un requisito di sourcing dalle sue istruzioni, la capacità di verificare una cifra dai suoi strumenti e una temperatura bassa che limita la creatività laddove è richiesto rigore.
L’oggetto Conversation
Una Conversation è la cronologia delle interazioni tra un utente e un agente—or tra un utente e un modello da solo. Contiene messaggi, risultati dell’esecuzione degli strumenti ed eventi di handoff.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Recupera l'ID conversazione per continuare in seguito
conversation_id = response.conversation_id
Il comportamento di questo oggetto nasconde alcune sorprese. La conversazione è persistente: la cronologia è archiviata lato Mistral, a meno che non passi store=False. È indipendente dall’agente, il che significa che una conversazione può perfettamente esistere senza un agente, in modalità modello diretto. Infine, è immutabile: ogni aggiunta restituisce un nuovo conversation_id, lasciando quello vecchio accessibile. Quest’ultimo punto è il più sorprendente: se archivi l’ID iniziale nel tuo database e lo riutilizzi al terzo turno, tornerai al contesto del primo scambio.
L’oggetto Entry
Un Entry è un’azione individuale all’interno di una conversazione: l’unità atomica della cronologia. Quando ricevi una risposta, il campo outputs contiene una lista di entry il cui tipo dipende da ciò che l’agente ha fatto. Un entry message.output trasporta una risposta testuale dell’agente, ovvero il testo che la tua interfaccia mostrerà. Un entry tool.execution trasporta il risultato dell’esecuzione di uno strumento, come codice o una ricerca web: lo script lanciato e il suo output, o le pagine restituite dal motore. Un entry agent.handoff segnala un evento di trasferimento verso un altro agente e appare quindi solo in scenari multi-agente.
Una singola risposta mescola comunemente questi tipi. Chiedi a un agente dotato di strumenti un calcolo e riceverai l’esecuzione, poi il commento che l’accompagna: il tuo codice deve quindi iterare su questa lista piuttosto che leggere un singolo campo.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Calculate the square root of 144"
)
for entry in response.outputs:
print(f"Type: {entry.type}")
if entry.type == "message.output":
print(f"Message: {entry.content}")
elif entry.type == "tool.execution":
print(f"Tool: {entry.name}")
Relazioni tra gli oggetti
Il seguente diagramma riassume l’articolazione dei tre livelli: una configurazione riutilizzabile, un filo cronologico e azioni unitarie.
Agent (configuration)
├── model, instructions, tools, guardrails
└── Can be referenced by N conversations
Conversation (history)
├── Linked to 0 or 1 Agent (optional)
├── Contains N ordered entries
└── Each append creates a new conversation_id
Entry (unit action)
├── message.output (text response)
├── tool.execution (tool result)
└── agent.handoff (agent transfer)
Opzioni della Conversation
L’avvio di una conversazione accetta impostazioni che impattano tanto sulla tua conformità quanto sulla tua architettura, ed è meglio deciderle tu piuttosto che subirle. Innanzitutto l’archiviazione: store=False impedisce qualsiasi salvataggio lato Mistral, cosa che userai per elaborare dati che la tua politica interna vieta di lasciare su un server di terze parti.
# Disabilita l'archiviazione cloud
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
La seconda impostazione definisce chi esegue gli handoff. In modalità server, il valore predefinito, Mistral concatena i trasferimenti di agente senza il tuo intervento; in modalità client, ricevi gli eventi di handoff e mantieni il controllo per registrarli, filtrarli o rifiutarli.
# Modalità server (predefinita) — Mistral gestisce automaticamente gli handoff
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Modalità client — Ricevi gli eventi di handoff e decidi cosa fare
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Punti chiave
- Agent = configurazione riutilizzabile (modello, istruzioni, strumenti, guardrails)
- Conversation = cronologia persistente archiviata sul server, indipendente dall’agente
- Entry = azione unitaria (messaggio, esecuzione strumento, handoff)
- Le conversazioni possono esistere senza un agente (modalità modello diretto)
- Ogni aggiunta a una conversazione crea un nuovo
conversation_id - La modalità
store=Falseimpedisce l’archiviazione lato Mistral