使用 watsonx Orchestrate ADK 和 IBM Cloud，通过 Langflow 构建自定义研究智能体

Langflow 是一个基于 Python 的开源框架，用于构建 AI 智能体和其他 AI 应用。Langflow 最初构建在它的母框架 LangChain 上。LangGraph 是同一系列中的另一个平台，也被用于通过基于图的架构构建智能体系统。Langflow 的与众不同之处在于其易于使用的拖放界面，用户可以在该界面中连接智能体组件来设计个性化的工作流或从预建的模板开始。作为这种低代码或无代码方法的替代方案，开发人员可以使用 Langflow API 构建自定义组件，并将分步智能体流程嵌入现有应用程序代码中。在本 Langflow 教程中，我们通过以下方式深入了解如何构建和部署智能体：

1. 使用 IBM® watsonx Orchestrate® 作为软件即服务 (SaaS)，并结合 IBM Cloud®，将智能体 LangFlow 流导入为 MCP 服务器。
2. 在本地使用 IBM watsonx Orchestrate Agent Development Kit (ADK) 导入基本 LangFlow 流程。

两种方法都对应于本教程的某一部分。注意，您也可以在 GitHub 上访问本教程。

我们开始吧！

本教程需要：

• 已安装最新版本的 Python。
• 用于创建 watsonx.ai 的 IBM Cloud 帐户项目 ID 和 API 密钥。提供精简版和免费版服务套餐。
  • 您可以从项目内部获取项目 ID。点击管理选项卡。然后，从常规页面的详细信息部分复制项目 ID。您需要此 ID 来完成本教程的 ADK 部分。
• watsonx Orchestrate 帐户（可以是试用帐户）。如果您还没有账户，请点击这里进行注册以获得 30 天免费试用。查看文档，了解有关如何在 IBM Cloud 上获得试用访问权限的详细说明。
• 已安装 IBM watsonx Orchestrate ADK。请按照此处的官方文档设置和安装 ADK。
  • 注意：如果您之前安装过 ADK 2.0 之前的 watsonx Orchestrate 开发者版本，请在升级之前先运行 Orchestrate 服务器重置来移除所有容器。watsonx Orchestrate 开发者版本不再依赖外部容器引擎。在升级前未能重置可能导致消耗不必要系统资源的多次应用安装，并引起端口冲突。
• IBM Cloud CLI 已安装。MacOS、Linux 和 Windows 的安装命令可以在入门指南中找到。

请注意，没有这些要求，将无法复制本教程。

在终端中运行以下命令。系统将提示您使用 IBMid 登录您的 IBM Cloud 帐户。如果您有多个帐户，则需要选择一个帐户。

注：凭据被拒？您可能是联合用户。再次登录时，使用 --sso 标记即可使用公司或企业单点登录 ID。有关使用联合 ID 登录的更多信息，请参阅文档。简而言之，当出现提示时，允许 URL 在默认浏览器中打开，并将出现的一次性代码粘贴回终端。

看到类似输出结果即表示登录成功。

输出：

注意：如果您发现区域不正确，请运行 ibmcloud target -r 后接正确的区域。例如，若区域服务端点为 us-east ，则运行 ibmcloud target -r us-east 。

要查看您的云资源，请运行 ibmcloud resource groups 。此命令应该能够检索您的资源组并产生类似的输出（您资源的名称和 ID 将有所不同）。

输出：

接下来，通过运行 ibmcloud target -g RESOURCE_GROUP 来定位特定资源。在这个例子中，命令将是 ibmcloud target -g itz-wxo-69305f32086a49ee3736ff 。

这个结果在输出中应该是相似的。

输出：

借助 IBM Cloud® Code Engine，您几乎可以运行任何容器化工作负载，而无需管理服务器或基础架构。该平台支持从微服务和应用程序到批处理作业和事件驱动功能的各种功能。它还提供从源代码创建内置映像的功能。因为所有工作量共享同一个 Kubernetes 环境，它们自然集成。Code Engine 的设计理念是让基础设施不再成为您的负担，以便您可以专注于构建应用程序。安装 Code Engine CLI 是我们的下一步。在终端中运行以下命令。

