Casi d'uso multi-agente
In questa pagina
Dal concetto alla realtà
Ora conosci i passaggi di consegna (handoffs), le modalità di esecuzione e il chaining. Questa lezione assembla questi mattoni in tre sistemi completi, ciascuno basato su una topologia diversa: una catena di escalation, una pipeline e un router. Mentre leggi, nota come l’architettura scaturisca dal problema, e non viceversa: è la natura del bisogno a dettare la forma, non la tecnologia.
Caso 1: Supporto clienti multi-livello
Le operazioni di supporto funzionano a livelli: la maggior parte delle richieste si risolve al primo contatto, una minoranza richiede una diagnosi tecnica e poche finiscono nelle mani di un umano. Questa realtà si mappa direttamente su una catena di escalation, dove ogni livello trasferisce solo al successivo.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Level 1: FAQ and simple questions
level1 = client.beta.agents.create(
model="mistral-medium-latest",
name="support-level1",
description="Level 1 support: FAQ, common questions, basic information.",
instructions="""You are the first level of support.
- Answer simple questions (hours, rates, FAQ)
- If the question is technical or complex, transfer to level 2
- Be polite and professional""",
tools=[{"type": "document_library", "library_ids": ["faq-library-id"]}]
)
# Level 2: Technical support
level2 = client.beta.agents.create(
model="mistral-large-latest",
name="support-level2",
description="Technical support: diagnosis, troubleshooting, configuration.",
instructions="""You are technical support.
- Diagnose technical issues
- Propose step-by-step solutions
- If the problem requires manual intervention, transfer to level 3""",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}]
)
# Level 3: Human escalation (simulation)
level3 = client.beta.agents.create(
model="mistral-large-latest",
name="support-level3",
description="Escalation: critical issues requiring human intervention.",
instructions="""Prepare a summary of the issue for the technical team:
- Problem context
- Diagnostic steps performed
- Solutions attempted
- Recommendation"""
)
# Chain the escalations
level1 = client.beta.agents.update(agent_id=level1.id, handoffs=[level2.id])
level2 = client.beta.agents.update(agent_id=level2.id, handoffs=[level3.id])
Due decisioni spiccano. Il Livello 1 gira su mistral-medium-latest, mentre i livelli successivi usano mistral-large-latest. Il Livello 1 assorbe il volume più alto: assegnargli il modello più costoso significherebbe pagare competenze non necessarie per domande sugli orari di apertura. Il Livello 3, invece, non risolve nulla; redige un fascicolo. È esattamente ciò che ti serve da un’escalation umana: l’ingegnere che subentra riceve il contesto, i passaggi diagnostici già eseguiti e le soluzioni già tentate, invece di ricominciare l’interrogatorio da zero.
Nella pratica, un cliente scrive: «Non riesco ad accedere al mio account». Il Livello 1 controlla le FAQ, non trova casi corrispondenti e trasferisce. Il Livello 2 diagnostica un problema al database oltre le sue competenze e trasferisce a sua volta. Il Livello 3 prepara il ticket con l’intera cronologia.
Caso 2: Pipeline di intelligence strategica
Qui l’ordine è fisso e noto in anticipo: non puoi analizzare ciò che non è stato raccolto, né scrivere ciò che non è stato analizzato. Una catena lineare è quindi obbligatoria e il punto di ingresso non è un router, ma il primo anello.
# Collector — searches for raw information
collector = client.beta.agents.create(
model="mistral-large-latest",
name="intelligence-collector",
description="Collects strategic information via web search.",
instructions="""Search for information on the requested topic.
- Cover multiple sources
- Include numerical data
- Note publication dates""",
tools=[{"type": "web_search"}]
)
# Analyst — extracts insights
analyst = client.beta.agents.create(
model="mistral-large-latest",
name="intelligence-analyst",
description="Analyzes and extracts insights from raw data.",
instructions="""Analyze the collected data:
- Identify trends
- Spot opportunities and threats
- Quantify when possible""",
tools=[{"type": "code_interpreter"}]
)
# Reporter — produces the report
reporter = client.beta.agents.create(
model="mistral-large-latest",
name="intelligence-reporter",
description="Writes structured intelligence reports.",
instructions="""Write a professional intelligence report:
## Executive Summary (3 sentences)
## Key Facts (bullet points)
## Analysis (2-3 paragraphs)
## Recommendations (concrete actions)
## Sources"""
)
# Pipeline
collector = client.beta.agents.update(agent_id=collector.id, handoffs=[analyst.id])
analyst = client.beta.agents.update(agent_id=analyst.id, handoffs=[reporter.id])
# Launch
response = client.beta.conversations.start(
agent_id=collector.id,
inputs="Strategic intelligence: sovereign AI market in Europe, Q1 2026."
)
La struttura del report è scritta nero su bianco nelle istruzioni del reporter, fino al numero di frasi nel sommario esecutivo. Questo livello di precisione rende l’intelligence utilizzabile nel tempo: ogni report esce nello stesso formato, permettendoti di confrontare settimana dopo settimana e distribuirli senza modifiche. Nota anche l’istruzione per il collector di registrare le date di pubblicazione: senza di essa, un report di intelligence può sembrare solido pur basandosi su fonti obsolete.
Caso 3: L’assistente versatile
Quando le richieste coinvolgono competenze non correlate, non c’è né escalation né pipeline: c’è routing. Il router centrale legge la query e la invia a uno dei suoi quattro specialisti, nessuno dei quali ha bisogno di conoscere gli altri.
# Specialists
web_researcher = client.beta.agents.create(
model="mistral-large-latest",
name="web-researcher",
description="Searches for current information on the internet.",
tools=[{"type": "web_search"}]
)
data_analyst = client.beta.agents.create(
model="mistral-large-latest",
name="data-analyst",
description="Data analysis, statistics, and visualizations.",
tools=[{"type": "code_interpreter"}]
)
doc_expert = client.beta.agents.create(
model="mistral-large-latest",
name="doc-expert",
description="Queries and synthesizes internal documents.",
tools=[{"type": "document_library", "library_ids": ["docs-lib-id"]}]
)
creative = client.beta.agents.create(
model="mistral-large-latest",
name="creative-agent",
description="Creates visual content and illustrations.",
tools=[{"type": "image_generation"}]
)
# Central router
assistant = client.beta.agents.create(
model="mistral-large-latest",
name="research-assistant",
description="Versatile research assistant.",
instructions="""You are a research assistant. Analyze each request and transfer to the appropriate specialist:
- Current information → web-researcher
- Calculations and data → data-analyst
- Questions about our documents → doc-expert
- Need for illustrations → creative-agent""",
handoffs=[web_researcher.id, data_analyst.id, doc_expert.id, creative.id]
)
Ogni specialista possiede esattamente uno strumento e le quattro descrizioni non si sovrappongono in alcun punto. È questa assenza di sovrapposizione a rendere stabile il routing: se due agenti potessero plausibilmente gestire la stessa richiesta, la scelta varierebbe da un’esecuzione all’altra e i tuoi utenti sperimenterebbero una qualità inconsistente senza capirne il motivo.
Cosa distingue un prototipo da un sistema
Questi tre sistemi condividono la stessa regola di progettazione: un agente, una responsabilità. Non appena un agente accumula due ruoli, le sue istruzioni si contraddicono e la sua descrizione diventa troppo vaga perché il router possa decidere correttamente. Scrivi quindi ogni descrizione pensando alla decisione che deve abilitare e redigi ogni set di istruzioni specificando sia ciò che l’agente deve fare, sia ciò che non deve fare.
Il passaggio alla produzione aggiunge quattro requisiti che un prototipo ignora. Primo, il logging: la modalità client ti permette di tracciare ogni handoff con i tuoi identificatori, che saranno l’unica risorsa nel giorno in cui un utente segnalerà una risposta aberrante. Secondo, i timeout, essenziali nelle catene lunghe dove un anello bloccato immobilizza il resto. Terzo, i fallback, perché alla domanda «cosa succede se questo agente fallisce?» devi avere una risposta scritta prima del go-live, non dopo il primo incidente. Infine, il monitoraggio dei costi: una catena a tre agenti consuma token a ogni relais e solo un contatore per conversazione ti dirà se la tua pipeline di intelligence costa pochi centesimi o molto di più.
Punti chiave
- Il supporto clienti multi-livello è un caso d’uso naturale per gli handoff
- Le pipeline di intelligence (raccogli → analizza → scrivi) sfruttano il chaining lineare
- Gli assistenti versatili usano un router centrale verso specialisti
- In produzione: logging, timeout, fallback e monitoraggio dei costi sono essenziali
- Un agente = una responsabilità, con una descrizione precisa per il routing