AI SDK与OpenAI Responses API实战指南：构建智能体与实现持久化对话

随着 OpenAI Responses API 的正式发布，构建新一代 AI 应用正迎来新的机遇。对于那些需要模型具备实时信息获取和长期记忆能力的应用来说，这无疑是一个强大的新工具。

如果你还不熟悉 OpenAI Responses API，可以通过我之前写的一篇介绍文章《2026年AI开发新标准来了！Chat Completion已过时，Open Responses横空出世》了解更多详情。

为了便于中文开发者学习，我还搭建了一个 Open Responses 中文镜像站点 openresponses-cn.top，提供了文档的中文翻译。

本文将重点探讨如何结合 AI SDK 来使用全新的 OpenAI Responses API。AI SDK 是一个强大的 TypeScript 工具包，旨在帮助开发者轻松地将大型语言模型（LLM）集成到应用中。它支持 React、Next.js、Vue、Svelte、Node.js 等主流前端和后端框架，能够抽象不同模型提供商的差异，简化开发流程。

AI SDK 快速入门

AI SDK 的核心是 AI SDK Core，它提供了一套统一的 API 来调用不同的 LLM。使用 AI SDK 通过新的 Responses API 调用 GPT-4o 模型，代码非常简单：

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const { text } = await generateText({
  model: openai.responses('gpt-4o'),
  prompt: '解释量子纠缠的概念。',
});

生成结构化数据

除了生成文本，你还可以让模型输出结构化的 JSON 数据，这对于信息提取、数据分类等场景非常有用。AI SDK Core 提供了 generateObject 和 streamObject 函数，并支持使用 zod 库定义输出模式。

import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const { object } = await generateObject({
  model: openai.responses('gpt-4o'),
  schema: z.object({
    recipe: z.object({
      name: z.string(),
      ingredients: z.array(z.object({ name: z.string(), amount: z.string() })),
      steps: z.array(z.string()),
    }),
  }),
  prompt: '生成一个千层面食谱。',
});

上面的代码会生成一个完全符合指定 zod 模式的类型安全的食谱对象。

使用工具调用构建智能体（Agent）

OpenAI Responses API 原生支持工具调用，这让模型能够与外部系统交互以执行任务。通过 AI SDK，我们可以很方便地定义和使用工具。

import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const { text } = await generateText({
  model: openai.responses('gpt-4o'),
  prompt: '今天旧金山的天气怎么样？',
  tools: {
    getWeather: tool({
      description: '获取某个地点的天气',
      inputSchema: z.object({
        location: z.string().describe('要获取天气的地点'),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72 + Math.floor(Math.random() * 21) - 10,
      }),
    }),
  },
  stopWhen: stepCountIs(5), // 启用多步骤 Agent
});

这里的关键是 stopWhen: stepCountIs(5) 参数。它允许模型自主地调用工具、分析结果，并根据需要继续调用其他工具。这就将一次简单的LLM调用转变为一个可以串联多个操作的智能体（Agent）。

内置网络搜索工具

Responses API 引入了一个内置的 webSearch 工具，让模型可以实时访问互联网来获取信息，从而增强回答的准确性和时效性。

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai.responses('gpt-4o-mini'),
  prompt: '上周旧金山发生了什么？',
  tools: {
    web_search_preview: openai.tools.webSearchPreview(),
  },
});

console.log(result.text);
console.log(result.sources); // 可以查看引用的来源

你还可以为搜索工具指定更详细的元数据，以提升搜索结果的质量。

import { generateText } from 'ai';

const result = await generateText({
  model: openai.responses('gpt-4o-mini'),
  prompt: '上周旧金山发生了什么？',
  tools: {
    web_search_preview: openai.tools.webSearchPreview({
      searchContextSize: 'high',
      userLocation: {
        type: 'approximate',
        city: 'San Francisco',
        region: 'California',
      },
    }),
  },
});

console.log(result.text);
console.log(result.sources);

