在 watsonx.ai 上使用 IBM Granite 部署 IT 支持 LangGraph ReAct 智能体

作者

AI Engineer, Developer Advocate

IBM

在本教程中，您将构建一个 ReAct（推理与行动）AI 智能体，方法是利用开源的 LangGraph 框架，并使用 IBM Granite 模型（通过在 Python 中调用 IBM® watsonx.ai API）。用例将是管理现有的 IT 支持工单和创建新的工单。

什么是 ReAct 智能体？

人工智能 (AI) 智能体是指能够通过设计其智能体工作流和利用可用工具，代表用户或其他系统自主执行任务的系统或程序。生成式 AI 智能体使用自然语言处理 (NLP) 的先进技术和大语言模型 (LLM)，逐步理解并响应用户输入，并决定何时调用外部工具。AI 智能体的核心组件是推理。当通过工具调用、人工干预或其他智能体获取新信息时，推理范式会指导智能体的后续步骤。

在每一次动作和每一次工具响应中，ReAct（推理与行动）范式都会指示智能体进行“思考”，并规划下一步操作。这种循序渐进、缓慢的推理让我们洞察分析智能体如何使用更新的上下文来得出结论。由于这一反思过程是持续进行的，它通常被称为“思考—行动—观察”循环，并且是一种链式思维提示形式。

使用 LangGraph 构建 ReAct 智能体

本教程将使用 LangGraph 框架，这是一种开源的 AI 智能体框架，旨在构建、部署和管理复杂的生成式 AI 智能体工作流。LangGraph 提供的预构建函数 create_react_agent ，是一种构建简单自定义智能体的便捷方式。简单的 ReAct 智能体，就像本教程中的图 1 所示的智能体一样，由两个节点组成。一个节点负责调用模型，另一个节点负责使用工具。常见的工具包括预先构建的 LangChain Wikipedia 工具、DuckDuckGoSearchRun 工具，甚至检索增强生成 (RAG)。在操作输入复杂的情况下，可以添加另一个节点，如图 2 所示。这个额外的节点旨在帮助确保智能体返回结构化输出。

在 LangGraph 中，“状态”功能作为一个记忆库，用于记录和跟踪 AI 系统每次迭代处理的所有重要信息。这些具有状态的图表使智能体能够回忆过去的信息和重要的上下文。当某一步的结果依赖于循环中之前的步骤时，ReAct 图的循环结构就会被利用。图中的节点，或称“执行者”，用于编码智能体逻辑，并通过边缘进行连接。边缘本质上是 Python 函数，它们根据当前状态决定下一个要执行的节点。

先决条件

您需要 IBM Cloud 帐户创建 watsonx.ai 项目。

步骤

要使用 watsonx 应用程序编程接口 (API)，您需要完成以下步骤。注意，您也可以在 GitHub 上访问本教程。

第 1 步：生成 watsonx.ai 凭据

使用您的 IBM Cloud 帐户登录 watsonx.ai 。
创建一个 watsonx.ai 运行时服务实例（选择适当的区域并选择 Lite 计划，这是一个免费实例）。
生成应用程序编程接口 (API) 密钥。

第 2 步：在 IDE 中设置项目

要轻松开始在 watsonx.ai 上部署智能体，请克隆此 GitHub 存储库并访问 IT 支持 ReAct 智能体项目。您可以在终端中运行以下命令来执行此操作。

git clone git@github.com:IBM/ibmdotcom-tutorials.git
cd react-agent-langgraph-it-support/base/langgraph-react-agent/

接下来，如果您尚未安装 poetry，请进行安装。Poetry 是一个用于管理 Python 依赖项和打包的工具。

pipx install --python 3.11 poetry

然后，激活虚拟环境。

source $(poetry -q env use 3.11 && poetry env info --path)/bin/activate

与使用 pip install 命令不同，poetry 工具允许我们通过在终端运行以下命令来添加依赖项。此步骤会将存储库中的 pyproject.toml 文件中列出的依赖项安装到您的独立虚拟环境中。

poetry install

对于后续步骤，需要将工作目录添加到 PYTHONPATH。在终端中执行：

export PYTHONPATH=$(pwd):${PYTHONPATH}

要设置您的环境，请按照 GitHub 上的 README.md 文件中的说明进行操作。此设置需要在 IDE 或命令行上运行多个命令。

第 3 步：设置环境变量

