OpenAI Agent Builder 新手指南

如果你探索过构建 AI 代理，就会知道这个过程就像一个复杂的谜题。到目前为止，它通常意味着要处理各种零散的工具——拼凑编排逻辑、构建自定义连接器、创建手动评估管道，以及花费数周时间进行前端工作，才能看到你的代理运行。那个复杂的时代即将结束。

本周，OpenAI 推出了 AgentKit，这是一套完整的工具，旨在统一构建、部署和优化代理的整个生命周期。AgentKit 为开发者提供了强大的集成工具包，帮助他们更快、更可靠地从创意到生产。其核心组件包括：

• Agent Builder：一个可视化的画布，用于创建和版本控制多步骤代理工作流。
• Connector Registry：一个中心位置，供管理员管理数据和工具如何跨 OpenAI 产品（例如 API 等）连接。
• ChatKit：一个工具包，用于直接在您的 Agentic 产品中构建可定制的基于聊天的代理体验。

虽然整个 AgentKit 套件标志着一次重大的飞跃，但创建过程的核心是 Agent Builder。它提供了一个可视化的画布，你可以在其中使用拖放节点编写逻辑、连接工具并配置自定义防护措施。凭借实时预览和完整版本控制等功能，它专为快速迭代而打造，可将好创意转化为优秀的代理。

在本分步指南中，我们将深入探讨 Agent Builder。你将学习如何利用它的强大功能，从头开始设计、测试并最终构建你的第一个功能性 AI 代理。让我们开始构建吧！

1、什么是 Agent Builder？

OpenAI 全新 AgentKit 生态系统的核心是 Agent Builder——一个可视化的画布，在这里，创意得以成形，代理得以真正落地。你可以将其视为 AI 工作流的设计工作室：在这里，你可以规划代理如何推理、检索数据并做出决策，而无需触及任何代码。

在传统的设置中，构建代理意味着手动定义每个步骤—编写脚本将数据从一个模型调用传递到另一个模型调用，管理 API 端点，以及调试几乎无法可视化的长逻辑链。Agent Builder 彻底改变了这一切。它引入了一个拖放界面，您可以直接从浏览器构建、预览和版本控制多步骤工作流。

你放置在画布上的每个元素都称为一个节点。节点可以表示从模型调用或数据转换到逻辑条件或外部工具的所有内容。你可以使用定义信息在系统中流动方式的边将它们连接起来。结果看起来更像是思维导图而不是脚本——这是有意为之。您可以实时观看工作流的运行情况，检查数据在节点之间的移动方式，并快速进行调整。

除了便捷性之外，Agent Builder 还为代理设计带来了工程规范。你创建的每个工作流都具有版本控制，这意味着你可以回滚更改或发布稳定的版本进行部署。你可以附加防护栏，以防止代理被提示注入或数据泄露，并使用跟踪评分直接在界面内评估其性能。这种可视化设计与严格测试的结合，使从原型到生产的转变比以往任何时候都更加轻松。

3、了解代理、工作流和节点

在开始构建之前，了解 Agent Builder 的词汇表（构成其核心的三个概念：代理、工作流和节点）会有所帮助。

从本质上讲，代理不仅仅是一个大型语言模型的调用。它是一个独立的系统，拥有目标、指令集以及通过多个步骤推理得出结果的能力。可以将其视为一个问题解决器，能够读取上下文、决定使用哪些工具并生成结构化结果。在 OpenAI 的生态系统中，每个代理还可以包含评估、安全检查和记忆功能，使其成为一个完整的逻辑单元，而不仅仅是一个提示。

工作流是将这些代理和工具连接在一起时发生的事情。它是描述信息如何从一个步骤转移到下一个步骤的蓝图——从获取用户输入到处理输入，再到生成最终输出。您可能会让一个代理重写问题以使其更清晰，另一个代理检索相关文档，第三个代理生成最终答案。这些步骤共同构成了一个工作流，可以像任何其他软件一样重复使用、版本控制和部署。

节点是该系统中最小的构建块——工作流中的单个操作。在 Agent Builder 中，每个节点都有明确的用途：一些节点运行模型，另一些节点获取数据、应用逻辑或执行安全检查。连接节点不仅定义了操作顺序，还定义了数据流，确保每个步骤都能准确接收所需的输入。

