Vercel fx AI SDK Harness Adapter erklärt: Architektur, Kosten und Limits

Vercel hat fx am August 31, 2026 zur AI SDK Harness-Schicht hinzugefügt. Sie können den leichtgewichtigen Coding-Agenten nun über dieselbe HarnessAgent-Schnittstelle ausführen, die auch für andere Coding-Harnesses genutzt wird. Der tatsächliche Nutzen liegt jedoch im reduzierten Integrationsaufwand, nicht in einem magisch austauschbaren Agenten.

Was der vercel fx ai sdk harness adapter eigentlich ist

fx ist ein Coding-Agent-Harness und Kommandozeilen-Tool. Ein Harness ist die Laufzeitumgebung um einen Modellaufruf: Er verwaltet den Workspace, Tools, Skills, Sitzungen, Berechtigungen, Kompaktierung und Subagenten, die es einem Modell ermöglichen, eine reale Programmieraufgabe zu erledigen.

Das unterscheidet diesen Schritt grundlegend vom Hinzufügen eines weiteren Modellanbieters zum AI SDK. Sie tauschen nicht einfach ein Textmodell gegen ein anderes aus. Sie binden eine vollständige Programmierlaufzeitumgebung an eine Schnittstelle an, die Ihre Anwendung bereits beherrscht.

Der neue @ai-sdk/harness-fx Adapter sitzt zwischen HarnessAgent und fx. Unter der Haube nutzt er das Agent Client Protocol (ACP) als gemeinsame Sprache, um Sitzungen zu starten, Prompts zu übermitteln, Fortschritte zu streamen, Tools zu verwalten und Ressourcen aufzuräumen.

Der Ablauf sieht nun so aus: Ihre Anwendung spricht mit HarnessAgent, der fx-Adapter übersetzt die Anfrage in ACP, fx läuft innerhalb einer Netzwerk-Sandbox, und die Modellanfragen laufen über das Vercel AI Gateway.

Das ist der ganze Mechanismus: Die Anwendung erhält eine einheitliche Schnittstelle, während der Harness sein individuelles Verhalten beibehält.

Warum das wichtig ist – und was es nicht beweist

Verändert hat sich vor allem der Integrationsaufwand. Wenn Ihr Produkt bereits HarnessAgent kapselt, bedeutet das Hinzufügen von fx nicht mehr, dass Sie einen weiteren Sitzungsmanager, Stream-Parser, Berechtigungs-Bridge und Bereinigungspfad implementieren müssen.

Plattform-Teams erhalten dadurch einen sauberen Weg, verschiedene Harnesses hinter einer einzigen Produktoberfläche zu vergleichen. Kleinere Anwendungen können zudem eine weitere Programmierlaufzeitumgebung ergänzen, ohne einen separaten Orchestrierungs-Stack pflegen zu müssen.

Auf der aktuellen fx-Website wird der Agent als v0.0.7, experimentell und unter Apache-2.0 lizenziert geführt. Auch die AI SDK Harness-Pakete sind experimentell. Das Setup eignet sich daher für einen gezielten technischen Test, ist aber keine ruhige Abhängigkeit, bei der man von dauerhafter Stabilität ausgehen sollte.

Es gibt keine veröffentlichten Vorher-Nachher-Zahlen zu Einrichtungszeit, Latenz, Codequalität oder Kosteneinsparungen. Man sollte „eine einheitliche API“ nicht mit unbelegten Leistungsvorteilen verwechseln. Der Adapter reduziert lediglich individuellen Infrastruktur-Code. Ob fx die Aufgaben in Ihren Repositories gut genug löst, müssen Sie weiterhin selbst evaluieren.

Wer fx direkt im Terminal nutzt, ist davon kaum betroffen. Dasselbe gilt für Anwendungen, die Modelle nur über gewöhnliche AI SDK-Generierungsfunktionen aufrufen und keinen Coding-Harness ausführen. Relevant ist diese Neuerung, wenn Sie Coding-Agenten in ein Produkt oder eine interne Plattform einbetten.

Wer die Integration morgen einsetzen kann

Solo-Gründer, die Repository-Reparaturen in ein SaaS integrieren

Angenommen, Ihre Anwendung nimmt ein Git-Repository entgegen und beauftragt einen Agenten mit der Reparatur eines fehlschlagenden Tests. Sie können den bestehenden Sitzungs- und Streaming-Pfad beibehalten und fx als Harness für eine Testgruppe auswählen. Der Vorteil ist ein echter Vergleich innerhalb desselben Produkts statt eines separaten fx-Prototyps mit eigenem Backend.

