AI SDK 連携

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

セットアップ

extensions パッケージをインストールして、AI SDK アダプターをインストールします:
Terminal window
```
npm install @openai/agents-extensions
```
目的のモデルパッケージを Vercel の AI SDK から選択してインストールします:
Terminal window
```
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',
    },
  },
};

確定済み出力テキストの正規化

一部のプロバイダーは、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 は、非ストリーミングレスポンスでは確定済みの assistant テキストに対して実行され、ストリーミングレスポンスでは最後の response_done イベントに対して実行されます。増分の output_text_delta イベントは変更しません。

リトライ

modelSettings.retry は AI SDK ベースのモデルでも動作します。リトライはデフォルトの OpenAI プロバイダーだけでなく、エージェントランタイムによって実装されているためです。

つまり、ほかの場所で使用するものと同じリトライ設定を適用できます:

Agent、Runner、またはその両方に modelSettings.retry を設定します。
networkError()、httpStatus([...])、providerSuggested() などの retryPolicies を組み合わせます。
ラップされた AI SDK モデルがアダプター経由でリトライに関する提案を公開できる場合にのみ、providerSuggested() が役立つことに注意してください。

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 を返せるようにします。

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

@openai/agents-extensions/ai-sdk アダプターはまだベータ版のため、選択したプロバイダーで慎重にテストする価値があります。特に小規模なプロバイダーでは重要です。
OpenAI モデルを使用している場合は、このアダプターではなく、デフォルトの OpenAI モデルプロバイダーを優先してください。
サポートされる AI SDK プロバイダーは、specificationVersion v2 または v3 を公開している必要があります。古い v1 プロバイダースタイルが必要な場合は、examples/ai-sdk-v1 のモジュールをプロジェクトにコピーしてください。
このアダプター経由で使用する場合、コンピュータツールには表示メタデータが必要です。ツールに environment と dimensions の両方のメタデータが含まれていることを確認してください。
遅延 Responses ツール読み込みフローはここではサポートされません。これには、toolNamespace()、deferLoading: true を指定した関数ツール、toolSearchTool() が含まれます。ツール検索が必要な場合は、OpenAI Responses モデルを直接使用してください。ツールとモデルを参照してください。

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(...) を使用します。

レスポンスヘルパーは、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 アプリを参照してください。