watsonx Orchestrate ADK와 IBM Cloud를 사용하여 Langflow에서 맞춤형 리서치 에이전트 구축하기

By Anna Gutowska

AI 에이전트 기술이 빠르게 발전하면서 이러한 자율형 에이전트를 조직 전반에 도입하는 데 부담을 느끼는 기업도 있습니다.¹ 주요 과제로는 거버넌스, 윤리, 사람과 AI의 협업, 배포, 확장성 등이 있습니다. 하지만 신뢰할 수 있는 AI 에이전트를 구축하는 과정이 반드시 복잡할 필요는 없습니다. IBM® watsonx Orchestrate를 사용하면 이러한 과제를 하나의 플랫폼에서 효과적으로 해결할 수 있습니다. 이 튜토리얼에서는 Langflow와 watsonx Orchestrate를 사용하여 안정적이고 확장 가능한 엔터프라이즈용 에이전트를 구축하는 방법을 알아봅니다.

Langflow란 무엇인가요?

Langflow는 오픈 소스 Python 기반 프레임워크로, AI 에이전트와 다양한 AI 애플리케이션을 구축하는 데 사용됩니다. Langflow는 상위 프레임워크인 LangChain을 기반으로 개발되었습니다. 같은 생태계에 속한 또 다른 플랫폼인 LangGraph는 그래프 기반 아키텍처를 사용해 에이전틱 시스템을 구축하는 데 활용됩니다. Langflow의 가장 큰 장점은 사용하기 쉬운 드래그 앤드 드롭 인터페이스입니다. 사용자는 에이전트 컴포넌트를 연결해 자신만의 워크플로를 설계하거나, 미리 제공되는 템플릿으로 빠르게 시작할 수 있습니다. 이러한 로우코드 또는 노코드 방식 대신, 개발자는 Langflow API를 사용하여 사용자 지정 컴포넌트를 개발하고 단계별 에이전트 플로를 기존 애플리케이션 코드에 통합할 수도 있습니다. 이 Langflow 튜토리얼에서는 다음 두 가지 방법으로 에이전트를 구축하고 배포하는 방법을 알아봅니다.

IBM Cloud와 함께 Software as a Service(SaaS) 형태의 IBM watsonx Orchestrate를 사용하여 에이전틱 Langflow 플로를 MCP 서버로 가져오는 방법
IBM® watsonx Orchestrate Agent Development Kit(ADK)를 로컬에서 사용하여 기본 Langflow 플로를 가져오는 방법

각 방법은 이 튜토리얼의 별도 섹션에서 다룹니다. 참고로 이 튜토리얼은 GitHub에서도 확인할 수 있습니다.

그럼 시작해 보겠습니다.

전제조건

이 튜토리얼을 진행하려면 다음이 필요합니다.

최신 버전의 Python이 설치되어 있어야 합니다.
IBM Cloud 계정(watsonx.ai를 생성하는 데 필요)프로젝트 ID 및 API 키 Lite 및 Free 서비스 플랜을 사용할 수 있습니다.
- 프로젝트 ID는 프로젝트에서 확인할 수 있습니다. Manage 탭을 클릭한 다음 General 페이지의 Details 섹션에서 프로젝트 ID를 복사합니다. 이 ID는 이 튜토리얼의 ADK 섹션에서 필요합니다.
watsonx Orchestrate 계정이 있어야 합니다. 평가판 계정을 사용해도 됩니다. 계정이 없는 경우 여기를 클릭하여 30일 무료 체험을 신청합니다. IBM Cloud에서 평가판 액세스를 받는 방법은 문서를 참고하세요.
IBM watsonx Orchestrate ADK가 설치되어 있어야 합니다. ADK를 설정하고 설치하는 방법은 공식 문서를 참고하세요.
- 참고: ADK 2.0 이전 버전의 watsonx Orchestrate Developer Edition을 설치한 적이 있다면 업그레이드하기 전에 orchestrate server reset을 실행하여 모든 컨테이너를 먼저 제거합니다. watsonx Orchestrate Developer Edition은 더 이상 외부 컨테이너 엔진에 의존하지 않습니다. 업그레이드 전에 초기화하지 않으면 애플리케이션이 중복 설치되어 불필요한 시스템 리소스를 사용하게 되고 포트 충돌이 발생할 수 있습니다.
IBM® Cloud CLI가 설치되어 있어야 합니다. macOS, Linux 및 Windows용 설치 명령은 시작 가이드에서 확인할 수 있습니다.

이러한 요구 사항을 충족하지 않으면 이 튜토리얼을 그대로 재현할 수 없습니다.

단계: IBM Cloud 방식

1단계. IBM Cloud 환경 구성

터미널에서 다음 명령을 실행합니다. IBMid를 사용하여 IBM Cloud 계정에 로그인하라는 메시지가 표시됩니다. 여러 계정을 사용하는 경우에는 사용할 계정을 선택해야 합니다.

ibmcloud login

참고: 자격 증명이 거부되나요? 페더레이션 사용자일 수 있습니다. 기업 또는 엔터프라이즈 싱글사인온(SSO) ID를 사용하려면 --sso 플래그를 사용하여 다시 로그인합니다. 페더레이션 ID로 로그인하는 방법에 대한 자세한 내용은 문서를 참고하세요. 요약하면, 안내가 표시되면 URL이 기본 브라우저에서 열리도록 허용한 다음, 표시되는 일회용 코드를 터미널에 붙여 넣으면 됩니다.

