Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Strumenti asincroni e paralleli

Lezione 8 di 25 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Strumenti asincroni e paralleli
  2. Strumenti asincroni
  3. Parallelismo automatico
  4. Controllo del parallelismo
  5. Pattern: aggregazione di risultati paralleli
  6. Timeout e resilienza
  7. Prestazioni: impatto del parallelismo
  8. Punti chiave

Strumenti asincroni e paralleli

In produzione, i tuoi strumenti chiamano API esterne, interrogano database o eseguono operazioni di I/O. Queste operazioni richiedono tempo e i secondi si sommano: un agente che concatena cinque chiamate da un secondo impiega cinque secondi per rispondere. Rendere gli strumenti asincroni e sfruttare il parallelismo nativo dell’SDK è ciò che separa una demo da un servizio utilizzabile.

Strumenti asincroni

Il decoratore @function_tool supporta nativamente le funzioni async. Nessuna configurazione necessaria: dichiara async def, usa un client HTTP asincrono e l’SDK gestisce il resto.

import httpx
from agents import function_tool

@function_tool
async def search_company(name: str) -> str:
    """Cerca informazioni sull'azienda tramite l'API di Societe.com."""
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.societe.com/v1/search",
            params={"q": name},
            timeout=10,
        )
        if response.status_code == 200:
            data = response.json()
            return f"Azienda: {data['name']}, SIREN: {data['siren']}, Fatturato: {data['revenue']}"
        return f"Nessun risultato per '{name}'"

@function_tool
async def verify_solvency(siren: str) -> str:
    """Verifica la solvibilità di un'azienda tramite il suo numero SIREN."""
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://api.credit-scoring.com/v1/{siren}",
            timeout=10,
        )
        data = response.json()
        return f"Punteggio di solvibilità: {data['score']}/100, rischio: {data['risk_level']}"

Quando il Runner esegue uno strumento asincrono, non blocca il loop degli eventi. In un server FastAPI, ciò significa che altre richieste continuano a essere elaborate mentre il tuo agente attende la risposta dell’API Societe.com.

Parallelismo automatico

Due strumenti asincroni indipendenti possono essere eseguiti simultaneamente. Il modello decide quando farlo e le tue istruzioni possono incoraggiarlo esplicitamente.

from agents import Agent, Runner

agent = Agent(
    name="Analista B2B",
    instructions="""Analizzi le aziende per prendere decisioni commerciali.
    Quando ti viene chiesto di analizzare un'azienda, recupera le sue informazioni
    E verifica la sua solvibilità allo stesso tempo.""",
    tools=[search_company, verify_solvency],
    model="gpt-5.6-terra",
)

# Il modello lancerà entrambi gli strumenti in parallelo
result = await Runner.run(
    agent,
    "Analizza l'azienda Acme Corp (SIREN 123456789)"
)

Poiché il SIREN è fornito nella query, la verifica di solvibilità non attende la ricerca dell’azienda: l’SDK esegue entrambe le chiamate simultaneamente. Il tempo totale equivale alla durata dello strumento più lento, non alla somma di entrambi.

Controllo del parallelismo

Il parallelismo non è sempre desiderabile. Se i tuoi strumenti scrivono sullo stesso record o se l’ordine è fondamentale per la coerenza dei dati, forza l’esecuzione sequenziale.

from agents import Agent

agent = Agent(
    name="Agente Prudente",
    instructions="Esegui gli strumenti uno alla volta per garantire la coerenza dei dati.",
    tools=[search_company, verify_solvency],
    model="gpt-5.6-terra",
    parallel_tool_calls=False,  # Forza l'esecuzione sequenziale
)

Il parametro parallel_tool_calls=False forza il modello a chiamare un solo strumento alla volta. Scambi la latenza con la prevedibilità.

Pattern: aggregazione di risultati paralleli

Il caso pratico più comune consiste nel raccogliere dati da più fonti per la stessa entità. Qui, il meteo di una città e la sua agenda culturale non hanno nulla a che fare l’uno con l’altro, ma la risposta necessita di entrambi.

import json
from agents import Agent, Runner, function_tool

@function_tool
async def get_weather(city: str) -> str:
    """Ottiene il meteo attuale per una città."""
    # Simulazione - in produzione: chiamata API meteo
    weather_data = {
        "Paris": {"temp": 22, "conditions": "sunny"},
        "Lyon": {"temp": 19, "conditions": "cloudy"},
        "Marseille": {"temp": 26, "conditions": "sunny"},
    }
    data = weather_data.get(city, {"temp": 0, "conditions": "unknown"})
    return json.dumps({"city": city, **data}, ensure_ascii=False)

@function_tool
async def get_events(city: str) -> str:
    """Ottiene i prossimi eventi in una città."""
    events = {
        "Paris": ["Concerto allo Stade de France", "Mostra al Louvre"],
        "Lyon": ["Festa delle Luci", "Fiera della Gastronomia"],
        "Marseille": ["Regata del Mediterraneo"],
    }
    return json.dumps({
        "city": city,
        "events": events.get(city, [])
    }, ensure_ascii=False)

agent = Agent(
    name="Agente di Viaggio",
    instructions="""Sei un agente di viaggio. Quando ti vengono chieste
    raccomandazioni per una città, recupera il meteo E gli eventi
    simultaneamente per fornire un consiglio completo.""",
    tools=[get_weather, get_events],
    model="gpt-5.6-terra",
)

# Il modello chiamerà entrambi gli strumenti in parallelo per ogni città
result = await Runner.run(
    agent,
    "Voglio visitare Parigi questo weekend. Cosa mi consigli?"
)
print(result.final_output)

Entrambi gli strumenti restituiscono JSON, rendendo più facile per il modello ricombinare i dati. Nota la formulazione dell’istruzione: la dicitura “E … simultaneamente” attiva la chiamata parallela invece di una catena pigra.

Timeout e resilienza

Un’API che non risponde mai blocca il tuo agente tanto sicuramente quanto uno strumento sincrono. Delimita ogni chiamata lenta con un timeout e trasforma i fallimenti in messaggi intelligibili.

import asyncio
from agents import function_tool

@function_tool
async def slow_api_call(query: str) -> str:
    """Chiama un'API che potrebbe essere lenta."""
    try:
        async with asyncio.timeout(5):  # Timeout di 5 secondi
            # La tua chiamata API qui
            await asyncio.sleep(0.1)  # Simulazione
            return f"Risultato per '{query}'"
    except asyncio.TimeoutError:
        return "L'API non ha risposto in tempo. Riprova."

Prestazioni: impatto del parallelismo

Mettiamo le cose in prospettiva. Tre strumenti da 500 ms eseguiti sequenzialmente costano 1500 ms; gli stessi tre strumenti in parallelo costano circa 500 ms, ovvero la durata di quello più lento. Per un agente che utilizza molti strumenti, la differenza è immediatamente percepibile nella pratica.

Punti chiave

  • Usa async per gli strumenti che effettuano chiamate di rete o operazioni di I/O
  • L’SDK esegue automaticamente gli strumenti indipendenti in parallelo
  • parallel_tool_calls=False forza l’esecuzione sequenziale quando necessario
  • Aggiungi timeout con asyncio.timeout() per la resilienza
  • Il parallelismo può dividere la latenza per il numero di strumenti