这种结构如此强大的原因在于其灵活性。您可以从一个简单的工作流（用于汇总文本的工作流）入手，然后逐步扩展它，添加新的节点用于分类、外部搜索或人工审批。每次添加都基于相同的可视化逻辑，因此您的代理可以自然地从原型演变为复杂的流程，而不会失去清晰度。

一旦你掌握了这种层次结构——工作流中的代理，由节点构成的工作流——整个 Agent Builder 体验就会变得顺畅。你无需再考虑 API 调用，而是开始思考逻辑：“接下来应该发生什么？在什么条件下？我应该传递哪些数据？”这才是代理设计真正发挥创意的地方。

4、Agent Builder 的工具箱：节点概览

了解工作流如何将代理连接在一起后，下一步就是了解节点——构成 Agent Builder 中每个工作流的基本单元。

如果将工作流视为流程图，节点就是一个个独立的框，每个框执行一项定义明确的任务。它们可以接收输入、处理输入，并将其传递给下一个节点。通过组合不同的节点类型，你可以赋予代理结构和功能：它如何思考、何时行动以及如何保持安全。

Agent Builder 将这些节点分为四大类：核心节点、工具节点、逻辑节点和数据节点。让我们仔细了解一下每个节点。

4.1 核心节点：每个工作流的基础

每个工作流都从这里开始。核心节点定义了代理的框架——它如何启动、如何推理以及如何注释或记录其间发生的事情。

起始节点是你的入口点。在基于聊天的工作流中，它会捕获用户的输入，将其附加到对话历史记录中，并将该消息以 input_as_text 的形式公开，然后将其传递到流程的其余部分。如果你的代理需要跟踪会话数据（例如用户 ID 或主题），你还可以定义额外的状态变量。

接下来是代理节点，它是工作流的核心。这是你的模型所在的位置——它是处理信息、执行指令并决定下一步操作的大脑。你可以为每个代理赋予各自的行为和作用域。

例如，在 OpenAI 的“家庭作业助手”示例中，一个代理会重写用户的查询以使其更清晰，另一个代理会按类型对其进行分类，第三个代理会生成最终答案。每个代理都专注于一项职责，从而使你的工作流保持模块化且易于调试。

最后是注释节点，它完全不影响执行。它只是用来记录画布内部发生的事情。注释的重要性常常被低估——当你开始使用多个代理构建更大规模的工作流程时，这些注释对于协作和一目了然地理解流程至关重要。

4.2 工具节点：扩展代理的功能

核心节点定义了代理的逻辑，而工具节点则赋予其与外部世界交互的能力——获取数据、搜索文档或执行安全检查。

你最常用的是文件搜索节点。它将你的代理连接到 OpenAI 平台上托管的向量存储，使其能够从你上传的文档中检索信息。你可以按向量存储 ID 进行搜索，并使用来自早期节点的变量动态注入查询。例如，你的代理可以接受用户的问题，在已上传的 PDF 中进行搜索，然后汇总结果。

另一个重要的工具是护栏节点，它充当你的安全检查点。它监控代理的输出，例如个人身份信息 (PII)、越狱尝试或幻觉。如果检查失败，你可以决定是正常结束工作流还是循环返回并提醒用户安全输入。实际上，此节点对于生产代理至关重要——它确保您的工作流行为可靠，并且不会泄露敏感数据。

最后，还有 MCP 节点。此节点允许你的代理连接到第三方服务，例如 Gmail、Notion 或 Zapier，甚至您定义的自定义服务器。它是你的代理与外部系统之间的桥梁，使其不仅能够推理和响应，还能在现实世界中采取实际行动——发送电子邮件、获取报告或发布更新。

4.3 逻辑节点：赋予你的代理条件智能

逻辑节点将决策引入你的工作流。它们使你代理动态化而非线性化——允许它在继续之前进行分支、循环或等待人工输入。

最常用的逻辑节点是 If/Else。它使用通用表达式语言 (CEL) 来定义条件并根据结果进行路由。例如，如果之前的代理将用户查询归类为“问答”，您可以将其路由到专门的答案生成代理。如果是开放式或研究型问题，您可以将其发送到另一个先检索文档的分支。