输出：

太棒了！现在，让我们以 Code Engine 中的一个项目为目标。首先，通过运行 ibmcloud ce project list 显示项目列表。

输出：

Code Engine 项目对应用程序、作业和内部版本等实体进行分组。它是管理资源和控制对这些实体的访问的单元。如果您没有任何活动的 Code Engine 项目，运行 ibmcloud ce project create --name PROJECT_NAME ，并用您选择的项目名称替换 CE_PROJECT_NAME （例如“code-engine-project”）。

要定位特定项目，请运行 ibmcloud ce project select --name CE_PROJECT_NAME 。在这个例子中，命令将是 ibmcloud ce project select --name ce-itz-wxo-69305f32086a49ee3736ff 。

输出：

注意：如果在此处遇到错误，请确保已使用 ibmcloud target -c ACCOUNT_ID -r REGION_NAME -g RESOURCE_GROUP_NAME 指定了正确的环境。

要在使用 Code Engine CLI 的同时使用 Langflow，请运行以下命令。

此命令可能会运行几分钟。请勿干预，任其运行。

输出：

在 Langflow 设置命令运行时，我们可以添加一个环境来与本地计算机和 SaaS 托管解决方案交互。

在新的终端窗口中，激活您选择的目录中的虚拟环境。可以将 my-env 更改为您选择的任何环境名称。

使用以下命令激活虚拟环境，如果使用了其他虚拟环境，则将 my-env 替换为您的环境名称：

MacOS/Linux：

Windows：

现在，在您偏好的浏览器中，访问您的 IBM Cloud 资源列表，展开 AI/机器学习下拉菜单，选择活动的 wxO 资源。例如，它的名字应类似于“Watson Orchestrate-itz”，然后复制在凭据窗口中找到的 URL。请在浏览器中保持此页面打开状态，因为您稍后会用到它。在以下命令中，将 YOUR_WXO_RESOURCE_URL 替换为检索到的 URL，并在终端中激活的虚拟环境中运行该命令。

输出：

当提示输入 wxO API 密钥时，返回浏览器中打开的资源页面。不要输入位于您复制的 URL 上方的 API 密钥。相反，点击“启动 Watsonx Orchestrate”按钮。然后，点击屏幕右上角带有您姓名缩写的圆形图标，打开设置。选择 API 详情标签，点击生成 API 密钥按钮。接下来，输入 API 密钥的任意名称和描述，然后在“泄露操作”部分选择“禁用泄露的密钥”。最重要的是，在“会话管理”部分选择“是”，启用 CLI 登录的会话管理，然后点击“创建”。应该会显示您的 API 密钥。请在您刚才使用的终端复制粘贴密钥，以满足输入 wxO API 密钥的请求。

输出：

太棒了！Langflow 现已启用。

要建立稳定的 Code Engine 环境，使其在固定超时期限后不会删除 Langflow 应用程序，请再次打开浏览器。访问 IBM Cloud 容器概览。您应该能看到您的 Code Engine 项目显示为最新创建的项目。打开项目。接下来，打开 Langflow 应用程序。在配置标签页中，打开资源与缩放组件。我们在这里需要做的唯一更改是将最小实例数从 0 增加到 1。最后，单击部署按钮以应用此配置修订版。

完成此步骤后，点击测试应用程序按钮，然后点击应用程序 URL 超链接。此操作将打开我们的 IBM Cloud Langflow 实例。

构建 Langflow 流程的方法有很多。您可以使用预构建的模板，也可以从头开始创建自己的模板。在本教程中，我们将深入了解后者。开始时，点击 + 空白流程。此示例演示了一个可以构建的流程，但您可以随意深入了解 Langflow 中内置的大量组件和集成。

1. 从菜单中添加以下内置组件节点：

