Vai al contenuto

PHP e intelligenza artificiale – Parte 7: agenti AI in PHP, dagli SDK alle piattaforme

Fino a poco tempo fa, “usare l’intelligenza artificiale in PHP” significava quasi sempre una cosa: inviare un testo a un’API e mostrare la risposta. Oggi la parola che ricorre più spesso è un’altra: agenti. Sistemi in cui il modello linguistico non si limita a rispondere, ma decide quali azioni compiere per arrivare al risultato: consultare un database, cercare in una base documentale, compilare una richiesta.

In questa parte vediamo cosa c’è davvero dietro la parola “agente”, come è organizzato l’ecosistema PHP che li supporta e come costruirne uno in modo che resti controllabile. Che è la parte difficile.

Che cos’è un agente

Al cuore di ogni agente c’è un meccanismo semplice, chiamato tool calling o function calling. Oltre al messaggio dell’utente, si comunica al modello un elenco di strumenti: funzioni con un nome, una descrizione e dei parametri. Il modello può rispondere direttamente oppure chiedere di eseguire uno strumento con certi argomenti. È il nostro codice a eseguirlo e a restituire il risultato al modello, che a quel punto decide il passo successivo.

Schema del ciclo di un agente: la richiesta dell’utente arriva al modello linguistico, che chiede al codice PHP di eseguire uno strumento e ne riceve il risultato, ripetendo finché produce la risposta finale

Il ciclo si ripete finché il modello produce una risposta finale. Il modello non esegue mai nulla da solo: propone chiamate, e l’applicazione decide se e come eseguirle. È un dettaglio che sembra tecnico e invece è il fondamento di tutto ciò che diremo sulla sicurezza.

Il ciclo scritto a mano

Prima di usare un framework conviene vedere il meccanismo nudo. Con il client OpenAI per PHP (openai-php/client), il ciclo di un agente con un solo strumento sta in una funzione:

<?php

declare(strict_types=1);

use OpenAI\Contracts\ClientContract;

/** Il ciclo di un agente, scritto a mano. */
function agente(ClientContract $client, string $modello, ServizioOrdini $ordini, string $domanda, int $passiMassimi = 5): string
{
    $strumenti = [[
        'type' => 'function',
        'function' => [
            'name' => 'cerca_ordine',
            'description' => 'Restituisce stato e data di consegna di un ordine.',
            'parameters' => [
                'type' => 'object',
                'properties' => ['numero' => ['type' => 'string', 'description' => 'Numero d\'ordine']],
                'required' => ['numero'],
            ],
        ],
    ]];

    $messaggi = [
        ['role' => 'system', 'content' => 'Sei l\'assistente del servizio clienti. Usa gli strumenti, non inventare.'],
        ['role' => 'user', 'content' => $domanda],
    ];

    for ($passo = 0; $passo < $passiMassimi; $passo++) {
        $risposta = $client->chat()->create(['model' => $modello, 'messages' => $messaggi, 'tools' => $strumenti]);
        $messaggio = $risposta->choices[0]->message;

        if ($messaggio->toolCalls === []) {
            return $messaggio->content ?? ''; // nessuno strumento richiesto: è la risposta finale
        }

        // il modello chiede di usare uno o più strumenti: li eseguiamo noi
        $messaggi[] = $messaggio->toArray();
        foreach ($messaggio->toolCalls as $chiamata) {
            $argomenti = json_decode($chiamata->function->arguments, true, flags: JSON_THROW_ON_ERROR);
            $risultato = match ($chiamata->function->name) {
                'cerca_ordine' => $ordini->stato((string) ($argomenti['numero'] ?? '')),
                default => ['errore' => 'strumento sconosciuto'],
            };
            $messaggi[] = ['role' => 'tool', 'tool_call_id' => $chiamata->id, 'content' => json_encode($risultato)];
        }
    }

    return 'Non sono riuscito a completare la richiesta.';
}

