AI SDK 連携

Agents SDK は標準で、Responses API または Chat Completions API を介して OpenAI モデルを利用できます。ただし、別のモデルを使用したい場合は、Vercel の AI SDK がサポートするさまざまなモデルを、このアダプターを介して Agents SDK に導入できます。

セットアップ

extensions パッケージをインストールして、AI SDK アダプターを追加します：
ターミナルウィンドウ
```
npm install @openai/agents-extensions
```
Vercel の AI SDK から目的のモデルパッケージを選択し、インストールします：
ターミナルウィンドウ
```
npm install @ai-sdk/openai
```
アダプターとモデルをインポートして、エージェントに接続します：
アダプターのインポート
```
import { openai } from '@ai-sdk/openai';
import { aisdk } from '@openai/agents-extensions/ai-sdk';
```

エージェントが使用するモデルのインスタンスを初期化します：

import { openai } from '@ai-sdk/openai';
import { aisdk } from '@openai/agents-extensions/ai-sdk';

const model = aisdk(openai('gpt-5.4'));

コード例

import { Agent, run } from '@openai/agents';

// Import the model package you installed
import { openai } from '@ai-sdk/openai';

// Import the adapter
import { aisdk } from '@openai/agents-extensions/ai-sdk';

// Create a model instance to be used by the agent
const model = aisdk(openai('gpt-5.4'));

// Create an agent with the model
const agent = new Agent({
  name: 'My Agent',
  instructions: 'You are a helpful assistant.',
  model,
});

// Run the agent with the new model
run(agent, 'What is the capital of Germany?');

プロバイダーメタデータの受け渡し

メッセージとともにプロバイダー固有のオプションを送信する必要がある場合は、providerMetadata を介して渡します。値は、基盤となる AI SDK モデルにそのまま転送されます。たとえば、Agents SDK の次の providerData は、

const providerData = {
  anthropic: {
    cacheControl: {
      type: 'ephemeral',
    },
  },
};

AI SDK 連携を使用すると、次のようになります。

const providerMetadata = {
  anthropic: {
    cacheControl: {
      type: 'ephemeral',
    },
  },
};

プロンプトキャッシュの保持

プロバイダーが openai.responses である AI SDK モデルでは、モデルが AI SDK 仕様バージョン v3 または v4 を使用している場合、アダプターはストリーミングおよび非ストリーミングのリクエストで modelSettings.promptCacheRetention を転送します。Agents SDK の値 'in-memory' は AI SDK プロバイダーの値 'in_memory' にマッピングされ、'24h' と null は変更されずに転送されます。

AI SDK v2 モデルはこのオプションをサポートしていないため、このオプションが設定されている場合、アダプターはモデルリクエストを行う前に UserError を発生させます。明示的な modelSettings.providerData.providerOptions.openai.promptCacheRetention の値は modelSettings.promptCacheRetention より優先され、アダプターはこの設定を他の AI SDK プロバイダーには転送しません。

この設定は従来の最大保持ポリシーを制御するもので、特定のモデルでのみサポートされます。現在の対応モデルと新しいキャッシュ有効期間の制御については、プロンプトキャッシュの保持を参照してください。

PDF ファイル入力

AI SDK アダプターは、Agents SDK の input_file コンテンツを、AI SDK v2、v3、および v4 モデルが想定するファイルパート形式に変換します。PDF は次の形式で指定できます：

data:application/pdf;base64,... のような base64 データ URL
.pdf ファイル名または providerData.mediaType のいずれかを伴う、空でない元の base64
.pdf パスまたは providerData.mediaType のいずれかを伴う、公開 HTTP(S) URL

ファイル名または URL パスが .pdf で終わる場合、アダプターは application/pdf と推測します。それ以外の場合は、providerData: { mediaType: 'application/pdf' } を明示的に設定してください。アダプターは公開 URL をダウンロードせずに AI SDK モデルへ直接転送するため、選択したプロバイダーとモデルが URL ベースの PDF ファイルパートをサポートしている必要があります。サポートしていない場合は、base64 表現を使用してください。OpenAI ファイル ID は AI SDK アダプター経由ではサポートされません。ファイルデータまたは公開 URL を渡すか、OpenAI Responses モデルを直接使用してください。

確定した出力テキストの正規化

一部のプロバイダーは、JSON コードフェンスなどの余分なラッピングを含むプレーンテキストとして構造化出力を返します。Agents ランタイムが最終出力を検証する前にプロバイダー固有のクリーンアップが必要な場合は、アダプターの作成時に transformOutputText を渡します：

import { openai } from '@ai-sdk/openai';
import { aisdk } from '@openai/agents-extensions/ai-sdk';

const model = aisdk(openai('gpt-5.4'), {
  transformOutputText(text) {
    return text.match(/```(?:json)?\s*([\s\S]*?)\s*```/)?.[1]?.trim() ?? text;
  },
});

transformOutputText は、非ストリーミングレスポンスでは確定したアシスタントテキストに対して、ストリーミングレスポンスでは最後の response_done イベントに対して実行されます。増分の output_text_delta イベントは変更しません。

再試行

modelSettings.retry は AI SDK を基盤とするモデルでも機能します。これは、再試行がデフォルトの OpenAI プロバイダーだけでなく、Agents ランタイムによって実装されているためです。

つまり、他の場所で使用するものと同じ再試行設定を指定できます：

Agent、Runner、またはその両方に modelSettings.retry を設定します。
networkError()、httpStatus([...])、providerSuggested() などの retryPolicies を組み合わせます。
providerSuggested() が役立つのは、ラップされた AI SDK モデルがアダプターを介して再試行に関する助言を提示できる場合に限られることに注意してください。

