Vercel fx AI SDK harness adapterの仕組みと本番導入の注意点

Vercelは2026年8月31日、AI SDKのハーネス層にfxを追加しました。これにより、他のコーディングハーネスと同じHarnessAgentインターフェースを介して軽量なコーディングエージェントを実行できるようになりました。ただし、真のメリットは統合作業の削減であり、エージェント自体が魔法のように完全に交換可能になるわけではありません。

vercel fx ai sdk harness adapterとは何か

fxはコーディングエージェントのハーネスおよびコマンドラインツールです。ハーネスとはモデル呼び出しを取り巻くランタイムであり、モデルが実際のコーディング作業を行うために必要なワークスペース、ツール、スキル、セッション、権限、コンパクション、サブエージェントを管理します。

これは、AI SDKに単なる別のモデルプロバイダーを追加することとは本質的に異なります。テキストモデルを別のものに差し替えるのではなく、アプリケーションがすでに解釈できるインターフェースの背後に、完全なコーディングランタイムを組み込むことになります。

新しい@ai-sdk/harness-fxアダプターは、HarnessAgentとfxの間に位置します。内部的には、セッションの開始、プロンプト送信、進捗ストリーミング、ツール処理、クリーンアップのための共通言語としてAgent Client Protocol（ACP）を使用しています。

現在の処理フローは次のようになります。アプリケーションがHarnessAgentにリクエストを送り、fxアダプターがその要求をACPに変換し、ネットワークサンドボックス内でfxが実行され、そのモデルリクエストはVercel AI Gatewayを経由します。

仕組みの全体像はこれだけです。アプリケーションは単一のインターフェースを得て、ハーネス側は独自の動作をそのまま維持します。

この変更が重要な理由と注意点

変化したのは、統合に伴うオーバーヘッドです。既存のプロダクトですでにHarnessAgentをラップしている場合、fxを追加するために新たなセッションマネージャー、ストリームパーサー、権限ブリッジ、クリーンアップパスを構築する必要はなくなりました。

これにより、プラットフォームチームは単一のプロダクトインターフェースの裏で複数のハーネスをすっきりと比較できるようになります。小規模なアプリケーションにとっても、個別のオーケストレーションスタックを保守することなく、別のコーディングランタイムを追加できるメリットがあります。

現在のfxのサイトでは、エージェントはv0.0.7、試験運用（experimental）、Apache-2.0ライセンスと記載されています。AI SDKのハーネスパッケージ群も同様に試験運用段階です。そのため、限定的な検証スパイクには適していますが、安定性が保証された依存関係として過信すべきではありません。

セットアップ時間、レイテンシ、コード品質、コスト削減に関する客観的なビフォーアフターの数値は公表されていません。「APIが1つになった」ことを根拠のないパフォーマンス向上と混同してはいけません。アダプターはカスタム実装の手間を減らすだけです。fxが対象リポジトリのタスクを十分に解決できるかどうかは、個別に評価する必要があります。

ターミナルでfxを直接使っているユーザーには、ほぼ影響はありません。コーディングハーネスを実行せず、通常のAI SDK生成関数のみでモデルを呼び出しているアプリケーションも同様です。この変更が重要になるのは、プロダクトや社内プラットフォームにコーディングエージェントを組み込む場合です。

どのようなケースで活用できるか

SaaSにリポジトリ修正機能を追加する個人創業者

たとえば、Gitリポジトリを受け取り、失敗しているテストをエージェントに修正させるアプリをすでに運用しているとします。既存のセッションやストリーミングのパスを維持したまま、一部のテストグループに対してfxをハーネスとして選択できます。独自のバックエンドを持つfxプロトタイプを別途構築することなく、同一プロダクト内で実環境の比較を行えるのが利点です。

ハーネスの評価を行うエージェントプラットフォームチーム

プラットフォームチームは、同一の修正プロンプトをfxや他のサポート対象ハーネスに送信し、同じアプリケーションレベルのストリームを取得して、タスク達成率を比較できます。ハーネス層では、Claude Code、Cline、Codex、Cursor、Deep Agents、Grok Build、OpenCode、Piなどもリストアップされています。

ただし、比較にはハーネス固有の評価基準が必要です。共通のインターフェースがあるからといって、権限動作、ツール、コンパクション、内部プランニングの仕組みまで同じになるわけではありません。

クライアント作業を分離したい受託開発会社

受託開発会社は、クライアントのリポジトリ修正用にVercel Sandboxを1つ起動し、既存のオペレーター向けダッシュボードに作業内容をストリーミングして、ジョブ完了時にセッションを破棄できます。これにより、クライアントのワークスペースがホストプロセスから隔離され、どのエージェントを選択しても同一のライフサイクルパターンを適用できます。

小規模な修正を自動化したい社内開発者向けツールチーム

社内ツールチームは、テストの修正や小さな機能変更といった限定的なタスクにfxを提供しつつ、既存のスキルやMCPサーバーの設定をハーネス層でそのまま維持できます。フロントエンドを別途用意することなく、ランタイムの選択肢を増やせます。

実装手順

現在のfxハーネスドキュメントには、TypeScriptによる完全な実装手順が記載されています。TypeScriptが実行可能なAI SDKプロジェクト内で利用してください。

1. 1

   3つのパッケージをインストールする

   ハーネスコア、fxアダプター、Vercel Sandboxアダプターを追加します。

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

