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',
    },
  },
};

在使用 AI SDK 集成时会变为

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

最终输出文本规范化

某些 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 中的模块复制到您的项目中。
通过此适配器使用 computer tools 时，需要提供显示元数据。请确保工具同时包含 environment 和 dimensions 元数据。
这里不支持 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?)：用于纯文本流式响应。
createAiSdkUiMessageStream(source)：用于更底层的 ReadableStream<UIMessageChunk>。
createAiSdkUiMessageStreamResponse(source, options?)：用于 UIMessageChunk 流式响应。

这些辅助函数接受 StreamedRunResult、类流 source 或兼容的包装对象。响应辅助函数会返回带有适合流式传输头部的 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 应用。