Migliori pratiche e prossimi passi
In questa pagina
Cosa hai appreso
Hai esplorato l’intera API Mistral Agents. Facciamo un riepilogo prima di approfondire le pratiche di produzione, dato che ogni parte di questo corso si basa sulla precedente.
Le prime tre lezioni hanno gettato le fondamenta: un agente AI è un sistema autonomo con un ciclo percezione-azione; l’API si basa su tre oggetti—Agent, Conversation ed Entry; e ciò che distingue un agente da un chatbot è la persistenza, gli strumenti e i passaggi di consegne (handoffs). Le lezioni dalla 4 alla 7 hanno reso questi oggetti utilizzabili: creazione e configurazione di agenti con client.beta.agents.create(), mantenimento di conversazioni persistenti con conversations.start() e conversations.append(), e utilizzo della modalità diretta senza agente quando stai facendo prototipazione e la persistenza non aggiunge valore.
Le lezioni dalla 8 alla 11 hanno aggiunto capacità. web_search ti dà accesso a informazioni attuali con citazioni automatiche; code_interpreter esegue Python in una sandbox, fornendo all’agente risultati esatti laddove il modello da solo approssimerebbe; image_generation produce elementi visivi da prompt testuali; document_library porta una RAG integrata sui tuoi documenti. Le lezioni dalla 12 alla 16 hanno poi mostrato più agenti che lavorano insieme: i passaggi di consegne trasferiscono il controllo da un agente all’altro, l’architettura di riferimento abbina un router centrale a specialisti, la modalità server automatizza laddove la modalità client ti mantiene nel ciclo decisionale, e il chaining illimitato si scompone in pattern lineari, a stella e ibridi. Infine, la Lezione 17 ha racchiuso il tutto con guardrail, il principio del minimo privilegio e la moderazione a monte.
Progettare agenti solidi
Una frase riassume l’intero corso: un agente, una responsabilità, una descrizione che dice quando chiamarlo. Il contrasto seguente rende tangibile la differenza.
# BUONO — agente specializzato con descrizione precisa
agent = client.beta.agents.create(
model="mistral-large-latest",
name="invoice-processor",
description="Processes invoices: extracts amounts, dates, vendors.",
instructions="Extract invoice information into structured JSON.",
tools=[{"type": "document_library", "library_ids": [invoices_lib.id]}]
)
# CATTIVO — agente generico e vago
agent = client.beta.agents.create(
model="mistral-large-latest",
name="helper",
description="A helpful agent.",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}, {"type": "image_generation"}]
)
Il secondo agente fallirà in due modi contemporaneamente. Nessun router saprà quando inoltrargli una richiesta, perché “un agente utile” non descrive alcuna situazione specifica. E quando verrà chiamato, i suoi tre strumenti gli lasceranno la libertà di cercare sul web qualcosa che avrebbe dovuto calcolare, o di illustrare qualcosa che gli era stato chiesto di analizzare.
Gestione degli errori
Le chiamate di rete prima o poi falliscono. Un retry con backoff esponenziale assorbe gli incidenti transitori senza trasformare un rallentamento momentaneo in un’interruzione visibile.
import time
def safe_conversation(agent_id, query, max_retries=3):
"""Conversazione con gestione errori e retry."""
for attempt in range(max_retries):
try:
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query
)
return response
except Exception as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # Backoff esponenziale
return None
Il backoff esponenziale—un secondo, poi due, poi quattro—distingue un retry civile dal martellamento di un servizio che sta già faticando. Nota anche che il tentativo finale rilancia l’eccezione invece di restituire None: il tuo chiamante deve sapere che l’operazione è fallita.
Osservare cosa succede
In produzione, un flusso di lavoro multi-agente che non puoi osservare diventa impossibile da debuggare. La modalità client ti offre esattamente gli agganci di cui hai bisogno.
import logging
import time
logger = logging.getLogger("agents")
def monitored_conversation(agent_id, query):
"""Conversazione con monitoraggio."""
start = time.time()
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query,
handoff_execution="client"
)
handoff_count = 0
tool_count = 0
for entry in response.outputs:
if entry.type == "agent.handoff":
handoff_count += 1
logger.info(f"Handoff #{handoff_count}: → {entry.next_agent_id}")
elif entry.type == "tool.execution":
tool_count += 1
logger.info(f"Tool #{tool_count}: {entry.tool_name}")
duration = time.time() - start
logger.info(f"Finished in {duration:.1f}s — {handoff_count} handoffs, {tool_count} tools")
return response
Quei due contatori valgono più di quanto la loro semplicità suggerisca: una deriva nel numero medio di handoff segnala un router che esita; un picco nelle chiamate agli strumenti indica query costose.
Il controllo dei costi si riduce quindi a decisioni concrete. Monitora i token per conversazione, poiché quella è l’unità reale di fatturazione. Usa mistral-medium-latest ovunque mistral-large-latest non aggiunga nulla—il primo livello di supporto è un esempio da manuale. Limita max_tokens in completion_args per evitare risposte infinite a domande semplici e disabilita l’archiviazione con store=False quando la persistenza non è richiesta.
Testare il routing
Testa un sistema multi-agente come un qualsiasi centralino: forniscigli casi la cui destinazione prevista conosci e verifica dove approdano.
def test_agent_routing():
"""Verifica che il router distribuisca correttamente."""
test_cases = [
("What is the price of Bitcoin?", "web-search-agent"),
("Calculate 25 * 48", "calculator-agent"),
("Summarize this document", "doc-agent"),
]
for query, expected_agent_name in test_cases:
response = client.beta.conversations.start(
agent_id=router.id,
inputs=query,
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target = client.beta.agents.get(agent_id=entry.next_agent_id)
assert target.name == expected_agent_name, \
f"Incorrect routing for '{ query}': {target.name} instead of {expected_agent_name}"
Costruisci questa suite di test nel tempo: ogni richiesta instradata male che intercetti in produzione diventa un’altra riga in test_cases, e saprai che riscrivere una descrizione risolve il caso mirato senza romperne un altro.
Architettura di riferimento
Per un progetto di produzione, ecco un’architettura consigliata:
Application
│
▼
Moderator Agent (filters requests)
│
▼
Router Agent (distributes to specialists)
├── Search Agent (web_search)
├── Analysis Agent (code_interpreter)
├── Documents Agent (document_library)
└── Creation Agent (image_generation)
│
▼
Logging + Monitoring + Alerting
Riunisce tutto ciò che hai visto in questo corso: il moderatore filtra prima di qualsiasi esecuzione, il router indirizza senza mai rispondere direttamente, ogni specialista porta uno strumento e una responsabilità, e l’osservazione avvolge l’intero sistema.
Dove andare adesso
Quattro direzioni estendono ciò che puoi fare ora. Function calling ti permette di costruire i tuoi strumenti personalizzati oltre a quelli integrati: chiamare un’API aziendale, interrogare un database, attivare un servizio interno. MCP Servers integrano il Model Context Protocol, che standardizza il modo in cui gli strumenti sono esposti. Structured outputs forzano le risposte in uno schema JSON, il che cambia tutto quando l’output di un agente alimenta un altro sistema piuttosto che un lettore umano. Infine, streaming restituisce le risposte in tempo reale invece che in un unico blocco—decisivo nelle catene lunghe, dove l’attesa silenziosa diventa scomoda.
Tre risorse accompagnano questo prossimo passo: la documentazione ufficiale su docs.mistral.ai/agents, i cookbook di Mistral che forniscono esempi di implementazione completi, e l’API Reference che documenta ogni endpoint in dettaglio.
Punti chiave
- Specializza i tuoi agenti—un agente = una responsabilità
- Monitora—registra ogni handoff ed esecuzione di strumento
- Testa—convalida il routing e le risposte di ogni agente
- Metti in sicurezza—guardrail, minimo privilegio, moderazione a monte
- Ottimizza i costi—modello dimensionato correttamente, max_tokens, store=False quando possibile
- Mistral Agents è in beta—tieniti aggiornato sulle modifiche all’API
Metti alla prova le tue conoscenze
Agenti, strumenti integrati, handoff: l’API Agents ha ancora punti ciechi?
1. Quando è necessario un agente e quando basta un chatbot?
Risposta: Un agente è giustificato quando hai bisogno di strumenti, persistenza e decisioni multi-step; per semplici domande e risposte, una conversazione standard è sufficiente—l’architettura segue il bisogno.
2. Cosa gestiscono le conversazioni persistenti nell'API Agents?
Risposta: La cronologia lato Mistral: continui una conversazione tramite il suo ID senza dover reinviare l’intero contesto—lo stato diventa un servizio.
3. Elenca gli strumenti integrati disponibili e il loro utilizzo.
Risposta: web_search (informazioni in tempo reale), code_interpreter (eseguire Python), image_generation (creare immagini), document_library (Q&A sui tuoi file)—capacità pronte all’uso, nessuna implementazione richiesta.
4. Come funziona un sistema multi-agente con handoff?
Risposta: Un router qualifica la richiesta e la passa all’agente specialista competente; ogni agente rimane semplice, l’orchestrazione fornisce la copertura—e gli handoff si concatenano in profondità.
5. Come si mettono in sicurezza gli agenti in produzione?
Risposta: Con guardrail su input/output, strumenti con ambito ristretto, tracciabilità delle azioni e validazione umana sulle decisioni ad alto rischio—l’autonomia si guadagna attraverso il controllo.
Agenti specializzati, strumenti integrati, routing, guardrail: l’architettura completa sta in quattro parole—e questo corso ti ha fatto costruire ciascuna di esse.