Agentes de IA no Vercel AI SDK: o adaptador ACP por dentro

O que a Vercel realmente lançou

Primeiro, vale separar as camadas que muita gente acaba confundindo.

Um modelo produz a próxima resposta. Um harness transforma esse modelo em um executor ao gerenciar sessões, ferramentas, aprovações, sandboxes, instruções, compactação e o ciclo de trabalho. Já o ACP, sigla de Agent Client Protocol, estabelece uma linguagem comum entre o cliente e o harness.

O HarnessAgent da Vercel já oferecia às aplicações uma API única para trabalhar com harnesses. O que faltava era o conector. Antes deste lançamento, a Vercel precisava de um adaptador específico para cada runtime, incluindo Claude Code, Codex, Pi, Deep Agents e OpenCode.

O novo adaptador ACP para harnesses encapsula o protocolo, não um runtime específico. Você informa ao createACP o pacote NPM que implementa ACP para o seu harness, o executável, as regras de autenticação e os mapeamentos de instruções e permissões. A partir daí, o adaptador genérico cuida da ponte, do cliente ACP, do repasse de ferramentas, dos eventos, das aprovações e do ciclo de vida da sessão.

Essa divisão resume a proposta: a Vercel mantém a ponte comum; o perfil do runtime concentra os detalhes que variam entre harnesses.

No momento, o adaptador oferece suporte ao ACP versão 1, e somente à versão 1. A compatibilidade existe no limite do protocolo; isso não significa que todos os harnesses passarão a se comportar da mesma forma depois de conectados.

A orientação da Vercel é direta. Para esses dois runtimes, use @ai-sdk/harness-claude-code ou @ai-sdk/harness-codex. Recorra ao @ai-sdk/harness-acp quando o harness tiver um pacote compatível, mas não contar com adaptador direto.

Por que isso importa para agentes de IA

O que mudou foi o trabalho necessário para integrar cada runtime.

Uma equipe de devtools não precisa mais recriar o gerenciamento de sessões, a tradução de eventos, o fluxo de aprovações, o repasse de ferramentas do host e o comportamento do ciclo de vida só para colocar outro runtime ACP atrás do HarnessAgent. Basta escrever o perfil do runtime e manter o restante da aplicação sobre a mesma API de harness.

Isso também preserva a camada de produto. Tanto HarnessAgent.generate() quanto HarnessAgent.stream() retornam resultados compatíveis com o AI SDK. Assim, uma equipe que já usa useChat pode manter o fluxo da interface mesmo trocando o executor nos bastidores.

O lançamento não torna um harness mais rápido, barato ou capaz. Também não faz diferentes implementações de ACP se comportarem de maneira idêntica nem substitui a sandbox. Todo harness ACP ainda precisa de uma sandbox com acesso à rede e pelo menos uma porta exposta.

Para quem usa Claude Code, Codex ou outro agente de programação diretamente, quase nada muda. O recurso se destina a quem constrói o produto ao redor desses agentes.

Quem já pode aproveitar o adaptador

Quem fundou uma empresa de devtools e quer integrar o AI SDK

Imagine que sua empresa desenvolva um harness de programação e já publique um pacote NPM compatível com ACP. Agora é possível definir um único perfil com createACP e oferecer aos usuários do AI SDK um caminho com suporte até o seu runtime.

O retorno vem na distribuição. Sua equipe mantém a instalação específica do pacote, a autenticação, as instruções e as permissões; o adaptador da Vercel assume toda a infraestrutura compartilhada ao redor desses pontos.

Uma pessoa de engenharia de plataforma responsável por vários runtimes

Uma plataforma de engenharia de médio porte pode querer um agente para corrigir repositórios, outro para executar migrações e um harness interno para automações próprias da empresa. Quem cuida da plataforma mantém um único contrato de sessão e resultado, escolhendo um perfil de harness diferente para cada tarefa.

As diferenças de comportamento não desaparecem. Elas passam a morar em perfis nomeados, que são mais fáceis de revisar do que pilhas de orquestração separadas.

Uma equipe de SaaS com uma interface já baseada no AI SDK

Uma equipe de produto pode colocar um executor de programação baseado em ACP por trás de uma aplicação existente do AI SDK sem reconstruir a experiência de chat. A mudança concreta fica no servidor: criar o perfil do harness, anexar uma sandbox, iniciar uma sessão e devolver o mesmo tipo de resultado, em streaming ou gerado de uma vez, que a interface já consome.

Se a escolha do agente ainda não foi feita — em vez de apenas integrá-lo ao produto —, comece pela comparação entre agentes de programação. Este adaptador só entra em cena depois dessa decisão de produto.

