Vercel's AI SDK ACP harness adapter, explained

What Vercel actually shipped

Start with the layers people tend to mix together.

A model produces the next response. A harness turns that model into a worker by managing sessions, tools, approvals, sandboxes, instructions, compaction, and the work loop. ACP, short for Agent Client Protocol, gives a client and a harness a common way to talk.

Vercel's HarnessAgent already gave applications one API for working with harnesses. The missing piece was the connector. Before this release, Vercel needed a separate adapter for each runtime, including Claude Code, Codex, Pi, Deep Agents, and OpenCode.

The new ACP harness adapter wraps the protocol instead of one named runtime. You give createACP the NPM package that implements ACP for your harness, its executable, authentication rules, instruction mapping, and permission mapping. The generic adapter then handles the bridge, ACP client, tool relay, events, approvals, and session lifecycle.

That split is the whole idea: Vercel owns the common bridge. The runtime profile owns the details that differ between harnesses.

The adapter currently supports ACP version 1, and only version 1. This is compatibility at the protocol boundary, not a promise that every harness behaves the same once connected.

Vercel is explicit about the choice. Use @ai-sdk/harness-claude-code or @ai-sdk/harness-codex for those two runtimes. Use @ai-sdk/harness-acp when the harness has a compatible package but no direct adapter.

Why this matters

The axis that moved is integration work.

A devtools team no longer needs to recreate session handling, event translation, approval plumbing, host-tool relay, and lifecycle behavior just to place another ACP runtime behind HarnessAgent. It writes the runtime profile and keeps the rest of the application on the same harness API.

That also protects the product layer. Both HarnessAgent.generate() and HarnessAgent.stream() return AI SDK-compatible results. A team already using useChat can keep its interface flow while changing the worker behind it.

The release does not make a harness faster, cheaper, or more capable. It does not make ACP implementations identical. It does not replace the sandbox either. Every ACP harness still needs a network sandbox with at least one exposed port.

People using Claude Code, Codex, or another coding agent directly are mostly unaffected. This feature is for the people building the product around those agents.

Who can use it tomorrow

A devtools founder adding AI SDK support

Say your company ships a coding harness and already publishes an ACP-compatible NPM package. You can now define one createACP profile and hand AI SDK users a supported path into your runtime.

The payoff is distribution. Your team maintains the package-specific install, auth, instructions, and permissions. Vercel's adapter handles the shared plumbing around them.

A platform engineer supporting several runtimes

A mid-size engineering platform may want one agent for repository repair, another for migration work, and an internal harness for company-specific automation. The platform engineer can keep one session and result contract, then choose a different harness profile for each job.

That does not erase behavior differences. It moves those differences into named profiles, where they are easier to review than separate orchestration stacks.

A SaaS team with an existing AI SDK interface

A product team can add an ACP-backed coding worker behind an existing AI SDK application without rebuilding its chat surface. The concrete change happens on the server: create the harness profile, attach a sandbox, start a session, and return the same kind of streamed or generated result the UI already consumes.

If you are still choosing the agent itself, rather than integrating one into a product, start with the coding agent comparison. This adapter matters after that product decision.

A security engineer defining the boundary

The security engineer gets clear control points. Credentials can be brokered so the sandboxed ACP process sees placeholders while real values are added to outbound requests. Permission modes can be mapped to the modes the runtime actually supports, with unsupported choices set to null so they fail instead of silently widening access.

The result is not automatic safety. It is a clear place to encode and test the safety rules.

The onboarding path

A complete documented example

Install the harness, ACP adapter, and Vercel Sandbox packages:

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

The shortest honest demo uses Vercel's complete Codex ACP profile because it shows package installation, direct credentials, AI Gateway configuration, instructions, and permissions in one place. It is a wiring example, not a recommendation to choose ACP for Codex. Vercel prefers the direct Codex adapter for a real Codex integration.

The code below is the current documented profile and call flow. Make either CODEX_API_KEY or OPENAI_API_KEY available for direct authentication. If AI_GATEWAY_API_KEY or VERCEL_OIDC_TOKEN is available, the default auth: 'auto' path chooses AI Gateway instead.

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',
        },
      },
    },
  },
});

The detail people get wrong is treating the runtime profile as a package name plus an API key. The permission mapping, instruction mapping, sandbox port, credential boundary, and session cleanup are part of the integration too.

The honest part

The harness packages are experimental. Breaking changes between releases are expected, so this is not a quiet dependency to float across production.

Package pinning needs an explicit choice. The simple source can pin an exact version, as the example pins @agentclientprotocol/codex-acp to 1.1.4. If you omit the version, the sandbox installs the package's latest tag and that version stays out of the harness identity. If you need a reproducible build, use the locked source with a package.json and pnpm-lock.yaml; Vercel installs it with pnpm install --frozen-lockfile.

ACP version 1 also leaves real gaps:

• It does not expose model-step boundaries or per-step usage. The adapter infers the boundaries, and per-step usage remains unknown.
• It has no portable manual compaction or mid-turn steering API.
• It cannot portably filter the harness's built-in tools. Filtering host tools still works, but trying to filter ACP built-ins throws.
• If the host-tool catalog changes, the ACP implementation must refresh its MCP tool list. A stale implementation fails explicitly.

There is no separate price for @ai-sdk/harness-acp stated on the Vercel pages read for this release. Do not turn that into “free agents.” The architecture still includes a model-authentication path and a required network sandbox, so your existing runtime costs and controls still apply.

The deeper limit is fidelity. ACP gives you a common connection, but a direct adapter can expose a harness's native behavior more closely. Standardization saves integration work. It does not erase the runtime underneath.

What to do now

My rule is simple.

Act this week if you own an ACP-compatible harness with no direct AI SDK adapter, or if your platform team needs to place several such runtimes behind one application contract. Build a thin profile, pin the package, and test every permission and failure path.

Wait if your production policy cannot accept an experimental package, if you require accurate per-step usage, or if manual compaction and mid-turn steering are core controls.

Stay on the direct adapter if you use Claude Code or Codex. You already have the path Vercel recommends, with less behavior squeezed through the protocol boundary.

You are unaffected if you call models directly, use a coding agent as an end user, or have no need to run a harness inside your own application.

If you want more plain-English breakdowns of the tools changing how teams ship, join the newsletter.