Agentes de IA en Vercel: cómo funciona el adaptador ACP de AI SDK

Qué lanzó realmente Vercel para los agentes de IA

Primero conviene separar las capas que suelen confundirse.

Un modelo genera la siguiente respuesta. Un harness lo convierte en un sistema capaz de ejecutar tareas al gestionar sesiones, herramientas, aprobaciones, sandboxes, instrucciones, compactación y el ciclo de trabajo. ACP, sigla de Agent Client Protocol, establece una forma común de comunicación entre el cliente y el harness.

El HarnessAgent de Vercel ya ofrecía a las aplicaciones una API única para trabajar con harnesses. Faltaba el conector. Antes de este lanzamiento, Vercel necesitaba un adaptador independiente para cada entorno, entre ellos Claude Code, Codex, Pi, Deep Agents y OpenCode.

El nuevo adaptador ACP para harnesses encapsula el protocolo, no un entorno concreto. A createACP se le proporciona el paquete NPM que implementa ACP para el harness, su ejecutable, las reglas de autenticación y los mapeos de instrucciones y permisos. El adaptador genérico se ocupa entonces del puente, el cliente ACP, la retransmisión de herramientas, los eventos, las aprobaciones y el ciclo de vida de la sesión.

Esa división resume toda la propuesta: Vercel mantiene el puente común y el perfil del entorno se encarga de los detalles que cambian entre harnesses.

Actualmente, el adaptador es compatible con ACP versión 1, y solo con la versión 1. Se trata de compatibilidad en el límite del protocolo, no de una promesa de que todos los harnesses vayan a comportarse igual una vez conectados.

Vercel deja clara la elección. Para esos dos entornos deben usarse @ai-sdk/harness-claude-code o @ai-sdk/harness-codex. @ai-sdk/harness-acp corresponde a los casos en los que el harness dispone de un paquete compatible, pero no de un adaptador directo.

Por qué importa este adaptador ACP

Lo que cambia es el trabajo de integración.

Un equipo de herramientas para desarrolladores ya no tiene que reconstruir la gestión de sesiones, la traducción de eventos, el flujo de aprobaciones, la retransmisión de herramientas del host y el ciclo de vida solo para colocar otro entorno ACP detrás de HarnessAgent. Basta con escribir el perfil del entorno y mantener el resto de la aplicación sobre la misma API de harness.

Esto también protege la capa de producto. Tanto HarnessAgent.generate() como HarnessAgent.stream() devuelven resultados compatibles con AI SDK. Un equipo que ya utilice useChat puede conservar el flujo de su interfaz mientras cambia el trabajador que opera por detrás.

El lanzamiento no vuelve al harness más rápido, barato ni capaz. Tampoco hace idénticas las distintas implementaciones de ACP ni sustituye el sandbox. Cada harness ACP sigue necesitando un sandbox de red con al menos un puerto expuesto.

Quienes usan directamente Claude Code, Codex u otro agente de programación apenas notarán el cambio. Esta función está dirigida a quienes construyen el producto alrededor de esos agentes.

Quién puede aprovecharlo desde mañana

Un fundador de herramientas para desarrolladores que quiere añadir compatibilidad con AI SDK

Si una empresa ofrece un harness de programación y ya publica un paquete NPM compatible con ACP, ahora puede definir un único perfil con createACP y dar a los usuarios de AI SDK una vía compatible para entrar en su entorno.

La ventaja es la distribución. El equipo mantiene la instalación específica del paquete, la autenticación, las instrucciones y los permisos. El adaptador de Vercel resuelve la infraestructura común que los rodea.

Un ingeniero de plataforma que mantiene varios entornos

Una plataforma de ingeniería mediana puede necesitar un agente para reparar repositorios, otro para realizar migraciones y un harness interno para automatizaciones propias de la empresa. El ingeniero de plataforma puede conservar un único contrato de sesión y resultados, y seleccionar un perfil de harness distinto para cada tarea.

Eso no elimina las diferencias de comportamiento. Las traslada a perfiles con nombre, más fáciles de revisar que varias pilas de orquestación independientes.

Un equipo de SaaS con una interfaz existente basada en AI SDK

Un equipo de producto puede añadir a una aplicación existente de AI SDK un trabajador de programación respaldado por ACP sin reconstruir la interfaz de chat. El cambio concreto se produce en el servidor: crear el perfil del harness, vincular un sandbox, iniciar una sesión y devolver el mismo tipo de resultado, generado o en streaming, que ya consume la interfaz.

Si todavía se está eligiendo el agente, en lugar de integrarlo en un producto, conviene empezar por la comparativa de agentes de programación. Este adaptador cobra relevancia después de esa decisión de producto.

