Automatizza i flussi di lavoro multi-step
In questa pagina
Lezione aggiornata il 3 novembre 2026 secondo le linee guida di integrazione Computer Use di OpenAI: l’agente non gestisce più il login; la convalida dei comandi e i rami che impegnano l’utente (recensioni, nuovi ordini) richiedono conferma umana; l’orchestratore ora verifica il criterio
success_text_containsche precedentemente ignorava, segnala i passaggi falliti invece di saltarli e non ripete mai un passaggio che crea dati. Fonte: Confirmation and consent.
Orchestrare compiti complessi
I flussi di lavoro reali consistono raramente in una singola azione. Popolare un CRM implica navigare tra pagine, trovare un contatto, aggiornarne le informazioni e quindi creare un’opportunità: quattro operazioni concatenate, ognuna delle quali può fallire per motivi propri. Affidare tutto questo blocco a un agente in un singolo prompt funziona a volte, ma non saprai mai dove si è verificato il guasto. Questa lezione ti insegna a strutturare queste automazioni multi-step in modo che ogni anello sia osservabile e ripetibile.
Architettura basata su passaggi
Inizia suddividendo il flusso di lavoro in passaggi atomici, ognuno con un obiettivo chiaro e un criterio di successo. Questo criterio è ciò che distingue una lista di cose da fare da un vero flusso di lavoro: senza di esso, il tuo orchestratore non può dire se l’agente ha effettivamente avuto successo o si è fermato su una pagina di errore. Nell’esempio seguente, l’apertura del modulo è verificata dall’URL e la ricerca dalla presenza del nome del contatto sullo schermo. Il login non è incluso qui: il tuo codice lo ha gestito in precedenza, senza esporre la password al modello (Lezione 8). Il passaggio finale ha "retry": False perché crea dati: ripeterlo dopo un fallimento parziale potrebbe creare un duplicato.
workflow = [
{
"name": "open_contacts",
"task": "Open the Contacts module in the CRM.",
"success_url_contains": "/contacts",
},
{
"name": "search_contact",
"task": "Search for contact 'Jean Dupont' in the search bar.",
"success_text_contains": "Jean Dupont",
},
{
"name": "update_record",
"task": "Open Jean Dupont's profile and update their phone number: 06 98 76 54 32.",
},
{
"name": "create_opportunity",
"task": "Create an opportunity: 'Cloud Migration Q2 2026', amount 50000 EUR, probability 60%.",
"retry": False, # non-replayable step: creates data
},
]
L’orchestratore
Ora devi eseguire questa lista. L’orchestratore percorre i passaggi in sequenza, avvolgendo ciascuno in un ciclo di retry: un passaggio che solleva un’eccezione o non soddisfa il suo criterio di successo viene ritentato fino a max_retries volte, a meno che non sia contrassegnato come non ripetibile. Questo dettaglio conta in produzione, perché molti fallimenti degli agenti visivi sono transitori: una pagina lenta, un rendering incompleto al momento dello screenshot. Un passaggio che fallisce definitivamente interrompe il flusso di lavoro, poiché i passaggi successivi dipendono da esso. Infine, l’orchestratore restituisce un log strutturato che indica, per ogni passaggio, il suo stato e il numero di tentativi consumati: il tuo primo strumento di diagnosi.
def run_workflow(workflow: list, page, max_retries: int = 2):
"""Executes a multi-step workflow with retries."""
results = []
for step in workflow:
step_name = step["name"]
print(f"\n--- Step: {step_name} ---")
attempts = max_retries + 1 if step.get("retry", True) else 1
error = "success criterion not met"
for attempt in range(attempts):
try:
run_agent(step["task"], page=page)
# Optional checks: URL, then visible text
url_check = step.get("success_url_contains")
if url_check and url_check not in page.url:
print(" Expected URL not found")
continue
text_check = step.get("success_text_contains")
if text_check and text_check not in page.locator("body").inner_text():
print(" Expected text not found")
continue
print(f" Success (attempt {attempt + 1})")
results.append({"step": step_name, "status": "success", "attempts": attempt + 1})
break
except Exception as e:
print(f" Error: {e}")
error = str(e)
else:
# No attempt succeeded: subsequent steps depend on this one
results.append({"step": step_name, "status": "failed", "error": error})
break
return results
Passare dati tra i passaggi
Spesso, un passaggio produce dati necessari per il successivo: il prezzo letto su una pagina del carrello deve essere verificato al passaggio di checkout; il numero di caso creato nel passaggio 2 serve come riferimento nel passaggio 5. Un contesto condiviso risolve questa esigenza senza trasformare il tuo codice in un groviglio di variabili globali. L’esempio seguente si ferma intenzionalmente prima del pagamento: OpenAI classifica la conferma di una transazione finanziaria come un’azione che richiede la validazione dell’utente al momento dell’esecuzione. La classe sottostante memorizza coppie chiave-valore ed espone un metodo inject che sostituisce i marcatori {key} in un template di prompt, permettendoti di scrivere i tuoi compiti come template parametrizzati.
class WorkflowContext:
"""Stores data shared between steps."""
def __init__(self):
self.data = {}
def set(self, key: str, value):
self.data[key] = value
def get(self, key: str, default=None):
return self.data.get(key, default)
def inject(self, template: str) -> str:
"""Replaces {key} variables in the template."""
task = template
for key, value in self.data.items():
task = task.replace("{" + key + "}", str(value))
return task
# Usage example
ctx = WorkflowContext()
# Step 1: agent reads a price
extracted_price = run_agent(
"Read the total price displayed and return only the number.",
page=page
)
ctx.set("price", extracted_price.strip())
# Step 2: agent verifies, without validating anything
verdict = run_agent(ctx.inject(
"The expected amount is {price} EUR. Compare it to the total on the payment page "
"and answer only OK or MISMATCH. Do not validate anything."
), page=page)
# Step 3: a transaction is confirmed at the moment of action, by a human
if verdict.strip() == "OK":
if input(f"Confirm order for {ctx.get('price')} EUR? [y/N] ").strip().lower() == "y":
run_agent("Click the order confirmation button.", page=page)
Flussi di lavoro condizionali
Le sequenze lineari raggiungono rapidamente i loro limiti, perché il passaggio successivo può dipendere dal risultato precedente. Il pattern da ricordare è questo: chiedi prima all’agente di leggere uno stato costringendolo a rispondere con un valore da un insieme chiuso, poi diramati in Python. Per il tracciamento degli ordini, uno stato “in elaborazione” porta al tracciamento del pacco, “consegnato” al recupero della data di consegna, “annullato” al recupero del motivo. I vincoli di formato nel prompt sono essenziali: senza di essi, l’agente restituisce una frase che i tuoi confronti mancheranno regolarmente. Tutti e tre i rami rimangono in sola lettura: pubblicare una recensione o riordinare impegnerebbe l’utente e richiederebbe la sua conferma.
def conditional_workflow(page):
"""Workflow with conditional branching."""
# Step 1: Read status
status = run_agent(
"Read the order status. "
"Return only: processing, delivered, or canceled.",
page=page
)
# Branch based on result
match status.strip().lower():
case "processing":
return run_agent("Click 'Track package' and note the displayed stage.", page=page)
case "delivered":
return run_agent("Note the displayed delivery date.", page=page)
case "canceled":
return run_agent("Note the displayed cancellation reason.", page=page)
case _:
raise ValueError(f"Unexpected status: {status!r}")
Parallelizzazione
Quando i compiti sono indipendenti, non c’è bisogno di elaborarli in sequenza. Estrarre dati da tre schede prodotto richiede molto meno tempo se tre agenti lavorano simultaneamente, ognuno nella sua scheda. La versione async di Playwright e asyncio.gather sono sufficienti: una coroutine per URL, una new_page per coroutine e chiusura sistematica della pagina per evitare di accumulare schede in memoria. run_agent_async è il ciclo della Lezione 4 riscritto con il client AsyncOpenAI e l’API async di Playwright: la stessa logica, con await prima di ogni chiamata. Tieni presente che il parallelismo moltiplica anche il throughput delle tue chiamate API, aumentando il rischio di raggiungere i tuoi limiti di frequenza (Lezione 11) e il carico sul sito di destinazione: tre schede passano inosservate, cinquanta molto meno.
import asyncio
from playwright.async_api import async_playwright
async def parallel_extraction(urls: list[str]):
"""Extracts data from multiple pages in parallel."""
async with async_playwright() as pw:
browser = await pw.chromium.launch(headless=True)
async def extract_one(url: str):
page = await browser.new_page(
viewport={"width": 1280, "height": 720}
)
try:
await page.goto(url)
result = await run_agent_async(
"Extract the product title and price.", page=page
)
finally:
await page.close()
return {"url": url, "data": result}
results = await asyncio.gather(
*[extract_one(url) for url in urls]
)
return results
# Run
urls = [
"https://shop.example.com/product/1",
"https://shop.example.com/product/2",
"https://shop.example.com/product/3",
]
data = asyncio.run(parallel_extraction(urls))
Punti chiave
- Suddividi i flussi di lavoro in passaggi atomici con criteri di successo espliciti
- Ripeti automaticamente i passaggi che possono essere ritentati in sicurezza, mai quelli che creano dati
- Usa un contesto condiviso per passare dati tra i passaggi
- I flussi di lavoro condizionali si adattano al contenuto della pagina; i rami che impegnano l’utente richiedono la sua conferma
- Parallelizza i compiti indipendenti per risparmiare tempo