在 config.toml 文件中，您将发现以下空白凭据，在尝试部署智能体之前必须填写这些凭据。您的 watsonx_apikey 和 watsonx_url 已在本教程的第 1 步中初始化。接下来，按照开发者访问权限页面上的简单表单选择您的部署空间或创建新的部署空间。在那里，您可以检索 space_id ，使用该 ID 将我们的智能体连接到 watsonx.ai 部署。最后，您的 model_id 设置为 IBM Granite 3.2 模型。

[deployment]
watsonx_apikey = ""
watsonx_url = "" # should follow the format: `https://{REGION}.ml.cloud.ibm.com`
space_id = "" # found in the "Manage" tab of your Deployment or in the Developer Access page here: https://dataplatform.cloud.ibm.com/developer-access

[deployment.custom]
# during creation of deployment additional parameters can be provided inside `CUSTOM` object for further referencing
# please refer to the API docs: https://cloud.ibm.com/apidocs/machine-learning-cp#deployments-create
model_id = "ibm/granite-3-2-8b-instruct"
thread_id = "thread-1" # More info here: https://langchain-ai.github.io/langgraph/how-tos/persistence/

第 4 步：将数据上传到 IBM Cloud Object Storage

我们的智能体需要数据源来提供最新信息并添加新数据。我们将把数据文件存储在 IBM® Cloud Object Storage 中。

首先，登录 IBM Cloud。然后，创建一个新项目。
在左侧菜单中，选择资源列表。使用创建资源按钮，创建新的 Cloud Object Storage 实例或直接使用此链接。
打开新创建的 IBM Cloud 存储空间实例，创建一个新存储区。在本教程中，您可以选择智能套餐，即免费套餐。根据指示上传文件。有关示例文件，请参阅第 2 步中链接的 GitHub 存储库中的 Tickets.csv 文件。

第 5 步：建立数据连接

为了为 ReAct 智能体提供 IT 工单管理功能，我们必须连接到 IBM Cloud Object Storage 中的数据源。对于这一步，我们可以使用 ibm_boto3 库。

在 tools.py 中， COS_ENDPOINT , COS_INSTance_CRN , BUCKET_NAME 和 CSV_FILE_NAME 必须填写正确的信息，这些信息可以通过在您的 Cloud Object Storage 实例的“配置”标签下找到的存储桶详细信息来获取。

COS_ENDPOINT = "" #find in your COS bucket configuration
COS_INSTANCE_CRN = "" #find in your COS bucket configuration
BUCKET_NAME = "" #find in your COS bucket configuration
CSV_FILE_NAME = "filename.csv" #you can use the provided tickets.csv sample file

cos = ibm_boto3.client(
"s3",
ibm_api_key_id=dep_config["watsonx_apikey"],
ibm_service_instance_id=COS_INSTANCE_CRN,
config=Config(signature_version="oauth"),
endpoint_url=COS_ENDPOINT,
)

第 6 步：创建自定义工具

我们的智能体将能够读取和写入我们文件中的数据。首先，让我们使用 LangChain 的@tool 装饰器创建一个用于读取数据的工具。

我们已将这个find_tickets 工具添加到tools.py 文件中。此工具从 Cloud Object Storage 中检索数据对象，并将其作为 Pandas DataFrame 返回。否则会出现异常。

@tool
def find_tickets():
"""Returns a list of of all tickets."""
try:
response = cos.get_object(Bucket=BUCKET_NAME, Key=CSV_FILE_NAME)
csv_data = pd.read_csv(response['Body'])
print("Ticket file loaded successfully:")
return csv_data
except Exception as e:
print(f"Error loading file from COS: {e}")
return None

接下来，我们添加了 create_ticket 工具。

@tool
def create_ticket(issue: str, urgency:str):
"""Creates a tickets for a customer issue. Request a detailed explanation of the customer issue and urgency level before creating a ticket.

Args:
issue (str): A description of the issue.
urgency (str): A category value for the level of urgency. Can be "low", "medium", or "high".

Returns:
The new ticket.
"""
try:
# retrieve the existing item to reload the contents
response = cos.get_object(Bucket=BUCKET_NAME, Key=CSV_FILE_NAME)
existing_body_df = pd.read_csv(response['Body'])
new_ticket = {"issue": issue, "date_added":datetime.now().strftime("%m-%d-%Y"), "urgency":urgency, "status":"open"}
# Add a new row (i.e. ticket) using loc[]
existing_body_df.loc[len(existing_body_df)] = new_ticket

