AI SDK 集成

Agents SDK 默认通过 Responses API 或 Chat Completions API 使用 OpenAI 模型。不过，如果您希望使用其他模型，Vercel AI SDK 提供了多种受支持的模型，可通过此适配器将它们引入 Agents SDK。

设置

安装扩展包，以安装 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：

base64 数据 URL，例如 data:application/pdf;base64,...。
非空的原始 base64，并提供 .pdf 文件名或 providerData.mediaType。
公共 HTTP(S) URL，并提供以 .pdf 结尾的路径或 providerData.mediaType。

当文件名或 URL 路径以 .pdf 结尾时，适配器会推断其类型为 application/pdf。否则，请显式设置 providerData: { mediaType: 'application/pdf' }。适配器会将公共 URL 直接转发给 AI SDK 模型，而不会下载文件，因此所选提供商和模型必须支持基于 URL 的 PDF 文件部分；如果不支持，请使用 base64 表示形式。AI SDK 适配器不支持 OpenAI 文件 ID；请传递文件数据或公共 URL，或者直接使用 OpenAI Responses 模型。

最终输出文本规范化

某些提供商会以带有额外包装的纯文本形式返回 structured outputs，例如 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 支持的模型，因为重试由 Agents 运行时实现，而不仅仅由默认 OpenAI 提供商实现。

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

在 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 适配器仍处于测试阶段，因此建议针对您选择的提供商进行仔细测试，尤其是规模较小的提供商。
如果使用 OpenAI 模型，请优先使用默认的 OpenAI 模型提供商，而不是此适配器。
受支持的 AI SDK 提供商必须公开 specificationVersion v2、v3 或 v4。旧版 v1 提供商示例已停用。有关使用受支持提供商接口的示例，请参阅 examples/ai-sdk。
通过此适配器使用计算机工具时，需要提供显示元数据。请确保该工具同时包含 environment 和 dimensions 元数据。
此处不支持延迟的 Responses 工具加载流程，包括 toolNamespace()、设置了 deferLoading: true 的函数工具以及 toolSearchTool()。如果需要工具搜索，请直接使用 OpenAI Responses 模型。请参阅工具和模型。
AI SDK 模型适配器不支持程序化工具调用。它会拒绝 programmaticToolCallingTool()、allowedCallers 中包含 'programmatic' 的工具、程序化工具调用历史项以及 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?)：用于纯文本流式响应。
createAiSdkUiMessageStream(source)：用于较低层级的 ReadableStream<UIMessageChunk>。
createAiSdkUiMessageStreamResponse(source, options?)：用于 UIMessageChunk 流式响应。

这些辅助函数接受 StreamedRunResult、类流数据源或兼容的包装对象。响应辅助函数会返回一个包含适合流式传输的标头的 Response。

当路由应直接返回 AI SDK 响应时，请使用 createAiSdkUiMessageStreamResponse(...)。如果您希望自行控制响应或渲染层，同时仍使用维护完善的 Agents SDK 到 AI SDK UIMessageChunk 转换，请使用 createAiSdkUiMessageStream(...)。如果只需要纯文本，请使用 createAiSdkTextStreamResponse(...)。

尽管 AI SDK 模型适配器无法发起使用程序化工具调用的流式 OpenAI Responses 运行，UI 流辅助函数仍可封装此类运行。程序项会作为 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 应用。