然后是 While 节点，它允许您的工作流根据条件循环。当您希望代理重试操作直到满足特定条件时，此功能非常有用——例如，检查是否生成了有效的响应或等待数据集完全处理完毕。

第三个逻辑节点“人工审批”将人工重新纳入循环。它非常适合你的代理起草仍需审核的内容（例如电子邮件、报告或社交媒体帖子）的工作流。当此节点触发时，代理会暂停并询问：“您想让我发送此内容吗？”或“您是否批准此草稿？”一旦用户确认，工作流将继续进行下一步，例如实际发送消息的 MCP 节点。

4.4 数据节点：管理和转换信息

最后，数据节点处理工作流中的数据移动和转换。它们不涉及推理或外部工具——它们只是塑造信息在各个步骤之间的流动方式。

转换节点就像一个数据格式化站。它重塑一个步骤的输出，以便它们可以被另一个步骤使用——例如，将对象转换为数组，或在下一个代理处理之前强制执行特定的模式。当您的输出结构变化或需要在重用前进行清理时，这尤其有用。

另一方面，设置状态节点允许您定义在整个工作流中持久存在的全局变量。假设您的代理生成了一个摘要或提取了一个您以后需要的关键字列表——您可以将其存储为状态变量，并在任何未来的节点中引用它。这是一种简单而强大的方法，可以为您的工作流提供记忆和连续性。

5、构建第一个 Agentic 工作流

在深入构建我们的第一个 Agentic 工作流之前，让我们先设置一下环境。我们将在 OpenAI 的 Agent Builder 中进行所有操作，这是一个用于设计和测试多步骤代理的可视化工作区。

• 前往 platform.openai.com/agent-builder 并使用您的 OpenAI 凭据登录。[如果您还没有帐户，请创建一个帐户并确保添加账单信息——这是在预览模式下运行代理所必需的。登录后，请访问您的帐户设置并验证您的组织。验证可确保您能够直接从画布中不受限制地执行和测试工作流。]
• 如果您的代理需要连接到外部数据（例如 Gmail、Notion 或其他 API），您还需要设置托管的 MCP（模型连接器协议）服务器。MCP 允许您的代理访问并处理存储在第三方服务中的信息，从而扩展其功能，使其超越内置工具。

在 Agent Builder 仪表板中，您会注意到顶部有三个主要选项卡：

• 工作流 → 列出所有已发布且准备部署的工作流。默认情况下，您可能会看到一个名为“我的流程”的示例项目。
• 草稿 → 包含所有正在进行或未发布的工作流 - 非常适合进行安全实验。
• 模板 → 提供预构建的开箱即用的代理示例。如果您想探索不同节点模式的工作原理，这些是很好的起点。

不过，在本教程中，我们将跳过模板，从一个空白流程开始。从头开始构建可以让我们完全掌控，并帮助您理解过程中的每个决策。

5、智能研究代理

让我们构建一个比一次性摘要器更智能的东西——一个可以决定何时真正需要在线查找信息的智能研究代理。这个想法很简单：代理接收原始用户查询，将其改写为结构良好的研究问题，检查该主题是否需要新的信息，然后执行网络搜索或直接根据模型自身的知识进行回答。

最终的工作流程如下：

5.1 开始 - 捕获用户查询

每个代理工作流程都以一个开始节点开始。在这里，您可以定义哪些信息进入系统，以及在对话过程中要跟踪哪些变量。

在我们的例子中，开始节点包含两部分：

• 输入变量 - input_as_text 此变量会自动存储用户在聊天中输入的任何内容。它将成为启动工作流程的原始查询。
• 状态变量 - research_prompt 事情变得有趣了。我们将使用此变量来存储用户问题的增强版本——即下一个代理将生成的经过清理的研究提示。您可以将其视为工作流程的“精炼记忆”，其他节点稍后可以访问。

设置方法：

• 在“开始”节点配置中，点击“状态变量”下的“+ 添加变量”。
• 将其命名为 research_prompt并将类型设置为字符串。
• 暂时将其值留空——一旦“提示增强器”代理运行，它将自动填充。

