Адаптер fx для Vercel AI SDK harness: как устроен и что дает

Vercel добавила fx в слой harness для AI SDK 31 августа 2026 года. Теперь этого легковесного агента для написания кода можно запускать через тот же интерфейс HarnessAgent, что и другие среды исполнения (harnesses). Однако реальная выгода здесь заключается в снижении затрат на интеграцию, а не в появлении волшебным образом взаимозаменяемого агента.

Что представляет собой адаптер fx для Vercel AI SDK на самом деле

fx — это harness для кодинг-агентов и инструмент командной строки. Понятием harness называют среду исполнения вокруг вызова модели: она управляет рабочей областью, инструментами, навыками, сессиями, разрешениями, сжатием контекста (compaction) и субагентами, которые позволяют нейросети выполнять реальную работу в кодовой базе.

В этом и заключается принципиальная разница по сравнению с подключением очередного провайдера моделей в AI SDK. Вы не просто меняете одну текстовую модель на другую. Вы подключаете полноценный рантайм для разработки ПО за интерфейсом, с которым ваше приложение уже умеет работать.

Новый адаптер @ai-sdk/harness-fx располагается между HarnessAgent и fx. Под капотом он использует Agent Client Protocol (ACP) как общий протокол для запуска сессии, отправки промпта, стриминга прогресса, обработки инструментов и очистки ресурсов.

Теперь цепочка вызовов выглядит следующим образом: ваше приложение обращается к HarnessAgent, адаптер fx транслирует запрос в ACP, сам fx выполняется внутри изолированной сетевой песочницы (sandbox), а запросы к моделям идут через Vercel AI Gateway.

В этом и заключается вся суть. Приложение взаимодействует с единым интерфейсом, а harness сохраняет собственное внутреннее поведение.

Почему это важно и каких иллюзий стоит избегать

Главное изменение коснулось расходов на интеграцию. Если в вашем продукте уже используется HarnessAgent, добавление fx больше не требует создания отдельного менеджера сессий, парсера потоков, шлюза разрешений и пайплайна очистки.

Для платформенных команд это дает чистый способ сравнивать различные среды исполнения за единым фасадом продукта. Небольшим проектам это позволяет подключать альтернативный рантайм для работы с кодом без поддержки дополнительного стека оркестрации.

На официальном сайте fx текущая версия агента обозначена как v0.0.7, имеет статус экспериментальной и распространяется под лицензией Apache-2.0. Пакеты harness в AI SDK также имеют экспериментальный статус. Решение полностью готово для изолированного инженерного спайка (исследования), но на данный момент его нельзя считать тихой и гарантированно стабильной зависимостью.

Опубликованных замеров «до и после» по времени настройки, задержкам (latency), качеству написания кода или экономии средств нет. Не стоит превращать концепцию «единого API» в ничем не подкрепленные заявления о производительности. Адаптер лишь избавляет от написания шаблонного связующего кода. Оценивать, насколько качественно fx решает задачи в вашем репозитории, по-прежнему предстоит вам.

Разработчиков, запускающих fx напрямую в терминале, эти изменения практически не затрагивают. То же касается приложений, вызывающих ИИ через стандартные функции генерации текста AI SDK без запуска полноценных кодинг-агентов. Нововведение имеет значение именно тогда, когда вы встраиваете агентов для кодинга в коммерческий продукт или внутреннюю платформу.

Кто может внедрить это уже сейчас

Соло-фаундеры, добавляющие автоисправление репозиториев в SaaS

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

Платформенные команды, тестирующие различные кодинг-агенты

Команда платформы может отправить один и тот же промпт на исправление бага через fx и любой другой поддерживаемый harness, перехватить унифицированный поток событий на уровне приложения и сравнить процент успешного выполнения задач. В слое harness также представлены Claude Code, Cline, Codex, Cursor, Deep Agents, Grok Build, OpenCode и Pi.

При этом бенчмаркинг по-прежнему требует специфической для каждого решения оценки: общий интерфейс не делает одинаковыми политики разрешений, доступные инструменты, сжатие контекста или внутреннее планирование шагов.

Агентства заказной разработки, изолирующие клиентский код

Агентство может поднять один Vercel Sandbox для исправления клиентского репозитория, транслировать прогресс в панель оператора и уничтожать сессию сразу после завершения задачи. Это изолирует код клиента от хост-процесса и обеспечивает единый шаблон управления жизненным циклом независимо от выбранного агента.

Внутренние команды DevTools для небольших правок

Команда инфраструктуры разработки может предложить fx для узких задач — починки тестов или небольших правок фичей, сохранив при этом настроенные навыки и конфигурации MCP-серверов на уровне harness. Итог — появление еще одной среды исполнения без необходимости переписывать фронтенд.

Пошаговое руководство по настройке

В текущей документации по fx harness представлен готовый пример на TypeScript. Используйте его в проекте с поддержкой AI SDK и TypeScript.

1. 1

   Установите три необходимых пакета

   Добавьте ядро harness, адаптер fx и драйвер Vercel Sandbox:

   pnpm add @ai-sdk/harness @ai-sdk/harness-fx @ai-sdk/sandbox-vercel

2. 2

   Передайте учетные данные AI Gateway в среду выполнения

   Укажите переменную VERCEL_OIDC_TOKEN либо AI_GATEWAY_API_KEY в окружении, где стартует агент. Если заданы обе, адаптер выберет VERCEL_OIDC_TOKEN.

   Не храните токены в исходном коде. Песочнице обязательно нужен доступ в сеть: первая сессия скачивает fx, а последующим требуется интернет для обращения к нейросетям и веб-ресурсам.

