コーディングエージェント基盤をつなぐVercel AI SDKのACPアダプター

Vercelがコーディングエージェント向けに提供したもの

まず、混同されやすいレイヤーを整理しましょう。

モデルは次の応答を生成します。ハーネスはセッション、ツール、承認、Sandbox、指示、コンテキスト圧縮、作業ループを管理し、そのモデルを実際に働く仕組みに変えます。Agent Client Protocolの略であるACPは、クライアントとハーネスが共通の方法で通信するためのプロトコルです。

VercelのHarnessAgentには、複数のハーネスを1つのAPIで扱う仕組みがすでにありました。足りなかったのは、それぞれをつなぐコネクターです。今回のリリース以前は、Claude Code、Codex、Pi、Deep Agents、OpenCodeを含め、ランタイムごとに別々のアダプターをVercelが用意する必要がありました。

新しいACPハーネスアダプターがラップするのは、特定のランタイムではなくプロトコルです。createACPには、対象ハーネスのACP実装を含むNPMパッケージ、実行ファイル、認証ルール、指示のマッピング、権限のマッピングを渡します。共通アダプターは、ブリッジ、ACPクライアント、ツールの中継、イベント、承認、セッションのライフサイクルを処理します。

設計の要点は、この役割分担にあります。共通ブリッジはVercelが担い、ハーネスごとの差分はランタイムプロファイルが担います。

現在のアダプターが対応するのはACP version 1のみです。保証されるのはプロトコル境界での互換性であり、接続後にすべてのハーネスが同じように振る舞うわけではありません。

Vercelは使い分けを明確にしています。Claude CodeとCodexには@ai-sdk/harness-claude-codeまたは@ai-sdk/harness-codexを使います。互換パッケージはあるものの専用アダプターがないハーネスには、@ai-sdk/harness-acpを選びます。

コーディングエージェント統合で重要な理由

変わるのは、統合にかかる作業量です。

devtoolsチームは、別のACPランタイムをHarnessAgentの背後に置くたびに、セッション管理、イベント変換、承認処理、ホストツールの中継、ライフサイクル制御を一から作り直す必要がなくなります。実装するのはランタイムプロファイルで、アプリケーションの残りの部分では同じハーネスAPIを使い続けられます。

プロダクト層もランタイムの差分から守られます。HarnessAgent.generate()とHarnessAgent.stream()は、どちらもAI SDK互換の結果を返します。すでにuseChatを使っているチームなら、背後のワーカーを変更してもインターフェースのフローを維持できます。

ただし、このリリースによってハーネスが高速、安価、高性能になるわけではありません。ACP実装の挙動が統一されるわけでも、Sandboxが不要になるわけでもありません。どのACPハーネスにも、少なくとも1つのポートを公開したネットワークSandboxが必要です。

Claude Code、Codex、その他のコーディングエージェントを直接使うだけなら、ほとんど影響はありません。この機能が対象にしているのは、それらのエージェントを組み込んだプロダクトを開発する側です。

すぐに活用できるのは誰か

AI SDK対応を追加したい開発者ツール企業の創業者

自社でコーディングハーネスを提供し、すでにACP互換のNPMパッケージを公開しているとします。createACPプロファイルを1つ定義すれば、AI SDKユーザーがそのランタイムを利用するための正式な経路を用意できます。

利点は配布のしやすさです。パッケージ固有のインストール、認証、指示、権限は自社チームが保守し、その周囲にある共通処理はVercelのアダプターに任せられます。

複数のランタイムを支えるプラットフォームエンジニア

中規模のエンジニアリングプラットフォームでは、リポジトリ修復には1つのエージェント、移行作業には別のエージェント、社内固有の自動化には内製ハーネスを使いたい場合があります。プラットフォームエンジニアはセッションと結果の契約を1つに保ち、ジョブごとに異なるハーネスプロファイルを選べます。

ランタイム間の挙動の違いが消えるわけではありません。その違いを名前付きプロファイルへ移すことで、別々のオーケストレーション基盤を管理するよりレビューしやすくなります。

既存のAI SDKインターフェースを持つSaaSチーム

既存のAI SDKアプリケーションなら、チャット画面を作り直さずに、ACP経由のコーディングワーカーを追加できます。具体的な変更はサーバー側で行います。ハーネスプロファイルを作成し、Sandboxを接続してセッションを開始し、UIがすでに扱っているものと同じ形式のストリーミング結果または生成結果を返します。

プロダクトへの組み込みではなく、どのエージェントを選ぶかを検討している段階なら、まずコーディングエージェントの比較をご覧ください。このアダプターが意味を持つのは、その選定を終えた後です。

境界を設計するセキュリティエンジニア