5.2 提示增强器代理——将查询转换为研究提示

接下来，拖入一个代理节点并将其命名为“提示增强器”。此代理的作用很简单但至关重要：它将用户的原始问题重写为清晰、结构良好的研究提示，以便您的其他工作流程可以一致地使用。

在“说明”字段中，输入类似以下内容的内容：

将“起始节点”中提供的用户查询改写为清晰且结构良好的研究问题。

保持“包含聊天历史记录”处于开启状态——这可以让代理查看原始输入以获得更好的上下文——并选择 GPT-5-Nano 模型，并将推理工作量设置为低。您在这里不需要任何工具，“输出”格式可以保留为文本。

在运行时，此代理将接收用户输入的任何内容（input_as_text），并返回一个精炼版本，例如：

“概述自 2020 年以来锂离子电池回收对环境的影响。”

这个重写的问题现在将成为您工作流程其余部分的黄金线索。

5.3 将代理连接到状态

为了使后续节点可以访问此增强型提示，请将提示增强器连接到“设置状态”节点。在“设置状态”配置中，将提示增强器的输出映射到您之前创建的状态变量。

这实际上将精炼的提示“保存”到工作流程的共享内存中。任何下游代理（例如您的网络搜索分类器或答案生成器）现在都可以通过调用 ${research_prompt} 来引用它。您的画布现在应该如下所示。

完成此步骤后，您的智能研究代理已经可以处理一个杂乱的问题，并将其转换为一个精炼、可重复使用的查询，并安全地存储在内存中。接下来，我们将教会它判断该问题是需要网络搜索，还是可以直接使用模型的内置知识来回答。

5.4 isWebSearch 代理 - 分类查询是否需要实时数据

现在您的工作流程可以生成一个完善的研究问题并将其存储在 research_prompt 中，下一步是教会代理何时真正需要查找内容。并非每个查询都需要实时网络搜索——有些答案可以直接从模型的现有知识中生成。

为了做出这个决定，添加另一个代理节点并将其命名为 isWebSearch。此节点充当您的分类器——一个虽小但至关重要的推理层，它决定问题是应该触发网络查找还是保持独立。

在“说明”字段中，引用上一步保存的状态变量，以便模型接收上图中的优化提示。此说明为代理提供了所需的所有上下文——增强的查询和清晰的输出格式指导。

将输出格式设置为 JSON——这是关键的更改。您可以在此处定义一个严格的 JSON Schema，您的代理在输出答案时将遵循该 Schema。

此结构化输出是 If/Else 节点在下一步中读取的内容，以决定要遵循哪个工作流分支。

5.5 If/Else 逻辑 - 在网页搜索和模型知识之间进行路由

现在，我们的 isWebSearch 分类器可以返回清晰的 JSON 输出，下一步是训练工作流智能地进行分支。并非每个问题都值得进行完整的在线搜索——有些问题永恒不变（“裂解反应是什么？”），而有些问题则需要实时数据（“裂解反应的活化能是多少？”）。If/Else 节点会决定要采取哪条路径。

将一个 If/Else 节点拖到画布上，并将其连接到 isWebSearch 代理之后。此节点会读取您之前定义的布尔值，并相应地路由流程。

在配置面板中，您将看到两个字段：

• If 标签：Web Search – 此分支的描述性名称
• 表达式：input.output_parsed.isWebSearch

该表达式使用通用表达式语言 (CEL) 引用您之前代理解析后的 JSON 输出。其底层工作原理如下：input → 引用来自 isWebSearch 代理的传入数据。output_parsed → 是自动解析的 JSON 对象。.isWebSearch → 访问您在结构化架构中定义的布尔属性。

因此，如果值为 true，工作流将遵循 Web Search 分支。如果值为 false，则自动路由到 Else 分支，我们将使用该分支获取 LLM 的直接答案。您的工作流现在应如下所示。

5.6 Web Search 与非 Web Search — 完成工作流

有了 If / Else 逻辑，您的智能研究代理现在可以根据布尔输出遵循两条智能路径中的一条。工作流程最终在此变得自适应——推理是查找信息还是直接回答。

我们将定义两个代理节点，每个路径一个：