Plattform-Teams für Agenten, die Harness-Vergleiche durchführen

Ein Plattform-Team kann denselben Reparatur-Prompt an fx und einen anderen unterstützten Harness senden, denselben Stream auf Anwendungsebene erfassen und die Aufgabenerfüllung direkt vergleichen. Neben fx sind auch Claude Code, Cline, Codex, Cursor, Deep Agents, Grok Build, OpenCode und Pi in der Harness-Schicht gelistet.

Der Vergleich erfordert weiterhin harnessespezifische Bewertungskriterien. Eine gemeinsame Schnittstelle vereinheitlicht weder Berechtigungsstrukturen noch Tools, Kompaktierung oder interne Planungslogik.

Softwareagenturen mit isolierten Kundenprojekten

Eine Agentur kann eine dedizierte Vercel Sandbox für die Fehlerbehebung in einem Kunden-Repository starten, die Arbeit in ihr bestehendes Operator-Dashboard streamen und die Sitzung nach Abschluss beenden. Das trennt den Workspace des Kunden vom Host-Prozess und bietet ein einheitliches Lifecycle-Muster über verschiedene Agenten hinweg.

Interne Tooling-Teams für kleinere Code-Anpassungen

Ein internes Entwicklertools-Team kann fx für eng umrissene Aufgaben wie das Beheben eines Tests oder kleine Feature-Anpassungen bereitstellen, während bestehende Skills und MCP-Server-Konfigurationen auf der Harness-Ebene erhalten bleiben. Der Gewinn ist eine zusätzliche Laufzeitumgebung ohne zusätzliche Benutzeroberfläche.

Schritt-für-Schritt-Implementierung

Die aktuelle fx-Harness-Dokumentation beschreibt den vollständigen Ablauf in TypeScript. Nutzen Sie diesen Pfad innerhalb eines AI SDK-Projekts mit TypeScript-Unterstützung.

1. 1

   Die drei Pakete installieren

   Installieren Sie den Harness-Kern, den fx-Adapter und den Vercel Sandbox-Adapter:

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

2. 2

   Gateway-Zugangsdaten in der Laufzeitumgebung hinterlegen

   Setzen Sie entweder VERCEL_OIDC_TOKEN oder AI_GATEWAY_API_KEY in der Umgebung, die den Agenten startet. Falls beide vorhanden sind, bevorzugt der Adapter VERCEL_OIDC_TOKEN.

   Hinterlegen Sie die Zugangsdaten keinesfalls im Quellcode. Die Sandbox benötigt Netzwerkzugriff, da die erste Sitzung fx herunterlädt und spätere Sitzungen das Netzwerk für Modell- und Webanfragen verwenden.

3. 3

   Eine Sitzung erstellen, streamen und beenden

   Hier ist das dokumentierte Basisbeispiel inklusive Bereinigung im Erfolgs- und Fehlerfall:

   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

   Berechtigungen und Ereignisse vor dem Produktiveinsatz testen

   Führen Sie zuerst eine unkritische Repository-Aufgabe aus. Prüfen Sie, ob Ihre Anwendung den Text-Stream empfängt, Berechtigungsanfragen beim Operator ankommen und session.destroy() auch bei einem Abbruch zuverlässig aufgerufen wird.

   Ein häufig übersehenes Detail ist der freigegebene Port: fx kommuniziert über eine ACP-Bridge, weshalb die Netzwerk-Sandbox mindestens einen offenen Port benötigt. Das Beispiel nutzt Port 4000.

Wenn Sie einen Adapter für einen anderen ACP-kompatiblen Agenten entwickeln müssen, beschreibt der entsprechende Leitfaden zum AI SDK ACP Harness Adapter diese Basisschicht.

Was der Betrieb kostet

fx selbst ist unter Apache-2.0 quelloffen, die eingebettete Ausführung verursacht jedoch Modell-Token- und Sandbox-Kosten.

Das AI Gateway berechnet 0 USD Aufschlag und 0 USD Plattformgebühr auf Tokens. Jedes Vercel-Team erhält monatlich ein Guthaben von 5 USD im Free-Tier für eine Auswahl an Modellen mit niedrigeren Rate-Limits pro Modell. Der Kauf von Gateway-Guthaben stuft das Team in den bezahlten Tarif ein und beendet das monatliche Gratisguthaben.

