AI SDK 連携
Agents SDK は、標準で Responses API または Chat Completions API を通じて OpenAI モデルを利用できます。ただし、別のモデルを使用したい場合は、Vercel AI SDK がサポートするさまざまなモデルを、このアダプターを通じて Agents SDK に組み込めます。
セットアップ
Section titled “セットアップ”-
拡張パッケージをインストールして、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 installedimport { openai } from '@ai-sdk/openai';
// Import the adapterimport { aisdk } from '@openai/agents-extensions/ai-sdk';
// Create a model instance to be used by the agentconst model = aisdk(openai('gpt-5.4'));
// Create an agent with the modelconst agent = new Agent({ name: 'My Agent', instructions: 'You are a helpful assistant.', model,});
// Run the agent with the new modelrun(agent, 'What is the capital of Germany?');プロバイダーメタデータの受け渡し
Section titled “プロバイダーメタデータの受け渡し”メッセージとともにプロバイダー固有のオプションを送信する必要がある場合は、providerMetadata を通じて渡します。値は、基盤となる AI SDK モデルに直接転送されます。たとえば、Agents SDK の次の providerData は、
const providerData = { anthropic: { cacheControl: { type: 'ephemeral', }, },};AI SDK 連携を使用すると、
const providerMetadata = { anthropic: { cacheControl: { type: 'ephemeral', }, },};のようになります。
プロンプトキャッシュの保持
Section titled “プロンプトキャッシュの保持”プロバイダーが 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 ファイル入力
Section titled “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 のファイルをダウンロードせず、URL を AI SDK モデルに直接転送します。そのため、選択したプロバイダーとモデルが URL ベースの PDF ファイルパートをサポートしている必要があります。サポートしていない場合は、base64 形式を使用してください。AI SDK アダプターでは OpenAI ファイル ID はサポートされていません。ファイルデータまたは公開 URL を渡すか、OpenAI Responses モデルを直接使用してください。
確定した出力テキストの正規化
Section titled “確定した出力テキストの正規化”一部のプロバイダーは、JSON コードフェンスなどの余分な囲みを付けたプレーンテキストとして構造化出力を返します。エージェントランタイムが最終出力を検証する前に、プロバイダー固有の整形処理が必要な場合は、アダプターの作成時に 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 イベントは変更しません。
リトライはデフォルトの OpenAI プロバイダーだけでなく、エージェントランタイムによって実装されているため、modelSettings.retry は AI SDK を利用するモデルでも機能します。
そのため、他の場所で使用するのと同じリトライ設定を適用できます。
Agent、Runner、またはその両方にmodelSettings.retryを設定します。networkError()、httpStatus([...])、providerSuggested()などのretryPoliciesを組み合わせます。providerSuggested()が役立つのは、ラップされた AI SDK モデルがアダプターを通じてリトライに関する助言を提供できる場合のみであることに注意してください。
aisdk(openai(...)) を使用した完全なコード例については、examples/ai-sdk/retry.ts を参照してください。ストリーミングやステートフルな後続リクエストに関する安全上の制約など、リトライ API 自体については、モデルを参照してください。
適切な連携方法の選択
Section titled “適切な連携方法の選択”@openai/agents-extensions には、関連する 2 つの連携機能があります。
@openai/agents-extensions/ai-sdkは、AI SDK モデルをAgentが利用できるように適合させます。@openai/agents-extensions/ai-sdk-uiは、Agents SDK のストリーミング実行を適合させ、AI SDK UI のルートが標準のストリーミングResponseを返せるようにします。
AI SDK モデルに関する注意事項
Section titled “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 モデルを直接使用してください。ツールとモデルを参照してください。 - AI SDK モデルアダプターは Programmatic Tool Calling をサポートしていません。
programmaticToolCallingTool()、allowedCallersに'programmatic'を含むツール、Programmatic Tool Calling の履歴項目、Responses のoutputSchemaは拒否されます。これらの機能には、OpenAI Responses モデルを直接使用してください。
ツールの画像出力
Section titled “ツールの画像出力”アダプターは、関数ツールが返す 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 ストリームヘルパー
Section titled “AI SDK UI ストリームヘルパー”@openai/agents-extensions/ai-sdk-ui は、Agents SDK のストリームを AI SDK UI のルートに接続するためのレスポンスヘルパーを提供します。
createAiSdkTextStreamResponse(source, options?):プレーンテキストのストリーミングレスポンス用createAiSdkUiMessageStream(source):低レベルのReadableStream<UIMessageChunk>用createAiSdkUiMessageStreamResponse(source, options?):UIMessageChunkのストリーミングレスポンス用
これらのヘルパーは、StreamedRunResult、ストリームのようなソース、または互換性のあるラッパーオブジェクトを受け取ります。レスポンスヘルパーは、ストリーミングに適したヘッダーを持つ Response を返します。
ルートから AI SDK のレスポンスを直接返す場合は、createAiSdkUiMessageStreamResponse(...) を使用してください。メンテナンスされている Agents SDK から AI SDK の UIMessageChunk への変換を利用しつつ、レスポンスやレンダリングレイヤーを自分で管理する場合は、createAiSdkUiMessageStream(...) を使用してください。プレーンテキストだけが必要な場合は、createAiSdkTextStreamResponse(...) を使用してください。
AI SDK モデルアダプターは Programmatic Tool Calling のフローを開始できませんが、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(): Promise< ReturnType<typeof createAiSdkUiMessageStream>> { 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 アプリを参照してください。