Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Scalabilità e Architetture Multi-Agente

Lezione 25 di 25 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Scalabilità e Architetture Multi-Agente
  2. Architettura di Produzione
  3. Pattern Multi-Agente
  4. Gestione dei Limiti di Frequenza (Rate Limits)
  5. Ottimizzazione dei Costi su Larga Scala
  6. Punti chiave
  7. Metti alla Prova le Tue Conoscenze

Scalabilità e Architetture Multi-Agente

Il tuo agente funziona per 10 utenti. Come fai a farlo funzionare per 10.000? Le sfide cambiano: non si tratta più di istruzioni che falliscono, ma di limiti di frequenza del provider, memoria del server e della tua fattura mensile. In questa lezione finale, imparerai come scalare i tuoi agenti, progettare architetture multi-agente ad alte prestazioni e gestire i vincoli di produzione su larga scala.

Architettura di Produzione

Il Backend dell’Agente con FastAPI

La prima decisione strutturale riguarda il ciclo di vita dell’agente. Creare un Agent per ogni richiesta spreca tempo e disperde la configurazione; il parametro lifespan di FastAPI ti permette di istanziarli una sola volta all’avvio e mantenerli in un registro indicizzato per tipo. La rotta legge il tipo richiesto, lo rifiuta pulitamente se non esiste, quindi trasmette la risposta: run_streamed emette delta man mano che la generazione procede, facendo apparire il testo sullo schermo immediatamente invece di lasciare l’utente a fissare un indicatore di caricamento per otto secondi.

from fastapi import FastAPI, Request, Depends, HTTPException
from fastapi.responses import StreamingResponse
from agents import Agent, Runner, function_tool
from contextlib import asynccontextmanager
import asyncio

# Pool di agenti pre-configurati
agents_registry = {}

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Inizializza gli agenti all'avvio
    agents_registry["sales"] = Agent(
        name="Sales Agent",
        instructions="You assist customers with their purchases.",
        model="gpt-5.6-terra",
        tools=[search_product, calculate_price],
    )
    agents_registry["support"] = Agent(
        name="Support Agent",
        instructions="You provide technical support.",
        model="gpt-5.6-terra",
        tools=[check_ticket, create_ticket],
    )
    yield
    agents_registry.clear()

app = FastAPI(lifespan=lifespan)

@app.post("/api/chat/{agent_type}")
async def chat(agent_type: str, request: Request):
    agent = agents_registry.get(agent_type)
    if not agent:
        raise HTTPException(404, f"Agent '{agent_type}' not found")

    body = await request.json()

    async def stream():
        result = Runner.run_streamed(agent, body["messages"])
        async for event in result.stream_events():
            if event.type == "raw_response_event":
                if hasattr(event.data, "delta") and event.data.delta:
                    yield f"data: {event.data.delta}\n\n"
        yield "data: [DONE]\n\n"

    return StreamingResponse(stream(), media_type="text/event-stream")

Gestione della Concorrenza

Condividere oggetti Agent tra tutte le richieste in questo modo è sicuro perché ogni richiesta crea un Runner indipendente: l’agente contiene la configurazione, il Runner contiene lo stato di esecuzione. L’SDK gestisce la concorrenza nativamente e l’elaborazione di un batch di messaggi significa impilare coroutine in asyncio.gather. Il dettaglio chiave qui è return_exceptions=True: senza di esso, una singola richiesta fallita annulla l’intero batch. Con esso, ottieni gli errori come valori, li abbini al messaggio originale ed elabori i novantanove risultati validi.

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="Concurrent Agent",
    instructions="You answer questions.",
    model="gpt-5.6-terra",
)

async def process_parallel_requests(messages: list[str]):
    """Elabora più richieste in parallelo."""
    tasks = [Runner.run(agent, msg) for msg in messages]
    results = await asyncio.gather(*tasks, return_exceptions=True)

    for msg, res in zip(messages, results):
        if isinstance(res, Exception):
            print(f"Error for '{msg}': {res}")
        else:
            print(f"'{msg}' -> {res.final_output[:50]}...")

    return results

Pattern Multi-Agente

Pattern Supervisor

Oltre una certa scala, un singolo agente con quindici strumenti diventa imprevedibile: le sue istruzioni si gonfiano, le sue scelte degradano. Il pattern supervisor divide il lavoro tra agenti specializzati—ricerca, analisi, scrittura—e delega il routing a un agente dedicato tramite handoff. Ogni specialista mantiene istruzioni brevi e un modello adatto al suo compito: l’analisi eredita un modello di ragionamento, mentre il supervisor, che deve solo scegliere un destinatario, gira su un modello veloce poiché la sua decisione dipende da poche parole.

