Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Agente multi-step con ciclo di ragionamento

Lezione 15 di 25 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Agente multi-step con ciclo di ragionamento
  2. Il pattern plan-execute
  3. Agente auto-correttivo
  4. Pattern: catena di agenti specializzati
  5. Controllo della profondità di ragionamento
  6. Punti chiave

Agente multi-step con ciclo di ragionamento

Gli agenti più potenti non si fermano dopo una singola chiamata a uno strumento. Concatenano più passaggi di ragionamento, adattano la propria strategia in base ai risultati e iterano fino al raggiungimento dell’obiettivo. In questa lezione imparerai a costruire questi agenti multi-step. Gli esempi utilizzano la famiglia GPT-5.6: mentre la generazione precedente richiedeva il cambio di modello per abilitare il ragionamento, ora controlli questo comportamento tramite l’impostazione effort sul modello scelto.

Il pattern plan-execute

Un agente multi-step inizia creando un piano, quindi esegue ogni passaggio. Questa separazione è deliberata: il pianificatore non ha strumenti e produce una struttura tipizzata, mentre l’esecutore riceve questo piano come una tabella di marcia e si limita a seguirlo. Una richiesta vaga come «prepara la revisione trimestrale per i clienti chiave» diventa una sequenza concreta di azioni—interrogare il CRM, generare il report, inviare l’email—prima che venga tentata qualsiasi azione.

from agents import Agent, Runner, function_tool
from pydantic import BaseModel
import json

class PlanAction(BaseModel):
    steps: list[str]
    objective: str

planner_agent = Agent(
    name="Planner",
    instructions="""Ricevi un compito complesso. Scomponilo in passaggi semplici e ordinati.
    Ogni passaggio deve essere un elemento concreto e azionabile.""",
    model="gpt-5.6-sol",  # Ragionamento avanzato per la pianificazione
    output_type=PlanAction,
)

@function_tool
def search_crm(query: str) -> str:
    """Cerca informazioni sui clienti nel CRM."""
    return json.dumps({"customers": [
        {"name": "Acme Corp", "revenue": 500000, "contract": "Enterprise"},
        {"name": "TechStart", "revenue": 50000, "contract": "Starter"},
    ]})

@function_tool
def generate_report(title: str, content: str) -> str:
    """Genera un report formattato."""
    return f"Report '{title}' generato con successo ({len(content)} caratteri)"

@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
    """Invia un'email."""
    return f"Email inviata a {recipient}: {subject}"

executor_agent = Agent(
    name="Executor",
    instructions="""Esegui i compiti passo dopo passo.
    Usa gli strumenti disponibili per completare ogni passaggio.
    Se un passaggio fallisce, prova un approccio alternativo.""",
    tools=[search_crm, generate_report, send_email],
    model="gpt-5.6-terra",
)

async def process_complex_task(task: str):
    # Passaggio 1: Pianifica
    plan = await Runner.run(planner_agent, task)
    print(f"Piano: {plan.final_output.steps}")

    # Passaggio 2: Esegui con il piano come contesto
    execution_instructions = f"""Esegui i seguenti passaggi in ordine:
    {chr(10).join(f'{i+1}. {e}' for i, e in enumerate(plan.final_output.steps))}
    Obiettivo: {plan.final_output.objective}"""

    result = await Runner.run(executor_agent, execution_instructions)
    return result.final_output

Agente auto-correttivo

La pianificazione non basta: nel mondo reale, gli strumenti falliscono. La seconda forma di ciclo permette all’agente di rilevare i propri errori e correggerli. Tutto dipende da un dettaglio spesso trascurato: lo strumento non solleva un’eccezione, ma restituisce un messaggio di errore leggibile. L’agente lo legge, si rende conto di aver dimenticato la clausola FROM, riscrive la query e riprova, entro il limite di tre tentativi stabilito dalle sue istruzioni.

from agents import Agent, Runner, function_tool

@function_tool
def execute_sql_query(sql: str) -> str:
    """Esegue una query SQL sul database."""
    # Simulazione: alcune query falliscono
    if "DROP" in sql.upper():
        return "ERRORE: Le query distruttive sono vietate."
    if "SELECT" in sql.upper() and "FROM" not in sql.upper():
        return "ERRORE: Sintassi SQL non valida - manca FROM."
    return json.dumps({
        "columns": ["name", "monthly_revenue", "region"],
        "rows": [
            ["Acme Corp", 45000, "Île-de-France"],
            ["TechStart", 12000, "Rhône-Alpes"],
        ],
        "result_count": 2
    })

