Vercel fx AI SDK harness adapter: análisis técnico y límites

Vercel añadió fx a la capa de harness de AI SDK el 31 de agosto de 2026. Ahora puedes ejecutar este agente de código ligero a través de la misma interfaz HarnessAgent utilizada para otros entornos de ejecución, pero la ventaja real es un menor trabajo de integración, no un agente mágicamente intercambiable.

Qué es exactamente el vercel fx ai sdk harness adapter

fx es un harness para agentes de código y una herramienta de línea de comandos. Un harness es el entorno de ejecución que rodea la llamada a un modelo: gestiona el espacio de trabajo, las herramientas, las habilidades, las sesiones, los permisos, la compactación y los subagentes que permiten a un modelo realizar un trabajo de desarrollo real.

Esto lo diferencia de añadir un proveedor de modelos más a AI SDK. No estás sustituyendo un modelo de texto por otro. Estás integrando un entorno de ejecución de código completo detrás de una interfaz con la que tu aplicación ya sabe comunicarse.

El nuevo adaptador @ai-sdk/harness-fx se sitúa entre HarnessAgent y fx. Por debajo, utiliza Agent Client Protocol (ACP) como lenguaje común para iniciar una sesión, enviar un prompt, transmitir el progreso en streaming, gestionar herramientas y limpiar los recursos.

El flujo actual funciona así: tu aplicación se comunica con HarnessAgent, el adaptador de fx traduce esa solicitud a ACP, fx se ejecuta dentro de un sandbox de red y sus peticiones al modelo pasan por Vercel AI Gateway.

Ese es todo el mecanismo. La aplicación obtiene una única interfaz. El harness conserva su propio comportamiento.

Por qué es relevante y qué no demuestra

Lo que ha cambiado es la carga técnica de la integración. Si tu producto ya utiliza HarnessAgent, añadir fx ya no implica construir otro gestor de sesiones, un parser de streams, un puente de permisos y un sistema de limpieza.

Esto ofrece a los equipos de plataforma una forma más limpia de comparar harnesses detrás de una misma superficie de producto. También permite que una aplicación más pequeña incorpore otro entorno de ejecución de código sin tener que mantener una infraestructura de orquestación independiente.

El sitio web actual de fx cataloga al agente como v0.0.7, experimental y con licencia Apache-2.0. Los paquetes de harness de AI SDK también son experimentales. Por tanto, está listo para una prueba de concepto acotada, pero no es una dependencia estable sobre la que debas asumir continuidad sin cambios.

No existen cifras publicadas de un antes y un después en cuanto a tiempo de configuración, latencia, calidad del código o ahorro de costes. No conviertas «una sola API» en una afirmación de rendimiento sin fundamentos. El adaptador reduce el código de infraestructura a medida. Todavía debes evaluar si fx resuelve adecuadamente las tareas de tus repositorios.

Quienes utilicen fx directamente en una terminal apenas notarán cambios. Lo mismo ocurre con una aplicación que solo invoca un modelo mediante las funciones de generación estándar de AI SDK y nunca ejecuta un harness de código. Esta novedad es relevante cuando estás integrando agentes de código dentro de un producto o en una plataforma interna.

Casos de uso inmediatos

Un fundador técnico que añade reparación de repositorios a un SaaS

Imagina que tu aplicación ya recibe un repositorio Git y solicita a un agente que corrija un test fallido. Puedes mantener la infraestructura actual de sesiones y streaming, y seleccionar fx como harness para un grupo de prueba. La ventaja es una comparación real dentro del mismo producto en lugar de crear un prototipo independiente de fx con su propio backend.

Un equipo de plataforma de agentes que evalúa harnesses

Un equipo de plataforma puede enviar el mismo prompt de reparación a través de fx y de otro harness compatible, capturar el mismo stream a nivel de aplicación y comparar la resolución de tareas. Claude Code, Cline, Codex, Cursor, Deep Agents, Grok Build, OpenCode y Pi también figuran en la capa de harnesses.

La comparativa sigue requiriendo una evaluación específica por harness. Disponer de una interfaz común no hace que el comportamiento de los permisos, las herramientas, la compactación o la planificación interna sean idénticos.

Una agencia de software que aísla el trabajo de clientes

Una agencia puede iniciar un Vercel Sandbox para corregir el repositorio de un cliente, transmitir el avance hacia su panel de control interno existente y destruir la sesión en cuanto termine el trabajo. Esto mantiene el espacio de trabajo del cliente aislado del proceso principal y proporciona al equipo un único patrón de ciclo de vida, independientemente del agente elegido.

Un equipo interno de herramientas para desarrolladores con tareas acotadas

Un equipo interno de herramientas puede ofrecer fx para tareas muy definidas, como corregir un test o modificar una pequeña funcionalidad, manteniendo su configuración de habilidades y servidores MCP en la capa de harness. La ventaja es contar con otra opción de ejecución sin rediseñar el frontend.

Guía práctica de implementación

La documentación actual del harness de fx incluye un ejemplo completo en TypeScript. Utilízalo dentro de un proyecto de AI SDK compatible con TypeScript.

1. 1

   Instalar los tres paquetes

   Añade el núcleo del harness, el adaptador de fx y el adaptador de Vercel Sandbox:

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