from agents import Agent, Runner, Handoff

search_agent = Agent(
    name="Search",
    instructions="You search for information on the web and in databases.",
    tools=[WebSearchTool(), search_crm],
    model="gpt-5.6-terra",
)

analysis_agent = Agent(
    name="Analysis",
    instructions="You analyze data and produce insights.",
    model="gpt-5.6-sol",
)

writing_agent = Agent(
    name="Writing",
    instructions="You write professional reports in English.",
    model="gpt-5.6-terra",
)

supervisor_agent = Agent(
    name="Supervisor",
    instructions="""You coordinate a team of specialized agents.
    For each request:
    1. Analyze what is needed
    2. Delegate to specialized agents via handoff
    3. The last agent produces the final response

    Available agents:
    - Search: to collect data
    - Analysis: to analyze and interpret
    - Writing: to produce the final deliverable""",
    handoffs=[
        Handoff(agent=search_agent, description="Collect data"),
        Handoff(agent=analysis_agent, description="Analyze data"),
        Handoff(agent=writing_agent, description="Write a report"),
    ],
    model="gpt-5.6-terra",  # Veloce per il routing
)

Pattern Pipeline

Quando la sequenza è nota in anticipo, lasciare che un modello decida la catena è una spesa inutile. Il pattern pipeline cabla i passaggi nel tuo codice: raccogli, analizza, scrivi. Un’analisi competitiva inizia quindi con due raccolte lanciate insieme—il web e il CRM non hanno motivo di aspettarsi a vicenda—poi passa tutto all’analisi, il cui output alimenta la scrittura. Ottieni un flusso di lavoro riproducibile, tracciabile passo dopo passo, la cui durata totale è quella della raccolta più lenta più i due passaggi successivi.

async def competitive_analysis_pipeline(company: str):
    # Passo 1: Raccolta dati parallela
    web_task = Runner.run(search_agent, f"Search for information about {company}")
    crm_task = Runner.run(crm_agent, f"CRM data for {company}")
    results = await asyncio.gather(web_task, crm_task)

    data = f"""Web data: {results[0].final_output}
    CRM data: {results[1].final_output}"""

    # Passo 2: Analisi
    analysis = await Runner.run(analysis_agent, f"Analyze this data: {data}")

    # Passo 3: Report
    report = await Runner.run(
        writing_agent,
        f"Write a competitive analysis report: {analysis.final_output}"
    )

    return report.final_output

Pattern Map-Reduce

Il terzo pattern affronta un problema di volume piuttosto che di complessità. Duemila verbatim dei clienti non stanno in una singola richiesta e non possono essere analizzati sequenzialmente in tempi ragionevoli. La fase MAP classifica ogni feedback in parallelo con un modello veloce e un output tipizzato; la fase REDUCE aggrega queste classificazioni, molto più compatte dei testi originali, e affida la sintesi a un modello più capace. Il costo crolla rispetto all’analisi completa, perché la maggior parte del volume è elaborata dal modello più economico.

async def analyze_feedbacks(feedbacks: list[str]):
    # MAP: analizza ogni feedback in parallelo
    classifier_agent = Agent(
        name="Classifier",
        instructions="Classify the feedback: positive, negative, or neutral. Identify the main theme.",
        model="gpt-5.6-terra",
        output_type=FeedbackClassification,
    )

    tasks = [Runner.run(classifier_agent, fb) for fb in feedbacks]
    classifications = await asyncio.gather(*tasks)

    # REDUCE: sintetizza i risultati
    summary_data = [
        {"feedback": fb, "class": c.final_output.dict()}
        for fb, c in zip(feedbacks, classifications)
    ]

    synthesizer_agent = Agent(
        name="Synthesizer",
        instructions="Synthesize the feedback classifications into a report with statistics and insights.",
        model="gpt-5.6-terra",
    )

    import json
    report = await Runner.run(
        synthesizer_agent,
        f"Synthesize these {len(feedbacks)} classified feedbacks: {json.dumps(summary_data, ensure_ascii=False)}"
    )

    return report.final_output

Gestione dei Limiti di Frequenza (Rate Limits)

