Come scrivere la scheda di capacità di un assistente AI

La prima riga può dire: cerca procedure approvate e risponde con la fonte. La seconda deve dire: non autorizza eccezioni e non agisce sui sistemi.

Se manca la seconda, non hai una scheda di capacità. Hai una brochure.

Una scheda utile spiega il lavoro ammesso dell'intero assistente AI: quali richieste accetta, su quali fonti lavora, cosa produce, quali azioni può avviare, quali prove ha superato e dove si ferma. Il nome del modello resta un dato di versione. Non è la risposta alla domanda che interessa a chi lo usa: posso affidargli questo compito?

Il paper Model Cards ha reso comune un principio semplice: chi rilascia un modello dovrebbe dichiarare usi previsti, condizioni di valutazione, prestazioni e limiti. Per un assistente aziendale serve un passo in più. Il comportamento nasce da modello, prompt, retrieval, tool, permessi e regole operative. La scheda deve descrivere quell'insieme.

Parti dal lavoro ammesso, non dal modello

Usa un LLM avanzato non dice cosa può fare l'assistente. Nemmeno assistente per il customer care basta: il customer care comprende ricerca, classificazione, scrittura, decisioni, rimborsi, modifiche all'account e comunicazioni verso una persona reale.

Scrivi il lavoro come una coppia di confini:

purpose: aiutare il supporto a trovare procedure approvate
allowed_tasks:
  - cercare una procedura per prodotto e paese
  - riassumere i passaggi con citazioni
  - preparare una bozza di risposta
forbidden_tasks:
  - approvare rimborsi
  - cambiare dati dell'account
  - interpretare eccezioni contrattuali
  - inviare la risposta al cliente

Il registro dei workflow AI ti aiuta a sapere quali sistemi esistono, chi li possiede e in quale stato si trovano. La scheda di capacità scende sul singolo assistente e traduce quel record per chi deve usarlo o approvarlo.

NIST suggerisce di chiarire scopo, utenti, contesto, assunzioni e limiti. Fallo prima di elencare le funzioni. La stessa ricerca può essere adatta a una persona del supporto e vietata a un utente esterno, perché cambiano fonti accessibili, conseguenze e possibilità di verifica.

Descrivi il sistema intero

Un assistente non coincide con il modello. Registra almeno questi componenti:

Non serve pubblicare prompt, credenziali o architettura sensibile. Serve un identificatore che permetta al team di risalire alla configurazione esatta. Assistente supporto v3 è leggibile. Dietro deve puntare a un manifest immutabile.

La scheda rivolta agli utenti può restare breve. Il registro tecnico conserva hash, dipendenze e ricevute. Due livelli, stessa versione.

Separa capacità dichiarata e capacità provata

Sa rispondere sulle procedure è un claim. Per diventare una capacità deve avere un test, un contesto e un esito.

Il profilo NIST GenAI raccomanda di valutare empiricamente i claim di capacità. Tradotto nel lavoro quotidiano: ogni riga importante della scheda punta a casi eseguiti, non a una demo scelta perché riuscita bene.

Usa tre stati semplici:

Non provata non significa per forza impossibile. Significa che l'organizzazione non ha ancora una prova sufficiente per prometterla. È una distinzione poco spettacolare e molto utile.

Lega ogni capacità a una prova

La tabella centrale della scheda ha quattro colonne: capacità, prova, limite, comportamento davanti al limite.

I numeri nell'esempio sono fittizi. Nella scheda reale derivano dalla suite di test e hanno una data.

La checklist per verificare un output AI aiuta a controllare una singola risposta. La scheda raccoglie ciò che quei controlli hanno dimostrato su una versione e rende visibile il confine a chi lavorerà domani.

Non usare una media per assorbire un difetto bloccante. Se 99 risposte sono corrette e una invia un rimborso non autorizzato, la capacità di gestire rimborsi non è verde. Quel caso definisce il confine.

Scrivi input, output e azioni con verbi precisi

Le parole gestisce, supporta e automatizza nascondono troppo. Sostituiscile con verbi osservabili.

Legge non è modifica. Propone non è approva. Prepara non è invia.

Per ogni funzione, indica:

• quali input accetta e da dove arrivano

• quale output restituisce

• se l'output è bozza, consiglio o azione

• chi conferma l'eventuale conseguenza all'esterno

• quale ricevuta resta dopo l'azione

Questa precisione evita il salto più pericoloso: una persona prova un assistente in sola lettura, vede che risponde bene e presume che possa anche scrivere sul CRM. La qualità della risposta non prova la sicurezza dell'azione.

Metti il limite accanto alla capacità

Una sezione Limitazioni in fondo viene letta una volta. Il limite deve comparire vicino all'uso che riguarda.

Esempio:

