ACP-адаптер Vercel AI SDK: как он устроен и кому нужен

Что именно выпустила Vercel для AI SDK

Сначала разделим уровни, которые часто смешивают.

Модель формирует следующий ответ. Агентная среда (harness) превращает модель в исполнителя: управляет сессиями, инструментами, разрешениями, песочницами, инструкциями, сжатием контекста и рабочим циклом. ACP, то есть Agent Client Protocol, задаёт общий язык для общения клиента с такой средой.

HarnessAgent от Vercel уже предоставлял приложениям единый API для работы с агентными средами. Не хватало связующего слоя. До этого релиза Vercel требовался отдельный адаптер для каждой среды выполнения — в том числе для Claude Code, Codex, Pi, Deep Agents и OpenCode.

Новый ACP-адаптер оборачивает сам протокол, а не конкретную среду. В createACP передаются NPM-пакет с реализацией ACP для нужной среды, исполняемый файл, правила аутентификации, сопоставление инструкций и разрешений. Универсальный адаптер берёт на себя связующий слой, ACP-клиент, передачу инструментов, события, подтверждения и жизненный цикл сессии.

В этом и состоит замысел: Vercel отвечает за общую связку, а профиль среды выполнения — за особенности конкретной агентной среды.

Сейчас адаптер поддерживает ACP версии 1, и только версии 1. Это совместимость на границе протокола, а не гарантия одинакового поведения всех подключённых сред.

Vercel даёт однозначную рекомендацию. Для Claude Code и Codex следует выбирать @ai-sdk/harness-claude-code или @ai-sdk/harness-codex. @ai-sdk/harness-acp нужен, когда у агентной среды есть совместимый пакет, но нет прямого адаптера.

Зачем нужен ACP-адаптер Vercel AI SDK

Изменился прежде всего объём интеграционной работы.

Команде, которая разрабатывает инструменты для разработчиков, больше не нужно заново реализовывать сессии, преобразование событий, обработку разрешений, передачу инструментов хоста и управление жизненным циклом только ради подключения ещё одной ACP-среды к HarnessAgent. Достаточно описать профиль среды выполнения, сохранив для остального приложения прежний API.

Это также изолирует продуктовый слой от изменений. И HarnessAgent.generate(), и HarnessAgent.stream() возвращают результаты, совместимые с AI SDK. Если команда уже использует useChat, интерфейс можно не менять при замене исполнителя на серверной стороне.

Этот релиз не делает агентную среду быстрее, дешевле или функциональнее. Он не делает разные реализации ACP одинаковыми и не заменяет песочницу. Любой ACP-совместимой агентной среде по-прежнему нужна сетевая песочница как минимум с одним открытым портом.

Для тех, кто напрямую пользуется Claude Code, Codex или другим ИИ-агентом для программирования, почти ничего не меняется. Новая возможность адресована разработчикам продуктов вокруг таких агентов.

Кому это пригодится уже завтра

Основателю devtools-продукта, который добавляет поддержку AI SDK

Предположим, компания разрабатывает собственную среду для ИИ-агентов, которые работают с кодом, и уже публикует ACP-совместимый NPM-пакет. Теперь можно один раз описать профиль createACP и предложить пользователям AI SDK официальный способ подключения к этой среде.

Главный выигрыш — более широкая дистрибуция. Команда продолжает отвечать за установку конкретного пакета, аутентификацию, инструкции и разрешения. Общую инфраструктуру вокруг них обеспечивает адаптер Vercel.

Платформенному инженеру, который поддерживает несколько сред

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

Различия в поведении никуда не исчезают. Они переходят в именованные профили, которые проверять проще, чем несколько независимых стеков оркестрации.

SaaS-команде с готовым интерфейсом на AI SDK

Продуктовая команда может подключить ИИ-агента для программирования через ACP к существующему приложению на AI SDK, не переделывая чат-интерфейс. Конкретные изменения остаются на сервере: создать профиль среды, подключить песочницу, запустить сессию и вернуть тот же тип потокового или готового результата, с которым уже работает интерфейс.

Если задача пока состоит в выборе самого агента, а не в его интеграции в продукт, начните со сравнения ИИ-агентов для программирования. Этот адаптер становится важен уже после такого продуктового решения.

Инженеру по безопасности, который определяет границы доступа

Инженер по безопасности получает явные точки контроля. Учётные данные можно передавать через брокер: процесс ACP в песочнице видит заглушки, а реальные значения добавляются только в исходящие запросы. Режимы разрешений сопоставляются с теми, которые действительно поддерживает среда; неподдерживаемым вариантам назначается null, чтобы запрос завершался ошибкой, а не незаметно расширял доступ.

Это не делает систему безопасной автоматически. Зато появляется конкретное место, где правила безопасности можно описать и протестировать.

Как подключить ACP-совместимую среду

Полный пример из документации

Установите пакеты агентной среды, ACP-адаптера и Vercel Sandbox:

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

Самый короткий и при этом содержательный пример — полный ACP-профиль Codex от Vercel. В нём одновременно показаны установка пакета, прямая передача учётных данных, настройка AI Gateway, инструкции и разрешения. Это пример подключения, а не рекомендация выбирать ACP для Codex: в реальной интеграции Codex Vercel предпочитает прямой адаптер.

