Chiedi a un chatbot di un ordine in ritardo e ti darà qualche consiglio. Chiedi a un agente AI e lui potrà cercare l’ordine, verificare il ritardo, applicare un voucher e riferire. La differenza è che un agente può intraprendere azioni e reagire a ciò che accade, invece di produrre una sola risposta.

Il termine viene esteso nel marketing, quindi questa guida si concentra su come funzionano effettivamente questi sistemi. Per renderlo concreto, abbiamo creato un piccolo loop agente in Python 3.13 e lo abbiamo eseguito, e l’output seguente proviene da quelle esecuzioni. Il nostro “modello” è una funzione basata su script, non un vero modello di intelligenza artificiale, in modo che il ciclo possa essere eseguito e testato da chiunque. Mostra la struttura di controllo, non l’intelligenza. Nuovo alle basi? Leggi prima cos’è un modello linguistico ampio.

Cos’è un agente AI?

Non esiste una definizione unica concordata. Nella pratica attuale, un agente AI è un software che persegue un obiettivo decidendo ripetutamente cosa fare dopo, utilizzando strumenti per agire sul mondo e adattandosi in base ai risultati. Di solito, il processo decisionale deriva da un ampio modello linguistico.

Pensa alla differenza tra una persona che dà indicazioni e una persona che fa la commissione. I primi rispondono una volta. Il secondo esce, trova il negozio chiuso, ne prova un altro e torna solo a lavoro finito.

Chatbot, flusso di lavoro o agente?

Questi esistono su uno spettro e molti sistemi utili sono un mix. La domanda chiave è quanto del percorso viene deciso in fase di esecuzione.

Cosa c’è dentro un agente

Il ciclo dell’agente

1. Decidi. Il modello guarda l’obiettivo e la storia e sceglie un’azione o decide che è terminata.
2. Act. Il tuo codice esegue lo strumento richiesto.
3. Osserva. Il risultato viene aggiunto alla cronologia.
4. Ripeti finché non viene raggiunto l’obiettivo o un limite.

Questo è il nocciolo della maggior parte degli agenti. La sofisticazione risiede principalmente nel modello, negli strumenti e nelle garanzie attorno a questo circuito.

Un ciclo che puoi eseguire

Il nostro piccolo agente gestisce gli ordini in ritardo. Ha due strumenti e uno di questi necessita dell’approvazione umana perché costa denaro:

ORDERS = {
    "A100": {"status": "delayed", "days_late": 6},
    "B200": {"status": "shipped", "days_late": 0},
}

def get_order(order_id):
    return ORDERS.get(order_id, {"error": "order not found"})

def issue_voucher(order_id, amount):
    return {"voucher": f"V-{order_id}", "amount": amount}

TOOLS = {"get_order": get_order, "issue_voucher": issue_voucher}
NEEDS_APPROVAL = {"issue_voucher"}

Ed ecco il loop stesso. È un codice ordinario e ogni regola di sicurezza risiede qui piuttosto che nel modello:

def run_agent(goal, model, approve, max_steps=5):
    history = []
    for step in range(1, max_steps + 1):
        decision = model(goal, history)
        if "finish" in decision:
            return decision["finish"]

        name, args = decision["tool"], decision["args"]
        if name in NEEDS_APPROVAL and not approve(name, args):
            result = {"denied": True}
        else:
            result = TOOLS[name](**args)

        history.append({"tool": name, "result": result})
    return None   # stopped: step limit reached

Per utilizzare un modello reale, sostituiresti la funzione model con una chiamata a un’API LLM, passandole l’obiettivo, la cronologia e le descrizioni dei tuoi strumenti. Il ciclo rimane quasi lo stesso.

Cosa è successo durante le nostre corse

Abbiamo provato cinque situazioni con la funzione decisionale basata su script e registrato ogni passaggio.

Un ordine in ritardo, con il buono approvato

step 1: get_order({'order_id': 'A100'}) -> {'status': 'delayed', 'days_late': 6}
step 2: issue_voucher({'order_id': 'A100', 'amount': 200}) -> {'voucher': 'V-A100', 'amount': 200}
step 3: finish -> Sorry for the delay. Voucher V-A100 issued.

Ogni passaggio utilizzava il risultato di quello precedente. Il voucher è stato preso in considerazione solo una volta confermato il ritardo.

Lo stesso ordine, con l’approvazione negata

step 2: issue_voucher({'order_id': 'A100', 'amount': 200}) -> {'denied': True}
step 3: finish -> Your order is late. A person will review compensation.

L’umano ha detto di no, lo strumento non è mai stato eseguito e l’agente ha adattato la sua risposta.

Un ordine sconosciuto

step 1: get_order({'order_id': 'Z999'}) -> {'error': 'order not found'}
step 2: finish -> I could not find that order.