Può confrontare due procedure approvate e indicare le differenze con citazioni. Non decide quale procedura prevale quando entrambe risultano valide: segnala il conflitto al knowledge owner.

Il limite dice dove si rompe il lavoro e cosa succede dopo. Può commettere errori è vero per qualunque assistente e quindi non aiuta. Può saltare note dentro tabelle acquisite via OCR orienta test, uso e review.

Dichiara anche i contesti esclusi: lingue non provate, documenti senza data, richieste ad alto impatto, allegati non supportati, periodi di indisponibilità del sistema sorgente. Se la condizione cambia, la scheda cambia.

Scrivi stop ed escalation come esiti normali

Un assistente che risponde sempre nasconde l'incertezza. La scheda deve mostrare almeno tre esiti ammessi:

ANSWER    risposta con fonte e limite
ABSTAIN   risposta non disponibile o fonte insufficiente
ESCALATE  serve una decisione o un'autorità diversa

Definisci i trigger. Fonte scaduta, conflitto fra documenti, dato mancante, richiesta fuori perimetro, azione irreversibile e possibile danno non possono finire tutti in non lo so. Hanno owner diversi.

L'escalation umana di un workflow AI descrive come progettare trigger, handoff e override. Nella scheda riporti la versione che serve a chi usa l'assistente: cosa vedrà, chi riceverà il caso e quali informazioni passeranno.

Esempio: Se due procedure correnti si contraddicono, non scegliere. Mostra titolo, versione e passaggio in conflitto; assegna il caso al knowledge owner. Questo è un comportamento testabile.

Versiona la scheda insieme all'assistente

Modello, prompt, corpus, tool o permessi possono cambiare il comportamento. Ogni modifica sostanziale apre una nuova versione della scheda o rende la precedente in revisione.

Registra:

capability_card_version: 1.4
assistant_release: support-assistant-2026-09-01
valid_from: 2026-09-03
tested_on: 2026-09-01
owners:
  product: support-ops
  knowledge: procedure-owner
  technical: ai-platform
next_review_trigger:
  - model-change
  - corpus-policy-change
  - new-tool
  - blocking-incident

Non mettere una scadenza standard se non sai sostenerla. Usa trigger legati alle superfici che cambiano. Una nuova versione del modello può richiedere il confronto completo; la correzione di un refuso in una caption no.

La scheda vecchia resta consultabile per spiegare un output storico. Sovrascriverla toglie il contesto proprio quando serve capire perché l'assistente si è comportato in quel modo.

Distribuiscila nel punto in cui si decide

Una scheda chiusa in una cartella di progetto non cambia il comportamento. Mettila dove una persona sceglie se usare l'assistente: onboarding, pagina del tool, procedura, catalogo interno e schermata di escalation.

La versione breve deve rispondere in meno di due minuti a cinque domande:

1. Per quale lavoro è ammesso?

2. Quali fonti e dati usa?

3. Cosa può fare davvero?

4. Dove si ferma?

5. Chi decide l'eccezione?

Il dettaglio tecnico resta dietro. Se chi usa l'assistente deve leggere 28 pagine per capire che non può inviare un'email, la documentazione ha fallito.

Esempio fittizio

Un assistente interno aiuta il team acquisti a cercare procedure e preparare richieste di offerta. La prima scheda dice supporta il processo di procurement. Durante il pilota una persona gli chiede di scegliere il fornitore con il prezzo più basso. L'assistente lo fa, ignorando requisiti di servizio presenti in un allegato.

Il team non aggiunge una nota generica sull'accuratezza. Riscrive il confine:

• può estrarre requisiti da documenti approvati

• può preparare una matrice con fonti

• non può assegnare pesi o scegliere il fornitore

• se un allegato non viene letto, il caso è INCOMPLETE_SOURCE_SET

• la decisione resta al responsabile acquisti

Aggiunge 18 casi con allegati, tabelle e requisiti in conflitto. La nuova versione passa 17 casi. Uno perde ancora una nota dentro un PDF scansionato. La scheda mantiene quella capacità come limitata e richiede verifica dell'elenco allegati.

La parte utile non è la percentuale. È il limite che ora ha un nome, una prova e un comportamento.

Think, Build, Enable applicato alla scheda

Think: definisci lavoro ammesso, utenti, conseguenze, fonti, azioni e autorità. Se il confine non entra in una pagina, il prodotto è ancora ambiguo.

Build: collega ogni capacità a casi ripetibili. Registra configurazione, limiti, stop, escalation e versione senza esporre segreti.

Enable: porta la scheda nel punto d'uso, allena le persone sui casi negativi e raccogli i fallimenti che devono entrare nella regressione.

Porta assistente, casi reali e fallimenti a MAIKER HUB per progettare chatbot e assistenti AI. La scheda non deve far sembrare capace il sistema. Deve permettere a una persona di usarlo senza inventarsi il confine.