• 聊天输入——接收聊天中的用户输入。

• 聊天输出- 将流程输出返回给聊天中的用户。

• 智能体-使用大型语言模型 (LLM) 集成来响应用户输入，可以连接到多个工具。²

• MCP 工具- 连接到模型上下文协议 (MCP) 服务器，并将 MCP 服务器的功能作为工具公开，供智能体用于响应输入^。2

• IBM® watsonx.ai - 提供对 IBM watsonx.ai 模型的访问权限以生成文本。³

• 新闻搜索 - 提取 Google News 内容并生成结构化的 DataFrame，其中包含每篇文章的标题、链接、出版日期和摘要。⁴

• arXiv - 在 arXiv.org 中搜索相关论文，并以 DataFrame 格式输出结果。⁵

  最后，在菜单底部选择+ 新建自定义组件。

  为了便于可视化，请按以下方式安排流程。

2.    将聊天输入组件连接到智能体组件的“输入”字段。

3.    将聊天输出组件连接到智能体组件的“响应”字段。

4.    在智能体组件中，从下拉列表中将“模型提供方”设置为“自定义”。若您使用的 Langflow 版本不同，可能只会看到“连接其他模型”。任何一种情况都是可以接受的。

5.     在 IBM Watsonx.ai 组件中，选择适合您 API 凭据的 watsonx.ai API 端点。接下来，将您的 watsonx.ai 项目 ID 和 API 密钥粘贴到相应的字段中。然后，选择所需的大语言模型名称。在本教程中，我们选择 openai/gpt-oss-120b 。确保将该组件设置为“语言模型”，而不是“模型响应”。这个设置很重要，因为我们想使用这个模型作为智能体的语言模型。因此，我们现在可以将 IBM watsonx.ai组件连接到智能体组件的“语言模型”字段中。

• 注意：如果您更喜欢使用全局变量而不是直接粘贴 API 凭据，请点击屏幕右上角的个人资料图标，然后选择“设置” 。在“全局变量”部分，添加您的WATSONX_PROJECT_ID 和WATSONX_APIKEY 用于您作为本教程先决条件而生成的 watsonx.ai 连接。返回流程后，应能在“watsonx.ai 项目 ID”和“API 密钥”文本字段中看到一个地球图标。单击该图标，然后从下拉列表中选择适当的密钥。

6. 使用 arXiv 、新闻搜索和自定义组件的切换开关启用工具模式。单击这些组件上的任意位置，即可在标题菜单中看到此切换开关。启用此模式后，您现在可以将这些组件连接到智能体组件的“工具”字段。arXiv 和 News Search 组件已配置并准备使用。我们现在可以专注于配置其他组件。

7. 在自定义组件的标题菜单中，选择<>代码。在这里，我们可以通过编辑定义该组件的 Python 代码来定制其行为^。6举个简单的例子，我们可以创建一个工具，返回今天的日期，并获取 LLM 原本无法访问的知识。请将以下样板代码替换为：

继续并保存更改。现在，您应该看到组件反映了新的名称、描述和图标。

8. 您提供给智能体的工具数量完全取决于您。但是，请记住不要用太多工具让您的智能体不堪重负，因为这可能会影响性能和准确性。我们要启用的最后一个工具是 MCP 服务器。您可以连接到您选择的任何服务器。在本教程中，我们将连接到 Alpha Vantage MCP 服务器。⁷官方的 Alpha Vantage MCP 服务器通过使用 Model Context 协议，方便 LLM 和智能体获取实时和过去的库存数据。要连接该服务器，请在 MCP工具组件中打开“MCP 服务器”下拉菜单，点击+添加 MCP 服务器。在 STDIO 标签页中，给服务器提供任意名称，例如 “av_mcp”，并粘贴以下命令：uvx av-mcp YOUR_API_KEY 。要生成免费的 Alpha Vantage API 密钥，请访问 Alpha Vantage 官方网站并将其粘贴到命令中，替换 YOUR_API_KEY 占位符。添加服务器后，在组件节点的标题菜单中启用“工具模式”切换开关。您会看到一大堆“操作”工具列表。该结果表明与 MCP 服务器的连接成功。现在您可以将最后一个组件连接到智能体组件的“工具”字段。