2. 2

   Proporcionar una credencial de Gateway al entorno

   Configura VERCEL_OIDC_TOKEN o AI_GATEWAY_API_KEY en el entorno de ejecución que inicializa el agente. Cuando ambas variables existen, el adaptador prioriza VERCEL_OIDC_TOKEN.

   No incluyas la credencial directamente en el código fuente. El sandbox requiere acceso a la red porque la primera sesión descarga fx y las sesiones posteriores necesitan la conexión para peticiones al modelo y llamadas web.

3. 3

   Crear, transmitir y destruir una sesión

   Este es el ejemplo básico documentado, incluyendo la limpieza de recursos tanto en caso de éxito como de error:

   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

   Probar permisos y eventos antes de pasar a producción

   Ejecuta primero una tarea inocua en el repositorio. Confirma que tu aplicación recibe el stream de texto, que las solicitudes de permisos llegan al operador y que session.destroy() se ejecuta si la tarea falla.

   Un detalle que suele pasarse por alto es el puerto expuesto. Como fx se comunica mediante un puente ACP, el sandbox de red requiere al menos un puerto abierto. El ejemplo utiliza el puerto 4000.

Si necesitas construir un adaptador para otro agente compatible con ACP, el artículo complementario sobre el adaptador de harness ACP de AI SDK profundiza en esa capa inferior.

Cuánto cuesta

Aunque fx es de código abierto bajo licencia Apache-2.0, una ejecución integrada sigue generando costes de tokens del modelo y del Sandbox.

AI Gateway no cobra recargos ($0 markup) ni comisiones de plataforma ($0 platform fee) sobre los tokens. Cada equipo en Vercel dispone de $5 al mes en créditos de nivel gratuito para un subconjunto de modelos, con límites de tasa más reducidos. Adquirir créditos de Gateway traslada al equipo al nivel de pago y da por finalizado ese crédito mensual gratuito.

En cuanto al sandbox, el propio ejemplo de Vercel para la región iad1 calcula una tarea de validación de código con IA de 5 minutos (con 2 vCPUs y 4 GB de memoria) en unos $0.03 bajo un 100% de uso de CPU. Con esa tarifa de referencia, 1,000 ejecuciones representan aproximadamente $30 de cómputo en Sandbox antes de sumar los tokens del modelo. El coste real de CPU activa puede ser inferior mientras el agente espera operaciones de I/O de red o respuestas del modelo.

El consumo de Sandbox en planes Pro se descuenta primero del crédito mensual de $20 incluido en el plan. El tiempo de espera predeterminado del Sandbox es de 5 minutos, por lo que conviene definir el timeout de cada tarea de forma explícita y destruir las sesiones finalizadas en lugar de dejarlas abiertas.

Los cinco límites para entornos de producción

1. Ambas capas son experimentales

Tanto el proyecto fx como los paquetes de harness de AI SDK llevan la etiqueta de experimentales. La documentación del harness advierte de forma explícita que pueden introducirse cambios incompatibles entre versiones.

2. El adaptador siempre descarga la última versión de fx

La primera sesión ejecuta el instalador oficial de fx, el cual resuelve la versión más reciente. El adaptador fija la fuente de instalación, el binario ejecutable, el comando de inicio y la versión de ACP, por lo que createFx() no permite congelar esas configuraciones. Esto supone un inconveniente para la reproducibilidad si tus despliegues en producción exigen versiones de binarios estrictamente auditadas.

3. La correspondencia de permisos no es exacta

Los modos allow-reads y allow-edits se asignan al modo ask de fx. Por su parte, allow-all se asigna a code. fx no ofrece un modo que autorice la edición de archivos pero siga requiriendo aprobación previa para comandos de terminal, por lo que no debes asumir que la nomenclatura de permisos de tu aplicación mantendrá exactamente su semántica.

4. ACP v1 presenta vacíos de observabilidad

Los eventos normales de herramientas nativas pueden omitir el nombre programático de la herramienta y los datos de entrada sin procesar. Además, ACP v1 carece de delimitación de pasos del modelo y de desglose de uso por paso, lo que dificulta la trazabilidad detallada y la atribución precisa de tokens en comparación con lo que sugiere una interfaz unificada.

5. Varios mecanismos de control no son portables

A través de esta arquitectura no existe soporte portable para compactación manual, intervención a mitad de turno (mid-turn steering) ni filtrado integrado de herramientas. Tampoco se admite la generación de respuestas estructuradas basadas en esquemas. Un adaptador ACP puede exponer menos funcionalidades de un harness que un adaptador directo; por esta razón, Vercel recomienda adaptadores directos para Claude Code y Codex cuando se encuentran disponibles.

Próximos pasos

Comienza a utilizar el adaptador esta semana si ya cuentas con una aplicación basada en HarnessAgent, deseas evaluar fx en tareas de repositorio bien delimitadas y puedes asumir una dependencia experimental. Empieza con un único tipo de tarea y registra las tasas de éxito, solicitudes de permisos, procesos de limpieza y el gasto tanto en modelos como en Sandbox.

Es preferible esperar si necesitas fijar una versión binaria concreta de fx, generar salidas estructuradas, medir el uso de tokens por paso, intervenir en mitad de la ejecución o contar con una separación estricta entre permisos de edición de archivos y aprobación en terminal. Estas restricciones derivan de la interfaz actual, no de errores de configuración.

Esta novedad no te afecta si utilizas fx únicamente como herramienta CLI en local o si tu aplicación solo realiza llamadas a modelos sin entornos de ejecución de código. No hay motivo para añadir una capa de harness solo porque exista un adaptador nuevo.

Para más análisis directos y técnicos sobre las herramientas que los equipos de ingeniería están implementando en producción, suscríbete a la newsletter.