다음과 비슷한 출력이 표시되면 로그인이 성공한 것입니다.

아웃풋:

API endpoint: https://cloud.ibm.com
Region: us-south
User: your.email@email.com
Account: itz-watsonx-event-001 (f1zzz9a2e11b432ea5316227cb901888) <-> 3021952
Resource group: No resource group targeted, use ‘ibmcloud target -g RESOURCE_GROUP’

참고: 리전이 올바르지 않은 경우 ibmcloud target -r 다음에 올바른 리전 값을 지정하여 실행합니다. 예를 들어 리전 서비스 엔드포인트가 us-east인 경우 ibmcloud target -r us-east을 실행합니다.

Cloud 리소스를 확인하려면 ibmcloud resource groups을 실행합니다. 이 명령을 실행하면 리소스 그룹이 조회되며, 다음과 비슷한 결과가 표시됩니다(리소스 이름과 ID는 환경에 따라 다릅니다).

아웃풋:

Retrieving all resource groups under account f1zzz9a2e11b432ea5316227cb901888 as your.email@email.com...
OK
Name ID Default Group State
watsonx 93018fa55c342de104afb8jje20c222c false ACTIVE
itz-wxo-69305f32086a49ee3736ff 48bbeb07ec5a4994b2fd39beb6027090 false ACTIVE

다음으로 ibmcloud target -g RESOURCE_GROUP을 실행하여 사용할 리소스를 대상으로 지정합니다. 이 예에서는 ibmcloud target -g itz-wxo-69305f32086a49ee3736ff을 실행합니다.

다음과 비슷한 출력이 표시됩니다.

아웃풋:

Targeted resource group itz-wxo-69305f32086a49ee3736ff
API endpoint: https://cloud.ibm.com
Region: us-south
User: your.email@email.com
Account: itz-watsonx-event-001 (f1zzz9a2e11b432ea5316227cb901888) <-> 3021952
Resource group: itz-wxo-69305f32086a49ee3736ff

2단계. IBM Cloud Code Engine CLI 설치

IBM® Cloud Code Engine을 사용하면 서버나 인프라를 직접 관리하지 않고도 거의 모든 컨테이너화된 워크로드를 실행할 수 있습니다. 이 플랫폼은 마이크로서비스와 웹 애플리케이션부터 배치 작업과 이벤트 기반 함수까지 다양한 워크로드를 지원합니다. 또한 소스 코드에서 이미지를 생성하는 기능도 기본으로 제공합니다. 모든 워크로드는 동일한 Kubernetes 환경을 공유하므로 자연스럽게 통합됩니다. Code Engine은 인프라 관리에 신경 쓰지 않고 애플리케이션 개발에 집중할 수 있도록 설계되었습니다. 다음 단계는 Code Engine CLI를 설치하는 것입니다. 터미널에서 다음 명령을 실행합니다.

ibmcloud plugin install code-engine -f

아웃풋:

Looking up ‘code-engine’ from repository ‘IBM Cloud’...
Plug-in ‘code-engine[ce] 1.57.0’ found in repository ‘IBM Cloud’
Attempting to download the binary file...
74.08 MiB / 74.08 MiB [============================================] 100.00% 1s
77680050 bytes downloaded
Installing binary...
OK
Plug-in ‘code-engine 1.57.0’ was successfully installed into /your/path/to/code-engine. Use ‘ibmcloud plugin show code-engine’ to show its details.

좋습니다! 이제 Code Engine에서 사용할 프로젝트를 지정해 보겠습니다. 먼저 ibmcloud ce project list을 실행하여 프로젝트 목록을 확인합니다.

아웃풋:

Getting projects...
OK

Name ID Status Enabled Selected Tags Region Resource Group Age
ce-itz-wxo-69305f32086a49ee3736ff 8991a30c-944f-422d-9e00-00789043e90e active true false us-south itz-wxo-69305f32086a49ee3736ff 7m32s

Code Engine 프로젝트는 애플리케이션, 작업(Job), 빌드(Build)와 같은 리소스를 하나의 단위로 묶어 관리합니다. 또한 이러한 리소스를 관리하고 접근 권한을 제어하는 기본 단위 역할을 합니다. 활성화된 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을 실행합니다.

아웃풋:

Selecting project ‘ce-itz-wxo-69305f32086a49ee3736ff’...
OK

참고: 이 단계에서 오류가 발생하면 ibmcloud target -c ACCOUNT_ID -r REGION_NAME -g RESOURCE_GROUP_NAME을 사용해 올바른 환경을 대상으로 지정했는지 확인합니다.

3단계. Code Engine CLI를 사용하여 Langflow 설정

Code Engine CLI에서 Langflow를 사용하려면 다음 명령을 실행합니다.

ibmcloud ce app create \
--name langflow \
--image langflowai/langflow:latest \
--port 7860

이 명령은 실행하는 데 몇 분 정도 걸릴 수 있습니다. 실행이 완료될 때까지 중단하지 말고 그대로 기다립니다.

아웃풋:

Creating application ‘langflow’...
Configuration ‘langflow’ is waiting for a Revision to become ready.
Ingress has not yet been reconciled.
Waiting for load balancer to be ready.
Run ‘ibmcloud ce application get -n langflow’ to check the application status.
OK

https://langflow.23h82g3y09cp.us-south.codeengine.appdomain.cloud

4단계. wxO 연결 및 Langflow 활성화