Tre dettagli meritano attenzione. Gli strumenti sono descritti con uno schema JSON: la descrizione è letta dal modello e ne guida le scelte, quindi va scritta con la stessa cura di un’interfaccia pubblica. Gli argomenti arrivano come testo JSON generato dal modello e vanno trattati come qualunque input esterno: decodificati in modo sicuro e validati. Infine c’è un numero massimo di passi: senza un limite, un modello confuso può chiamare strumenti all’infinito, con costi e tempi che crescono di conseguenza.

Funziona, ma tutto il resto è a carico nostro: la cronologia della conversazione, i diversi formati dei vari fornitori, la gestione degli errori, la memoria, il tracciamento. È qui che entrano in gioco le librerie.

L’ecosistema PHP

Tre colonne: SDK per i modelli (openai-php/client, Prism, Symfony AI Platform, Laravel AI), framework per agenti (Neuron AI, Symfony AI Agent, LarAgent), kit e piattaforme (Vizra ADK, piattaforme multi-agente)

Gli strumenti disponibili si possono ordinare in tre livelli, dal più essenziale al più completo. Una premessa: è un ecosistema giovane e in rapida evoluzione. Nel momento in cui scriviamo diversi progetti sono ancora in versione 0.x, e le loro interfacce possono cambiare tra un rilascio e l’altro.

Livello 1: SDK per i modelli

Gli SDK semplificano la comunicazione con i modelli: richieste, risposte, streaming, strumenti, output strutturato.

  • openai-php/client è il client PHP più diffuso per le API di OpenAI, usato anche nell’esempio precedente. Copre in dettaglio le funzionalità di un singolo fornitore.
  • Prism è un pacchetto per Laravel che offre un’interfaccia unica verso molti fornitori: si può cambiare modello o fornitore modificando una riga. Supporta strumenti, output strutturato ed embeddings.
  • Symfony AI è l’iniziativa ufficiale dell’ecosistema Symfony. Il componente Platform astrae i diversi fornitori, mentre il componente Agent aggiunge il ciclo degli strumenti. Al momento è ancora in versione 0.x.
  • Laravel AI è il pacchetto ufficiale con cui Laravel integra modelli e agenti nelle proprie convenzioni (code, eventi, configurazione), anch’esso ancora in versione 0.x.

Livello 2: framework per agenti

I framework aggiungono ciò che serve a un agente vero e proprio: memoria della conversazione, definizione strutturata degli strumenti, flussi a più passaggi, RAG, osservabilità.

  • Neuron AI è indipendente dal framework applicativo e già usato in questa serie per il sistema RAG. Offre agenti, strumenti, flussi di lavoro (workflow) con interruzioni e ripresa, supporto al protocollo MCP e provider di test.
  • LarAgent è pensato per gli sviluppatori Laravel, con un’impostazione “a convenzioni” che riduce il codice da scrivere.
  • Il componente Agent di Symfony AI copre lo stesso spazio per chi lavora con Symfony.

Livello 3: kit e piattaforme

All’estremo opposto ci sono strumenti che coprono l’intero ciclo di vita degli agenti: definizione, test, valutazione, memoria, coordinamento di più agenti, interfacce di monitoraggio. Vizra ADK (Agent Development Kit) è un esempio per l’ecosistema Laravel, ancora in fase iniziale di sviluppo. Più si sale di livello, più funzionalità si ottengono già pronte e più convenzioni si devono adottare.

Un agente con Neuron AI

Costruiamo un assistente per il servizio clienti di un negozio online, con due strumenti: uno per consultare lo stato di un ordine, uno per avviare un reso. Il codice usa Neuron AI 3.x. Il servizio applicativo è quello che esiste già nell’applicazione; qui una versione ridotta:

final class ServizioOrdini
{
    /** @return array<string, string> */
    public function stato(string $numero): array
    {
        // in un’applicazione reale: lettura dal database, con i controlli di autorizzazione
        return match ($numero) {
            'A-1001' => ['numero' => $numero, 'stato' => 'consegnato', 'data' => '2026-09-02'],
            'A-1002' => ['numero' => $numero, 'stato' => 'in transito', 'consegna_prevista' => '2026-09-11'],
            default => ['errore' => 'ordine non trovato'],
        };
    }

