AI SDK 集成

Agents SDK 开箱即用，可通过 Responses API 或 Chat Completions API 使用 OpenAI 模型。不过，如果您想使用其他模型，Vercel AI SDK 提供了一系列受支持的模型，可通过此适配器将其接入 Agents SDK。

设置

安装扩展包，以安装 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 会对最终助手文本运行；对于流式响应，则会对最终的 response_done 事件运行。它不会修改增量 output_text_delta 事件。

重试

modelSettings.retry 也适用于由 AI SDK 支持的模型，因为重试由智能体运行时实现，而不只由默认的 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 提供商必须公开值为 v2、v3 或 v4 的 specificationVersion。如果需要较旧的 v1 提供商样式，请将 examples/ai-sdk-v1 中的模块复制到您的项目中。
通过此适配器使用计算机工具时，需要提供显示元数据。请确保该工具同时包含 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 模型适配器无法发起使用程序化工具调用的流程，UI 流辅助函数仍可封装使用该流程的 OpenAI Responses 流式运行。程序项会作为 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 应用。