watsonx.ai 모델을 watsonx Orchestrate의 Tool로 사용하기 — OpenAPI 파일 한 장으로 연결하는 방법

이 기사에서는 watsonx.ai에서 구동하는 대규모 언어 모델(LLM)을 watsonx Orchestrate의 Agent에 Tool로 통합하는 방법을 해설합니다.

이 기사에서 알 수 있는 내용:

• watsonx.ai와 watsonx Orchestrate 연동 시의 "장벽"과 그 해결 접근 방식
• OpenAPI 정의 파일 한 장을 사용한 연동 절차 (3단계)
• 실제로 구동하기까지의 주의사항과 대처법

watsonx Orchestrate는 "AI 에이전트가 여러 개의 Tool을 자율적으로 구분하여 사용하는" 플랫폼입니다. Tool로 등록할 수 있는 것은 주로 외부 API이며, OpenAPI (OAS 3.0) 형식으로 사양을 기술해야 합니다.

한편, watsonx.ai는 IBM이 제공하는 파운데이션 모델 (Foundation Model) 실행 기반으로, Granite, Llama 등의 모델을 API를 통해 호출할 수 있습니다.

이 두 가지를 조합하면,

"watsonx Orchestrate의 에이전트가 watsonx.ai 상의 LLM을 Tool로 호출한다"

라는 구성을 실현할 수 있습니다. 하지만, 공식적으로 "이대로 붙여넣으면 작동하는" OpenAPI 파일이 준비되어 있지 않은 것이 현상황입니다.

watsonx.ai의 API 레퍼런스를 읽고 직접 YAML을 작성하려고 하면 다음과 같은 문제에 직면하게 됩니다.

model_id나 project_id의 기본값(default value) 설정 방법이 알기 어려움 - 인증 방식 (IAM 토큰) 기술을 OpenAPI의 securitySchemes에 어떻게 작성해야 할지 망설여짐 - 리전에 따라 servers.url을 전환해야 하지만 어디를 바꿔야 할지 불명확함 - Orchestrate 측의 파일 검증 (YAML 구문 체크)에서 거부됨

이러한 수고를 덜기 위해, "3곳만 수정하면 작동하는" OpenAPI 정의 파일을 템플릿으로 공개했습니다.

연동의 전체 모습은 심플합니다.

watsonx Orchestrate (에이전트)
│
│ OpenAPI Tool로서 호출
...

watsonx Orchestrate는 에이전트가 사용자의 지시를 받으면, 등록된 Tool 중에서 적절한 것을 선택하여 자동으로 API를 호출합니다. model_id나 생성 파라미터는 기본값으로서 YAML에 미리 심어두기 때문에, 에이전트는 "무엇을 물어볼 것인가 (프롬프트)"만 생각하면 됩니다.

연동에 필요한 정보는 3가지입니다.

정보	취득 장소
프로젝트 ID	watsonx.ai → 프로젝트 → 관리 → 일반 탭
모델 ID	Prompt Lab → ">코드 표시" → model_id
리전 URL	Prompt Lab → ">코드 표시" → cURL의 URL

자주 사용되는 리전 URL 목록:

리전	URL
US South (달라스)	https://us-south.ml.cloud.ibm.com
...

리포지토리에서 watsonx-ai-openapi.yaml을 다운로드하여 다음 3곳을 수정합니다.

① 서버 URL (리전)

# 도쿄 리전을 사용하는 경우
servers:
- url: https://jp-tok.ml.cloud.ibm.com

② model_id의 기본값 (2곳)

/ml/v1/text/generation과 /ml/v1/text/generation_stream 모두를 변경합니다.

model_id:
  default: "ibm/granite-3-3-8b-instruct"

③ project_id의 기본값 (2곳)

project_id:
  default: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

YOUR_MODEL_ID / YOUR_PROJECT_ID라는 문자열이 남아 있으면 Orchestrate의 파일 검증에서 경고가 발생할 수 있으니 주의하십시오.

• watsonx Orchestrate를 열고, Agent 생성 화면으로 이동합니다.
• **「Toolset」→「Tools」→「Add Tool」**을 클릭합니다.
• **「Open API」**를 선택하고, 편집된 watsonx-ai-openapi.yaml을 업로드합니다. 사용할 Operation을 선택합니다 (보통 모두 선택).
• Connection을 선택합니다.

Connection (인증)에 대하여

인증 방식은 Bearer Token입니다. IBM Cloud API 키를 IAM 엔드포인트에 전달하여 획득한 액세스 토큰 (Access Token)을 사용합니다.

Connection이 아직 없다면 「Add new item」에서 생성하십시오.

IAM 토큰 획득 URL: https://iam.cloud.ibm.com/identity/token

「Operations」에서 선택한 기능이 목록에 표시되면 등록이 완료되었습니다 ✅

이 구성이 특히 유효한 경우는 다음과 같습니다.

케이스 1 — 사내 AI 에이전트에 여러 모델을 부여하기

Orchestrate의 에이전트는 여러 개의 Tool을 가질 수 있습니다. "가벼운 처리는 Granite 3.3 2B", "고정밀 분석은 Llama 3.3 70B"와 같이, 모델을 Tool로서 나누어 사용하는 구성을 YAML을 여러 개 등록하는 것만으로 실현할 수 있습니다.

케이스 2 — 프로토타입을 빠르게 만들기

Orchestrate에 LLM 기능을 추가할 때, 커스텀 코드 (Custom Code)를 전혀 작성하지 않고 YAML 한 장으로 프로토타입을 구동할 수 있습니다. 요구사항이 확정된 후 백엔드 (Backend)를 자체 구현으로 전환하는 것도 용이합니다.

케이스 3 — LLM 교체가 용이함

모델을 바꾸고 싶을 때는 YAML의 model_id를 수정하여 다시 업로드하기만 하면 됩니다. 애플리케이션 측의 변경이 필요 없기 때문에, A/B 테스트와 같은 모델 평가에도 사용할 수 있습니다.

증상	원인 및 대처
YAML 업로드 시 검증 에러	YOUR_MODEL_ID / YOUR_PROJECT_ID가 남아 있음. 수정을 확인하십시오
401 Unauthorized	Connection의 IAM 토큰이 만료되었거나, API 키가 잘못됨
403 Forbidden	프로젝트 ID가 틀렸거나, API 키에 프로젝트 접근 권한이 없음
404 Not Found	model_id가 존재하지 않는 모델 ID로 설정됨
리전 (Region) 에러	servers.url이 사용 중인 리전과 일치하지 않음

• watsonx.ai의 LLM을 watsonx Orchestrate의 Tool로 사용하려면, OpenAPI 정의 파일을 3곳 수정하는 것만으로 연동할 수 있습니다. - YAML 템플릿은 리포지토리 (Repository)에서 공개하고 있습니다: https://github.com/IBM/connect_wxo-wxai
• 여러 모델의 구분 사용, 프로토타이핑, 모델 교체 등의 상황에서 즉시 활용 가능합니다.

코드를 전혀 작성하지 않고 "에이전트가 LLM을 Tool로서 호출하는" 구성을 테스트할 수 있으므로, watsonx의 AI 기반을 사용하기 시작한 분들께 꼭 시도해 보시기를 권장합니다.

• GitHub 리포지토리: connect_wxo-wxai
• watsonx.ai 온보딩 가이드
• watsonx.ai API 레퍼런스 (Reference)
• watsonx Orchestrate 문서
• IBM Cloud IAM 토큰 획득

본 기사의 내용은 저 개인의 견해이며, 반드시 제가 소속된 단체나 기업의 입장, 전략, 의견을 대표하는 것은 아닙니다.