连接 MCP（模型上下文协议）工具

Responses API 还支持连接到 MCP 服务器，这意味着模型可以调用由远程 MCP 服务器暴露的丰富工具集。

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai.responses('gpt-5-mini'),
  prompt: '在网上搜索最新的纽约市长选举结果',
  tools: {
    mcp: openai.tools.mcp({
      serverLabel: 'web-search',
      serverUrl: 'https://mcp.exa.ai/mcp',
      serverDescription: '面向 AI Agent 的网络搜索 API',
    }),
  },
});

console.log(result.text);

关于 MCP 工具的更多配置细节，如身份验证、工具过滤等，请参阅 OpenAI 官方的提供商文档。

使用持久化聊天历史功能

OpenAI Responses API 的一个显著优势是可以在服务器端持久化存储聊天历史。这样，在后续请求中，你只需要发送用户的最新消息，模型就能自动获取完整的对话上下文。

有两种主要方式来利用这一持久化功能。

使用 previousResponseId

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result1 = await generateText({
  model: openai.responses('gpt-4o-mini'),
  prompt: '发明一个新节日并描述其传统。',
});

const result2 = await generateText({
  model: openai.responses('gpt-4o-mini'),
  prompt: '用两句话总结',
  providerOptions: {
    openai: {
      previousResponseId: result1.providerMetadata?.openai.responseId as string,
    },
  },
});

使用 Conversation（对话）对象

你也可以先通过 OpenAI API 创建一个对话，然后在后续请求中继续这个对话。

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const result = await generateText({
  model: openai.responses('gpt-4o-mini'),
  prompt: '用两句话总结',
  providerOptions: {
    openai: {
      // 使用通过 OpenAI API 预先创建好的对话 ID
      conversation: 'conv_123',
    },
  },
});

从 Completions API 迁移到 Responses API

如果你之前在使用 AI SDK 调用 OpenAI 的 Completions API，迁移到新的 Responses API 非常直观。主要改动是将模型提供商的实例从 openai(modelId) 改为 openai.responses(modelId)。

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

// 之前的 Completions API 调用方式
const { text: text1 } = await generateText({
  model: openai('gpt-4o'),
  prompt: '解释量子纠缠的概念。',
});

// 新的 Responses API 调用方式
const { text: text2 } = await generateText({
  model: openai.responses('gpt-4o'),
  prompt: '解释量子纠缠的概念。',
});

同时，之前直接在模型提供商实例上配置的一些专属选项，现在需要移动到 providerOptions 对象中。

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

// Completions API (旧方式，部分配置在 model 实例上)
const { text: text1 } = await generateText({
  model: openai('gpt-4o', { parallelToolCalls: false }), // 旧版写法
  prompt: '解释量子纠缠的概念。',
});

// Responses API (新方式，配置统一在 providerOptions)
const { text: text2 } = await generateText({
  model: openai.responses('gpt-4o'),
  prompt: '解释量子纠缠的概念。',
  providerOptions: {
    openai: {
      parallelToolCalls: false, // 新版写法
    },
  },
});

如何开始？

准备好动手尝试了吗？以下是帮助你快速上手的步骤：

1. 查阅官方文档：访问 ai-sdk.dev/docs 深入了解 AI SDK 的全部功能。
2. 学习实战示例：查看 ai-sdk.dev/examples 上的示例代码，获取项目灵感。
3. 钻研高级主题：通过 ai-sdk.dev/docs/guides 上的指南学习 RAG、多模态聊天等进阶内容。
4. 使用现成模板：在 vercel.com/templates?type=ai 上寻找即用型 AI 应用模板，加速开发。

再次提醒，可以通过 openresponses-cn.top 访问 OpenAI Responses API 的中文翻译文档。

希望这篇指南能帮助你快速掌握使用 AI SDK 和 OpenAI Responses API 构建强大 AI 应用和智能体的方法。在实践中如果遇到任何问题，欢迎在 云栈社区 与其他开发者交流讨论。