做得好！您的流程已完成，应类似于以下屏幕截图。

要验证研究管道是否按预期运行，请打开演习场并与您新建的智能体聊天！向智能体提出需要调用已连接工具的问题。一些示例输入值包括：

• 简单来说：
  • “今天是几号？”
  • “给我找 5 篇关于量子计算的研究论文。”
• 适中：
  • “分析过去 30 天内 IBM 的股票价格。”
• 复杂：
  • “最近是否有任何消息表明 IBM 股票将上涨或下跌？”

您应该看到智能体调用其可用工具并生成正确的输出。如果您在此阶段体验到任何问题，请返回您的流程，确保您的凭据正确，并且您已按照每个步骤操作。

将此流程连接到 watsonx Orchestrate 的一种方法是将其作为 MCP 服务器。点击右上角的分享下拉菜单，然后选择“MCP 服务器”。点击进入“JSON”选项卡。您应该看到类似于以下示例的代码：

复制 JSON 片段中的 URL。请注意，这将与前面的例子有所不同。返回终端，粘贴您的 MCP 服务器 URL 代替 MCP_SERVER_URL 占位符。在 watsonx Orchestrate CLI 中运行以下命令，我们可以将此 MCP 服务器作为工具包导入到平台中。

输出：

步骤 8. 创建智能体并测试工具调用

在浏览器中，前往 Watsonx Orchestrate 并从头开始构建一个新的智能体。输入您智能体的姓名和描述。创建后，打开工具集标签，点击添加工具按钮。从那里选择从 MCP 服务器导入工具。在选择 MCP 服务器下拉菜单中，选择我们导入的服务器，通过切换激活激活工具，关闭窗口。接下来，点击部署。部署完成后，您可以在预览聊天窗口或折叠页面菜单中的聊天界面与您的智能体聊天。

让我们向智能体询问一下吧！例如：“查找 5 篇有关量子计算的研究论文”。

太棒了！智能体聊天机器人的行为如预期般，不仅输出了正确的回答，还调用了正确的 arXiv 工具。请随意尝试不同的提示。

采用这种方法时，不需要 Code Engine。这种方法使用 watsonx Orchestrate Developer Edition SDK（watsonx Orchestrate 的一个轻量级版本，可用作本地开发服务器）来建立本地开发环境。

• 机器规格：
  • 16 GB 内存
  • 8 个核心
  • 25GB 磁盘空间

在开始使用 Langflow 进行本地构建之前，请安装 WxO ADK 的开发者版。请注意，本教程的第一种方法不需要此开发者版本。

1. 在您的首选 IDE 中，设置您的环境。创建一个名为 wxo-langflow-agent 的文件夹，用于存储所有智能体和工具。您可以在 Github 上找到这个项目，作为参考。文件夹结构应为：

   wxo-langflow-agent/
   ├── .env
   ├── tools/
   └── agents/
   

2. 打开终端并激活虚拟环境。可以将 my-env 更改为您选择的任何环境名称。

使用以下命令激活虚拟环境，如果使用了其他虚拟环境，则将 my-env 替换为您的环境名称：

MacOS/Linux：

Windows：

3.  在 .env 文件中，设置以下环境变量。更多信息请参见设置指南。

4.  运行以下命令安装 Watsonx Orchestrate Developer Edition 服务器。我们无需安装 Langflow，因为它已包含在 ADK 开发者版本中。--with-langflow 命令标志通过拉取必要的容器映像并执行初始配置来启用 Langflow 支持，从而使 Langflow 在本地可访问。

如果是首次激活服务器，此命令运行可能需要数分钟。

故障排除：如果您过去在 ADK 版本 2.0 之前安装了 watsonx Orchestrate 开发者版，并且在启动容器时遇到错误，请运行：

