Quando i “visitatori” non sono più persone: progettare esperienze per AI agent

Negli ultimi mesi sta diventando evidente un cambio di paradigma: una quota crescente delle interazioni con prodotti e piattaforme web non arriva da persone che cliccano una UI, ma da AI agent e automazioni che consumano API, CLI e documentazione.

Questo non è solo un tema “di backend”. Impatta direttamente anche chi fa frontend e product engineering, perché modifica:

• come progettiamo funzionalità (prima l’automazione, poi la UI)
• come misuriamo l’adozione (azioni eseguite via API/CLI, non solo eventi UI)
• come curiamo la DX (documentazione, esempi, stabilità contrattuale)
• come difendiamo la piattaforma (rate limit, audit, identità macchina)

Dalla UI come centro del prodotto alla UI come “vista” di un’API

Per anni l’assunto implicito è stato: l’utente entra in dashboard, clicca, configura, salva. Oggi sempre più flussi diventano:

1. un agente legge lo stato (API)
2. decide una modifica
3. la applica (API o CLI)
4. verifica (API)

La UI non sparisce, ma cambia ruolo: diventa uno dei client dell’API, spesso il più “umano”, non necessariamente il più usato.

Conseguenza pratica

Quando una feature nasce con solo una schermata, manca la domanda fondamentale: come la usa un agente?

• Esiste un endpoint o un comando CLI per farla?
• È idempotente e automatizzabile?
• È osservabile (log/audit) e sicura (permessi granulari)?

Se la risposta non è “sì”, la feature è incompleta.

Un criterio semplice: “API/CLI-first”

Un modo pragmatico di impostare il lavoro è questo:

1. Definisci l’operazione come contratto (API): input, output, errori, limiti
2. Esponila via CLI (anche minima): deve essere scriptabile
3. Costruisci la UI come client: la dashboard è una comoda rappresentazione

Questo approccio ha due vantaggi immediati:

• riduce il rischio di creare UI bellissime ma non automatizzabili
• obbliga a chiarire casi limite e stati (spesso ignorati nelle sole interfacce)

UX per agenti: non è “meno UX”, è un’altra UX

Un agente non “si perde” in un form, ma fallisce su:

• errori non deterministici
• messaggi poco strutturati
• assenza di codici errore stabili
• risposte non versionate
• side effect impliciti

Linee guida utili

• Errori strutturati: codici, messaggi brevi, dettagli machine-readable
• Idempotenza: PUT/DELETE e operazioni ripetibili senza effetti collaterali
• Dry-run e preview: eseguire e vedere cosa cambierebbe prima di applicare
• Rate limit espliciti: header chiari, backoff suggerito
• Versioning: compatibilità nel tempo (gli agenti “ricordano” contratti)

Documentazione: da “guida” a superficie di prodotto

Se gli agenti consumano API e CLI, la documentazione non è più un allegato: è parte dell’esperienza.

Cosa conviene trattare come first-class:

• esempi completi copiabili (curl, node, python)
• snippet CLI con output realistico
• descrizione di errori comuni e recovery
• changelog e deprecazioni con migrazioni chiare

Un buon segnale di qualità: uno script scritto in 10 minuti riesce a fare ciò che la dashboard permette di fare in 10 click.

Osservabilità e audit: quando l’utente è una macchina

Con più azioni automatiche, cresce il bisogno di capire chi ha fatto cosa e perché.

Checklist essenziale:

• audit log consultabile e filtrabile (anche via API)
• tracciamento di token/identità macchina (agent, integrazione, CI)
• correlazione tra chiamate (request id) e impatto (risorse modificate)
• possibilità di revocare rapidamente credenziali e limitare permessi

Per un frontend team, questo spesso significa costruire viste di audit e strumenti di debug interni… ma guidati da dati affidabili a monte.

Come cambia il lavoro del frontend

Anche se l’agente non “vede” la UI, il frontend diventa più importante in tre punti:

1. Dashboard come strumento di ispezione: osservare stato, confrontare configurazioni, diagnosticare problemi
2. Design system per azioni ad alto rischio: conferme, rollback, preview, cronologia modifiche
3. Coerenza UI/API: la UI non deve poter fare cose che l’API non può fare (e viceversa)

Un buon pattern è costruire la UI solo su endpoint pubblici (o equivalenti interni). Se devi “barare” con un endpoint nascosto per far funzionare la dashboard, è probabile che stai creando un vicolo cieco per automazioni e agenti.

Un test finale per ogni feature

Prima di considerare “finita” una funzionalità, prova a rispondere a queste domande:

• Posso completare l’operazione via CLI in modo scriptabile?
• Esiste un’API chiara, documentata e stabile?
• Gli errori sono gestibili da una macchina (codici, retry, limiti)?
• È tracciabile e sicura (audit, permessi, revoche)?
• La UI è semplicemente un client ben fatto di quel contratto?

Se sì, stai progettando per il presente: un web dove, sempre più spesso, il “next click” non lo fa una persona, ma un agente.