cos.put_object(Bucket=BUCKET_NAME, Key=CSV_FILE_NAME, Body=existing_body_df.to_json())
return "New ticket successfully created!"
except Exception as e:
print("Unable to create new ticket. Please try again.")

此工具将用户对问题的描述和问题的紧迫性作为其论据。将此信息添加到 COS 中的文件中，从而创建新工单。否则会出现异常。

我们必须在 tools.py 文件中添加的最后一个工具是 get_todays_date 工具，它使用 datetime 模块返回今天的日期，格式为 MM-DD-YYYY。这个工具对于获取当前日期非常有用，因为智能体无法通过其他方式获取日期信息，LLM 也没有在训练中包含这部分数据。

@tool
def get_todays_date():
"""Returns today's date in MM-DD-YYYY format."""
date = datetime.now().strftime("%m-%d-%Y")
return date

为了授予我们的智能体访问这些工具的权限，我们已经将它们添加到 TOOLS 列表中，该列表位于 extensions 模块的 init.py 文件中。该列表应为 init.py 您位于 src/langgraph_react_agent 目录下文件的内容。

from .tools import (
find_tickets,
get_todays_date,
create_ticket
)

TOOLS = [
find_tickets,
get_todays_date,
create_ticket
]

这些工具被导入 agent.py 文件，并传递给预构建的 LangGraph create_react_agent 函数，担任智能体执行器。其他参数包括使用 ChatWatsonx 类初始化的大语言模型（允许在 watsonx.ai 上调用工具）、内存保存器以及系统提示。请注意，不同的提示表现可能有所不同，因此根据您选择的 LLM，可能需要进行一定程度的提示优化。

在部署智能体之前，请记得在文件中填写所有必要的 config.toml 信息。

第 7 步：与您的智能体聊天

有三种方式可以与您的智能体聊天。

选项 1：在本地查询智能体

运行脚本以执行本地 AI 服务。

poetry run python examples/execute_ai_service_locally.py

选项 2：将智能体部署到 watsonx.ai 中的内置聊天界面

最后一个选项是访问 watsonx.ai 上“Deployments”空间中的智能体。为此，请在左侧菜单上选择“Deployments”。然后，选择您的部署空间，点击“Assets”标签，选择您的在线 ai_service 资产，再次选择带有“wx-agent”标签的资产，最后打开“Preview”标签。现在，您可以在交互式聊天界面中与智能体聊天。这 3 个选项中的每一个都应该会产生类似的输出。

选项 3：在 IDE 中部署智能体并与智能体聊天

要运行部署脚本，请初始化 deployment_id 变量（在 query_existing_deployment.py 文件中）。

您的部署 deployment_id 可以通过运行 scripts/deploy.py 文件获得。

接下来，运行部署脚本。

poetry run python scripts/deploy.py

然后，运行用于查询部署的脚本。

poetry run python examples/query_existing_deployment.py

在本教程中，我们选择选项 2，以智能体聊天机器人的形式在 watsonx.ai 上查询已部署的智能体。让我们为智能体提供一些需要使用工具的提示。执行选项 3 中列出的步骤后，您应在 watsonx.ai 上看到一个聊天界面。在那里，我们可以输入我们的提示。

首先，让我们测试 create_ticket 是否能够成功调用该工具。让我们提示智能体创建一个新工单。

正如您在智能体的最终回答中看到的，AI 系统成功地使用 create_ticket 工具进行问题解决并创建了一个新工单。能够查看工具调用情况对于调试非常有帮助。现在，让我们检查工单是否已成功添加到作为智能体知识库的数据文件中。

太棒了！智能体已成功将工单添加到文件中。

总结

在本教程中，您使用 ReAct 框架创建了一个智能体，该智能体使用决策功能来解决复杂的任务，例如检索和创建支持工单。目前有几种 AI 模型支持智能体工具调用，例如 Google 的 Gemini、IBM 的 Granite 和 OpenAI 的 GPT-4。在我们的项目中，我们通过 watsonx.ai API 使用 IBM Granite AI 模型。无论在本地还是在 watsonx.ai 上部署时，该模型的表现都符合预期。接下来，请查看 LlamaIndex 和 crewAI multiagent 模板，这些模板可在 watsonx-developer-hub GitHub 存储库中获取，用于构建 AI 智能体。

2025 年主要战略技术趋势：智能体式 AI

下载这份 Gartner 研究报告，了解智能体式 AI 对 IT 领导者的潜在机遇和风险，以及如何为这新一轮 AI 创新做好准备。