Introduzione ai passaggi di consegne tra agenti multipli
In questa pagina
Perché orchestrare più agenti?
Finora hai lavorato con agenti singoli: un agente, le sue istruzioni, i suoi strumenti. Questo modello mostra rapidamente i suoi limiti quando un compito richiede competenze eterogenee. Prendi una richiesta di ricerca di mercato: devi cercare dati, analizzarli numericamente e poi produrre un rapporto leggibile. Potresti provare ad affidare tutto a un singolo agente, con istruzioni che si gonfiano a ogni nuova esigenza fino a diventare un blocco di testo contraddittorio che il modello applica sempre meno efficacemente. Le API Mistral offrono un’alternativa: catene di agenti specializzati che si passano il testimone.
Questo è il concetto di passaggio di consegne (handoff): un agente trasferisce il controllo della conversazione a un altro agente meglio attrezzato per il sotto-compito corrente. La conversazione stessa non cambia: cambia solo la mano che tiene le redini.
Come funzionano i passaggi di consegne
Il meccanismo rispecchia esattamente ciò che fa un’organizzazione umana di fronte a una richiesta composita. Un agente router riceve la query iniziale, come un operatore di centralino che prende una chiamata. Analizza la richiesta, identifica quale agente specialista è nella posizione migliore per gestirla e poi trasferisce la conversazione a quello specialista. Lo specialista gestisce il suo sotto-compito e, se incontra un bisogno che esula dal suo ambito, può trasferire il controllo a un terzo agente. La risposta finale torna all’utente, che vede un unico interlocutore.
Ne derivano quattro vantaggi, che si rafforzano a vicenda. Primo, la specializzazione: ogni agente ha un ambito limitato e istruzioni precise. L’agente di ricerca web non gestisce i calcoli e viceversa. Questo migliora la qualità della risposta perché nessuna istruzione ne contraddice un’altra. Secondo, la manutenibilità: modificare il comportamento di uno specialista non impatta gli altri. Puoi cambiare il suo modello, le sue istruzioni o i suoi strumenti senza toccare il resto del sistema. Terzo, la scalabilità ne consegue direttamente: aggiungere una capacità significa creare un nuovo agente specialista e registrarlo come destinazione di un passaggio di consegne. Il router lo selezionerà poi quando la richiesta corrisponderà. Infine, la tracciabilità: ogni passaggio di consegne genera un evento agent.handoff negli output, permettendoti di ricostruire a posteriori quale agente ha gestito quale parte della richiesta senza dover strumentare nulla tu stesso.
Architettura tipica
User
│
▼
Router Agent (orchestrator)
├── Web Search Agent (web_search)
├── Calculator Agent (code_interpreter)
├── Writer Agent (specific instructions)
└── Document Agent (document_library)
Il router decide dinamicamente a quale agente trasferire il controllo in base alla query. Non è limitato a un singolo passaggio: può anche orchestrare flussi sequenziali, come cercare, poi calcolare, poi scrivere, con ogni passo che arricchisce il contesto per il successivo.
Seguiamo una richiesta reale: «Trova l’attuale tasso di interesse della BCE e calcola l’effetto composto su 10 anni per un investimento di 100.000 €». L’agente Finance, che agisce da router, riceve la richiesta e vede che contiene due esigenze distinte. Trasferisce prima il controllo all’agente Web Search, che recupera l’attuale tasso della BCE: un dato che nessun modello può conoscere a memoria. Un secondo passaggio di consegne passa il controllo all’agente Calculator, che applica la formula dell’interesse composto al tasso appena trovato. L’utente riceve un unico risultato, accompagnato dalle fonti della ricerca e dai dettagli del calcolo.
Modalità di esecuzione
Le API Mistral offrono due modalità per i passaggi di consegne, e tu scegli quale usare all’avvio della conversazione. La modalità server è quella predefinita.
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Complex query",
handoff_execution="server"
)
Mistral gestisce poi tutto automaticamente: trasferimenti, esecuzione degli agenti e sintesi della risposta. Ricevi solo il risultato finale, il che è comodo e sufficiente finché non hai bisogno di interporre qualcosa tra i passaggi.
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Complex query",
handoff_execution="client"
)
In modalità client, ricevi gli eventi di passaggio di consegne e decidi cosa fare a ogni passo. Scegli questa modalità quando un umano deve approvare un trasferimento sensibile, quando devi registrare ogni passaggio per fini di audit, o quando la tua logica di business richiede un instradamento che il modello non può inferire. La lezione dedicata a queste due modalità dettaglierà i compromessi.
Eventi di output
Quando avviene un passaggio di consegne, tre tipi di eventi appaiono negli output:
agent.handoff— L’Agente A trasferisce il controllo all’Agente B (contiene entrambi gli ID degli agenti)tool.execution— L’Agente B esegue i suoi strumentimessage.output— La risposta dell’Agente B
for entry in response.outputs:
if entry.type == "agent.handoff":
print(f"Transfer: {entry.previous_agent_id} → {entry.next_agent_id}")
elif entry.type == "tool.execution":
print(f"Tool executed: {entry.tool_name}")
elif entry.type == "message.output":
print(f"Response: {entry.content}")
Scrivi questo ciclo durante i tuoi primi test, anche prima che il sistema sia completo. Un sistema multi-agente che risponde correttamente ma il cui percorso non puoi tracciare diventa impossibile da riparare il giorno in cui risponde male: non saprai se il router ha instradato male, se lo specialista ha performato male o se il passaggio di consegne si è perso lungo la strada. Tre istruzioni print ben posizionate ti salvano da questa cecità.
Punti chiave
- I passaggi di consegne permettono a un agente di trasferire il controllo a un altro agente specializzato
- Architettura tipica: agente router → agenti specialisti
- Modalità server = completamente automatica; modalità client = controllo manuale dei trasferimenti
- Ogni passaggio di consegne genera un evento tracciabile negli output
- Non c’è limite alla profondità della catena tra agenti