3. 3

   Создайте сессию, запустите стриминг и освободите ресурсы

   Базовый пример из документации с корректным освобождением ресурсов при любом исходе:

   import { HarnessAgent } from '@ai-sdk/harness/agent';
   import { fx } from '@ai-sdk/harness-fx';
   import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
   
   const agent = new HarnessAgent({
     harness: fx,
     model: 'openai/gpt-5.6-luna',
     sandbox: createVercelSandbox({
       runtime: 'node24',
       ports: [4000],
     }),
   });
   
   const session = await agent.createSession();
   
   let exitCode = 0;
   try {
     const result = await agent.stream({
       session,
       prompt: 'Check the test failures and fix the production code.',
     });
   
     for await (const part of result.stream) {
       if (part.type === 'text-delta') {
         process.stdout.write(part.text);
       }
     }
   } catch (err) {
     exitCode = 1;
     console.error(err);
   } finally {
     await session.destroy();
     process.exit(exitCode);
   }

4. 4

   Проверьте права доступа и события перед боевым запуском

   Сначала протестируйте сценарий на безопасной задаче в репозитории. Убедитесь, что приложение получает текстовый поток, запрос на подтверждение действий доходит до оператора, а метод session.destroy() срабатывает даже при ошибке.

   Критическая деталь, о которой часто забывают, — открытый порт. fx общается через мост ACP, поэтому изолированной сетевой песочнице требуется как минимум один доступный порт. В примере используется порт 4000.

Если вам требуется разработать адаптер под другого агента с поддержкой ACP, обратитесь к материалу об адаптере AI SDK ACP harness, где детально разобран этот низкоуровневый слой.

Стоимость использования

Исходный код самого fx открыт под лицензией Apache-2.0, однако встроенное выполнение расходует токены моделей и ресурсы Sandbox.

AI Gateway не берет наценок ($0 markup) и сервисных сборов ($0 platform fee) за токены. Каждой команде на Vercel предоставляется бесплатный ежемесячный лимит в $5 на определенный пул моделей с пониженными рейтримитами. Покупка платных кредитов Gateway переводит команду на платный тариф и отключает этот ежемесячный бесплатный баланс.

Что касается песочницы: по расчетам Vercel для региона iad1, 5-минутная задача по валидации кода агентом на конфигурации из 2 vCPU и 4 GB памяти обходится примерно в $0.03 при 100% нагрузке на процессор. При таких вводных 1,000 запусков будут стоить около $30 за вычислительные мощности Sandbox без учета токенов моделей. Фактическая стоимость Active CPU может быть ниже, пока агент простаивает в ожидании ответа модели или сетевого ввода-вывода.

На тарифе Pro расходы на Sandbox сначала списываются из включенного ежемесячного лимита в $20. По умолчанию таймаут песочницы составляет 5 минут, поэтому выставляйте лимиты времени осознанно и не забывайте уничтожать сессии сразу после завершения работы.

Пять ограничений перед выходом в продакшен

1. Экспериментальный статус обоих слоев

Сам проект fx и пакеты AI SDK harness помечены как экспериментальные. Документация прямо предупреждает о возможных ломающих изменениях (breaking changes) между релизами.

2. Привязка к последней версии fx

Первая сессия запускает стандартный установщик fx, который всегда скачивает самый свежий релиз. Адаптер жестко фиксирует источник установки, исполняемый файл, команду запуска и версию ACP, поэтому createFx() не позволяет зафиксировать конкретную версию бинарника. Это критично для сред, где каждый продакшен-рантайм обязан использовать строго утвержденные версии.

3. Неточное сопоставление уровней доступа

Режимы allow-reads и allow-edits транслируются в режим ask внутри fx. Режим allow-all соответствует code. В fx отсутствует режим, разрешающий правку файлов без подтверждения, но требующий аппрува на запуск терминальных команд. Следовательно, нельзя рассчитывать на сохранение точной семантики разрешений вашего приложения.

4. Пробелы в наблюдаемости (observability) в ACP v1

Стандартные нативные события инструментов могут терять программное имя инструмента и сырые входные параметры. В версии ACP v1 также отсутствуют границы шагов модели (step boundaries) и детализация расхода токенов по шагам. Из-за этого детальная трассировка и учет затрат работают хуже, чем можно ожидать от унифицированного интерфейса.

5. Отсутствие переносимости ряда возможностей

Через этот адаптер недоступны ручное сжатие контекста, корректировка инструкций в процессе выполнения (mid-turn steering) и встроенная фильтрация инструментов. Структурированный вывод по строгой схеме (structured output) также не поддерживается. ACP-адаптер часто предоставляет меньше возможностей среды исполнения, чем прямой адаптер — именно поэтому для Claude Code и Codex Vercel рекомендует прямые адаптеры, когда они доступны.

Что делать дальше

Использовать адаптер можно уже на этой неделе, если в вашем приложении уже внедрен HarnessAgent, вы хотите протестировать fx на изолированных задачах и готовы мириться с экспериментальным статусом зависимостей. Начните с одного узкого класса задач и зафиксируйте метрики: процент успешного выполнения, поведение подтверждений, корректность очистки сессий, а также расходы на нейросети и вычислительные мощности Sandbox.

Рекомендуется подождать, если критически важны фиксация версии бинарника fx, структурированный вывод, пошаговый учет токенов, прямое управление агентом в процессе генерации или четкое разделение прав на редактирование файлов и выполнение команд в шелле. Все это — фундаментальные ограничения текущего интерфейса, а не ошибки конфигурации.

Если вы работаете с fx только через локальный CLI или ваше приложение выполняет лишь простые вызовы моделей, вам ничего менять не нужно. Нет никакого практического смысла усложнять архитектуру слоем harness только ради того, чтобы попробовать свежий адаптер.

Чтобы не пропустить честные технические разборы инструментов, которые разработчики используют в реальном продакшене, подписывайтесь на рассылку.