watsonx.ai上のIBM Graniteを使用してITサポートLangGraph ReActエージェントをデプロイする

執筆者

AI Engineer, Developer Advocate

IBM

このチュートリアルでは、PythonのIBM® watsonx.ai® APIを通じてIBM® Graniteモデルを使用して、オープンソースのLangGraphフレームワークでReAct（推論とアクション）AIエージェントを構築します。ユースケースは、既存のITサポート・チケットの管理と新しいITサポート・チケットの作成です。

ReActエージェントとは

人工知能（AI）エージェントとは、ワークフローを設計し、利用可能なツールを活用することで、ユーザーまたは別のシステムに代わってタスクを自律的に実行できるシステムまたはプログラムです。生成AIエージェントは、大規模言語モデル（LLM）の高度な自然言語処理技術（NLP）を活用して、ユーザーの入力を段階的に理解・対応し、外部ツールを呼び出すタイミングを決定します。AIエージェントの中核となるコンポーネントは推論です。ツールの呼び出し、人間の介入、または他のエージェントを通じて新しい情報を取得すると、推論パラダイムがエージェントの次のステップを導きます。

各アクションと各ツールの応答について、ReAct（推論とアクション）パラダイムは、エージェントに「考察」して次のステップを計画するよう指示します。この段階的な低速の推論により、エージェントが更新されたコンテキストをどのように使用して結論を導き出すかについての洞察が得られます。この反省のプロセスは継続的であるため、Think（思考）-Act（行動）-Observe（観察）ループと呼ばれることが多く、思考の連鎖を促す形式です。

LangGraphを使用してReActエージェントを構築

このチュートリアルでは、複雑な生成AIエージェントのワークフローを構築、展開、管理するために設計されたオープンソースAIエージェント・フレームワークであるLangGraphフレームワークを使用します。LangGraphが提供する、事前構築済みの create_react_agent 関数は、シンプルなカスタム・エージェントを簡単に構築する方法です。このチュートリアルの図1に示すような単純なReActエージェントは、2つのノードで構成されています。一方のノードはモデルの呼び出し、もう一方のノードはツールの使用を役割としています。一般的なツールには、事前構築されたLangChain Wikipediaツール、DuckDuckGoSearchRunツール、さらには検索拡張生成（RAG）などがあります。複雑なアクション入力がある場合には、図2のように、別のノードを追加できます。この追加ノードは、エージェントが構造化された出力を確実に返せるようにするためのものです。

ReActエージェント・アーキテクチャーの図

LangGraph内では、state機能がAIシステムの各イテレーションによって処理されたすべての貴重な情報を記録および追跡するメモリー・バンクとなります。これらのステートフルなグラフにより、エージェントは過去の情報や貴重なコンテキストを思い出すことができます。ReActグラフの循環構造は、1つのステップの結果がループ内の以前のステップに依存する場合に活用されます。グラフ内のノード、つまり「アクター」は、エージェント・ロジックをエンコードし、エッジによって接続されます。エッジは本質的に、現在の状態に応じて次に実行するノードを決定するPythonの機能です。

前提条件

watsonx.aiプロジェクトを作成するにはIBM Cloudのアカウントが必要です。

ステップ

watsonxのアプリケーション・プログラミング・インターフェース（API）を使用するには、次の手順を完了する必要があります。なお、このチュートリアルにはGitHubでもアクセスできます。

ステップ1. watsonx.aiの認証情報を生成する

watsonx.aiにログインします。IBM Cloudアカウントを使用します
watsonx.ai Runtimeサービス・インスタンスを作成します（適切なリージョンを選択し、無料インスタンスである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で初期化されました。次に、開発者アクセスページにある簡単なフォームに従って、デプロイメント・スペースを選択するか、新しいデプロイメント・スペースを作成します。そこでエージェントをwatsonx.aiのデプロイメントに接続するために必要な space_id を取得できます。最後に、 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 Storage Instanceを開き、新しいバケットを作成します。このチュートリアルでは、無料利用枠であるSmat Tierを選択できます。指示に従い、ファイルをアップロードします。サンプル・ファイルについては、ステップ2でリンクしたGitHubリポジトリーのticket.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データフレームとして返します。それ以外の場合は、例外がスローされます。

@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

エージェントにこれらのツールへのアクセスを許可するため、これらを拡張機能モジュールの init.pyファイル内の TOOLSリストに追加しました。このリストは、 TOOLSリストに 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 AgentExecutorとして渡されます。他のパラメーターには、 ChatWatsonx クラスを使って初期化された大規模言語モデルを含めます。このクラスは、watsonx.ai、メモリー・セーバー、システム・プロンプトでのツール呼び出しを可能にします。注：一部のプロンプトは他のプロンプトよりも優れて動作するため、選択したLLMによっては、ある程度のプロンプト・エンジニアリングが必要になる場合があります。

エージェントをデプロイする前に、ファイル内の必要なすべての情報をファイル内に、忘れずに入力します。

ステップ7. エージェントとチャットする

エージェントとチャットするには3つの方法があります。

オプション1. エージェントをローカルでクエリする

ローカルでAIサービスを実行するためのスクリプトを実行します。

poetry run python examples/execute_ai_service_locally.py

オプション2. watsonx.aiの組み込みチャット・インターフェースにエージェントをデプロイする

最後のオプションは、watsonx.aiのデプロイメント領域でエージェントにアクセスすることです。これを行うには、左側のメニューで[デプロイメント]を選択します。次に、デプロイメント領域を選択し、[アセット]タブからonline ai_service アセットを選択し、「wx-agent」タグの付いたアセットをもう一度選択し、最後に[プレビュー]タブを開きます。これで、インタラクティブ・チャットのインターフェースでエージェントとチャットすることができるようになりました。これら3つのオプションはそれぞれ、同様の出力を実現します。

オプション3. IDEでエージェントをデプロイしてチャットする

デプロイメント・スクリプトを実行するには、 query_existing_deployment.py ファイル内の deployment_id 変数を初期化します。

query_existing_deployment.py デプロイメントのスクリプトは、 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 呼び出されるかどうかテストしましょう。エージェントに新しいチケットを作成するようプロンプトしてみましょう。

watsonx.aiにデプロイしたエージェントにクエリして新しいチケットを作成

エージェントの最終的な回答からわかるように、AIシステムは問題解決を正常に使用し、 create_ticket ツールによって新しいチケットを作成しました。ツール呼び出しを可視化すると、デバッグに役立ちます。それでは、チケットがエージェントのナレッジ・ベースとして機能するデータ・ファイルに正常に追加されたかどうかを確認してみましょう。

watsonx.aiにデプロイしたエージェントにクエリして最近のチケットを取得

成功です。エージェントはチケットをファイルに正常に追加しました。

結論

このチュートリアルでは、意思決定を利用してサポート・チケットの取得や作成などの複雑なタスクを解決するReActフレームワークを使用してエージェントを作成しました。現在、GoogleのGemini、IBMのGranite、OpenAIのGPT-4など、エージェント・ツールの呼び出しを可能にするAIモデルがいくつかあります。このプロジェクトでは、watsonx.ai APIを通じてIBM Granite AIモデルを使用しました。このモデルはローカルでも、watsonx.aiにデプロイしても、期待どおりに動作しました。次のステップとして、LlamaIndexとcrewAI マルチエージェントテンプレートをチェックしましょう。これらは、AIエージェント構築用にwatsonx-developer-hub GitHubリポジトリーで利用できます。