Responses 入门应用

此仓库包含一个基于 Responses API 构建的 NextJS 入门应用。它利用内置工具（网页搜索 和 文件搜索）并实现了一个支持多轮对话的聊天界面。

特性：

• 多轮对话处理
• 流式响应与工具调用
• 函数调用
• 显示注释
• 网页搜索工具配置
• 向量存储创建及文件上传，用于文件搜索工具
• MCP 服务器配置
• 通过第一方连接器实现 Google 日历和 Gmail 集成

该应用旨在作为构建对话式助手的起点，您可以根据自身需求进行定制。

使用方法

1. 设置 OpenAI API：

   • 如果您是 OpenAI API 的新用户，请 注册账户。
   • 按照 快速入门指南 获取您的 API 密钥。

2. 设置 OpenAI API 密钥：

   两种方式：

   • 在您的系统中全局设置 OPENAI_API_KEY 环境变量 参考文档
   • 在项目中设置 OPENAI_API_KEY 环境变量：在项目根目录下创建 .env 文件，并添加以下行（请参考 .env.example）：

   OPENAI_API_KEY=<your_api_key>
   

3. 克隆仓库：

   git clone https://github.com/openai/openai-responses-starter-app.git
   

4. 安装依赖：

   在项目根目录下运行：

   npm install
   

5. 运行应用：

   npm run dev
   

   应用将可在 http://localhost:3000 访问。

工具

此入门应用展示了如何使用内置工具、MCP 服务器以及第一方连接器与 Responses API 配合使用。

您可以通过 UI 直接配置这些工具，但某些工具需要额外的设置（例如 Google OAuth）。

内置工具

Responses API 提供了多种开箱即用的工具可供使用。此演示应用实现了以下工具，并允许您直接从 UI 进行配置：

• 文件搜索：使模型能够访问向量存储中的文件
• 网页搜索：使模型能够搜索互联网
• 代码解释器：使模型能够运行 Python 代码解决问题

其他内置工具，如计算机操作或图像生成，并未在此演示应用中实现。

MCP 服务器

UI 允许您配置一个公共 MCP 服务器以与 Responses API 配合使用。如果您希望使用需要身份验证的 MCP 服务器，可以更新 lib/tools/tools.ts 文件以添加您自己的逻辑。您可以参考 Google 连接器集成示例，了解如何使用访问令牌。

自定义函数

此演示应用附带示例函数 get_weather 和 get_joke。您可以将自己的函数添加到 config/functions.ts 文件中。

Google 集成

此应用展示了如何使用 OpenAI 的第一方连接器与 Google 集成，让助手读取您的日历和邮箱。应用会在您的浏览器中执行安全的 OAuth 流程，按会话存储令牌，并使用您的访问令牌将 Google 连接器附加到 Responses API 工具列表中。

要测试此功能，请按照以下说明设置 Google OAuth 2.0 客户端，并启用 Google 日历和 Gmail API。

有关可用的第一方连接器的更多信息，请参阅 我们的文档。

设置（Google OAuth）

1. 在您的 Google Cloud 项目中为 Web 应用创建一个 OAuth 2.0 客户端（请参阅 文档 以了解如何使用 OAuth 2.0 访问 Google API）。

   • 在 Google Cloud 中，前往“API 和服务”>“Google 身份验证平台”>“客户端”>“创建客户端”> Web。
   • 添加您的重定向 URI：http://localhost:3000/api/google/callback。
   • 复制客户端 ID。创建并复制客户端密钥。

2. 在同一项目中启用以下 API：

   • Google 日历 API
   • Gmail API

3. 在 Google 身份验证平台中配置数据访问范围，以匹配您的需求。此演示使用：

   • openid
   • email
   • profile
   • https://www.googleapis.com/auth/calendar.events
   • https://www.googleapis.com/auth/gmail.modify

4. 在项目根目录下创建 .env.local 文件（可复制 .env.example），并添加：

   GOOGLE_CLIENT_ID="your-google-client-id"
   GOOGLE_CLIENT_SECRET="your-google-client-secret"
   GOOGLE_REDIRECT_URI="http://localhost:3000/api/google/callback"
   