Langflow 설정 명령이 실행되는 동안 로컬 시스템 및 SaaS 호스팅 솔루션과 연동할 환경을 추가할 수 있습니다.

새 터미널 창을 열고 선택한 디렉터리에서 가상 환경을 활성화합니다. my-env에는 원하는 가상 환경 이름을 사용할 수 있습니다.

python -m venv my-env

다음 명령으로 가상 환경을 활성화합니다. 다른 이름을 사용했다면 my-env을 해당 이름으로 바꿔 실행합니다.

macOS/Linux:

source my-env/bin/activate

Windows:

my-env\Scripts\activate

이제 원하는 브라우저에서 IBM® Cloud 리소스 목록으로 이동한 다음, AI/Machine Learning 드롭다운을 펼쳐 활성화된 wxO 리소스를 선택합니다. 예를 들어 이름은 "Watson Orchestrate-itz"와 비슷한 형식입니다. 해당 리소스를 연 다음 Credentials 창에 있는 URL을 복사합니다. 곧 다시 사용할 예정이므로 이 페이지는 브라우저에서 열린 상태로 유지합니다. 다음 명령에서 YOUR_WXO_RESOURCE_URL을 복사한 URL로 바꾼 후, 터미널에서 활성화된 가상 환경에서 명령을 실행합니다.

orchestrate env add \
-n langflow \
-u YOUR_WXO_RESOURCE_URL \
--type ibm_iam \
--activate

아웃풋:

[INFO] - Environment ‘langflow’ has been created
Please enter WXO API key:

wxO API 키를 입력하라는 메시지가 표시되면 브라우저에 열려 있는 리소스 페이지로 돌아갑니다. 복사한 URL 위에 있는 API 키는 입력하지 마세요. 대신 Launch watsonx Orchestrate 버튼을 클릭합니다. 그런 다음 화면 오른쪽 위에 있는 이니셜 아이콘을 클릭하고 Settings를 엽니다. API details 탭을 선택한 다음 Generate API key 버튼을 클릭합니다. 다음으로 API 키의 이름과 설명을 입력한 다음 "Leaked action" 섹션에서 "Disable the leaked key"를 선택합니다. 가장 중요한 단계로, "Session management" 섹션에서 "Yes"를 선택하여 CLI 로그인에 대한 세션 관리를 활성화한 다음 "Create"를 클릭합니다. API 키가 표시됩니다. 조금 전에 사용하던 터미널로 돌아가 API 키를 붙여 넣어 wxO API 키 입력을 완료합니다.

아웃풋:

[INFO] - Environment ‘langflow’ is now active

좋습니다! 이제 Langflow를 사용할 준비가 되었습니다.

5단계. Code Engine 리소스 구성

일정 시간이 지나도 Langflow 애플리케이션이 삭제되지 않는 안정적인 Code Engine 환경을 구성하려면 브라우저를 다시 엽니다. IBM Cloud의 containers overview에 접속합니다. 가장 최근에 생성한 Code Engine 프로젝트가 표시됩니다. 프로젝트를 엽니다. 다음으로 Langflow 애플리케이션을 엽니다. Configuration 탭에서 Resources and scaling 컴포넌트를 엽니다. 여기에서는 최소 인스턴스 수를 0에서 1로 변경하기만 하면 됩니다. 마지막으로 Deploy 버튼을 클릭하여 변경된 구성을 적용합니다.

이 단계를 완료한 후 Test application 버튼을 클릭한 다음 Application URL 하이퍼링크를 클릭합니다. 그러면 IBM Cloud에서 실행 중인 Langflow 인스턴스가 열립니다.

6단계. 플로 구축

Langflow 플로를 구축하는 방법은 여러 가지입니다. 미리 제공되는 템플릿을 사용하거나 처음부터 직접 만들 수 있습니다. 이 튜토리얼에서는 후자의 방법을 살펴보겠습니다. 시작하려면 + Blank Flow를 클릭합니다. 이 예제에서는 구축할 수 있는 하나의 플로를 소개하지만, Langflow에 기본 제공되는 다양한 컴포넌트와 통합 기능도 자유롭게 살펴보세요.

메뉴에서 다음 기본 제공 컴포넌트 노드를 추가합니다.

Chat Input - 채팅에서 사용자 입력을 받습니다.
Chat Output - 플로의 출력 결과를 채팅에서 사용자에게 반환합니다.
Agent - 대규모 언어 모델(LLM) 통합을 사용하여 사용자 입력에 응답하며 여러 툴에 연결할 수 있습니다.²
MCP Tools - Model Context Protocol(MCP) 서버에 연결하고, MCP 서버의 기능을 에이전트가 입력에 응답하는 데 사용할 수 있는 툴로 제공합니다.²
IBM watsonx.ai - IBM watsonx.ai 모델에 액세스할 수 있도록 합니다. 텍스트 생성용³
News Search - Google 뉴스 콘텐츠를 가져와 각 기사의 제목, 링크, 게시 날짜 및 요약이 포함된 구조화된 DataFrame을 생성합니다.⁴
arXiv - arXiv.org에서 관련 논문을 검색하고 결과를 DataFrame 형식으로 출력합니다.⁵

마지막으로 메뉴 하단에서 + New Custom Component를 선택합니다.

보기 쉽도록 플로를 다음과 같이 배치합니다.

2. Chat Input 컴포넌트를 Agent 컴포넌트의 "Input" 필드에 연결합니다.