输出结果的末尾部分应类似于以下示例。

输出：

如前面的输出所示，Langflow 编辑器可通过 watsonx Orchestrate 开发者版在端口 7861 上使用。

1. 在您的网络浏览器中，导航至 http://localhost:7861。
2. 构建您的流程。我们可以重新利用本教程第一部分中构建的流程，或者您也可以构建自己的流程。在本教程的后续部分，您可能会发现为流程指定自定义名称和描述（而不是默认名称和描述）会很有帮助。您可以将光标悬停在屏幕顶部的流程名称上，然后单击铅笔图标来完成此操作。

• 流程名称示例：研究智能体
• 流程描述示例：新闻搜索、arXiv、今日日期和 Alpha Vantage API 的访问权限。

我们可以深入了解将 Langflow 流程导入本地 watsonx Orchestrate 服务器的两个选项：

a) 将该流程导入为本地 MCP 服务器。

b) 将流程导入为 JSON。

这一步骤与本教程前半部分中的步骤 7 类似，只有一些细微的差别。

4.    在工具集选项卡中，点击添加工具按钮。选择“本地实例”以添加我们已导入的 MCP 服务器，勾选对应已导入 MCP 服务器的框，然后点击添加到智能体。

5.    开始聊天！

作为将流程导入为 MCP 服务器的替代方案，我们可以使用 ADK 以导出的 JSON 文件形式导入流程。

1.这种方法最适合简单的流程。出于演示目的，我们使用此流程：

单击分享按钮并选择导出，将流程导出为 JSON 格式。输入您想要的工具/流程的任何名称和描述。工具名称只能包含字母数字字符和下划线，并且不能以数字或下划线开头。

2. 将新导出的 JSON 文件添加到 tools 文件夹。

3.  运行以下命令将您的流程导入到 watsonx Orchestrate。

4.  将 Langflow 流程导入为工具后，后续步骤是将其连接到智能体系统。要完成此步骤，您可以在 watsonx Orchestrate 用户界面中创建新智能体，或者将以下智能体定义复制到 agents 文件夹中的新 arxiv_agent.yml 文件。

现在，通过运行以下命令导入简单智能体：

5.  刷新本地运行的 watsonx Orchestrate 聊天用户界面的浏览器，以查看我们的更改是否已反映出来。在智能体下拉菜单中，选择“ArXiv 智能体”，并提出需要使用 arXiv 工具的问题！

提示示例：“给我找 5 篇关于量子计算的研究论文。”

输出：

太棒了！智能体认为有必要为此用户查询调用 arxiv 工具。工具输出将显示在折叠的推理流程中，并作为响应显示在聊天窗口中。

本教程为您提供了利用 Langflow 和 watsonx Orchestrate 构建强大、可扩展的企业级智能体的关键技能。您学习了如何使用 watsonx Orchestrate 作为软件即服务 (SaaS) 以及 IBM Cloud，将智能体式 LangFlow 流导入为 MCP 服务器。此外，您现在还熟悉了在本地使用 IBM® watsonx Orchestrate Agent Development Kit (ADK) 时如何导入基本的 LangFlow 流程。通过按照分步说明进行操作，您已经学会了设计、开发和部署会调用自定义和预构建工具来解决用户查询的智能体。借助 Langflow 直观的可视化界面，您可以创建复杂的工作流，而 watsonx Orchestrate 则帮助您高效管理和扩展这些智能体。下一步，通过处理实际用例来运用从本教程中获得的知识。选择组织内可从自动化中获益的具体业务问题或流程，并设计基于 Langflow 和 watsonx Orchestrate 的解决方案来加以解决。这种实践体验将巩固您的理解，并帮助您确定需要进一步改进或探索的领域。

如果遇到问题或有任何疑问，请查阅文档。故障排除指南涵盖了大多数常见问题。您还可以评论 GitHub issues，看看其他人是否遇到过类似的问题。