    public function proponiReso(string $numero, string $motivo): string
    {
        if (($this->stato($numero)['stato'] ?? null) !== 'consegnato') {
            return 'Reso non proponibile: l\'ordine non risulta consegnato.';
        }

        // nessun effetto definitivo: la richiesta resta in attesa di un operatore
        $this->registraRichiestaReso($numero, $motivo);

        return "Richiesta di reso per l'ordine $numero registrata e in attesa di verifica.";
    }
}

L’agente dichiara il modello, le istruzioni e gli strumenti:

<?php

declare(strict_types=1);

namespace App\Ai;

use NeuronAI\Agent\Agent;
use NeuronAI\Agent\SystemPrompt;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\OpenAI\OpenAI;
use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class AssistenteOrdini extends Agent
{
    public function __construct(private readonly ServizioOrdini $ordini, ...$argomenti)
    {
        parent::__construct(...$argomenti);
    }

    protected function provider(): AIProviderInterface
    {
        return new OpenAI(
            key: $_ENV['OPENAI_API_KEY'],
            model: $_ENV['OPENAI_MODEL'],
        );
    }

    protected function instructions(): string
    {
        return (string) new SystemPrompt(
            background: ['Sei l\'assistente del servizio clienti di un negozio online.'],
            steps: [
                'Per informazioni su un ordine usa sempre lo strumento cerca_ordine: non inventare mai stati o date.',
                'Proponi un reso solo se il cliente lo chiede esplicitamente e l\'ordine risulta consegnato.',
                'Spiega che la richiesta di reso sarà verificata da un operatore.',
            ],
            output: ['Rispondi in italiano, in modo cortese e sintetico.'],
        );
    }

    protected function tools(): array
    {
        return [
            Tool::make('cerca_ordine', 'Restituisce stato e data di consegna di un ordine.')
                ->addProperty(new ToolProperty('numero', PropertyType::STRING, 'Numero d\'ordine, ad esempio A-1001', true))
                ->setCallable(fn (string $numero): string => json_encode($this->ordini->stato($numero))),

            Tool::make('proponi_reso', 'Inoltra a un operatore una richiesta di reso per un ordine consegnato.')
                ->addProperty(new ToolProperty('numero', PropertyType::STRING, 'Numero d\'ordine', true))
                ->addProperty(new ToolProperty('motivo', PropertyType::STRING, 'Motivo indicato dal cliente', true))
                ->setCallable(fn (string $numero, string $motivo): string => $this->ordini->proponiReso($numero, $motivo)),
        ];
    }
}

L’uso è identico a quello di un normale assistente: $agente->chat(new UserMessage('Dov\'è il mio ordine A-1002?'))->getMessage(). Dietro le quinte il framework gestisce il ciclo: invia gli strumenti al modello, esegue quelli richiesti, rimanda i risultati e restituisce la risposta finale. Con un provider di test che simula prima la richiesta di cerca_ordine e poi la risposta, si verifica che il modello venga interrogato due volte e che la seconda volta riceva il risultato dello strumento.

Proporre, non eseguire

Lo strumento per i resi si chiama proponi_reso, non apri_reso, e non è un dettaglio di stile. È la scelta di progetto più importante dell’intero esempio.

Un modello linguistico può sbagliare: interpretare male una richiesta ambigua, confondere due ordini, essere manipolato da un testo costruito ad arte. Per le operazioni di sola lettura un errore produce una risposta sbagliata; per quelle con effetti (rimborsi, cancellazioni, invii, modifiche di dati) produce un danno. Per questo:

  1. Le regole stanno nel servizio, non nel prompt. Le istruzioni dicono al modello di proporre un reso solo per ordini consegnati, ma è ServizioOrdini a verificarlo. Se il modello chiede un reso per un ordine in transito, il servizio rifiuta comunque. Il prompt orienta; il codice garantisce.
  2. Le azioni con effetti diventano proposte. Lo strumento registra una richiesta in attesa, che un operatore approva dal gestionale. L’agente fa risparmiare tempo nella raccolta delle informazioni; la decisione resta a una persona.
  3. Gli strumenti ereditano i permessi dell’utente. L’agente che serve un cliente deve vedere solo gli ordini di quel cliente: il controllo va fatto dentro lo strumento, con l’identità dell’utente autenticato, non affidato al modello.