3. Chat Output 컴포넌트를 Agent 컴포넌트의 "Response" 필드에 연결합니다.

4. Agent 컴포넌트에서 드롭다운을 열고 "Model Provider"를 "Custom"으로 설정합니다. 사용 중인 Langflow 버전에 따라 대신 "Connect other models"가 표시될 수도 있습니다. 어느 옵션을 선택해도 됩니다.

5. In the IBM watsonx.ai 컴포넌트에서 API 자격 증명에 맞는 watsonx.ai API 엔드포인트를 선택합니다. 그런 다음 해당 입력란에 watsonx.ai 프로젝트 ID와 API 키를 붙여 넣습니다. 이어서 사용할 대규모 언어 모델(LLM)을 선택합니다. 이 튜토리얼에서는 openai/gpt-oss-120b을 선택합니다. 컴포넌트가 "Model Response"가 아니라 "Language Model"로 설정되어 있는지 확인합니다. 이 모델을 에이전트의 언어 모델로 사용할 것이므로 이 설정이 중요합니다. 따라서 이제 IBM® watsonx.ai를 연결할 수 있습니다.컴포넌트를 Agent 컴포넌트의 "Language Model" 필드에 연결할 수 있습니다.

참고: API 자격 증명을 직접 붙여 넣는 대신 전역 변수를 사용하려면 화면 오른쪽 상단의 프로필 아이콘을 클릭한 다음 Settings를 선택합니다. Global Variables 섹션에서 이 튜토리얼의 사전 준비 단계에서 생성한 watsonx.ai 연결용 WATSONX_PROJECT_ID과 WATSONX_APIKEY을 추가합니다. 플로로 돌아오면 "watsonx.ai Project ID"와 "API key" 입력 필드에 지구본 아이콘이 표시됩니다. 지구본 아이콘을 클릭한 다음 드롭다운에서 사용할 키를 선택합니다.

6. arXiv, News Search, Custom Component의 토글을 사용하여 Tools Mode를 활성화합니다. 각 컴포넌트의 아무 곳이나 클릭하면 헤더 메뉴에 이 토글이 표시됩니다. 이 모드를 활성화하면 이제 이러한 컴포넌트를 Agent 컴포넌트의 "Tools" 필드에 연결할 수 있습니다. arXiv 및 News Search 컴포넌트는 이미 구성되어 사용할 준비가 되었습니다. 이제 나머지 컴포넌트를 구성해 보겠습니다.

7. Custom Component의 헤더 메뉴에서 <> Code를 선택합니다. 여기에서는 컴포넌트를 정의하는 Python 코드를 편집하여 컴포넌트의 동작을 사용자 지정할 수 있습니다.⁶ 간단한 예로, LLM이 자체적으로는 알 수 없는 오늘 날짜를 반환하는 툴을 만들어 보겠습니다. 기본 제공 코드를 다음 코드로 바꿉니다.

from langflow.custom.custom_component.component import Component
from langflow.io import MessageTextInput, Output
from langflow.schema.data import Data
from datetime import date

class CustomComponent(Component):
    display_name = “Date”
    description = “Returns today’s date.”
    documentation: str = “https://docs.langflow.org/components-custom-components”
    icon = “calendar-check”
    name = “CustomDateComponent”

    inputs = [] # No input needed

    outputs = [
        Output(display_name=”Today’s Date”, name=”output”, method=”build_output”),
    ]

def build_output(self) -> Data:
    today = date.today()
    data = Data(value=today)
    self.status = data
    return data

변경 사항을 저장합니다. 이제 컴포넌트에 새 이름, 설명 및 아이콘이 반영된 것을 확인할 수 있습니다.

에이전트에 제공할 툴의 수는 자유롭게 결정할 수 있습니다. 다만 너무 많은 툴을 제공하면 성능과 정확도가 떨어질 수 있으므로 필요한 만큼만 추가하는 것이 좋습니다. 마지막으로 활성화할 툴은 MCP 서버입니다. 원하는 MCP 서버를 자유롭게 연결할 수 있습니다. 이 튜토리얼에서는 Alpha Vantage MCP 서버에 연결합니다.⁷ 공식 Alpha Vantage MCP 서버를 사용하면 대규모 언어 모델(LLM)과 에이전트가 Model Context Protocol을 통해 실시간 및 과거 주식 데이터를 손쉽게 가져올 수 있습니다. 이 서버에 연결하려면 MCP Tools 컴포넌트에서 "MCP Server" 드롭다운을 열고 + Add MCP Server를 클릭합니다. STDIO 탭에서 서버 이름을 입력합니다. 예를 들어 "av_mcp"를 사용할 수 있습니다. 그런 다음 다음 명령을 붙여 넣습니다. uvx av-mcp YOUR_API_KEY 무료 Alpha Vantage API 키를 생성하려면 공식 Alpha Vantage 웹사이트를 방문한 다음, YOUR_API_KEY 자리 표시자를 발급받은 API 키로 바꿔 명령에 붙여 넣습니다. 서버를 추가한 후 컴포넌트 노드의 헤더 메뉴에서 Tools Mode 토글을 활성화합니다. 수많은 툴이 "Actions"로 표시됩니다. 이렇게 표시되면 MCP 서버에 성공적으로 연결된 것입니다. 이제 마지막 컴포넌트를 Agent 컴포넌트의 "Tools" 필드에 연결합니다.

