watsonx.ai에서 IBM Granite를 활용해 IT 지원 LangGraph ReAct 에이전트 배포

작성자

AI Engineer, Developer Advocate

IBM

이 튜토리얼에서는 IBM® Granite 모델을 사용하는 오픈 소스 LangGraph 프레임워크로 ReAct(추론 및 행동) AI 에이전트를 구축하며, 이를 위해 Python에서 IBM® watsonx.ai API를 사용합니다. 사용 사례는 기존 IT 지원 티켓을 관리하고 새 티켓을 만드는 것입니다.

ReAct 에이전트란 무엇인가요?

인공 지능(AI) 에이전트는 에이전트 워크플로를 설계하고 사용 가능한 툴을 활용하여 사용자 또는 다른 시스템을 대신하여 자율적으로 작업을 수행할 수 있는 시스템 또는 프로그램을 말합니다. 생성형 AI 에이전트는 대규모 언어 모델(LLM)의 고급 자연어 처리(NLP) 기술을 사용하여 사용자 입력을 단계별로 이해하고 응답하며 외부 도구를 호출할 시점을 결정합니다. AI 에이전트의 핵심 구성 요소는 추론입니다. 도구 호출, 인간 개입 또는 기타 에이전트를 통해 새로운 정보를 획득하면 추론 패러다임이 에이전트의 다음 단계를 안내합니다.

각 작업과 각 도구 응답에 대해 ReAct(추론 및 행동) 패러다임은 에이전트에게 다음 단계를 '생각'하고 계획하도록 지시합니다. 이 단계별로 느리게 진행되는 추론을 통해 에이전트가 업데이트된 컨텍스트를 사용하여 결론을 공식화하는 방법에 대한 인사이트를 얻을 수 있습니다. 이 성찰 과정은 연속적이기 때문에 종종 생각-행동-관찰 루프라고도 하며 생각의 연결고리 프롬프트의 한 형태입니다.

ReAct 에이전트 구축을 위한 LangGraph 활용

이 튜토리얼에서는 복잡한 생성형 AI 워크플로를 구축, 배포, 관리하도록 설계된 오픈 소스 AI 에이전트 프레임워크인 LangGraph 프레임워크를 사용합니다. LangGraph에서 제공하는 사전 구축된 create_react_agent 함수를 사용하면 간단한 맞춤 에이전트를 쉽게 구축할 수 있습니다. 이 튜토리얼의 그림 1과 같이 간단한 ReAct 에이전트는 두 개의 노드로 구성됩니다. 한 노드는 모델 호출을 담당하고 다른 노드는 도구 사용을 담당합니다. 일반적인 도구로는 사전 구축된 LangChain Wikipedia 도구, DuckDuckGoSearchRun 도구, 심지어 검색 증강 생성(RAG)도 있습니다. 복잡한 행동 입력이 있는 경우 그림 2와 같이 다른 노드를 추가할 수 있습니다. 이 추가 노드는 에이전트가 아웃풋을 반환하도록 하는 데 도움이 됩니다.

ReAct 에이전트 아키텍처 다이어그램

LangGraph에 있는 "상태" 기능은 AI 시스템의 각 반복에서 처리하는 모든 중요 정보를 기록하고 추적하는 기억 장치 역할을 합니다. 에이전트는 이러한 상태 그래프를 통해 과거 정보와 귀중한 컨텍스트를 기억할 수 있습니다. ReAct 그래프의 순환 구조는 한 단계의 결과가 루프의 이전 단계에 따라 달라질 때 활용됩니다. 그래프의 노드 또는 '액터'는 에이전트 로직을 인코딩하고 에지에 의해 연결됩니다. 에지는 기본적으로 현재 상태에 따라 다음에 실행할 노드를 결정하는 Python 함수입니다.

전제조건

watsonx.ai 프로젝트를 생성하려면 IBM Cloud 계정이 필요합니다.

단계

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단계에서 초기화되었습니다. 그런 다음 개발자 액세스 페이지에 있는 간단한 양식에 따라 배포 공간을 선택하거나 새 공간을 만듭니다. 여기에서 에이전트를 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 인스턴스를 열고 새 버킷을 생성합니다. 이 튜토리얼에서는 무료 티어인 스마트 티어를 선택할 수 있습니다. 지시가 있으면 파일을 업로드합니다. 샘플 파일은 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 함수(에이전트 실행자 역할을 함)에 전달됩니다. 다른 매개변수에는 watsonx.ai에서 도구 호출을 허용하는 메모리 세이버 및 시스템 프롬프트인 ChatWatsonx 클래스를 사용하여 초기화된 대규모 언어 모델이 포함됩니다. 일부 프롬프트는 다른 프롬프트보다 더 잘 작동하므로, 선택한 LLM에 따라 어느 정도의 프롬프트 엔지니어링이 필요할 수 있음에 유의하세요.

에이전트를 배포하기 전에 필요한 모든 정보를 config.toml 파일에 모두 입력해야 합니다.

7단계. 에이전트와 채팅하기

에이전트와 채팅하는 방법에는 세 가지가 있습니다.

옵션 1. 에이전트를 로컬로 쿼리

로컬 AI 서비스 실행을 위한 스크립트를 실행합니다.

poetry run python examples/execute_ai_service_locally.py

옵션 2. watsonx.ai의 기본 제공 채팅 인터페이스에 에이전트 배포

마지막 옵션은 watsonx.ai의 배포 공간에서 에이전트에 액세스하는 것입니다. 이렇게 하려면 왼쪽 메뉴에서 '배포'를 선택합니다. 그런 다음 배포 공간을 선택하고 '자산' 탭을 선택한 다음online ai_service 자산을 선택하고 'wx-agent' 태그가 있는 자산을 한 번 더 선택한 후 마지막으로 '미리보기' 탭을 엽니다. 이제 대화형 채팅 인터페이스에서 에이전트와 채팅할 수 있습니다. 이 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 도구가 성공적으로 호출될지 테스트해보겠습니다. 에이전트에게 새 티켓을 만들도록 요청해 보겠습니다.

새 티켓을 생성하기 위해 watsonx.ai에 배포된 에이전트를 쿼리

에이전트의 최종 답변에서 볼 수 있듯이 AI 시스템은 create_ticket 도구를 통해 문제 해결을 성공적으로 사용하여 새 티켓을 생성했습니다. 도구 호출에 대한 가시성을 확보하면 디버깅에 유용합니다. 이제 티켓이 에이전트의 지식 기반 역할을 하는 데이터 파일에 성공적으로 추가되었는지 확인해 보겠습니다.

최근 티켓을 조회하기 위해 watsonx.ai에 배포된 에이전트를 쿼리

좋습니다! 에이전트가 파일에 티켓을 추가했습니다.

결론

이 튜토리얼에서 우리는, 지원 티켓 조회와 생성 같은 복잡한 작업을 해결하기 위해 의사 결정을 사용하는 ReAct 프레임워크를 사용하여 에이전트를 만들었습니다. Google의 Gemini, IBM의 Granite, OpenAI의 GPT-4 등 여러 AI 모델이 에이전트 툴 호출을 허용합니다. 우리 프로젝트에서는 watsonx.ai API를 통해 IBM Granite AI 모델을 사용했습니다. 모델은 로컬에서와 watsonx.ai에 배포했을 때 모두 예상대로 작동했습니다. 다음 단계로 AI 에이전트 구축을 위해 watsonx-developer-hub GitHub 리포지토리에서 사용할 수 있는 LlamaIndex 및 crewAI 다중 에이전트 템플릿을 확인해 보세요.