KI-Agenten mit Vercels AI SDK: Der ACP-Harness-Adapter erklärt

Was Vercel tatsächlich veröffentlicht hat

Zunächst müssen die Ebenen sauber getrennt werden, die oft durcheinandergeraten.

Ein Modell erzeugt die nächste Antwort. Ein Harness macht daraus einen arbeitsfähigen Agenten, indem es Sitzungen, Tools, Freigaben, Sandboxes, Anweisungen, Kontextkomprimierung und den Arbeitszyklus verwaltet. ACP, kurz für Agent Client Protocol, schafft eine gemeinsame Kommunikationsgrundlage für Client und Harness.

Vercels HarnessAgent bot Anwendungen bereits eine einheitliche API für die Arbeit mit Harnesses. Es fehlte jedoch die Verbindungsschicht. Vor diesem Release benötigte Vercel für jede Laufzeitumgebung einen eigenen Adapter, darunter Claude Code, Codex, Pi, Deep Agents und OpenCode.

Der neue ACP-Harness-Adapter kapselt das Protokoll statt einer bestimmten Laufzeitumgebung. createACP erhält das NPM-Paket, das ACP für das jeweilige Harness implementiert, sowie die ausführbare Datei, Authentifizierungsregeln, die Zuordnung von Anweisungen und die Berechtigungszuordnung. Der generische Adapter übernimmt anschließend die Brücke, den ACP-Client, die Tool-Weiterleitung, Events, Freigaben und den gesamten Sitzungslebenszyklus.

Genau diese Aufteilung ist der Kern: Vercel verantwortet die gemeinsame Brücke, das Laufzeitprofil die Details, die sich von Harness zu Harness unterscheiden.

Der Adapter unterstützt derzeit ACP-Version 1 – und ausschließlich Version 1. Die Kompatibilität gilt an der Protokollgrenze; sie garantiert nicht, dass sich alle angeschlossenen Harnesses gleich verhalten.

Vercel formuliert die Entscheidung eindeutig: Für Claude Code und Codex sind @ai-sdk/harness-claude-code beziehungsweise @ai-sdk/harness-codex vorgesehen. @ai-sdk/harness-acp passt dann, wenn ein Harness ein kompatibles Paket, aber keinen direkten Adapter besitzt.

Warum das für KI-Agenten wichtig ist

Entscheidend verändert hat sich der Integrationsaufwand.

Ein DevTools-Team muss Sitzungsverwaltung, Event-Übersetzung, Freigabelogik, Host-Tool-Weiterleitung und Lebenszyklussteuerung nicht mehr neu aufbauen, nur um eine weitere ACP-Laufzeitumgebung hinter HarnessAgent zu platzieren. Es erstellt das Laufzeitprofil; der Rest der Anwendung bleibt auf derselben Harness-API.

Auch die Produktschicht bleibt dadurch stabiler. Sowohl HarnessAgent.generate() als auch HarnessAgent.stream() liefern mit dem AI SDK kompatible Ergebnisse. Wer bereits useChat einsetzt, kann den bestehenden Oberflächenablauf beibehalten und lediglich den Worker dahinter austauschen.

Das Release macht ein Harness weder schneller noch günstiger oder leistungsfähiger. Auch werden ACP-Implementierungen dadurch nicht identisch. Ebenso wenig ersetzt der Adapter die Sandbox: Jedes ACP-Harness benötigt weiterhin eine Netzwerk-Sandbox mit mindestens einem freigegebenen Port.

Wer Claude Code, Codex oder einen anderen Coding Agent direkt nutzt, merkt von diesem Feature in der Regel wenig. Es richtet sich an Teams, die ein Produkt um solche Agenten herum entwickeln.

Wer den Adapter unmittelbar einsetzen kann

Ein DevTools-Gründer bringt sein Harness ins AI SDK

