Strumenti asincroni e paralleli
In questa pagina
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
asyncper gli strumenti che effettuano chiamate di rete o operazioni di I/O - L’SDK esegue automaticamente gli strumenti indipendenti in parallelo
parallel_tool_calls=Falseforza l’esecuzione sequenziale quando necessario- Aggiungi timeout con
asyncio.timeout()per la resilienza - Il parallelismo può dividere la latenza per il numero di strumenti