2. 2

   ランタイムにGatewayの認証情報を1つ設定する

   エージェントを起動するランタイムに、VERCEL_OIDC_TOKENまたはAI_GATEWAY_API_KEYのいずれかを設定します。両方が存在する場合、アダプターはVERCEL_OIDC_TOKENを優先します。

   認証情報をソースコード内に直接記述しないでください。初回セッションでfxがダウンロードされ、以降のセッションでもモデルやWebへのリクエストが発生するため、サンドボックスにはネットワークアクセスが必要です。

3. 3

   セッションの作成、ストリーミング、破棄を行う

   以下はドキュメントに記載されている基本例であり、成功時および失敗時のクリーンアップ処理も含まれています。

   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

   本番運用の前に権限とイベントをテストする

   まずは影響のないリポジトリタスクから実行してください。アプリケーションがテキストストリームを正常に受信できること、権限要求がオペレーターに届くこと、タスク失敗時にsession.destroy()が正しく動作することを確認します。

   見落とされがちなのが、ポートの開放です。fxはACPブリッジ経由で通信するため、ネットワークサンドボックスには少なくとも1つの開放ポートが必要です。この例ではポート4000を使用しています。

別のACP互換エージェント用のアダプターを作成する必要がある場合は、この下位層を解説したAI SDK ACP harness adapterの解説記事を参照してください。

利用にかかるコスト

fx自体はApache-2.0ライセンスのオープンソースですが、組み込み環境で実行する場合はモデルトークン費用とSandbox費用が発生します。

AI Gatewayはトークンに対してマークアップやプラットフォーム手数料を課さず、$0で提供されます。各Vercelチームには一部のモデルを対象に月額$5の無料枠クレジットが付与されますが、モデルごとのレート制限は低めに設定されています。Gatewayクレジットを購入すると有料プランに移行し、この月額無料クレジットは終了します。

サンドボックスについて、Vercelが提示するiad1の例では、2 vCPU、4 GBメモリ構成で5分間のAIコード検証ジョブを実行した場合、CPU使用率100%で約$0.03と試算されています。このレートに基づくと、1,000回のジョブ実行でモデルトークン費用を除いて約$30のSandboxコンピュート費用がかかります。実際のアクティブCPUコストは、エージェントがモデルやネットワークのI/O待ち状態にある間は低くなる可能性があります。

ProプランのSandbox利用では、まずプランに含まれる月額$20のクレジットから消費されます。Sandboxのデフォルトのタイムアウト時間は5分に設定されているため、タスクのタイムアウトは意図して適切に設定し、終了したセッションは放置せず確実に破棄してください。

本番導入前に知るべき5つの制約

1. 両方のレイヤーが実験的段階にある

fxの製品本体およびAI SDKのハーネスパッケージはいずれも実験的（experimental）と位置づけられています。ハーネスのドキュメントには、リリース間で破壊的変更が入る可能性があると明記されています。

2. アダプターが常に最新のfxリリースを追従する

初回セッションではfxの公式インストーラーが実行され、そのインストーラーが最新のリリースを取得します。アダプター側でインストール元、実行バイナリ、起動コマンド、ACPバージョンが固定されているため、createFx()でこれらの詳細をピン留め（バージョン固定）することができません。すべての本番実行で承認済みバイナリバージョンを使用しなければならない環境では、再現性の問題が生じます。

3. 権限モードが正確に対応していない

allow-readsとallow-editsはどちらもfxのaskモードに対応づけられます。一方、allow-allはcodeに対応します。fxには、ファイルの編集を許可しつつターミナルコマンドの実行には承認を求めるような権限モードが存在しないため、アプリケーション層の権限設定がそのまま意図通り反映されるとは限りません。

4. ACP v1によるオブザーバビリティの不足

標準的なネイティブツールのイベントでは、プログラム上のツール名や未加工の入力データが省略される場合があります。また、ACP v1にはモデルのステップ境界やステップごとのトークン消費量を把握する仕組みがないため、共通インターフェースから期待されるほど詳細なトレースやトークン帰属の追跡ができません。

5. ポータビリティのない制御項目が存在する

この構成では、手動コンパクション、ターン途中のステアリング、組み込みのツールフィルタリングなどのポータブルな機能が利用できません。スキーマに基づいた構造化出力もサポート外です。ACPアダプターは直接のアダプターよりもハーネスの機能を十分に引き出せない場合があるため、VercelはClaude CodeやCodexにおいて直接のアダプターが提供されている場合はそちらの利用を推奨しています。

今後のアプローチ

すでにHarnessAgentアプリケーションを運用しており、限定的なリポジトリタスクでfxを評価したく、実験的依存関係を許容できるのであれば、今週中にアダプターを試す価値があります。まずは単一のタスクタイプから始め、完了率、権限プロンプト、クリーンアップ、モデル費用、Sandbox費用を記録してください。

もし、固定されたfxバイナリ、構造化出力、ステップごとのトークン使用量、ターン途中のステアリング、またはファイル編集とターミナル承認の厳密な権限分離が必要な場合は、導入を見送るのが賢明です。これらは設定ミスではなく、インターフェース自体の制約だからです。

fxをローカルCLIとしてのみ利用している場合や、通常のモデル呼び出しのみを行っているアプリケーションであれば、影響はありません。単に新しいアダプターが登場したという理由だけで、無理にハーネス層を導入する必要はありません。

エンジニアが現場で実際に導入しているツールに関するわかりやすい解説は、ぜひニュースレターにご登録ください。