Vercel выпустила 7-ю версию своего AI SDK с функцией scoped tool context, которая заставляет каждый инструмент в AI-агенте получать только те секреты, которые он явно декларирует. Ограничивая область видимости, разработчики могут предотвратить случайный доступ сторонних инструментов ко всем учетным данным, хранящимся в их окружении.

Почему это важно

AI-агенты часто объединяют множество внешних сервисов — поиск заказов, создание тикетов, обработка платежей — каждый из которых требует свои API-ключи или URL. Распространенный способ упрощения — передавать весь объект process.env каждому инструменту:

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

Такой паттерн создает неявное расширение привилегий: добавление нового инструмента мгновенно предоставляет ему доступ ко всем существующим секретам, включая пароли к базам данных или платежные токены, без каких-либо уведомлений при проверке кода. Риск заключается в том, что скомпрометированный или ошибочный инструмент может внезапно раскрыть учетные данные, которые никогда не предназначались для него.

Как работает scoped tool context

В SDK 7 инструмент объявляет context schema — определение точных полей, необходимых ему, на базе Zod. Когда агент вызывает инструмент, вызывающая сторона передает объект toolsContext, содержащий только эти объявленные поля. SDK проверяет структуру перед выполнением, и любые отсутствующие или лишние ключи вызывают ошибку.

Минимальная демонстрация показывает два инструмента с разрозненными требованиями:

  • lookupOrder — требует baseUrl для вызова внутреннего сервиса заказов.
  • createTicket — требует supportToken для открытия тикета в службу поддержки.

Каждый инструмент экспортирует contextSchema, в которой перечислен его единственный необходимый ключ. При запуске агента передается:

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

Только lookupOrder видит baseUrl; createTicket никогда к нему не прикасается, и наоборот. SDK обеспечивает соблюдение этой границы во время выполнения, превращая скрытую зависимость в явный список возможностей, который можно проверить при аудите.

Преимущества для безопасности

  • Ограничивает раскрытие данных — учетные данные остаются там, где они необходимы.
  • Валидирует контекст — несоответствие или отсутствие полей прерывает выполнение.
  • Делает возможности явными — проверяющие могут точно видеть, к чему имеет доступ каждый инструмент.
  • Уменьшает радиус поражения — если инструмент будет скомпрометирован, злоумышленник получит только те секреты, которые были разрешены этому инструменту.

Эта функция не заменяет традиционную песочницу (sandboxing). Разработчики по-прежнему должны использовать маскирование логов, контроль исходящего сетевого трафика и регулярную ротацию токенов. Scoped context — это граница, а не герметизация помещения.

Что нужно изменить разработчикам

  1. Определите схему для каждого инструмента — используйте библиотеку Zod, которая поставляется вместе с SDK.
  2. Передавайте узкий toolsContext — избегайте использования process.env как универсального решения.
  3. Проверьте существующих агентов — выявите секреты, которые можно удалить из вызовов инструментов.
  4. Добавьте автоматизированные тесты — убедитесь, что валидация контекста завершается ошибкой при попытке внедрения лишних данных.

Быстрый старт выглядит так:

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

Создайте demo.ts, объявите contextSchema для каждого инструмента и запустите его с помощью tsx demo.ts. SDK выдаст ошибку, если вы попытаетесь передать инструменту секрет, о котором он не просил.

Контраргумент

Некоторые команды могут возразить, что дополнительные определения схем создают лишний шаблонный код (boilerplate) и замедляют прототипирование. Хотя это и так, цена невелика — всего несколько строк на инструмент — а выгода в плане безопасности растет вместе с количеством интегрированных сервисов. В средах, работающих с платежными данными или персональной информацией, этим компромиссом трудно пренебречь.

На что обратить внимание в будущем

  • Метрики внедрения — первые пользователи сообщают о меньшем количестве инцидентов с утечкой секретов.
  • Инструментарий сообщества — плагины, которые автоматически генерируют схемы контекста из конфигурационных файлов.
  • Будущие релизы SDK — есть намеки на то, что Vercel может расширить возможности scoped contexts, включив в них сетевые разрешения и ограничения частоты запросов (rate-limit).

Если вы уже создаете AI-агентов с помощью Vercel SDK, первым шагом должен стать аудит текущего использования process.env. Найдите значение, которое можно исключить из всех вызовов инструментов, и замените универсальный паттерн на ограниченный toolsContext. Результатом станет более строгая модель безопасности без ущерба для гибкости, которая делает AI-агентов столь мощными.