演示流程

尝试网页搜索 + 代码解释器

在 UI 中启用网页搜索和代码解释器后，向模型提问：

“你能获取旧金山八月份的气温，并生成一张绘制这些气温的图表吗？”

模型应使用网页搜索工具获取气温数据，然后使用代码解释器工具生成图表，并在 UI 中显示。

尝试文件搜索

• 保存 PDF 文件，例如博客文章（您可以使用 这篇文章），然后打印页面并选择“另存为 PDF”选项。
• 创建一个新的向量存储，并上传 PDF 文件。
• 启用文件搜索功能，然后向模型提出一个可以用 PDF 文件回答的问题，例如：

  “Responses API 有哪些新功能？”

• 模型应使用文件搜索工具在 PDF 文件中找到相关信息，并显示答案。

尝试 Google 集成

• 在 UI 中点击“连接 Google 集成”，完成 OAuth 流程；您将被重定向回页面，并显示 connected=1。
• 让助手执行一些任务——例如，“显示我接下来的五个日历事件”，或者“总结最近的 Wirecutter 邮件”。
• 应用将使用您的访问令牌，通过 MCP 将 Google 日历和 Gmail 连接器附加到工具列表中，并将结果流式传输回 UI。
• 若要使 OAuth 会话失效，请清除应用的 Cookie（Chrome 开发工具 > 应用程序 > 存储 > Cookie）。如果您只清除 gc_access_token，应用将使用 gc_refresh_token 进行刷新，而无需重新认证。

贡献

欢迎您提出问题或提交 PR 来改进此应用，但请注意，我们可能不会审核所有建议。

许可证

本项目采用 MIT 许可证授权。详情请参阅 LICENSE 文件。

openai-responses-starter-app 快速上手指南

本指南帮助中国开发者快速搭建基于 OpenAI Responses API 的 Next.js 对话助手应用。

环境准备

• 系统要求：Node.js 18+ 版本（推荐 LTS 版）
• 前置依赖：
  • Git
  • npm 或 yarn 包管理器
  • OpenAI API Key（需访问 OpenAI 平台 获取）
  • （可选）Google Cloud 项目配置（如需使用 Google 日历/邮箱集成）

💡 国内用户建议配置全局代理或使用加速服务以确保 npm install 和 API 调用稳定。

安装步骤

1. 克隆项目仓库

   git clone https://github.com/openai/openai-responses-starter-app.git
   cd openai-responses-starter-app
   

2. 安装依赖

   npm install
   

   如遇网络问题，可临时切换镜像源：

   npm config set registry https://registry.npmmirror.com
   npm install
   

3. 配置环境变量

   在项目根目录创建 .env 文件，填入你的 OpenAI API Key：

   OPENAI_API_KEY=<your_api_key>
   

   （可选）若需启用 Google 集成，额外创建 .env.local 并配置：

   GOOGLE_CLIENT_ID="your-google-client-id"
   GOOGLE_CLIENT_SECRET="your-google-client-secret"
   GOOGLE_REDIRECT_URI="http://localhost:3000/api/google/callback"
   

基本使用

1. 启动开发服务器

   npm run dev
   

2. 访问应用 打开浏览器访问 http://localhost:3000

3. 体验核心功能

   • 联网搜索 + 代码解释器：在聊天框输入
     "Can you fetch the temperatures in SF for August and then generate a chart plotting them?"
     模型将自动调用网页搜索获取数据，并用代码解释器生成图表。

   • 文件搜索：

     1. 在 UI 中创建 Vector Store 并上传 PDF 文件（如博客文章）
     2. 启用 "File Search" 工具
     3. 提问："What's new with the Responses API?"
        模型将从上传的文档中检索答案。

   • 自定义函数：编辑 config/functions.ts 添加自有函数逻辑，无需重启即可生效。

所有工具（网页搜索、文件检索、MCP 服务器等）均可通过界面直接配置，无需修改代码。