O adaptador fx para o AI SDK Harness da Vercel, explicado

A Vercel adicionou o fx à camada de harness do AI SDK em August 31, 2026. Agora você pode executar esse agente de codificação leve por meio da mesma interface HarnessAgent usada para outros harnesses de código. O ganho real está na redução do trabalho de integração, não em um agente magicamente intercambiável.

O que o adaptador fx realmente é

O fx é um harness de agente de programação e uma ferramenta de linha de comando. Um harness é o ambiente de execução em torno de uma chamada ao modelo: ele gerencia o espaço de trabalho, ferramentas, skills, sessões, permissões, compactação e subagentes que permitem a um modelo realizar um trabalho real de código.

Isso torna essa novidade diferente de apenas adicionar outro provedor de modelos ao AI SDK. Você não está trocando um modelo de texto por outro. Você está adicionando um runtime de codificação completo por trás de uma interface que sua aplicação já sabe consumir.

O novo adaptador @ai-sdk/harness-fx fica entre o HarnessAgent e o fx. Por baixo dos panos, ele usa o Agent Client Protocol, ou ACP, como a linguagem comum para iniciar uma sessão, enviar um prompt, fazer streaming de progresso, manipular ferramentas e realizar a limpeza.

O fluxo agora funciona assim: sua aplicação conversa com o HarnessAgent, o adaptador do fx traduz essa requisição para ACP, o fx roda dentro de uma sandbox de rede e suas chamadas ao modelo passam pelo Vercel AI Gateway.

Essa é a grande sacada. A aplicação mantém uma interface única. O harness preserva o seu próprio comportamento.

Por que isso importa e o que isso não prova

O custo de integração é a parte que mudou de lugar. Se o seu produto já utiliza o HarnessAgent, incluir o fx não exige mais criar do zero outro gerenciador de sessões, parser de stream, ponte de permissões e rotina de encerramento.

Isso dá a uma equipe de plataforma uma maneira mais limpa de comparar harnesses por trás de uma única superfície de produto. Também permite que uma aplicação menor adicione outro runtime de codificação sem precisar manter uma stack de orquestração separada.

O site atual do fx rotula o agente como v0.0.7, experimental e sob licença Apache-2.0. Os pacotes de harness do AI SDK também são experimentais. Portanto, isso está pronto para um spike técnico controlado, mas não é uma dependência madura que você deva assumir como estável.

Não existem dados publicados de antes e depois sobre tempo de configuração, latência, qualidade de código ou redução de custos. Não transforme "uma única API" em uma afirmação infundada de desempenho. O adaptador reduz o trabalho braçal de infraestrutura. Você ainda precisa avaliar se o fx resolve bem as tarefas do seu repositório.

Quem usa o fx diretamente no terminal praticamente não é afetado. O mesmo vale para uma aplicação que faz apenas chamadas normais a modelos usando funções padrão de geração do AI SDK sem nunca rodar um harness de codificação. Essa mudança importa quando você está incorporando agentes de codificação em um produto ou em uma plataforma interna.

Quem pode usar isso amanhã

Um fundador solo adicionando correção de repositórios a um SaaS

Imagine que sua aplicação já recebe um repositório Git e pede a um agente para corrigir um teste quebrado. Você pode manter o fluxo existente de sessões e streaming e simplesmente selecionar o fx como o harness para um grupo de testes. A vantagem é ter uma comparação real dentro do próprio produto, em vez de criar um protótipo separado do fx com seu próprio backend.

Uma equipe de plataforma avaliando harnesses de IA

Uma equipe de plataforma pode enviar o mesmo prompt de correção pelo fx e por outro harness suportado, capturar o mesmo stream no nível da aplicação e comparar a taxa de conclusão das tarefas. Claude Code, Cline, Codex, Cursor, Deep Agents, Grok Build, OpenCode e Pi também estão listados na camada de harness.

Essa comparação ainda exige métricas específicas para cada harness. Uma interface comum não torna idênticos o comportamento de permissões, ferramentas, compactação de contexto ou planejamento interno.

Uma software agency isolando o trabalho de clientes

Uma agência pode iniciar uma Vercel Sandbox para corrigir o repositório de um cliente, transmitir o progresso diretamente para o painel de controle existente e destruir a sessão assim que o job for concluído. Isso mantém o ambiente do cliente isolado do processo host e padroniza o ciclo de vida entre diferentes agentes.

Um time interno de developer tools resolvendo pequenas correções

Uma equipe de ferramentas internas pode oferecer o fx para tarefas pontuais, como corrigir um teste ou implementar um pequeno ajuste, mantendo as skills e configurações de servidores MCP existentes na camada de harness. O ganho é ter mais uma opção de runtime sem precisar reconstruir o front-end.

O passo a passo prático

A documentação atual do harness fx oferece o caminho completo em TypeScript. Use-a dentro de um projeto AI SDK preparado para TypeScript.

1. 1

   Instale os três pacotes

   Adicione o núcleo do harness, o adaptador do fx e o adaptador do Vercel Sandbox:

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