Uma pessoa de segurança definindo os limites

Para a área de segurança, o adaptador cria pontos claros de controle. As credenciais podem passar por intermediação: o processo ACP isolado na sandbox enxerga valores substitutos, enquanto os valores reais são inseridos nas requisições de saída. Também é possível associar os modos de permissão àqueles que o runtime realmente aceita e definir opções incompatíveis como null, fazendo com que falhem em vez de ampliar o acesso silenciosamente.

Isso não produz segurança automática. O que se ganha é um lugar explícito para codificar e testar as regras de proteção.

Como colocar a integração em funcionamento

Um exemplo completo da documentação

Instale os pacotes do harness, do adaptador ACP e da Vercel Sandbox:

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

A demonstração mais curta que não omite os detalhes usa o perfil ACP completo do Codex publicado pela Vercel. Ele reúne instalação do pacote, credenciais diretas, configuração do AI Gateway, instruções e permissões em um só lugar. É um exemplo de conexão, não uma recomendação para escolher ACP com Codex. Para uma integração real com Codex, a preferência da Vercel é pelo adaptador direto.

O código abaixo reproduz o perfil e o fluxo de chamadas documentados atualmente. Disponibilize CODEX_API_KEY ou OPENAI_API_KEY para autenticação direta. Se houver AI_GATEWAY_API_KEY ou VERCEL_OIDC_TOKEN, o caminho padrão com auth: 'auto' selecionará o 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',
        },
      },
    },
  },
});

Um erro comum é tratar o perfil do runtime como se ele se resumisse ao nome de um pacote e a uma chave de API. O mapeamento de permissões e instruções, a porta da sandbox, o limite das credenciais e a limpeza da sessão também fazem parte da integração.

Limites que não podem ser ignorados

Os pacotes de harness são experimentais. Mudanças incompatíveis entre versões são esperadas, portanto não se trata de uma dependência que deva avançar silenciosamente de versão em produção.

Fixar a versão exige uma decisão explícita. A origem simples permite travar uma versão exata, como no exemplo que fixa @agentclientprotocol/codex-acp em 1.1.4. Se a versão for omitida, a sandbox instalará a tag latest do pacote, e essa versão ficará fora da identidade do harness. Para uma build reproduzível, use a origem bloqueada com package.json e pnpm-lock.yaml; a Vercel fará a instalação com pnpm install --frozen-lockfile.

O ACP versão 1 também tem lacunas relevantes:

• Não expõe os limites entre as etapas do modelo nem o uso por etapa. O adaptador infere esses limites, e o consumo de cada etapa continua desconhecido.
• Não oferece uma API portátil para compactação manual ou direcionamento no meio de uma execução.
• Não permite filtrar, de forma portátil, as ferramentas nativas do harness. O filtro das ferramentas do host continua funcionando, mas tentar filtrar as ferramentas internas do ACP gera um erro.
• Se o catálogo de ferramentas do host mudar, a implementação do ACP precisará atualizar sua lista de ferramentas MCP. Uma implementação desatualizada falha de forma explícita.

As páginas da Vercel consultadas para este lançamento não informam um preço separado para o @ai-sdk/harness-acp. Isso não quer dizer que existam “agentes grátis”. A arquitetura ainda inclui um caminho de autenticação do modelo e exige uma sandbox com acesso à rede, então os custos e controles atuais do runtime continuam valendo.

O limite mais profundo é a fidelidade. O ACP oferece uma conexão comum, mas um adaptador direto consegue expor com mais precisão o comportamento nativo de um harness. A padronização reduz o trabalho de integração; ela não apaga o runtime que existe por baixo.

O que fazer agora

Minha regra é simples.

Vale agir nesta semana se você mantém um harness compatível com ACP que ainda não possui um adaptador direto para o AI SDK ou se sua equipe de plataforma precisa colocar vários desses runtimes atrás de um único contrato de aplicação. Crie um perfil enxuto, fixe a versão do pacote e teste cada permissão e caminho de falha.

É melhor esperar se a política de produção não aceita um pacote experimental, se o uso exato por etapa é indispensável ou se a compactação manual e o direcionamento no meio da execução são controles essenciais.

Continue no adaptador direto se usa Claude Code ou Codex. Esse já é o caminho recomendado pela Vercel e comprime menos comportamentos na fronteira do protocolo.

Nada muda para quem chama modelos diretamente, usa um agente de programação como usuário final ou não precisa executar um harness dentro da própria aplicação.

Para receber mais análises em linguagem direta sobre as ferramentas que estão mudando a forma de entregar software, assine a newsletter.