Un ingeniero de seguridad que define los límites

El ingeniero de seguridad dispone de puntos de control claros. Las credenciales pueden intermediarse para que el proceso ACP aislado vea marcadores de posición, mientras los valores reales se incorporan a las solicitudes salientes. Los modos de permiso pueden asociarse con los que admite el entorno; las opciones incompatibles se establecen en null para que fallen en vez de ampliar el acceso sin avisar.

El resultado no es seguridad automática, sino un lugar claro donde codificar y probar las reglas de seguridad.

Cómo ponerlo en marcha

Un ejemplo completo basado en la documentación

Primero se instalan el harness, el adaptador ACP y los paquetes de Vercel Sandbox:

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

La demostración más breve que no oculta detalles utiliza el perfil ACP completo de Codex publicado por Vercel, porque reúne en un solo lugar la instalación del paquete, las credenciales directas, la configuración de AI Gateway, las instrucciones y los permisos. Es un ejemplo de conexión, no una recomendación de elegir ACP para Codex. Para una integración real con Codex, Vercel prefiere el adaptador directo.

El código siguiente muestra el perfil y el flujo de llamadas documentados actualmente. Para la autenticación directa, debe estar disponible CODEX_API_KEY u OPENAI_API_KEY. Si existe AI_GATEWAY_API_KEY o VERCEL_OIDC_TOKEN, la ruta predeterminada auth: 'auto' selecciona 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',
        },
      },
    },
  },
});

El error habitual es reducir el perfil del entorno a un nombre de paquete y una clave de API. El mapeo de permisos, el mapeo de instrucciones, el puerto del sandbox, el límite de las credenciales y la limpieza de la sesión también forman parte de la integración.

Las limitaciones, sin rodeos

Los paquetes de harness son experimentales. Cabe esperar cambios incompatibles entre versiones, por lo que no es una dependencia que convenga actualizar sin control en producción.

Fijar la versión exige una decisión explícita. El origen simple permite indicar una versión exacta, como en el ejemplo, que fija @agentclientprotocol/codex-acp en 1.1.4. Si se omite la versión, el sandbox instala la etiqueta latest del paquete y esa versión queda fuera de la identidad del harness. Para obtener una compilación reproducible, debe usarse el origen bloqueado con un package.json y un pnpm-lock.yaml; Vercel lo instala mediante pnpm install --frozen-lockfile.

ACP versión 1 también presenta carencias importantes:

• No expone los límites entre los pasos del modelo ni el uso por paso. El adaptador deduce esos límites, mientras que el uso por paso sigue siendo desconocido.
• No cuenta con una API portátil para compactación manual ni para redirigir el agente a mitad de un turno.
• No permite filtrar de forma portátil las herramientas integradas del harness. El filtrado de herramientas del host sí funciona, pero intentar filtrar las herramientas integradas de ACP provoca un error.
• Si cambia el catálogo de herramientas del host, la implementación de ACP debe actualizar su lista de herramientas MCP. Una implementación desactualizada falla de forma explícita.

Las páginas de Vercel consultadas para este lanzamiento no indican un precio específico para @ai-sdk/harness-acp. Eso no equivale a «agentes gratis». La arquitectura sigue incluyendo una vía de autenticación del modelo y un sandbox de red obligatorio, de modo que continúan aplicándose los costos y controles existentes del entorno.

El límite de fondo es la fidelidad. ACP ofrece una conexión común, pero un adaptador directo puede reflejar mejor el comportamiento nativo de un harness. La estandarización reduce el trabajo de integración; no borra el entorno subyacente.

Qué conviene hacer ahora

La regla es sencilla.

Conviene actuar esta semana si se mantiene un harness compatible con ACP que no dispone de adaptador directo para AI SDK, o si el equipo de plataforma necesita colocar varios entornos de ese tipo detrás de un único contrato de aplicación. La vía es crear un perfil ligero, fijar la versión del paquete y probar cada permiso y cada ruta de error.

Es mejor esperar si la política de producción no admite un paquete experimental, si es imprescindible medir con precisión el uso por paso o si la compactación manual y la redirección a mitad del turno son controles esenciales.

Quienes utilicen Claude Code o Codex deberían conservar el adaptador directo. Es la vía que recomienda Vercel y obliga a pasar menos comportamiento por el límite del protocolo.

Nada cambia para quien llama directamente a los modelos, utiliza un agente de programación como usuario final o no necesita ejecutar un harness dentro de su propia aplicación.

Para recibir más análisis claros sobre las herramientas que están cambiando la forma de lanzar productos, suscríbete al boletín.