2. 2

   Defina uma credencial para o Gateway no runtime

   Configure VERCEL_OIDC_TOKEN ou AI_GATEWAY_API_KEY no runtime que inicia o agente. Quando ambos estiverem presentes, o adaptador prioriza o VERCEL_OIDC_TOKEN.

   Não coloque a credencial no código-fonte. A sandbox precisa de acesso à rede porque a primeira sessão baixa o fx, e as sessões seguintes usam a internet para requisições de modelo e web.

3. 3

   Crie, faça o streaming e destrua a sessão

   Este é o exemplo básico documentado, incluindo o encerramento da sessão tanto em caso de sucesso quanto de falha:

   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

   Teste permissões e eventos antes de colocar em produção

   Execute primeiro uma tarefa inofensiva no repositório. Confirme se a sua aplicação recebe o stream de texto, se o pedido de permissão chega ao operador e se session.destroy() é executado caso a tarefa falhe.

   O detalhe que muitos esquecem é a porta exposta. O fx se comunica via ponte ACP, portanto a sandbox de rede precisa de pelo menos uma porta disponível. O exemplo usa a porta 4000.

Se você precisar construir um adaptador para outro agente compatível com ACP, o nosso artigo sobre o adaptador de harness ACP do AI SDK aborda essa camada mais baixa.

Quanto custa

O fx em si é código aberto sob licença Apache-2.0, mas uma execução embarcada ainda gera custos de tokens de modelo e de uso da Sandbox.

O AI Gateway cobra $0 de margem (markup) e $0 de taxa de plataforma sobre os tokens. Cada equipe na Vercel recebe $5 por mês em créditos no plano gratuito para um conjunto específico de modelos, com limites de requisição por modelo mais baixos. Comprar créditos do Gateway migra a equipe para o nível pago e encerra esses créditos gratuitos mensais.

Para a sandbox, o exemplo da própria Vercel na região iad1 precifica um job de 5 minutos de validação de código com IA usando 2 vCPUs e 4 GB de memória em cerca de $0.03 a 100% de utilização de CPU. Com essa taxa de referência, 1,000 jobs custam por volta de $30 de computação na Sandbox antes de contabilizar os tokens do modelo. O custo real de Active CPU pode ser menor enquanto o agente aguarda I/O de rede ou do modelo.

O uso da Sandbox no plano Pro consome primeiro o crédito mensal de $20 do plano. O tempo limite padrão da Sandbox é de 5 minutos, portanto defina o timeout da tarefa de forma deliberada e destrua sessões finalizadas em vez de deixá-las abertas.

Os cinco limites para produção

1. Ambas as camadas são experimentais

O fx e os pacotes de harness do AI SDK possuem selo experimental. A documentação do harness alerta explicitamente que breaking changes podem ocorrer entre versões.

2. O adaptador sempre busca a versão mais recente do fx

A primeira sessão executa o instalador padrão do fx, que sempre baixa a versão mais recente. O adaptador fixa a origem da instalação, o executável, o comando de inicialização e a versão do ACP, de modo que createFx() não permite travar esses detalhes. Isso gera problemas de reprodutibilidade se o seu ambiente de produção exigir o uso de binários com versão homologada.

3. Os modos de permissão não têm mapeamento direto

allow-reads e allow-edits são mapeados para o modo ask do fx. Já allow-all é mapeado para code. O fx não oferece um modo que permita editar arquivos e, ao mesmo tempo, exija aprovação para comandos de terminal. Dessa forma, você não pode assumir que os nomes de permissão da sua aplicação manterão o significado exato.

4. O ACP v1 deixa lacunas de observabilidade

Eventos de ferramentas nativas comuns podem omitir o nome programático da ferramenta e os dados brutos de entrada (raw input). O ACP v1 também não expõe limites entre passos do modelo nem consumo por etapa, o que torna o rastreamento detalhado e a atribuição de tokens menos precisos do que a interface unificada sugere.

5. Vários controles não são portáveis

Não há suporte portável para compactação manual de contexto, direcionamento no meio do turno (mid-turn steering) ou filtragem nativa de ferramentas por esse fluxo. Saídas estruturadas validadas por schema também não são suportadas. Um adaptador ACP costuma expor menos recursos de um harness do que um adaptador direto — razão pela qual a Vercel recomenda adaptadores diretos para Claude Code e Codex quando disponíveis.

O que fazer agora

Use o adaptador esta semana se você já tem uma aplicação rodando HarnessAgent, quer avaliar o fx em tarefas controladas de repositório e pode lidar com dependências experimentais. Comece com uma única classe de tarefa e registre a taxa de sucesso, prompts de permissão, rotinas de limpeza e gastos com modelos e Sandbox.

Aguarde se você precisa de um binário fx com versão fixa, saídas estruturadas, métricas de consumo por etapa, intervenção no meio do turno ou uma divisão clara entre permissão de edição de arquivos e aprovação de comandos de terminal. Essas são limitações da interface, não erros de configuração.

Se você roda o fx apenas como CLI local ou sua aplicação faz apenas chamadas diretas a modelos, você não é afetado. Não há motivo para adicionar uma camada de harness apenas porque um novo adaptador foi lançado.

Para mais análises diretas sobre as ferramentas que os desenvolvedores estão realmente colocando em produção, assine a newsletter.