Vercel ha lanzado la versión 7 de su AI SDK con una función de contexto de herramientas con alcance limitado (scoped tool context) que obliga a que cada herramienta en un agente de IA reciba únicamente los secretos que declara explícitamente. Al limitar la exposición, los desarrolladores pueden evitar que las herramientas de terceros vean accidentalmente todas las credenciales almacenadas en su entorno.

Por qué es importante este cambio

Los agentes de IA suelen integrar múltiples servicios externos —búsqueda de pedidos, creación de tickets, procesamiento de pagos— y cada uno requiere sus propias claves de API o URLs. El atajo habitual es entregar el objeto process.env completo a cada herramienta:

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

Ese patrón crea una expansión implícita de privilegios: añadir una nueva herramienta le otorga instantáneamente acceso a todos los secretos existentes, incluyendo contraseñas de bases de datos o tokens de pago, sin que se active ninguna alerta en la revisión de código. El riesgo es que una herramienta comprometida o con errores filtre repentinamente credenciales que nunca debieron estar a su alcance.

Cómo funciona el contexto de herramientas con alcance limitado

En el SDK 7, una herramienta declara un esquema de contexto (context schema), una definición basada en Zod de los campos exactos que necesita. Cuando el agente invoca una herramienta, el llamador suministra un objeto toolsContext que contiene únicamente esos campos declarados. El SDK valida la estructura antes de la ejecución, y cualquier clave faltante o adicional provocará un error.

Una demostración mínima muestra dos herramientas con requisitos distintos:

  • lookupOrder – necesita baseUrl para llamar a un servicio de pedidos interno.
  • createTicket – necesita supportToken para abrir un ticket de soporte.

Cada herramienta exporta un contextSchema que enumera su única clave requerida. Cuando el agente se ejecuta, pasa:

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

Solo lookupOrder ve baseUrl; createTicket nunca la toca, y viceversa. El SDK impone este límite en tiempo de ejecución, convirtiendo una dependencia oculta en una lista de capacidades explícita que los revisores pueden auditar.

Ventajas de seguridad

  • Limita la exposición de datos – las credenciales permanecen donde se necesitan.
  • Valida el contexto – si los campos no coinciden o faltan, la ejecución se aborta.
  • Hace que las capacidades sean explícitas – los revisores pueden ver exactamente a qué puede acceder cada herramienta.
  • Reduce el radio de impacto – si una herramienta se ve comprometida, el atacante solo obtiene los secretos a los que esa herramienta tenía permiso.

Esta función no sustituye al sandboxing tradicional. Los desarrolladores aún deben emplear la redacción de logs (log redaction), controles de salida de red (network egress controls) y la rotación regular de tokens. El contexto con alcance limitado es un límite; no sella la habitación.

Qué deben ajustar los desarrolladores

  1. Definir un esquema para cada herramienta – utiliza la biblioteca Zod que viene con el SDK.
  2. Pasar un toolsContext restringido – evita el uso generalizado de process.env.
  3. Revisar los agentes existentes – identifica cualquier secreto que pueda eliminarse de las llamadas a las herramientas.
  4. Añadir pruebas automatizadas – asegúrate de que la validación del contexto falle cuando se inyecten datos adicionales.

Un inicio rápido se ve así:

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

Crea demo.ts, declara el contextSchema de cada herramienta y ejecútalo con tsx demo.ts. El SDK lanzará un error si intentas darle a una herramienta un secreto que no haya solicitado.

Contrapunto

Algunos equipos podrían argumentar que las definiciones de esquema adicionales añaden código repetitivo (boilerplate) y ralentizan el prototipado. Si bien es cierto, el coste es modesto —solo unas pocas líneas por herramienta— y el beneficio de seguridad aumenta con el número de servicios integrados. En entornos que manejan datos de pago o información personal, el compromiso es difícil de ignorar.

Qué observar a continuación

  • Métricas de adopción – los primeros usuarios están reportando menos incidentes de filtración de secretos.
  • Herramientas de la comunidad – complementos que generan automáticamente esquemas de contexto a partir de archivos de configuración.
  • Próximos lanzamientos del SDK – indicios de que Vercel podría ampliar los contextos con alcance limitado para incluir permisos de red y límites de tasa (rate-limit caps).

Si ya estás construyendo agentes de IA con el SDK de Vercel, el primer paso es auditar tu uso actual de process.env. Identifica el valor único que puede eliminarse de todas las llamadas a las herramientas y sustituye el patrón general por un toolsContext con alcance limitado. El resultado es una postura de seguridad más sólida sin sacrificar la flexibilidad que hace que los agentes de IA sean potentes.