Lanciare duemila chiamate simultanee non le fa finire più velocemente: il provider ti rifiuta e perdi il batch. Un semaforo limita il numero di esecuzioni concorrenti e il gestore sottostante aggiunge un backoff esponenziale con tetto a sessanta secondi quando si verifica un errore di limite. Il contatore degli errori si resetta non appena una chiamata ha successo, evitando penalità a lungo termine per il servizio a causa di un incidente transitorio.

import asyncio
from agents import Runner

class RateLimitManager:
    def __init__(self, max_concurrent: int = 10):
        self.semaphore = asyncio.Semaphore(max_concurrent)
        self.error_count = 0

    async def execute(self, agent, message, **kwargs):
        async with self.semaphore:
            try:
                result = await Runner.run(agent, message, **kwargs)
                self.error_count = 0
                return result
            except Exception as e:
                if "rate_limit" in str(e).lower():
                    self.error_count += 1
                    wait_time = min(2 ** self.error_count, 60)
                    await asyncio.sleep(wait_time)
                    return await self.execute(agent, message, **kwargs)
                raise

manager = RateLimitManager(max_concurrent=20)

Ottimizzazione dei Costi su Larga Scala

Poi c’è la fattura. Due leve la riducono senza degradare il servizio. La prima è non pagare un modello di ragionamento per rispondere a «quali sono i vostri orari»: una tabella di lookup mappa il livello di complessità al modello adatto, dal più economico per domande semplici al più capace per casi critici, con un default per qualsiasi cosa non classificata. La seconda sfrutta la ripetizione—nel supporto clienti, le stesse domande tornano centinaia di volte al giorno, e una cache indicizzata su un hash del messaggio restituisce la risposta istantaneamente e gratis. Riserva questa cache per domande la cui risposta non dipende né dall’utente né dal tempo: una politica di reso si cached bene, lo stato di un ordine mai.

# Strategia del modello per complessità
def choose_model(complexity: str) -> str:
    models = {
        "simple": "gpt-5.6-terra",      # Domande semplici: economiche
        "medium": "gpt-5.6-terra",       # La maggior parte dei casi
        "complex": "gpt-5.6-terra",     # Ragionamento veloce
        "critical": "gpt-5.6-sol",      # Casi critici: massima qualità
    }
    return models.get(complexity, "gpt-5.6-terra")

# Cache per risposte frequenti
from functools import lru_cache
import hashlib

response_cache = {}

async def execute_with_cache(agent, message: str):
    key = hashlib.md5(message.encode()).hexdigest()
    if key in response_cache:
        return response_cache[key]

    result = await Runner.run(agent, message)
    response_cache[key] = result.final_output
    return result.final_output

Punti chiave

  • Pre-configura i tuoi agenti all’avvio e riutilizzali tra le richieste
  • L’SDK gestisce la concorrenza nativamente tramite asyncio.gather()
  • Il pattern supervisor coordina agenti specializzati tramite handoff
  • Il pattern map-reduce parallelizza l’elaborazione di grandi volumi
  • Gestisci i limiti di frequenza con un semaforo e un backoff esponenziale
  • Ottimizza i costi con la selezione del modello per complessità e la caching

Metti alla Prova le Tue Conoscenze

Prima di scalare, verifica la tua conoscenza dell’architettura degli agenti.

1. Quali sono i mattoni fondamentali dell'SDK Agents?

Risposta: Agent (il ruolo e le sue istruzioni), Runner (il loop di esecuzione), Tool (le capacità) e Guardrail (validazioni input/output)—l’anatomia di qualsiasi agente SDK.

2. A cosa servono i Guardrails?

Risposta: A validare ciò che entra ed esce dall’agente: filtrare le richieste fuori scope, controllare gli output prima che agiscano—sicurezza dichiarata nell’architettura, non sperata nel prompt.

3. Cos'è un handoff?

Risposta: Il trasferimento di una conversazione da un agente a un altro, più specializzato: orchestrazione multi-agente dove ogni agente fa ciò che sa fare meglio, con il contesto che segue.

4. Perché il tracing è indispensabile in produzione?

Risposta: Perché un agente decide dinamicamente: senza tracce di passaggi, strumenti chiamati e decisioni, il debug o la valutazione sono impossibili—il grading del tracing valuta precisamente queste esecuzioni.

5. Quando dovresti passare a un'architettura multi-agente?

Risposta: Quando un singolo agente accumula troppi ruoli e strumenti: ti specializzi (triage, expertise, esecuzione) e orchestrati tramite handoff—ogni agente torna semplice e testabile.

SDK, guardrails, handoffs, tracing: l’impalcatura è completa—la scalabilità sopra ti dice come distribuirla senza indebolirla.