Angenommen, ein Unternehmen bietet ein Coding-Harness an und veröffentlicht bereits ein ACP-kompatibles NPM-Paket. Dann lässt sich nun ein einziges createACP-Profil definieren, das Nutzern des AI SDK einen unterstützten Zugang zur eigenen Laufzeitumgebung eröffnet.

Der Nutzen liegt in der Distribution. Das Team pflegt Installation, Authentifizierung, Anweisungen und Berechtigungen für sein Paket. Vercels Adapter kümmert sich um die gemeinsame Infrastruktur ringsherum.

Ein Plattformtechniker unterstützt mehrere Laufzeitumgebungen

Eine mittelgroße Engineering-Plattform könnte einen Agenten für Repository-Reparaturen, einen zweiten für Migrationen und ein internes Harness für unternehmensspezifische Automatisierung benötigen. Der Plattformtechniker behält einen gemeinsamen Vertrag für Sitzungen und Ergebnisse bei und wählt für jede Aufgabe ein anderes Harness-Profil.

Die Verhaltensunterschiede verschwinden dadurch nicht. Sie wandern in benannte Profile und lassen sich dort leichter prüfen als in voneinander getrennten Orchestrierungsstacks.

Ein SaaS-Team besitzt bereits eine Oberfläche für das AI SDK

Ein Produktteam kann eine ACP-gestützte Coding-Laufzeit hinter eine vorhandene AI-SDK-Anwendung setzen, ohne die Chat-Oberfläche neu zu bauen. Die konkrete Änderung findet auf dem Server statt: Harness-Profil erstellen, Sandbox anbinden, Sitzung starten und wieder ein gestreamtes oder generiertes Ergebnis jenes Typs liefern, den die Oberfläche bereits verarbeitet.

Falls zunächst noch der Coding Agent selbst ausgewählt werden muss, statt ihn in ein Produkt zu integrieren, hilft zuerst der Vergleich der Coding Agents. Dieser Adapter wird erst nach dieser Produktentscheidung relevant.

Ein Sicherheitstechniker definiert die Grenze

Für die Sicherheit gibt es klar erkennbare Kontrollpunkte. Zugangsdaten lassen sich so vermitteln, dass der ACP-Prozess in der Sandbox nur Platzhalter sieht, während ausgehende Anfragen die echten Werte erhalten. Berechtigungsmodi können den tatsächlich unterstützten Modi der Laufzeitumgebung zugeordnet werden; nicht unterstützte Optionen erhalten null und schlagen damit fehl, statt den Zugriff unbemerkt auszuweiten.

Das schafft nicht automatisch Sicherheit. Es schafft aber einen eindeutigen Ort, an dem sich Sicherheitsregeln festlegen und testen lassen.

Der Weg zur ersten Integration

Ein vollständiges Beispiel aus der Dokumentation

Zunächst werden Harness, ACP-Adapter und die Pakete für Vercel Sandbox installiert:

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

Das kürzeste belastbare Beispiel verwendet Vercels vollständiges Codex-ACP-Profil, weil es Paketinstallation, direkte Zugangsdaten, die Konfiguration von AI Gateway, Anweisungen und Berechtigungen an einer Stelle zeigt. Es demonstriert die Integration und ist keine Empfehlung, Codex über ACP anzubinden. Für eine echte Codex-Integration bevorzugt Vercel den direkten Codex-Adapter.

Der folgende Code entspricht dem aktuell dokumentierten Profil und Aufrufablauf. Für die direkte Authentifizierung muss entweder CODEX_API_KEY oder OPENAI_API_KEY verfügbar sein. Liegt AI_GATEWAY_API_KEY oder VERCEL_OIDC_TOKEN vor, wählt der voreingestellte Pfad auth: 'auto' stattdessen 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',
        },
      },
    },
  },
});

Ein entscheidendes Detail wird häufig übersehen: Ein Laufzeitprofil besteht nicht nur aus Paketname und API-Schlüssel. Auch Berechtigungszuordnung, Anweisungszuordnung, Sandbox-Port, Zugangsdaten-Grenze und Sitzungsbereinigung gehören zur Integration.