잘하셨습니다! 이제 플로가 완성되었으며 다음 화면과 비슷한 모습이어야 합니다.

연구 파이프라인이 예상대로 작동하는지 확인하려면 Playground를 열고 방금 만든 에이전트와 대화해 보세요. 연결된 툴 중 하나를 사용해야 하는 질문을 에이전트에게 해 보세요. 다음과 같은 입력 예제를 사용할 수 있습니다.

간단한 예:
- "오늘 날짜가 어떻게 되나요?"
- "양자 컴퓨팅에 관한 연구 논문 5편을 찾아줘."
중간 난이도 예:
- "지난 30일 동안 IBM 주가를 분석해 줘."
복잡한 예:
- "IBM 주가가 상승세인지 하락세인지를 시사하는 최근 뉴스가 있을까?"

에이전트가 사용할 수 있는 툴을 호출하여 올바른 결과를 생성하는 것을 확인할 수 있습니다. 이 단계에서 문제가 발생하면 플로로 돌아가 자격 증명이 올바른지, 그리고 각 단계를 빠짐없이 수행했는지 확인하세요.

7단계. 플로를 MCP 서버로 wxO에 가져오기

이 플로를 watsonx Orchestrate에 연결하는 방법 중 하나는 MCP 서버로 사용하는 것입니다. 오른쪽 위에 있는 Share 드롭다운을 클릭한 다음 "MCP Server"를 선택합니다. "JSON" 탭을 클릭합니다. 다음 예제와 비슷한 코드가 표시됩니다.

{
    “mcpServers”: {
    “lf-starter_project”: {
    “command”: “uvx”,
    “args”: [
        “mcp-proxy”,
        “https://langflow.23h82g3y09cp.us-south.codeengine.appdomain.cloud/api/v1/mcp/project/b797fbc9-cd21-46e9-bc23-8fa813f94810/sse”
            ]
        }
    }
}

JSON 스니펫에 있는 URL을 복사합니다. 이 URL은 앞의 예시와 다를 수 있습니다. 터미널로 돌아가 MCP_SERVER_URL 자리 표시자 대신 MCP 서버 URL을 붙여 넣습니다. 다음 명령을 watsonx Orchestrate CLI에서 실행하면 이 MCP 서버를 플랫폼에 툴킷으로 가져올 수 있습니다.

orchestrate toolkits add \
--kind mcp \
--name langflow_mcp \
--description “LangFlow MCP Server” \
--command “uvx mcp-proxy MCP_SERVER_URL” \
--tools “*”

아웃풋:

[INFO] - Successfully imported tool kit langflow_mcp

8단계. 에이전트를 만들고 툴 호출을 테스트합니다.

브라우저에서 watsonx Orchestrate로 이동한 다음 새 에이전트를 처음부터 만듭니다. 에이전트의 이름과 설명을 입력합니다. 에이전트를 만든 후 Toolset 탭을 열고 Add tool 버튼을 클릭합니다. 그런 다음 MCP 서버에서 툴을 가져오는 옵션을 선택합니다. Select MCP server 드롭다운에서 가져온 서버를 선택한 다음 활성화 토글을 켜서 툴을 활성화하고 창을 닫습니다. 다음으로 Deploy를 클릭합니다. 배포가 완료되면 Preview 채팅 창이나 접힌 페이지 메뉴에 있는 채팅 인터페이스에서 에이전트와 대화할 수 있습니다.

이제 에이전트에게 질문을 해보겠습니다! 예를 들어, "양자 컴퓨팅에 관한 연구 논문 5편을 찾아줘."라고 입력합니다.

잘하셨습니다! 에이전트형 챗봇이 올바른 응답을 생성할 뿐 아니라 적절한 arXiv 툴도 호출하여 예상대로 동작하는 것을 확인할 수 있습니다. 다양한 프롬프트를 자유롭게 시도해 보세요.

단계: ADK 방식(로컬)

이 방법에서는 Code Engine이 필요하지 않습니다. 이 방법은 로컬 개발 서버로 동작하는 watsonx Orchestrate의 경량 버전인 watsonx Orchestrate Developer Edition SDK를 사용하여 로컬 개발 환경을 구성합니다.

전제조건

시스템 사양:
- 16GB RAM
- 8코어
- 25GB 디스크 공간

1단계. wxO Developer Edition SDK 설치

Langflow를 사용하여 로컬에서 개발을 시작하기 전에 wxO ADK의 Developer Edition을 설치합니다. 이 튜토리얼의 첫 번째 방법에서는 이 Developer Edition이 필요하지 않았습니다.

선호하는 IDE에서 개발 환경을 설정합니다. 모든 에이전트와 툴을 저장할 wxo-langflow-agent 폴더를 생성합니다. 이 프로젝트는 GitHub에서 참고할 수 있습니다. 폴더 구조는 다음과 같습니다.
```
wxo-langflow-agent/
├── .env
├── tools/ └── agents/
```

2. 터미널을 열고 가상 환경을 활성화합니다. 원하는 환경 이름으로 my-env을(를) 변경할 수 있습니다.

python -m venv my-env

다음 명령으로 가상 환경을 활성화합니다. 다른 이름을 사용했다면 my-env을 해당 이름으로 바꿔 실행합니다.

macOS/Linux:

source my-env/bin/activate

Windows:

my-env\Scripts\activate

3. .env 파일에서 다음 환경 변수를 설정합니다. 자세한 내용은 setup guide를 참조하세요.