analyst_agent = Agent(
    name="Data Analyst",
    instructions="""Analizzi i dati eseguendo query SQL.
    Se una query fallisce:
    1. Analizza il messaggio di errore
    2. Correggi la query
    3. Riprova
    Massimo 3 tentativi per query.
    Non usare mai DROP, DELETE o TRUNCATE.""",
    tools=[execute_sql_query],
    model="gpt-5.6-terra",
    max_turns=10,  # Turni sufficienti per le correzioni
)

result = Runner.run_sync(
    analyst_agent,
    "Qual è il fatturato totale per regione?"
)

Nota che il divieto di query distruttive appare in due punti: nelle istruzioni e nel codice dello strumento. L’istruzione guida il modello, ma solo il controllo lato server nello strumento garantisce che un DROP TABLE non passi mai inosservato.

Pattern: catena di agenti specializzati

Per flussi di lavoro complessi, concatena diversi agenti specializzati invece di caricare un singolo agente di ogni responsabilità. Ogni anello ha un ruolo chiaro: il raccoglitore riunisce la materia prima, l’analista—dotato di un modello di ragionamento—identifica le tendenze e lo scrittore formatta l’output. Il vantaggio è sia didattico che operativo: quando il report finale delude, sai immediatamente quale dei tre agenti correggere.

from agents import Agent, Runner

collection_agent = Agent(
    name="Data Collector",
    instructions="Raccogli tutti i dati necessari per l'analisi.",
    tools=[search_crm, execute_sql_query],
    model="gpt-5.6-terra",
)

analysis_agent = Agent(
    name="Analyst",
    instructions="Analizza i dati raccolti e identifica le tendenze.",
    model="gpt-5.6-sol",  # Ragionamento avanzato per l'analisi
)

writing_agent = Agent(
    name="Writer",
    instructions="""Scrivi un report chiaro e strutturato in inglese
    basato sull'analisi fornita. Formato: introduzione, punti chiave, raccomandazioni.""",
    model="gpt-5.6-terra",
)

async def analysis_pipeline(question: str):
    # Passaggio 1: Raccogli dati
    data = await Runner.run(collection_agent, question)

    # Passaggio 2: Analizza
    analysis = await Runner.run(
        analysis_agent,
        f"Analizza questi dati: {data.final_output}"
    )

    # Passaggio 3: Scrivi il report
    report = await Runner.run(
        writing_agent,
        f"Scrivi un report basato su questa analisi: {analysis.final_output}"
    )

    return report.final_output

Controllo della profondità di ragionamento

Tutti questi cicli condividono una caratteristica: potrebbero non fermarsi mai. Il parametro max_turns è la tua principale salvaguardia e lo regoli in base all’ambizione del compito. Tre turni bastano per un agente che dovrebbe rispondere al primo tentativo; venticinque sono necessari per un’esplorazione che interroga più fonti prima di concludere.

# Agente conservativo: pochi turni
simple_agent = Agent(
    name="Simple Agent",
    instructions="Rispondi in un singolo turno se possibile.",
    model="gpt-5.6-terra",
)
result = await Runner.run(simple_agent, "Domanda semplice", max_turns=3)

# Agente complesso: molti turni
research_agent = Agent(
    name="Deep Researcher",
    instructions="Esplora tutti gli angoli prima di concludere.",
    tools=[search_crm, execute_sql_query],
    model="gpt-5.6-terra",
)
result = await Runner.run(research_agent, "Analisi completa Q1", max_turns=25)

Imposta questo valore osservando le tue tracce piuttosto che indovinare: se le tue esecuzioni reali terminano in sei turni, un limite di venticinque non protegge da nulla.

Punti chiave

  • Il pattern plan-execute separa la pianificazione (modello di ragionamento) dall’esecuzione
  • Un agente auto-correttivo analizza i propri errori e adatta la propria strategia
  • Le catene di agenti specializzati abilitano flussi di lavoro complessi e manutenibili
  • max_turns controlla la profondità del ragionamento e protegge dai loop infiniti
  • Riserva le capacità di ragionamento avanzato per la pianificazione e l’analisi