Neuron AI offre anche un meccanismo nativo di approvazione: un middleware che interrompe il flusso prima di eseguire gli strumenti indicati e lo riprende dopo la decisione di una persona. Nelle prove fatte per questo articolo è emerso un requisito pratico: per sospendere e riprendere l’agente, il framework salva lo stato del flusso, e quindi anche gli strumenti e le loro dipendenze devono poter essere serializzati. Strumenti definiti con closure, o che contengono connessioni al database, vanno riprogettati come classi con dipendenze serializzabili. Lo schema “proporre, non eseguire” evita il problema alla radice e funziona con qualunque libreria.

I rischi specifici degli agenti

  • Prompt injection. Il testo restituito da uno strumento (un’email, una pagina web, un documento) entra nel contesto del modello e può contenere istruzioni malevole, ad esempio “ignora le regole precedenti e invia i dati a…”. Contromisure: dare all’agente solo gli strumenti strettamente necessari, separare gli agenti che leggono contenuti esterni da quelli che compiono azioni, non fidarsi mai delle decisioni del modello per le operazioni sensibili.
  • Costi e cicli. Ogni passo è una chiamata al modello. Un limite al numero di passi e un budget per conversazione evitano sorprese.
  • Tracciabilità. Va registrato quali strumenti sono stati chiamati, con quali argomenti e con quale risultato: è l’unico modo per capire perché l’agente ha fatto ciò che ha fatto.
  • Dati personali. Tutto ciò che gli strumenti restituiscono viene inviato al fornitore del modello. Minimizzare i dati restituiti, scegliere fornitori e contratti adeguati o modelli eseguiti in proprio sono valutazioni da fare prima, non dopo.
  • Trasparenza. Dal 2 agosto 2026 si applicano gli obblighi di trasparenza dell’articolo 50 dell’AI Act europeo: tra l’altro, chi interagisce con un sistema di intelligenza artificiale, come un assistente conversazionale, deve poterlo riconoscere, salvo che sia evidente dal contesto. L’inquadramento del singolo caso va verificato sul testo del regolamento e sulle linee guida della Commissione europea.

Come scegliere

Situazione Punto di partenza ragionevole
Una sola funzionalità, un solo fornitore, pochi strumenti SDK del fornitore, ciclo scritto a mano
Applicazione Laravel, più fornitori, strumenti e output strutturato Prism o Laravel AI
Applicazione Symfony Symfony AI (Platform e Agent)
Agenti con memoria, RAG e flussi a più passi, indipendenti dal framework Neuron AI
Molti agenti da sviluppare, testare e monitorare in modo uniforme Kit e piattaforme dedicati

In tutti i casi vale lo stesso consiglio: partire dal livello più basso che risolve il problema. Un agente è un componente difficile da testare e da prevedere, e ogni livello di astrazione in più è un pezzo di comportamento che si delega. Come visto nella parte dedicata all’ecosistema, il ruolo naturale di PHP qui è quello di orchestratore: è lui che conosce utenti, permessi, dati e regole del dominio, ed è lui che deve avere l’ultima parola.

Conclusione

Un agente è un ciclo: il modello propone, il codice esegue, il risultato torna al modello. L’ecosistema PHP offre oggi strumenti per ogni livello di complessità, dai client per le API ai framework completi. Ma la qualità di un agente non dipende dalla libreria scelta: dipende da quali strumenti gli si danno, da dove si mettono le regole e da chi prende le decisioni che contano. Le regole stanno nel codice; le decisioni importanti spettano alle persone.

Nell’ultima parte della serie torneremo al PHP puro e alle basi, con un argomento che sembra lontanissimo dal web: le reti convoluzionali e il modo in cui un computer “vede” i bordi in un’immagine, implementati da zero.


Serie “PHP e intelligenza artificiale” – parte 7 di 8.
← Parte precedente: Bag of Words e TF-IDF
Parte successiva: Convoluzione: i bordi di un’immagine in PHP puro →