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 installedimport { openai } from '@ai-sdk/openai';
// Import the adapterimport { aisdk } from '@openai/agents-extensions/ai-sdk';
// Create a model instance to be used by the agentconst model = aisdk(openai('gpt-5.4'));
// Create an agent with the modelconst agent = new Agent({ name: 'My Agent', instructions: 'You are a helpful assistant.', model,});
// Run the agent with the new modelrun(agent, 'What is the capital of Germany?');提供商元数据传递
Section titled “提供商元数据传递”如果需要随消息发送特定提供商的选项,请通过 providerMetadata 传递。这些值会直接转发给底层 AI SDK 模型。例如,Agents SDK 中的以下 providerData
const providerData = { anthropic: { cacheControl: { type: 'ephemeral', }, },};在使用 AI SDK 集成时会变为
const providerMetadata = { anthropic: { cacheControl: { type: 'ephemeral', }, },};。
提示缓存保留
Section titled “提示缓存保留”对于提供商为 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 文件输入
Section titled “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 模型。
最终输出文本规范化
Section titled “最终输出文本规范化”一些提供商会将结构化输出作为带有额外包装的纯文本返回,例如用 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。 - 组合使用
networkError()、httpStatus([...])或providerSuggested()等retryPolicies。 - 请注意,只有当封装的 AI SDK 模型能够通过适配器提供重试建议时,
providerSuggested()才能发挥作用。
有关使用 aisdk(openai(...)) 的完整代码示例,请参阅 examples/ai-sdk/retry.ts。有关重试 API 本身的信息,包括流式传输和有状态后续请求的安全边界,请参阅模型指南。
集成方案选择
Section titled “集成方案选择”@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 模型注意事项
Section titled “AI SDK 模型注意事项”@openai/agents-extensions/ai-sdk适配器仍处于 beta 阶段,因此建议针对您选择的提供商进行仔细测试,尤其是规模较小的提供商。- 如果使用 OpenAI 模型,请优先使用默认的 OpenAI 模型提供商,而不是此适配器。
- 受支持的 AI SDK 提供商必须暴露值为
v2、v3或v4的specificationVersion。旧版 v1 提供商代码示例已停用。有关使用受支持提供商接口的代码示例,请参阅 examples/ai-sdk。 - 通过此适配器使用计算机工具时,需要提供显示元数据。请确保工具同时包含
environment和dimensions元数据。 - 此适配器不支持 Responses 工具延迟加载流程,包括
toolNamespace()、设置了deferLoading: true的函数工具,以及toolSearchTool()。如果需要工具搜索,请直接使用 OpenAI Responses 模型。请参阅工具指南和模型指南。 - AI SDK 模型适配器不支持编程式工具调用。它会拒绝
programmaticToolCallingTool()、allowedCallers包含'programmatic'的工具、编程式工具调用历史记录项,以及 ResponsesoutputSchema。如需使用这些功能,请直接使用 OpenAI Responses 模型。
图像工具输出
Section titled “图像工具输出”适配器会保留函数工具返回的 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 流辅助函数
Section titled “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(...)。
UI 流辅助函数可以封装使用编程式工具调用的 OpenAI Responses 流式执行,尽管 AI SDK 模型适配器无法发起该流程。程序项会作为 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(): Promise< ReturnType<typeof createAiSdkUiMessageStream>> { 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 应用。