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?');

传递 provider 元数据

如果您需要随消息发送 provider 特定选项，请通过 providerMetadata 传递。这些值会被直接转发到底层 AI SDK 模型。例如，Agents SDK 中以下 providerData

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

会变成

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

当使用 AI SDK 集成时即如此。

规范化最终输出文本

某些 provider 会将 structured outputs 作为带额外包装的纯文本返回，例如 JSON 代码围栏。如果您需要在 Agents 运行时验证最终输出前进行 provider 特定清理，请在创建适配器时传入 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 的模型，因为重试由 Agents 运行时实现，而不只由默认 OpenAI provider 实现。

这意味着您可以附加与其他场景相同的重试配置：

在 Agent、Runner 或两者上设置 modelSettings.retry。
组合 retryPolicies，例如 networkError()、httpStatus([...]) 或 providerSuggested()。
请注意，仅当被包装的 AI SDK 模型能通过适配器暴露重试建议时，providerSuggested() 才有帮助。

如需查看使用 aisdk(openai(...)) 的完整示例，请参见 examples/ai-sdk/retry.ts。关于重试 API 本身（包括流式传输与有状态后续请求的安全边界），请参见模型。

选择合适的集成

@openai/agents-extensions 中有两个相关集成：

@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 适配器仍处于 beta 阶段，因此值得结合您选择的 provider（尤其是较小的 provider）进行充分测试。
如果您使用的是 OpenAI 模型，建议优先使用默认 OpenAI 模型 provider，而不是此适配器。
支持的 AI SDK provider 必须暴露 specificationVersion v2 或 v3。如果您需要旧版 v1 provider 风格，请将 examples/ai-sdk-v1 中的模块复制到您的项目中。
此处不支持 Deferred Responses 工具加载流程。包括 toolNamespace()、带 deferLoading: true 的函数工具，以及 toolSearchTool()。如果您需要工具搜索，请直接使用 OpenAI Responses 模型。请参见工具和模型。

AI SDK UI 流辅助函数

@openai/agents-extensions/ai-sdk-ui 提供了响应辅助函数，用于将 Agents SDK 流接入 AI SDK UI 路由：

createAiSdkTextStreamResponse(source, options?)：用于纯文本流式响应。
createAiSdkUiMessageStreamResponse(source, options?)：用于 UIMessageChunk 流式响应。

这两个辅助函数都接受 StreamedRunResult、类流式 source 或兼容包装对象，并返回带有流式友好请求头的 Response。

当您的 UI 需要工具调用或推理片段等结构化分块时，请使用 createAiSdkUiMessageStreamResponse(...)。当您只需要纯文本时，请使用 createAiSdkTextStreamResponse(...)。

用于 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 应用。