• 网页搜索代理 → 当 isWebSearch = true 时激活
• 无网页搜索代理 → 当 isWebSearch = false 时激活

两个分支都使用核心研究提示 ({{state.research_prompt}}) 相同，但在检索和处理信息的方式上有所不同。

网络搜索路径：当查询需要外部数据（例如时事、最新研究论文或动态信息）时，网络搜索代理会介入。在“工具”下，启用内置的网络搜索连接器——这将授予模型从网络中提取经过验证的最新信息的权限。

无网络搜索路径：对于不需要实时查找的常识性问题，无网络搜索代理提供了更快、更简洁的路径。它使用相同的模型配置（GPT-5，推理工作量低），但没有连接任何工具。这使得工作流程轻量且高效地进行静态查询。

配置完两个分支后，将它们的输出连接到最终的结束节点。现在，无论选择哪条路径，系统始终会干净地终止——要么返回网络增强答案，要么返回基于模型的解释。

现在我们已经完成了整个工作流的构建，它应该如下所示：

6、测试您的代理

工作流准备就绪后，点击 Agent Builder 中的“预览”进行实时测试。您将看到每个节点实时执行——从提示增强器优化您的输入，到 isWebSearch 代理决定要遵循哪个分支。

例如，当被问到“什么是裂解反应？”时，模型会将其识别为一个通用主题，并使用内置知识直接回答。但是，当被问到“裂解反应建模的最新进展是什么？”时，isWebSearch 节点会将其标记为需要新数据，从而触发 Web 搜索分支。

这个简单的测试确认了您的代理可以根据上下文进行推理——自动在基于知识的响应和基于 Web 的增强响应之间切换。一旦满意，您就可以继续发布和部署您的工作流。

7、评估您的工作流

当您的代理构建完成并顺利运行后，Agent Builder 可以让您更进一步——评估其性能。

在“评估”选项卡下，您可以查看工作流程运行的详细轨迹。每个轨迹都会记录每个节点的执行情况、运行时间和模型响应。这有助于您确定哪个步骤耗时最长、推理可能需要改进的地方，或者某个节点是否产生了意外的输出。

您还可以创建评分器，根据您自己的标准自动评估运行情况。例如，您可以定义一个评分器，用于检查代理是否礼貌、事实是否正确或是否遵循公司语气准则。评分器可以手动或自动运行，以跟踪不同工作流程版本的一致性。

这个内置的评估层将 Agent Builder 从一个简单的原型设计工具转变为一个完整的生命周期环境，用于持续构建、测试和改进代理。

8、发布和部署

测试您的工作流程后，最后一步是将其上线。Agent Builder 会自动保存您的进度，但发布会创建代理的版本快照，可集成到任何位置。

点击顶部导航栏中的“发布”即可生成新的版本 ID。现在，您有两种主要的部署选项：

• ChatKit 集成：最简单的方式——只需将您的工作流 ID 传入 ChatKit，即可将功能齐全的聊天式代理嵌入到您的 Web 或移动应用中。
• Agents SDK：对于高级用例，请下载生成的 SDK 代码，在您自己的基础架构上运行您的代理，从而获得完全的自定义和控制权。

部署完成后，您可以随时返回 Agent Builder 修改工作流、运行评估并发布新版本——让您的代理与您的想法同步发展。

9、结束语

就是这样——您刚刚使用 OpenAI 的 Agent Builder 构建、测试和评估了您的第一个智能工作流。

从使用可视化节点设计逻辑到在 Web 和基于模型的推理之间进行分支，您已经了解了 AgentKit 如何将复杂的代理行为转化为直观的拖放流程。借助内置的评估工具、版本控制以及通过 ChatKit 或 Agents SDK 进行的无缝部署，您现在拥有将想法从原型转变为可用于生产的代理所需的一切。

这个智能研究代理只是一个起点。您可以使用自定义工具、MCP 连接器或多智能体协作来扩展它，从而构建用于研究、数据分析、客户支持或自动化的专用助手。

智能体设计的新时代已经到来，构建从未如此简单。

原文链接：A Step-by-Step Guide to Building Your First Agent with OpenAI's Agent Builder

汇智网翻译整理，转载请标明出处