WO_DEVELOPER_EDITION_SOURCE=orchestrate
WO_INSTANCE=<service_instance_url>
WO_API_KEY=<wxo_api_key>

4. 다음 명령을 실행하여 watsonx Orchestrate Developer Edition 서버를 설치합니다. Langflow는 ADK Developer Edition에 포함되어 있으므로 별도로 설치할 필요가 없습니다. --with-langflow 명령 플래그는 필요한 컨테이너 이미지를 가져오고 초기 구성을 수행하여 Langflow를 로컬에서 사용할 수 있도록 함으로써 Langflow 지원을 활성화합니다.

orchestrate server start -e <path-.env-file> --with-langflow

서버를 처음 활성화하는 경우 이 명령을 실행하는 데 몇 분 정도 걸릴 수 있습니다.

Troubleshooting: 이전에 ADK 버전 2.0 이전의 watsonx Orchestrate Developer Edition을 설치했고 컨테이너 시작 중 오류가 발생하는 경우 다음 명령을 실행합니다.

orchestrate server reset
orchestrate server purge
pip install --upgrade ibm-watsonx-orchestrate

출력의 마지막 부분은 다음 예제와 비슷하게 표시됩니다.

아웃풋:

[INFO] - Migration ran successfully.
[INFO] - Waiting for orchestrate server to be fully initialized and ready...
[INFO] - Orchestrate services initialized successfully
[INFO] - no local tenant found. A default tenant is created
[INFO] - You can run `orchestrate env activate local` to set your environment or `orchestrate chat start` to start the UI service and begin chatting.
[INFO] - Langflow has been enabled, the Langflow UI is available at http://localhost:7861

2단계. 로컬 wxO 채팅 UI 활성화

watsonx Orchestrate ADK에서 환경은 연결할 수 있는 watsonx Orchestrate 인스턴스를 의미합니다. 이 튜토리얼에서는 노트북에서 실행 중인 Developer Edition 인스턴스를 환경으로 사용합니다. orchestrate env list 명령을 사용하면 현재 CLI에서 사용할 수 있는 모든 환경을 확인할 수 있습니다. 기본적으로 local 환경이 제공됩니다. 다음 명령을 실행하여 local 환경을 활성화합니다.
```
orchestrate env activate local
```
아웃풋:
```
[INFO] - local tenant를 찾았습니다.
[INFO] - 'local' 환경이 활성화되었습니다.
```

다음으로 기본 브라우저에서 채팅 UI를 시작하려면 다음 명령을 실행합니다.

orchestrate chat start

아웃풋:

[INFO] - Chat UI 서비스가 성공적으로 시작되었습니다.
[INFO] - UI 컴포넌트가 초기화되기를 기다리는 중...
[INFO] - http://localhost:3000/chat-lite에서 채팅 인터페이스를 여는 중

3단계. Langflow 플로 생성

앞의 출력에서 확인한 것처럼 Langflow 편집기는 watsonx Orchestrate Developer Edition의 포트 7861에서 사용할 수 있습니다.

웹 브라우저에서 http://localhost:7861으로 이동합니다.
플로를 구축합니다. 이 튜토리얼의 첫 번째 부분에서 만든 플로를 재사용하거나 직접 새로 만들어도 됩니다. 이 튜토리얼의 이후 단계를 진행할 때 기본 이름과 설명 대신 사용자 지정 이름과 설명을 지정해 두면 도움이 될 수 있습니다. 화면 상단의 플로 이름 위에 마우스를 올린 다음 연필 아이콘을 클릭하면 이름과 설명을 변경할 수 있습니다.

예시 플로 이름: Research agent
예시 플로 설명: 뉴스 검색, arXiv, 오늘 날짜 및 Alpha Vantage API에 액세스합니다.

4단계. 플로를 wxO에 가져오기

Langflow 플로를 로컬 watsonx Orchestrate 서버로 가져오는 두 가지 방법을 살펴보겠습니다.

a) 플로를 로컬 MCP 서버로 가져옵니다.

b) 플로를 JSON으로 가져옵니다.

옵션 1: 로컬 MCP 서버로 가져오기

이 단계는 약간의 차이만 있을 뿐 이 튜토리얼 전반부의 7단계와 거의 동일합니다.

Langflow 오른쪽 위에 있는 Share 드롭다운을 클릭한 다음 "MCP Server"를 선택합니다. "JSON" 탭을 클릭합니다. 다음 예제와 비슷한 코드가 표시됩니다.

{
    "mcpServers": {
        "lf-starter_project": {
        "command": "uvx",
        "args": [
            "mcp-proxy",
            "http://localhost:7861/api/v1/mcp/project/41c9434f-67bf-439e-8dac-b7bb09b1d1ca/sse"
            ]
        }
    }
}

JSON 스니펫에 있는 URL을 복사합니다. 이 URL은 앞의 예시와 다를 수 있습니다. 터미널로 돌아가 아래 예시 URL 대신 복사한 URL을 사용하여 다음 명령을 붙여 넣습니다. IBM Cloud에서 실행했던 명령과 달리, 여기서는 localhost를 host.docker.internal로 바꿔야 합니다. 다음은 예시입니다.
```
orchestrate toolkits add \
    --kind mcp \
    --name langflow_research_mcp \
    --description "LangFlow MCP Server" \
    --command "uvx mcp-proxy http://host.docker.internal:7861/api/v1/mcp/project/41c9434f-67bf-439e-8dac-b7bb09b1d1ca/sse" \
 --tools "*"
```
아웃풋:
```
[INFO] - 툴킷 langflow_research_mcp를 성공적으로 가져왔습니다.
```
브라우저에서 실행 중인 로컬 watsonx Orchestrate 인스턴스에서 "Create new agent"를 클릭한 다음 새 에이전트의 이름과 설명을 입력합니다. 그런 다음 Create 버튼을 클릭합니다.