セキュリティエンジニアにとっては、明確な制御点が得られます。認証情報をブローカー経由にすれば、Sandbox内のACPプロセスにはプレースホルダーだけを見せ、外向きのリクエストへ実値を追加できます。権限モードはランタイムが実際に対応するモードへマッピングでき、未対応の選択肢にはnullを設定できます。これにより、アクセス範囲が暗黙に広がるのではなく、処理を失敗させられます。

それだけで安全が自動的に保証されるわけではありません。安全ルールを記述し、テストする場所が明確になるということです。

導入までの流れ

ドキュメントに沿った完全な実装例

ハーネス、ACPアダプター、Vercel Sandboxの各パッケージをインストールします。

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

簡潔でありながら必要事項を省かないデモには、Vercelが公開している完全なCodex ACPプロファイルが適しています。パッケージのインストール、直接認証、AI Gatewayの設定、指示、権限を1か所で確認できるからです。ただし、これは配線を示す例であり、CodexでACPを選ぶことを推奨するものではありません。実際にCodexを統合する場合、Vercelは専用のCodexアダプターを推奨しています。

以下のコードは、現在ドキュメントに掲載されているプロファイルと呼び出しフローです。直接認証にはCODEX_API_KEYまたはOPENAI_API_KEYのいずれかを用意します。AI_GATEWAY_API_KEYまたはVERCEL_OIDC_TOKENがあれば、デフォルトのauth: 'auto'経路で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',
        },
      },
    },
  },
});

よくある誤解は、ランタイムプロファイルを「パッケージ名とAPIキーだけ」と考えることです。権限のマッピング、指示のマッピング、Sandboxのポート、認証情報の境界、セッションのクリーンアップまで含めて統合となります。

制約も直視する

ハーネス関連のパッケージは実験的な段階にあります。リリース間で破壊的変更が起こると想定されているため、本番環境で静かに追従させてよい依存関係ではありません。

パッケージのバージョン固定は明示的に判断する必要があります。simple sourceでは、例の@agentclientprotocol/codex-acpを1.1.4にしているように、正確なバージョンを固定できます。バージョンを省略すると、Sandboxはパッケージのlatestタグをインストールし、そのバージョンはハーネスの識別情報に含まれません。再現可能なビルドが必要なら、package.jsonとpnpm-lock.yamlを含むlocked sourceを使います。Vercelはpnpm install --frozen-lockfileでインストールします。

ACP version 1には、次のような実質的な制約もあります。

• モデルのステップ境界やステップごとの使用量は公開されません。アダプターが境界を推定し、ステップごとの使用量は不明のままです。
• 移植可能な手動コンテキスト圧縮APIや、ターン途中のステアリングAPIはありません。
• ハーネス内蔵ツールを移植可能な形で絞り込めません。ホストツールのフィルタリングは機能しますが、ACP内蔵ツールを絞り込もうとするとエラーになります。
• ホストツール一覧が変わった場合、ACP実装側でMCPツールリストを更新する必要があります。古い一覧を保持した実装は明示的に失敗します。

今回のリリースに関して確認したVercelのページには、@ai-sdk/harness-acp単体の価格は記載されていません。だからといって「無料のエージェント」と捉えるべきではありません。この構成にはモデル認証の経路と必須のネットワークSandboxが含まれるため、既存のランタイムコストと管理ルールは引き続き適用されます。

さらに根本的な制約は、ランタイム固有の挙動をどこまで保てるかです。ACPは共通の接続手段を提供しますが、専用アダプターのほうがハーネス本来の挙動をより忠実に公開できます。標準化によって統合作業は減りますが、その下で動くランタイムの違いまでは消えません。

いま取るべき選択

判断基準はシンプルです。

専用のAI SDKアダプターがないACP互換ハーネスを提供している場合、または複数の該当ランタイムを1つのアプリケーション契約の背後で動かしたいプラットフォームチームなら、今週着手する価値があります。薄いプロファイルを作り、パッケージのバージョンを固定し、すべての権限と失敗経路をテストしてください。

実験的なパッケージを本番ポリシーで許容できない場合、正確なステップごとの使用量が必要な場合、または手動コンテキスト圧縮とターン途中のステアリングが中核的な制御要件なら、導入を待つべきです。

Claude CodeまたはCodexを使う場合は、専用アダプターを使い続けてください。Vercelが推奨する経路がすでにあり、プロトコル境界によって失われる挙動も少なくて済みます。

モデルを直接呼び出すだけ、コーディングエージェントをエンドユーザーとして使うだけ、あるいは自社アプリケーション内でハーネスを動かす必要がない場合、この変更の影響はありません。

チームのプロダクト開発を変えるツールについて、平易な解説を今後も読みたい方は、ニュースレターにご登録ください。