Die Einschränkungen ohne Beschönigung

Die Harness-Pakete sind experimentell. Zwischen Releases ist mit Breaking Changes zu rechnen; diese Abhängigkeit sollte in Produktion daher nicht unkontrolliert aktualisiert werden.

Die Versionsfixierung verlangt eine bewusste Entscheidung. Die einfache Paketquelle kann eine exakte Version festschreiben, wie im Beispiel @agentclientprotocol/codex-acp auf 1.1.4. Fehlt die Versionsangabe, installiert die Sandbox das latest-Tag des Pakets, und diese Version fließt nicht in die Harness-Identität ein. Für reproduzierbare Builds ist die gesperrte Paketquelle mit package.json und pnpm-lock.yaml vorgesehen; Vercel installiert sie über pnpm install --frozen-lockfile.

ACP-Version 1 weist außerdem spürbare Lücken auf:

• Grenzen zwischen Modellschritten und die Nutzung je Schritt werden nicht offengelegt. Der Adapter leitet die Grenzen ab; die Nutzung pro Schritt bleibt unbekannt.
• Eine portable API für manuelle Kontextkomprimierung oder Steuerung während eines laufenden Turns fehlt.
• Die eingebauten Tools des Harness lassen sich nicht portabel filtern. Host-Tools können weiterhin gefiltert werden, ein Filterversuch für eingebaute ACP-Tools löst jedoch einen Fehler aus.
• Ändert sich der Host-Tool-Katalog, muss die ACP-Implementierung ihre MCP-Tool-Liste aktualisieren. Eine veraltete Implementierung schlägt ausdrücklich fehl.

Auf den für dieses Release geprüften Vercel-Seiten wird kein eigener Preis für @ai-sdk/harness-acp genannt. Daraus sollte nicht abgeleitet werden, KI-Agenten seien kostenlos. Zur Architektur gehören weiterhin ein Pfad zur Modellauthentifizierung und eine notwendige Netzwerk-Sandbox; die bisherigen Laufzeitkosten und Kontrollmechanismen gelten also weiter.

Die grundlegendere Grenze ist die Nähe zur Laufzeitumgebung. ACP schafft eine gemeinsame Verbindung, während ein direkter Adapter das native Verhalten eines Harness präziser abbilden kann. Standardisierung spart Integrationsarbeit, beseitigt aber nicht die Eigenheiten der zugrunde liegenden Laufzeitumgebung.

Was jetzt sinnvoll ist

Meine Faustregel ist einfach.

Noch diese Woche aktiv werden sollten Teams, die ein ACP-kompatibles Harness ohne direkten AI-SDK-Adapter betreiben oder mehrere solcher Laufzeitumgebungen hinter einem gemeinsamen Anwendungsvertrag bündeln müssen. Dafür genügt ein schlankes Profil; das Paket sollte fixiert und jeder Berechtigungs- sowie Fehlerpfad getestet werden.

Abwarten ist sinnvoll, wenn die Produktionsrichtlinien kein experimentelles Paket zulassen, wenn eine exakte Nutzung je Modellschritt benötigt wird oder wenn manuelle Kontextkomprimierung und Steuerung während des Turns unverzichtbar sind.

Beim direkten Adapter bleiben sollten Nutzer von Claude Code oder Codex. Das ist bereits der von Vercel empfohlene Weg, bei dem weniger Laufzeitverhalten durch die Protokollgrenze gepresst wird.

Nicht betroffen sind Anwendungen, die Modelle direkt aufrufen, sowie Endnutzer eines Coding Agent und Teams, die kein Harness innerhalb einer eigenen Anwendung betreiben müssen.

Weitere verständliche Einordnungen zu den Tools, die Softwareteams verändern, gibt es im Newsletter.