Für die Sandbox veranschlagt Vercels eigenes iad1-Rechenbeispiel einen 5-minütigen KI-Codevalidierungsjob mit 2 vCPUs und 4 GB Arbeitsspeicher bei 100% CPU-Auslastung mit etwa 0.03 USD. Bei diesem Beispielwert kosten 1,000 Durchläufe rund 30 USD an Sandbox-Rechenleistung vor Abzug der Modell-Tokens. Die tatsächlichen Active-CPU-Kosten können geringer ausfallen, wenn der Agent auf Modellantworten oder Netzwerk-I/O wartet.

Die Nutzung der Pro Sandbox wird zunächst mit dem monatlichen Guthaben von 20 USD des Tarifs verrechnet. Der Standard-Timeout der Sandbox liegt bei 5 Minuten. Daher sollten Sie Aufgaben-Timeouts bewusst definieren und beendete Sitzungen sofort schließen, statt sie offen zu lassen.

Die fünf Grenzen für den Produktiveinsatz

1. Beide Ebenen sind experimentell

Sowohl das fx-Projekt als auch die AI SDK Harness-Pakete sind als experimentell eingestuft. Die Dokumentation warnt ausdrücklich vor potenziellen Breaking Changes zwischen einzelnen Releases.

2. Der Adapter erzwingt die jeweils neueste fx-Version

Die erste Sitzung führt das offizielle Installationsskript von fx aus, welches stets die neueste Version bezieht. Der Adapter legt Installationsquelle, Binärdatei, Startbefehl und ACP-Version fest, sodass createFx() diese Details nicht fixieren kann. Das erschwert die Reproduzierbarkeit, falls in Ihrer Produktionsumgebung freigegebene Binärversionen zwingend vorgeschrieben sind.

3. Berechtigungsmodi lassen sich nicht 1:1 abbilden

Sowohl allow-reads als auch allow-edits werden auf den fx-Modus ask gemappt. allow-all entspricht code. fx bietet keinen Modus, der Dateiänderungen erlaubt, aber für Terminalbefehle weiterhin eine Bestätigung verlangt. Sie können daher nicht davon ausgehen, dass Berechtigungsnamen Ihrer Anwendungsebene ihr Verhalten exakt beibehalten.

4. ACP v1 hat Lücken bei der Observability

Standardmäßige native Tool-Ereignisse enthalten mitunter weder den programmatischen Tool-Namen noch die Rohdaten der Eingabe. Zudem fehlen in ACP v1 Modellschritt-Grenzen und verbrauchsgenaue Step-Angaben, was detaillierte Traces und Token-Zuordnungen ungenauer macht, als die einheitliche Schnittstelle vermuten lässt.

5. Mehrere Steuerungsfunktionen sind nicht portierbar

Über diesen Pfad gibt es weder eine portable manuelle Kompaktierung noch Steuerungsbefehle während eines Turns (Mid-Turn Steering) oder integrierte Tool-Filter. Auch schemabasierte strukturierte Ausgaben werden nicht unterstützt. Ein ACP-Adapter kann systembedingt weniger Funktionen eines Harnesses abbilden als ein direkter Adapter. Aus diesem Grund empfiehlt Vercel für Claude Code und Codex direkte Adapter, sofern verfügbar.

Nächste Schritte

Setzen Sie den Adapter jetzt ein, wenn Sie bereits eine auf HarnessAgent basierende Anwendung betreiben, fx für isolierte Repository-Aufgaben evaluieren wollen und eine experimentelle Abhängigkeit tragen können. Beginnen Sie mit einer einzelnen Aufgabenklasse und messen Sie Erfolgsrate, Berechtigungsabfragen, Bereinigungsverhalten sowie Modell- und Sandbox-Kosten.

Warten Sie ab, wenn Sie fest definierte fx-Versionen, strukturierte Ausgaben, schrittweise Nutzungsdaten, Mid-Turn Steering oder eine strikte Trennung zwischen Dateiberechtigungen und Terminalbestätigungen benötigen. Dies sind architektonische Limits der Schnittstelle, keine Konfigurationsfehler.

Wer fx ausschließlich lokal über das Terminal nutzt oder mit seiner Anwendung lediglich Standard-Modellaufrufe tätigt, muss nichts unternehmen. Es gibt keinen Grund, eine Harness-Schicht einzuführen, nur weil ein neuer Adapter verfügbar ist.

Für weitere praxisnahe Analysen der Tools, die Entwicklungsteams tatsächlich in Produktion einsetzen, abonnieren Sie den Newsletter.