Fornire agli strumenti messaggi di errore chiari aiuta. Un vero modello può leggerli e rispondere in modo sensato, piuttosto che indovinare.

Un modello che si incastra

Abbiamo anche inserito una funzione decisionale errata che ripeteva la stessa azione per sempre:

step 1: get_order({'order_id': 'B200'}) -> {'status': 'shipped', 'days_late': 0}
step 2: get_order({'order_id': 'B200'}) -> {'status': 'shipped', 'days_late': 0}
step 3: get_order({'order_id': 'B200'}) -> {'status': 'shipped', 'days_late': 0}
stopped: step limit reached

Gli agenti possono davvero cadere in circuiti come questo e ogni passaggio con un modello reale costa denaro. Senza max_steps, questo non sarebbe mai finito.

Come funzionano gli strumenti

Questa è la parte più fraintesa. Un modello linguistico non può eseguire nulla da solo. Produce un testo strutturato che indica quale strumento desidera, con quali argomenti. Il tuo codice decide se eseguirlo. Ecco perché il ciclo è il posto giusto per autorizzazioni, convalida e registrazione.

I fornitori di modelli offrono strumenti o funzioni che lo richiedono. Il Model Context Protocol (MCP) è uno standard aperto per connettere modelli a strumenti e dati e il nostro articolo su Playwright MCP ne mostra un utilizzo. Scrivi nomi e descrizioni chiari degli strumenti, perché il modello fa affidamento su di essi per scegliere correttamente.

Memoria

Le attività lunghe possono superare la finestra di contesto di un modello, quindi i sistemi spesso riepilogano i passaggi più vecchi. I riepiloghi possono perdere dettagli, il che è uno dei motivi per cui gli agenti con esecuzione prolungata potrebbero deviare dal percorso.

Sistemi multiagente

Alcuni sistemi dividono il lavoro tra diversi agenti specializzati, come un pianificatore, un ricercatore e un revisore. Questo può aiutare con compiti di grandi dimensioni che si dividono ordinatamente. Inoltre aggiunge costi, più modi per fallire e un debug più difficile. Prova prima un singolo agente con buoni strumenti e dividilo solo quando c’è un motivo chiaro.

Rischi e limiti

• Azioni sbagliate. L’errore di un chatbot è una brutta frase. L’errore di un agente potrebbe essere un’e-mail inviata o un record eliminato.
• Iniezione rapida. Una pagina web o un’e-mail letta dall’agente potrebbe contenere istruzioni nascoste. Tratta tutti gli output dello strumento come dati non attendibili, non come comandi.
• Errori cumulativi. Un piccolo errore nella fase iniziale può indirizzare ogni passaggio successivo nella direzione sbagliata.
• Costo e latenza. Ogni passaggio può essere un’altra chiamata al modello, quindi un’attività potrebbe essere molto più lenta e costosa di un singolo prompt.
• Incoerenza. Lo stesso obiettivo può prendere un percorso diverso in ogni esecuzione, il che rende i test più difficili.
• Responsabilità. Le persone rimangono responsabili di ciò che fa il sistema, quindi tieni i registri.

Guardrail che contano

1. Privilegio minimo. Fornisci a ciascun agente solo gli strumenti e l’accesso di cui ha bisogno.
2. Approvazione umana per qualsiasi cosa costosa, irreversibile o esterna, come fa la nostra demo.
3. Limiti rigidi su passaggi, tempo e spesa.
4. Convalida gli input dello strumento nel codice e non fare affidamento sulle istruzioni del modello.
5. Registra ogni passaggio, in modo da poter vedere perché è successo qualcosa. Vedi monitoraggio vs osservabilità.
6. Test con scenari reali, compresi i guasti. Controllare i risultati finali e le risposte individuali. La nostra guida alle best practice per gli agenti AI va oltre l’implementazione.

Quando utilizzare un agente

Gli assistenti di codifica sono uno degli esempi più maturi oggi, poiché possono leggere file, eseguire test, vedere gli errori e riprovare, con un essere umano che rivede il risultato. Una suite di test dà loro un chiaro segnale di successo. La nostra guida al prompt engineering si applica anche alla scrittura di istruzioni valide per l’agente. Inizia con la cosa più semplice che potrebbe funzionare, perché una singola chiamata ben motivata spesso batte un agente complicato.

Considerazioni finali

Un agente AI è meno misterioso di quanto sembri: un modello, alcuni strumenti e un circuito con limiti. La parte difficile è la fiducia, non il codice. Per scoprire come si comportano, prendi il nostro piccolo loop, collegalo a un modello reale con strumenti di sola lettura e osserva i log mentre funziona. Presto vedrai dove brilla e dove ha bisogno di un essere umano.

Domande frequenti

Continua a imparare