Architettura dell'agente: il ciclo ragionamento-strumento
In questa pagina
Aggiornato il 3 novembre 2026: in
rechercher_produit, mancavano le virgolette alle chiaviprixestock, causando unNameErroralla prima chiamata dello strumento.
Architettura dell’agente: il ciclo ragionamento-strumento
Per costruire agenti efficaci, devi comprenderne l’architettura interna. Un agente OpenAI opera secondo un ciclo di ragionamento: riceve un compito, riflette, utilizza uno strumento, osserva il risultato e decide se ha finito o se deve continuare. Tutto ciò che farai in seguito—dichiarare strumenti, impostare guardrail, orchestrare più agenti—si basa su questo ciclo.
Il ciclo di vita dell’agente
Ogni esecuzione segue sei passaggi:
- Ricezione: l’agente riceve il messaggio dell’utente e le istruzioni di sistema
- Ragionamento: il modello analizza la richiesta e decide la prossima azione
- Chiamata dello strumento: se necessario, l’agente invoca uno o più strumenti
- Osservazione: l’agente riceve i risultati degli strumenti
- Decisione: l’agente decide se continuare (tornando al passaggio 2) o rispondere
- Risposta: l’agente produce la sua risposta finale
La chiave è il ciclo tra i passaggi 2 e 5, che può ripetersi più volte. Un agente può concatenare 5, 10 o anche 20 chiamate di strumenti prima di produrre una risposta finale, senza che tu scriva una singola riga di codice di orchestrazione. L’esempio seguente lo dimostra: vengono dichiarati due strumenti indipendenti e il modello decide come concatenarli.
from agents import Agent, Runner, function_tool
@function_tool
def rechercher_produit(nom: str) -> str:
"""Searches for a product in the catalog."""
# Simulation - in production, call your database
catalogue = {
"laptop-pro": {"prix": 1299, "stock": 45},
"tablet-air": {"prix": 599, "stock": 120},
}
produit = catalogue.get(nom)
if produit:
return f"Produit {nom}: {produit['prix']}€, stock: {produit['stock']}"
return f"Produit {nom} non trouvé"
@function_tool
def calculer_remise(prix: float, pourcentage: float) -> str:
"""Calculates the price after discount."""
prix_final = prix * (1 - pourcentage / 100)
return f"Prix après {pourcentage}% de remise : {prix_final:.2f}€"
agent = Agent(
name="Sales Agent",
instructions="You help customers find products and calculate discounts.",
tools=[rechercher_produit, calculer_remise],
model="gpt-5.6-terra",
)
# The agent will: 1) find the product, 2) calculate the discount, 3) respond
result = Runner.run_sync(
agent,
"What is the price of the laptop-pro with a 15% discount?"
)
print(result.final_output)
La domanda richiede due operazioni non esplicitamente collegate nel codice. L’agente esegue automaticamente due chiamate di strumento in sequenza: prima rechercher_produit, poi calculer_remise con il prezzo recuperato. Questa concatenazione è una decisione del modello, non una tua istruzione.
Struttura interna: elementi e messaggi
Le Responses API strutturano ogni interazione come elementi (items). Leggerli ti mostra cosa ha fatto effettivamente il tuo agente. Tre tipi compaiono nella conversazione:
message: un messaggio di testo (dall’utente o dall’agente)function_call: una chiamata di strumento decisa dall’agentefunction_call_output: il risultato restituito dallo strumento
result = Runner.run_sync(agent, "Find the tablet-air")
# Inspect the reasoning steps
for item in result.raw_responses:
print(f"Type: {type(item).__name__}")
# You'll see: message input → function_call → function_call_output → message output
Prendi l’abitudine di tracciare questo ciclo ogni volta che un agente produce una risposta sorprendente. Nove volte su dieci, l’anomalia appare in una function_call con argomenti inaspettati.
Chiamate parallele vs sequenziali
Non tutti i passaggi dipendono l’uno dall’altro. Quando due chiamate sono indipendenti, l’agente può decidere di eseguirle in parallelo.
@function_tool
def obtenir_meteo(ville: str) -> str:
"""Gets the current weather for a city."""
meteos = {"Paris": "18°C, sunny", "Lyon": "16°C, cloudy"}
return meteos.get(ville, "Data unavailable")
agent = Agent(
name="Travel Agent",
instructions="You help plan trips.",
tools=[obtenir_meteo, rechercher_produit],
model="gpt-5.6-terra",
)
# The agent will call obtenir_meteo("Paris") and obtenir_meteo("Lyon") in parallel
result = Runner.run_sync(
agent,
"What's the weather in Paris and Lyon?"
)
Il meteo di Lione non dipende da quello di Parigi: l’SDK gestisce automaticamente il parallelismo e avvia entrambe le chiamate simultaneamente, riducendo la latenza. Confrontalo con l’esempio di vendita precedente, dove il calcolo dello sconto doveva attendere il prezzo: lì, la sequenza si impone da sé.
Il parametro max_turns
Un ciclo autonomo può, nel peggiore dei casi, non fermarsi mai: l’agente chiama uno strumento, il risultato lo spinge a chiamarne un altro, e così via. La salvaguardia è un singolo parametro.
result = Runner.run_sync(
agent,
"Full catalog analysis",
max_turns=10 # Maximum 10 loop iterations
)
Se l’agente raggiunge il limite, si ferma con i risultati ottenuti fino a quel momento. In produzione, questa è una sicurezza essenziale: limita sia il tempo di risposta che i costi.
Punti chiave
- Un agente esegue un ciclo: ragionamento → strumento → osservazione → decisione
- Questo ciclo può eseguirsi più volte prima di produrre una risposta
- Il modello decide automaticamente quali strumenti chiamare e in quale ordine
- Le chiamate di strumenti indipendenti vengono eseguite in parallelo
max_turnslimita il numero di iterazioni per sicurezza