Vercel's fx AI SDK harness adapter, explained

Vercel added fx to the AI SDK harness layer on August 31, 2026. You can now run the lightweight coding agent through the same HarnessAgent interface used for other coding harnesses, but the useful win is less integration work, not a magically interchangeable agent.

What the fx adapter actually is

fx is a coding-agent harness and command-line tool. A harness is the runtime around a model call: it manages the workspace, tools, skills, sessions, permissions, compaction, and subagents that let a model do a real coding job.

That makes this different from adding another model provider to AI SDK. You aren't swapping one text model for another. You're adding a complete coding runtime behind an interface your application can already speak.

The new @ai-sdk/harness-fx adapter sits between HarnessAgent and fx. Underneath, it uses Agent Client Protocol, or ACP, as the common language for starting a session, sending a prompt, streaming progress, handling tools, and cleaning up.

The path now looks like this: your app talks to HarnessAgent, the fx adapter translates that request into ACP, fx runs inside a network sandbox, and its model requests go through Vercel AI Gateway.

That's the whole trick. The application gets one interface. The harness keeps its own behavior.

Why this matters, and what it does not prove

The integration tax is the part that moved. If your product already wraps HarnessAgent, adding fx no longer means building another session manager, stream parser, permission bridge, and cleanup path.

That gives a platform team a cleaner way to compare harnesses behind one product surface. It also lets a smaller app add another coding runtime without maintaining a separate orchestration stack.

The current fx site labels the agent v0.0.7, experimental, and Apache-2.0 licensed. The AI SDK harness packages are experimental too. So this is ready for a contained engineering spike, but it is not a quiet dependency you should assume will stay stable.

There is no published before-and-after number for setup time, latency, coding quality, or cost savings. Do not turn “one API” into an unsupported performance claim. The adapter reduces custom plumbing. You still have to evaluate whether fx solves your repository tasks well enough.

People using fx directly in a terminal are mostly unaffected. The same is true for an app that only calls a model with ordinary AI SDK generation functions and never runs a coding harness. This change matters when you are embedding coding agents into a product or an internal platform.

Who can use it tomorrow

A solo founder adding repository repair to a SaaS

Say your app already accepts a Git repository and asks an agent to fix a failing test. You can keep the existing session and streaming path, then select fx as the harness for a trial cohort. The payoff is a real comparison inside the same product instead of a separate fx prototype with its own backend.

An agent-platform team running harness evaluations

A platform team can send the same repair prompt through fx and another supported harness, capture the same application-level stream, and compare task completion. Claude Code, Cline, Codex, Cursor, Deep Agents, Grok Build, OpenCode, and Pi are also listed in the harness layer.

The comparison still needs harness-specific scoring. A common interface does not make permission behavior, tools, compaction, or internal planning identical.

A software agency isolating client work

An agency can start one Vercel Sandbox for a client-repository fix, stream the work into its existing operator dashboard, and destroy the session when the job ends. That keeps the client workspace away from the host process and gives the team one lifecycle pattern across agent choices.

An internal developer-tools team handling small fixes

A developer-tools team can offer fx for narrow jobs such as fixing a test or editing a small feature while keeping its existing skills and MCP server configuration at the harness layer. The payoff is another runtime option without another front end.

The hands-on path

The current fx harness documentation gives a complete TypeScript path. Use it inside an AI SDK project that can run TypeScript.

1. 1

   Install the three packages

   Add the harness core, the fx adapter, and the Vercel Sandbox adapter:

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

2. 2

   Give the runtime one Gateway credential

   Set either VERCEL_OIDC_TOKEN or AI_GATEWAY_API_KEY in the runtime that starts the agent. When both exist, the adapter prefers VERCEL_OIDC_TOKEN.

   Do not put the credential in source code. The sandbox needs network access because the first session downloads fx and later sessions need the network for model and web requests.

3. 3

   Create, stream, and destroy one session

   This is the documented basic example, including cleanup on both success and failure:

   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

   Test permissions and events before real work

   Run a harmless repository task first. Confirm that your application receives the text stream, that a permission request reaches the operator, and that session.destroy() runs when the task fails.

   The detail people miss is the exposed port. fx talks over an ACP bridge, so the network sandbox needs at least one. The example uses port 4000.

If you need to build an adapter for a different ACP-compatible agent, the related AI SDK ACP harness adapter explainer covers that lower layer.

What it costs

fx itself is open source under Apache-2.0, but an embedded run still incurs model-token and Sandbox costs.

AI Gateway charges $0 markup and $0 platform fee on tokens. Each Vercel team gets $5 per month in free-tier credit for a subset of models, with lower per-model rate limits. Buying Gateway credits moves the team to the paid tier and ends that monthly free credit.

For the sandbox, Vercel's own iad1 example prices a 5-minute AI code-validation job with 2 vCPUs and 4 GB of memory at about $0.03 under 100% CPU utilization. At that example rate, 1,000 jobs are about $30 of Sandbox compute before model tokens. Actual Active CPU cost can be lower while the agent waits for model or network I/O.

Pro Sandbox usage first draws against the plan's $20 monthly credit. The default Sandbox timeout is 5 minutes, so set the task timeout deliberately and destroy finished sessions instead of leaving them open.

The five production limits

1. Both layers are experimental

The fx product and the AI SDK harness packages carry experimental labels. The harness documentation explicitly warns that breaking changes can land between releases.

2. The adapter tracks the latest fx release

The first session runs fx's canonical installer, and that installer resolves the latest release. The adapter fixes the installation source, executable, launch command, and ACP version, so createFx() cannot pin those details. That is a reproducibility problem if every production run must use an approved binary version.

3. Permission modes do not map cleanly

allow-reads and allow-edits both map to fx's ask mode. allow-all maps to code. fx does not expose a mode that permits file edits while still requiring approval for terminal commands, so you cannot assume your application-level permission names preserve their exact meaning.

4. ACP v1 leaves observability gaps

Ordinary native tool events can omit the programmatic tool name and raw input. ACP v1 also lacks model-step boundaries and per-step usage, which makes fine-grained traces and token attribution weaker than the common interface suggests.

5. Several controls are not portable

There is no portable manual compaction, mid-turn steering, or built-in tool filtering through this path. Schema-backed structured output is unsupported too. An ACP adapter can expose less of a harness than a direct adapter, which is why Vercel recommends direct adapters for Claude Code and Codex when they are available.

What to do now

Use the adapter this week if you already have a HarnessAgent application, want to evaluate fx on a contained repository task, and can tolerate an experimental dependency. Start with a single task class and record completion, permission prompts, cleanup, model spend, and Sandbox spend.

Wait if you need a pinned fx binary, structured output, per-step usage, mid-turn steering, or a clean split between file-edit permission and terminal approval. Those are interface limits, not configuration mistakes.

You are unaffected if you run fx only as a local CLI or your app only makes model calls. There is no reason to add a harness layer just because another adapter exists.

For more plain-English breakdowns of the tools operators are actually shipping with, join the newsletter.