"Create agent locally"를 실행 중인 watson Orchestrate 스크린샷

4. Toolset 탭에서 Add tool 버튼을 클릭합니다. 이미 가져온 MCP 서버를 추가하려면 "local instance"를 선택하고, 가져온 MCP 서버의 확인란을 선택한 다음 Add to agent를 클릭합니다.

5. 이제 대화를 시작합니다!

옵션 2: JSON으로 가져오기

플로를 MCP 서버로 가져오는 대신 ADK를 사용하여 내보낸 JSON 파일 형태로 가져올 수도 있습니다.

1. 이 방법은 단순한 플로에 가장 적합합니다. 예제로 다음 플로를 사용해 보겠습니다.

Share 버튼을 클릭한 다음 Export를 선택하여 플로를 JSON으로 내보냅니다. 툴 또는 플로의 이름과 설명을 원하는 대로 입력합니다. 툴 이름에는 영문자, 숫자 및 밑줄만 사용할 수 있으며, 숫자나 밑줄로 시작해서는 안 됩니다.

2. 새로 내보낸 JSON 파일을 tools 폴더에 추가합니다.

3. 다음 명령을 실행하여 플로를 watsonx Orchestrate로 가져옵니다.

orchestrate tools import -k langflow -f tools/arxiv.json

4. Langflow 플로를 툴로 가져온 후에는 다음 단계로 이를 에이전트 시스템에 연결합니다. watsonx Orchestrate UI에서 새 에이전트를 만들거나, 다음 에이전트 정의를 agents 폴더의 새 arxiv_agent.yml 파일에 복사하여 이 단계를 완료할 수 있습니다.

kind: native
name: arxiv_agent
display_name: ArXiv Agent
description: Access to arXiv tool.
context_access_enabled: true
context_variables: []
llm: watsonx/ibm/granite-4-h-small
style: default
instructions: ‘’
guidelines: []
collaborators: []
tools:
- arxiv
knowledge_base: []
spec_version: v1

이제 다음 명령을 실행하여 간단한 에이전트를 가져옵니다.

orchestrate agents import -f agents/arxiv_agent.yml

5. 변경 사항이 반영되도록 로컬에서 실행 중인 watsonx Orchestrate 채팅 UI의 브라우저를 새로 고칩니다. Agents 드롭다운 메뉴에서 "ArXiv Agent"를 선택한 다음 arXiv 툴을 사용해야 하는 질문을 해 보세요!

예시 프롬프트: "양자 컴퓨팅에 관한 연구 논문 5편을 찾아줘."

아웃풋:

좋습니다! 에이전트는 이 사용자 질의를 처리하기 위해 arxiv 툴을 호출해야 한다고 판단했습니다. 툴 출력은 접힌 추론 흐름과 채팅 창의 응답에 표시됩니다.

결론

이 튜토리얼에서는 Langflow와 watsonx Orchestrate를 활용하여 견고하고 확장 가능하며 엔터프라이즈 환경에 적합한 에이전트를 구축하는 데 필요한 핵심 기술을 익혔습니다. IBM Cloud와 함께 SaaS(Software as a Service) 형태의 watsonx Orchestrate를 사용하여 에이전트형 Langflow 플로를 MCP 서버로 가져오는 방법을 배웠습니다. 또한 IBM watsonx Orchestrate Agent Development Kit(ADK)를 로컬에서 사용할 때 기본 Langflow 플로를 가져오는 방법도 익혔습니다. 단계별 지침을 따라 사용자 지정 툴과 사전 구축된 툴을 호출하여 사용자 질의를 해결하는 에이전트를 설계, 개발 및 배포하는 방법을 익혔습니다. Langflow의 직관적인 시각적 인터페이스를 사용하여 복잡한 워크플로를 만들었으며, watsonx Orchestrate를 통해 이러한 에이전트를 효율적으로 관리하고 확장하는 방법을 익혔습니다. 다음 단계로 실제 사용 사례에 적용해 보면서 이 튜토리얼에서 배운 내용을 활용해 보세요. 자동화의 이점을 얻을 수 있는 조직 내의 특정 비즈니스 문제나 프로세스를 선택한 다음, 이를 해결할 Langflow 및 watsonx Orchestrate 기반 솔루션을 설계해 보세요. 이러한 실습을 통해 이해를 더욱 확고히 하고 추가로 개선하거나 탐색할 수 있는 영역을 찾는 데 도움이 될 것입니다.

문제가 발생하거나 궁금한 점이 있으면 설명서를 참조하세요. 가장 일반적인 문제는 troubleshooting guide에서 다루고 있습니다. 다른 사용자도 비슷한 문제를 겪었는지 GitHub 이슈를 확인해 볼 수도 있습니다.

작성자

Anna Gutowska

AI Engineer, Developer Advocate

IBM

ROI 실현 시작: 에이전틱 AI 실용 가이드