Ниже приведены актуальные профиль и последовательность вызовов из документации. Для прямой аутентификации должна быть доступна переменная CODEX_API_KEY или OPENAI_API_KEY. Если задана AI_GATEWAY_API_KEY либо VERCEL_OIDC_TOKEN, стандартный режим auth: 'auto' выбирает AI Gateway.

import { createACP, type ACPPermissionModeMapping } from '@ai-sdk/harness-acp';
import { createCredentialRequestTransformation } from '@ai-sdk/harness/utils';
import { secureJsonParse } from '@ai-sdk/provider-utils';

export const codexACPHarness = createACP({
  harnessId: 'acp-codex',
  // Define the runtime's built-in tool names and input schemas to expose
  // provider-executed calls as typed HarnessAgent tools.
  // builtinTools: { ... },
  source: {
    type: 'npm-simple',
    packageName: '@agentclientprotocol/codex-acp',
    packageVersion: '1.1.4',
  },
  executable: 'codex-acp',
  forwardEnv: ['CODEX_CONFIG'],
  credentialEnv: ['CODEX_API_KEY', 'OPENAI_API_KEY'],
  credentialBrokering: ({ env }) => {
    const credential = env.CODEX_API_KEY ?? env.OPENAI_API_KEY;
    if (!credential) return [];
    const config =
      env.CODEX_CONFIG == null
        ? undefined
        : (secureJsonParse(env.CODEX_CONFIG) as {
            model_provider?: string;
            model_providers?: Record<string, { base_url?: string }>;
          });
    const baseUrl =
      config?.model_providers?.[config.model_provider ?? '']?.base_url ??
      'https://api.openai.com/v1';
    return [
      createCredentialRequestTransformation({
        baseUrl,
        headers: { Authorization: `Bearer ${credential}` },
      }),
    ];
  },
  instructionMapping: {
    type: 'launch-env-json',
    variable: 'CODEX_CONFIG',
    path: ['developer_instructions'],
  },
  permissionModeMapping: {
    'allow-reads': null,
    'allow-edits': null,
    'allow-all': { type: 'session-mode', modeId: 'agent-full-access' },
  } as const satisfies ACPPermissionModeMapping,
  authentication: {
    methodId: 'api-key',
  },
  providerAuthentication: {
    gateway: {
      env: {
        CODEX_API_KEY: { $source: 'gateway-api-key' },
        CODEX_CONFIG: {
          model: 'openai/gpt-5.6-sol',
          model_provider: 'ai_gateway',
          model_providers: {
            ai_gateway: {
              name: 'AI Gateway',
              base_url: {
                $source: 'gateway-base-url',
                ensureSuffix: '/v1',
              },
              env_key: 'CODEX_API_KEY',
              wire_api: 'responses',
              supports_websockets: false,
              http_headers: {
                'User-Agent': { $source: 'client-app' },
                'x-client-app': { $source: 'client-app' },
              },
            },
          },
          model_supports_reasoning_summaries: true,
          preferred_auth_method: 'apikey',
        },
      },
    },
  },
});

Распространённая ошибка — считать, что для профиля среды достаточно имени пакета и API-ключа. Сопоставление разрешений и инструкций, порт песочницы, граница передачи учётных данных и корректное завершение сессии — такие же обязательные части интеграции.

Где проходят реальные ограничения

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

Стратегию фиксации версий нужно выбирать явно. В простом источнике можно указать точную версию: в примере @agentclientprotocol/codex-acp зафиксирован на 1.1.4. Если версию не указывать, песочница установит пакет с тегом latest, причём эта версия не станет частью идентификатора среды. Для воспроизводимой сборки используйте фиксированный источник с package.json и pnpm-lock.yaml: Vercel устанавливает его командой pnpm install --frozen-lockfile.

У ACP версии 1 остаются существенные пробелы:

• Протокол не передаёт границы шагов модели и статистику использования по каждому шагу. Адаптер определяет границы приблизительно, а использование по шагам остаётся неизвестным.
• Нет переносимого API для ручного сжатия контекста или вмешательства по ходу выполнения.
• Нельзя единообразно фильтровать встроенные инструменты агентной среды. Фильтрация инструментов хоста работает, но попытка отфильтровать встроенные ACP-инструменты приводит к ошибке.
• Если набор инструментов хоста меняется, реализация ACP должна обновить список MCP-инструментов. Устаревшая реализация явно завершится ошибкой.

На страницах Vercel, изученных для этого релиза, отдельная цена @ai-sdk/harness-acp не указана. Это не означает, что «агенты бесплатны». В архитектуре по-прежнему есть аутентификация модели и обязательная сетевая песочница, поэтому действующие расходы на среду выполнения и меры контроля сохраняются.

Более глубокое ограничение связано с точностью передачи возможностей. ACP создаёт общий способ подключения, однако прямой адаптер способен полнее раскрыть нативное поведение конкретной среды. Стандартизация сокращает интеграционную работу, но не устраняет различия между средами выполнения.

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

Практическое правило простое.

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

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

Оставайтесь на прямом адаптере, если используете Claude Code или Codex. Для них уже есть путь, рекомендованный Vercel: он меньше ограничивает нативное поведение рамками протокола.

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

Если вам нужны такие же понятные разборы инструментов, которые меняют процесс разработки, подпишитесь на рассылку.