Vercel ha rilasciato la versione 7 del suo AI SDK con una funzionalità di scoped tool context che obbliga ogni strumento in un agente AI a ricevere solo i segreti che dichiara esplicitamente. Limitando l'esposizione, gli sviluppatori possono impedire agli strumenti di terze parti di visualizzare accidentalmente ogni credenziale memorizzata nel proprio ambiente.

Perché questo cambiamento è importante

Gli agenti AI spesso integrano molteplici servizi esterni — ricerca ordini, creazione ticket, elaborazione pagamenti — ognuno dei quali richiede le proprie chiavi API o URL. La scorciatoia comune è passare l'intero oggetto process.env a ogni strumento:

execute(input, { context: process.env })

Questo schema crea un'espansione implicita dei privilegi: l'aggiunta di un nuovo strumento concede istantaneamente l'accesso a tutti i segreti esistenti, inclusi password del database o token di pagamento, senza alcun segnale durante la revisione del codice. Il rischio è che uno strumento compromesso o difettoso possa improvvisamente far trapelare credenziali che non gli erano mai destinate.

Come funziona lo scoped tool context

Nella versione 7 dell'SDK, uno strumento dichiara uno schema di contesto — una definizione basata su Zod dei campi esatti di cui ha bisogno. Quando l'agente invoca uno strumento, il chiamante fornisce un oggetto toolsContext che contiene solo i campi dichiarati. L'SDK valida la struttura prima dell'esecuzione, e qualsiasi chiave mancante o extra causa un errore.

Una demo minima mostra due strumenti con requisiti distinti:

  • lookupOrder – necessita di baseUrl per chiamare un servizio ordini interno.
  • createTicket – necessita di supportToken per aprire un ticket di supporto.

Ogni strumento esporta un contextSchema che elenca la sua singola chiave richiesta. Quando l'agente viene eseguito, passa:

{
  lookupOrder: { baseUrl: "https://orders.internal" },
  createTicket: { supportToken: "s3cr3t-token" }
}

Solo lookupOrder vede baseUrl; createTicket non la tocca mai, e viceversa. L'SDK impone questo confine a runtime, trasformando una dipendenza nascosta in un elenco esplicito di capacità che i revisori possono auditare.

Vantaggi per la sicurezza

  • Limita l'esposizione dei dati – le credenziali rimangono dove sono necessarie.
  • Valida il contesto – campi errati o mancanti interrompono l'esecuzione.
  • Rende esplicite le capacità – i revisori possono vedere esattamente a cosa può accedere ogni strumento.
  • Riduce il raggio d'azione (blast radius) – se uno strumento viene compromesso, l'attaccante ottiene solo i segreti a cui quello strumento era autorizzato.

La funzionalità non sostituisce il tradizionale sandboxing. Gli sviluppatori devono comunque impiegare la redazione dei log, controlli sull'uscita di rete (egress) e la rotazione regolare dei token. Lo scoped context è un confine; non sigilla la stanza.

Cosa devono regolare gli sviluppatori

  1. Definire uno schema per ogni strumento – utilizzare la libreria Zod inclusa nell'SDK.
  2. Passare un toolsContext ristretto – evitare l'uso generico di process.env.
  3. Revisionare gli agenti esistenti – identificare eventuali segreti che possono essere rimossi dalle chiamate agli strumenti.
  4. Aggiungere test automatizzati – assicurarsi che la validazione del contesto fallisca quando vengono iniettati dati extra.

Un avvio rapido è simile a questo:

mkdir scoped-tools && cd scoped-tools
npm init -y
npm install ai zod
npm install -D typescript tsx @types/node

Crea demo.ts, dichiara il contextSchema di ogni strumento ed eseguilo con tsx demo.ts. L'SDK restituirà un errore se provi a fornire a uno strumento un segreto che non ha richiesto.

Punto di vista opposto

Alcuni team potrebbero sostenere che le definizioni di schema extra aggiungano codice ripetitivo (boilerplate) e rallentino la prototipazione. Sebbene sia vero, il costo è modesto — solo poche righe per strumento — e il ritorno in termini di sicurezza cresce con il numero di servizi integrati. In ambienti che gestiscono dati di pagamento o informazioni personali, il compromesso è difficile da ignorare.

Cosa monitorare in futuro

  • Metriche di adozione – i primi utilizzatori segnalano un minor numero di incidenti legati alla fuga di segreti.
  • Strumenti della community – plug-in che generano automaticamente gli schemi di contesto dai file di configurazione.
  • Prossime release dell'SDK – indizi sul fatto che Vercel potrebbe estendere gli scoped context per includere permessi di rete e limiti di rate-limiting.

Se stai già costruendo agenti AI con l'SDK di Vercel, il primo passo è auditare l'uso attuale di process.env. Identifica il singolo valore che può essere rimosso da tutte le chiamate agli strumenti e sostituisci il pattern generico con uno scoped toolsContext. Il risultato è una postura di sicurezza più solida senza sacrificare la flessibilità che rende potenti gli agenti AI.