기업 전반에서 측정 가능한 ROI를 달성할 수 있도록 에이전틱 AI를 확장하는 방법을 알아보세요. 이 플레이북에서는 효과를 제한하는 주요 장벽, ROI를 효과적으로 측정하는 방법, 그리고 기업 전반에서 성공적인 도입을 추진하기 위한 실용적인 프레임워크를 설명합니다.

리소스

에이전트 보호

현재 AI 모델 역전 공격은 미화 평균 600만 달러의 비용을 발생시키며, 이로 인해 AI 시스템 및 민감한 데이터를 보호하는 데 점점 더 많은 어려움을 겪고 있습니다.

엔터프라이즈 규모의 AI 네이티브 항공사 설계

수익 마진이 적을 때는 아주 작은 비효율도 치명적입니다. 레거시 시스템이 항공 업계 전반에서 AI의 잠재력을 계속해서 가로막고 있을 때, Riyadh Air 다른 길을 선택했습니다. Riyadh Air는 IBM과의 파트너십을 통해 세계 최초의 AI 네이티브 항공사를 구축하며, 더 스마트하고 빠르며 직관적인 여행의 기준을 새롭게 정의하고 있습니다.

2030년 엔터프라이즈: 지속적인 혁신을 위한 설계

2030년 가장 성공적인 기업을 결정짓는 다섯 가지 전망과, 리더가 AI 중심 경쟁 우위를 확보하기 위해 취해야 할 단계를 확인하세요.

AI 거버넌스 필수 요소: 변화하는 규제와 에이전틱 AI의 등장

변화하는 규제와 AI 에이전트의 등장이 어떻게 강력한 AI 거버넌스 프레임워크 구축의 필요성을 재편하고 있는지 알아보세요.

에이전틱 AI 설명

IBM의 Techsplainers에서 핵심 개념부터 실제 사용 사례까지 에이전틱 AI의 필수 요소를 분석합니다. 명확하고 간결한 에피소드를 통해 기본 개념을 빠르게 이해할 수 있습니다.

AI ROI 활용: 기업 생산성을 위한 전술 가이드

AI와 혁신을 핵심으로 삼아 생산성을 높이고 기업 혁신을 강화하는 검증된 전략을 알아보세요.

AI 에이전트 및 어시스턴트가 조직에 도움이 되는 방법

주요 사용 사례와 핵심 능력을 분석하여 단계별 권장 사항을 제공하는 이 종합 가이드를 통해 비즈니스에 적합한 솔루션을 선택하는 데 도움을 받으세요.

AI 에이전트 및 어시스턴트로 비즈니스 생산성 재구상

AI 에이전트와 AI 어시스턴트를 함께 사용하여 새로운 차원의 생산성을 달성하는 방법을 알아보세요.

watsonx Orchestrate 사용해보기

생성형 AI 어시스턴트가 어떻게 워크로드를 줄이고 생산성을 높일 수 있는지 알아보세요.

AI 프로젝트에서 수익으로: 에이전틱 AI로 지속 가능한 재무 성과를 달성하는 방법

조직이 단편적인 AI 시범 사업에서 벗어나, 에이전틱 AI를 통해 핵심 비즈니스 혁신을 어떻게 이끌어내고 있는지 확인해 보세요.

강화된 인텔리전스에 대한 Omdia 보고서: AI 에이전트의 영향

AI 에이전트를 통해 생성형 AI의 잠재력을 최대한으로 활용하는 방법을 알아보세요.

AI 에이전트가 생산성을 혁신하는 방법

AI를 사용하여 더 창의적이고 효율적으로 일하고 AI 에이전트와 긴밀히 협력하는 미래에 적응하는 방법을 알아보세요.

에이전트형 엔터프라이즈 도입: 전체 기술 자산에서 AI 활용하기

AI 혁명의 중요한 전환점이 될 새로운 AI 에이전트의 최신 동향을 확인하세요.

에이전트의 미래, AI 에너지 소비, Anthropic의 컴퓨터 사용 기능, 그리고 Google의 AI 생성 텍스트 워터마킹

이번 Mix of Experts 에피소드에서 IBM의 AI 전문가들과 함께 AI 에이전트의 미래 등에 대해 자세히 알아보세요.

Comparus가 '뱅킹 어시스턴트'를 사용하는 방법

Comparus는 watsonx.ai 솔루션을 활용해 새로운 상호작용 모델로서 대화형 뱅킹의 가능성을 인상적으로 보여주었습니다.

각주

¹ Satyadhar Joshi. “Review of Autonomous Systems and Collaborative AI Agent Frameworks.” International Journal of Science and Research Archive, 제14권, 제2호, 2025년 2월 28일, pp. 961–972, https://ijsra.net/content/review-autonomous-systems-and-collaborative-ai-agent-frameworks.

² “Agents | Langflow Documentation.” Langflow.org, 2025, docs.langflow.org/components-agents.

³ “IBM | Langflow Documentation.” Langflow.org, 2025, docs.langflow.org/bundles-ibm.

⁴ “Data | Langflow Documentation.” Langflow.org, 2025, docs.langflow.org/components-data.

⁵ “ArXiv | Langflow Documentation.” Langflow.org, 2025, docs.langflow.org/bundles-arxiv.

⁶ “Components Overview | Langflow Documentation.” Langflow.org, 2025, docs.langflow.org/concepts-components.

⁷ “Alpha Vantage MCP for Stock Market Data.” Alphavantage.co, 2025, mcp.alphavantage.co/.