Esecuzione Server vs. Client
In questa pagina
Lezione aggiornata il 3 novembre 2026 sulla base dell’SDK
mistralai3.7.0 e della documentazione Handoffs di Mistral: una voceagent.handoffidentifica l’agente di destinazione tramitenext_agent_id(nonto_agent), econversations.appendnon accetta il parametroagent_id: il codice più vecchio fallirebbe. La ripresa dell’agente di destinazione avviene qui tramite una nuova conversazione, alla quale passi il contesto. Fonti: Handoffs · client-python.
Due Modi per Gestire i Passaggi di Consegna
Quando un agente trasferisce il controllo a un altro agente, le API di Mistral offrono due modalità di esecuzione: server (automatica) e client (manuale). L’impostazione è una singola parola, ma determina chi guida effettivamente il flusso di lavoro. In modalità server, deleghi l’intera coreografia a Mistral e ricevi il risultato. In modalità client, riprendi il controllo tra ogni passaggio. Tutto il resto — gli agenti, i loro strumenti, i loro obiettivi di consegna — rimane esattamente lo stesso.
Modalità Server, l’Impostazione Predefinita
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze and calculate market trends.",
handoff_execution="server" # Default — può essere omesso
)
Il flusso è completamente gestito: il router riceve la richiesta, decide di trasferirla all’agente di ricerca e Mistral esegue il trasferimento; l’agente di ricerca svolge il suo lavoro, poi trasferisce al calcolatore e Mistral esegue anche questo; il calcolatore produce il risultato. Ricevi la risposta finale, accompagnata da tutti gli output intermedi: vedi quindi cosa è successo, ma a posteriori.
Questa modalità ha tre qualità che spiegano perché è quella predefinita. È semplice, poiché non scrivi alcuna logica di controllo dal tuo lato. È veloce, perché l’intera catena viene eseguita su Mistral senza round-trip di rete a ogni relais. È affidabile, dato che la gestione degli errori e i timeout tra gli agenti sono gestiti per te.
I suoi limiti sono l’esatto contraltare. Non hai alcun controllo intermedio: impossibile convalidare o modificare un passaggio mentre avviene. Il costo è opaco, nel senso che tutti gli agenti della catena vengono eseguiti senza che tu possa interrompere a metà flusso una richiesta che si dirige verso una direzione inutile. E non puoi inserire alcuna logica personalizzata tra i passaggi: nessun logging granulare, nessuna convalida, nessuna decisione aziendale.
Modalità Client, Quando Vuoi il Controllo
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Analyze the cloud market.",
handoff_execution="client"
)
Il router riceve la richiesta e decide di trasferirla, esattamente come prima. Ma invece che il trasferimento venga eseguito, ricevi un evento agent.handoff e la catena si ferma lì. Spetta a te riavviarla chiamando l’agente di destinazione, il che ti lascia la libertà di convalidare, registrare, arricchire il contesto o semplicemente rifiutare.
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Search for the latest tech news.",
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target_agent_id = entry.next_agent_id
print(f"Handoff requested to: {target_agent_id}")
# Convalida, poi passa all'agente di destinazione, con il contesto utile
next_response = client.beta.conversations.start(
agent_id=target_agent_id,
inputs="Search for the latest tech news.",
)
# Elabora la risposta dell'agente di destinazione
for next_entry in next_response.outputs:
print(f"{next_entry.type}: {next_entry.content}")
Un punto merita attenzione: la documentazione di Mistral descrive la modalità client — il controllo ti viene restituito al momento del trasferimento — ma non fornisce alcun metodo per far riprendere la stessa conversazione all’agente di destinazione, e conversations.append non accetta il parametro agent_id. L’esempio avvia quindi una conversazione con l’agente di destinazione, al quale trasmetti esplicitamente ciò di cui ha bisogno: la richiesta originale e, se applicabile, un riepilogo di ciò che è già stato fatto. Questa è anche un’opportunità per trasmettere solo ciò che devono vedere.
Lo snippet sopra gestisce solo un singolo relais. Una catena reale ne collega diversi, il che richiede un ciclo.
def execute_with_control(router_id, query):
"""Esegue un flusso di lavoro multi-agente con controllo a ogni passaggio."""
response = client.beta.conversations.start(
agent_id=router_id,
inputs=query,
handoff_execution="client"
)
conversation_id = response.conversation_id
results = []
while True:
handoff_found = False
for entry in response.outputs:
if entry.type == "agent.handoff":
handoff_found = True
target = entry.next_agent_id
print(f"[LOG] Handoff to {target}")
# Qui puoi aggiungere: convalida, logging, metriche
response = client.beta.conversations.start(
agent_id=target,
inputs=query, # la richiesta originale, arricchita se necessario
handoff_execution="client",
)
conversation_id = response.conversation_id
break
elif entry.type == "message.output":
results.append(entry.content)
if not handoff_found:
break
return results
La struttura è quella di una pompa: finché un passaggio di consegna appare negli output, lo elabori e riavvii; non appena un’iterazione del ciclo non ne trova nessuno, la catena è finita ed esci con i messaggi accumulati. Il commento al centro segna la posizione che giustifica l’intera modalità: è lì, e solo lì, che il tuo codice si interpone tra due agenti.
Scegliere tra le Due
La modalità server copre la produzione standard. Se il tuo flusso di lavoro è prevedibile, se ti fidi degli agenti che hai scritto, o se stai facendo prototipazione e vuoi vedere rapidamente i risultati, l’automazione completa è la scelta giusta: scrivere un ciclo di controllo sarebbe uno sforzo inutile.
La modalità client è giustificata non appena un requisito esterno entra nella catena. Convalida umana, quando un operatore deve approvare un trasferimento a un agente che attiva azioni sensibili. Necessità di logging e auditing, quando la conformità richiede di tracciare ogni passaggio con i tuoi identificativi e i tuoi timestamp. Routing condizionale, quando la decisione dipende da regole aziendali che il modello non può conoscere: stato del cliente, ora del giorno, una quota. Un limite, o rate limiting, quando vuoi vincolare il numero di agenti eseguiti per una richiesta. Una strategia di fallback, infine, quando il fallimento di un agente deve innescare qualcosa di diverso da un errore mostrato all’utente.
Ecco come appare la prima di queste situazioni, ridotta al suo scheletro.
def workflow_with_validation(router_id, query):
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 = entry.next_agent_id
approval = input(f"Authorize transfer to {target}? (y/n) ")
if approval.lower() == "y":
response = client.beta.conversations.start(
agent_id=target,
inputs=query,
)
else:
print("Transfer refused.")
break
L’input della console serve come dimostrazione; in un’applicazione, sarà sostituito da una notifica a un operatore e dalla ripresa del flusso di lavoro quando arriva la risposta. Il principio rimane lo stesso: il trasferimento avviene solo se il tuo codice lo attiva.
L’approccio giusto è iniziare in modalità server e passare all’altra solo il giorno in cui un vincolo specifico lo richiede. Passare alla modalità client “per sicurezza” ti fa pagare immediatamente la complessità di un ciclo e i round-trip di rete, per un controllo che non stai ancora utilizzando.
Punti chiave
- Modalità server = completamente automatica, semplice e veloce, nessun controllo intermedio
- Modalità client = ricevi eventi di passaggio di consegna e decidi cosa fare
- La modalità client abilita convalida, logging, routing condizionale e gestione degli errori
- Nella maggior parte dei casi, la modalità server è sufficiente: passa alla modalità client quando hai bisogno di controllo
- Entrambe le modalità supportano le stesse catene di agenti; cambia solo il controllo