aisdk(openai(...)) を使用した完全なコード例については、examples/ai-sdk/retry.tsを参照してください。ストリーミングおよび状態を保持する後続リクエストの安全上の境界を含む再試行 API 自体については、モデルを参照してください。

適切な連携の選択

@openai/agents-extensions には、関連する 2 つの連携があります：

@openai/agents-extensions/ai-sdk は、Agent が AI SDK モデル上で実行できるように、そのモデルを適応させます。
@openai/agents-extensions/ai-sdk-ui は、AI SDK UI ルートが標準のストリーミング Response を返せるように、ストリーミングされた Agents SDK の実行を適応させます。

AI SDK モデルに関する注意事項

@openai/agents-extensions/ai-sdk アダプターはまだベータ版であるため、選択したプロバイダー、特に小規模なプロバイダーでは入念にテストすることをお勧めします。
OpenAI モデルを使用する場合は、このアダプターではなく、デフォルトの OpenAI モデルプロバイダーを使用してください。
サポート対象の AI SDK プロバイダーは、specificationVersion v2、v3、または v4 を公開する必要があります。従来の v1 プロバイダーのコード例は廃止されました。サポート対象のプロバイダーインターフェースを使用するコード例については、examples/ai-sdkを参照してください。
このアダプターを介してコンピューターツールを使用する場合は、ディスプレイメタデータが必要です。ツールに environment と dimensions の両方のメタデータが含まれていることを確認してください。
遅延 Responses ツール読み込みフローは、ここではサポートされません。これには、toolNamespace()、deferLoading: true を設定した関数ツール、および toolSearchTool() が含まれます。ツール検索が必要な場合は、OpenAI Responses モデルを直接使用してください。ツールおよびモデルを参照してください。
Programmatic Tool Calling は AI SDK モデルアダプターではサポートされません。programmaticToolCallingTool()、allowedCallers に 'programmatic' を含むツール、Programmatic Tool Calling の履歴項目、および Responses の outputSchema は拒否されます。これらの機能には、OpenAI Responses モデルを直接使用してください。

画像ツール出力

アダプターは、関数ツールから返された ToolOutputImage の値を保持します。これには、リモート URL、base64 データ、OpenAI ファイル ID が含まれます。AI SDK v2 モデルは media パートを受け取ります。AI SDK v3 モデルは image-url、image-data、または image-file-id パートを受け取ります。AI SDK v4 モデルは file パートを受け取り、そのデータは URL、インラインデータ、またはファイル ID に対するプロバイダー参照として表現されます。これにより、サポートされている各モデルバージョンで元の画像表現を使用できます。

完全なコード例については、examples/ai-sdk/image-tool-output.tsを参照してください。

AI SDK UI ストリームヘルパー

@openai/agents-extensions/ai-sdk-ui は、Agents SDK のストリームを AI SDK UI ルートに接続するためのレスポンスヘルパーを提供します：

プレーンテキストのストリーミングレスポンス用の createAiSdkTextStreamResponse(source, options?)
低レベルの ReadableStream<UIMessageChunk> 用の createAiSdkUiMessageStream(source)
UIMessageChunk のストリーミングレスポンス用の createAiSdkUiMessageStreamResponse(source, options?)

これらのヘルパーは、StreamedRunResult、ストリームに似たソース、または互換性のあるラッパーオブジェクトを受け取ります。レスポンスヘルパーは、ストリーミングに適したヘッダーを持つ Response を返します。

ルートから AI SDK のレスポンスを直接返す場合は、createAiSdkUiMessageStreamResponse(...) を使用します。保守されている Agents SDK から AI SDK の UIMessageChunk への変換を引き続き使用しながら、レスポンスまたはレンダリングレイヤーを自分で制御する場合は、createAiSdkUiMessageStream(...) を使用します。プレーンテキストのみが必要な場合は、createAiSdkTextStreamResponse(...) を使用します。

AI SDK モデルアダプターではこのフローを開始できませんが、UI ストリームヘルパーは、Programmatic Tool Calling を使用するストリーミングされた OpenAI Responses の実行をラップできます。プログラム項目は programmatic_tool_calling ツール入力として出力され、対応するプログラム結果は program_output ツール出力として出力されます。

レスポンスヘルパーは、options を介してオプションのレスポンス設定も受け取ります：

headers：ストリーミングレスポンスにマージする追加のレスポンスヘッダー
status：返される Response の HTTP ステータスコード
statusText：返される Response の HTTP ステータステキスト

低レベルの UI メッセージストリームのコード例：

import { Agent, run } from '@openai/agents';
import { createAiSdkUiMessageStream } from '@openai/agents-extensions/ai-sdk-ui';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'Reply with a short answer.',
});

export async function createStream() {
  const stream = await run(agent, 'Hello there.', { stream: true });
  return createAiSdkUiMessageStream(stream);
}

UI メッセージのストリーミング用 Next.js ルートのコード例：

import { Agent, run } from '@openai/agents';
import { createAiSdkUiMessageStreamResponse } from '@openai/agents-extensions/ai-sdk-ui';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'Reply with a short answer.',
});

export async function POST() {
  const stream = await run(agent, 'Hello there.', { stream: true });
  return createAiSdkUiMessageStreamResponse(stream);
}

テキストのみのストリーミング用 Next.js ルートのコード例：

import { Agent, run } from '@openai/agents';
import { createAiSdkTextStreamResponse } from '@openai/agents-extensions/ai-sdk-ui';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'Reply with a short answer.',
});

export async function POST() {
  const stream = await run(agent, 'Hello there.', { stream: true });
  return createAiSdkTextStreamResponse(stream);
}

エンドツーエンドでの使用方法については、このリポジトリの examples/ai-sdk-ui アプリを参照してください。