コンテンツにスキップ

AI SDK 連携

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

  1. 拡張パッケージをインストールして、AI SDK アダプターをインストールします。

    ターミナルウィンドウ
    npm install @openai/agents-extensions
  2. Vercel の AI SDK から使用するモデルのパッケージを選び、インストールします。

    ターミナルウィンドウ
    npm install @ai-sdk/openai
  3. エージェントに接続するために、アダプターとモデルをインポートします。

    アダプターのインポート
    import { openai } from '@ai-sdk/openai';
    import { aisdk } from '@openai/agents-extensions/ai-sdk';
  4. エージェントが使用するモデルのインスタンスを初期化します。

    モデルの作成
    import { openai } from '@ai-sdk/openai';
    import { aisdk } from '@openai/agents-extensions/ai-sdk';
    const model = aisdk(openai('gpt-5.4'));
AI SDK のセットアップ
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?');

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

Section titled “プロバイダーメタデータの受け渡し”

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

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

AI SDK 連携を使用すると、

AI SDK の providerMetadata
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 プロバイダーには転送しません。

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

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 自体については、モデルを参照してください。

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

  • @openai/agents-extensions/ai-sdk は、AI SDK モデルを Agent が利用できるように適合させます。
  • @openai/agents-extensions/ai-sdk-ui は、Agents SDK のストリーミング実行を適合させ、AI SDK UI のルートが標準のストリーミング Response を返せるようにします。
  • @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 モデルを直接使用してください。

アダプターは、関数ツールが返す 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 を参照してください。

@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 メッセージストリームの例:

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 ルートの例:

UI メッセージストリームレスポンス
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 アプリを参照してください。