Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Architettura dell'agente: il ciclo ragionamento-strumento

Lezione 2 di 25 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Architettura dell’agente: il ciclo ragionamento-strumento
  2. Il ciclo di vita dell’agente
  3. Struttura interna: elementi e messaggi
  4. Chiamate parallele vs sequenziali
  5. Il parametro max_turns
  6. Punti chiave

Aggiornato il 3 novembre 2026: in rechercher_produit, mancavano le virgolette alle chiavi prix e stock, causando un NameError alla 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:

  1. Ricezione: l’agente riceve il messaggio dell’utente e le istruzioni di sistema
  2. Ragionamento: il modello analizza la richiesta e decide la prossima azione
  3. Chiamata dello strumento: se necessario, l’agente invoca uno o più strumenti
  4. Osservazione: l’agente riceve i risultati degli strumenti
  5. Decisione: l’agente decide se continuare (tornando al passaggio 2) o rispondere
  6. 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’agente
  • function_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_turns limita il numero di iterazioni per sicurezza