노드 사용법 익히기 - 어빌리티(Ability) 노드

이 튜토리얼에서는 에이전트리아(Agentria) 의 어빌리티(Ability) 노드 사용법을 안내합니다. 어빌리티 노드는 내가 미리 만들어 둔 다른 어빌리티(Ability)를 현재 워크플로(Workflow)에 노드 형태로 불러와 실행합니다. 특정 기능을 담당하는 어빌리티를 한 번 만들어 두면, 여러 워크플로에서 노드로 재사용할 수 있습니다.

이 튜토리얼에서는 달러 금액을 원화로 환산하는 '환율 변환기' 어빌리티를 먼저 만들어 버전을 생성하고, 이를 어빌리티 노드로 불러와 상품 가격을 원화로 변환하는 워크플로를 완성합니다.

사전 준비

에이전트리아 캔버스 진입 방법은 🔗3단계 핵심 가이드를 참고하시기 바랍니다.

어빌리티 노드는 불러올 어빌리티가 먼저 완성되어 있고, 버전이 생성된 상태여야 사용할 수 있습니다. 따라서 이 튜토리얼은 두 부분으로 나뉩니다.

• A. 사전 어빌리티 만들기: 불러올 '환율 변환기' 어빌리티를 만들고 버전을 생성합니다.

• B. 어빌리티 노드 사용하기: 만들어 둔 어빌리티를 노드로 불러와 실행합니다.

이 튜토리얼을 완료하면 다음을 수행할 수 있습니다.

1. 재사용할 어빌리티를 만들고 버전을 생성할 수 있습니다.

2. 어빌리티 노드를 캔버스에 배치하고 불러올 어빌리티를 선택할 수 있습니다.

3. 바인딩(Binding)을 통해 현재 워크플로의 변수를 어빌리티의 인풋 변수와 연결할 수 있습니다.

4. 어빌리티 노드의 아웃풋을 종료 노드로 전달할 수 있습니다.

💡 어빌리티 노드를 언제 쓰면 좋은가요?
환율 변환, 날짜 포맷 정리, 사내 용어 번역처럼 여러 워크플로에서 똑같이 반복되는 기능이 있다면, 그 기능을 어빌리티 하나로 만들어 두고 어빌리티 노드로 불러 쓰면 됩니다. 로직을 한 곳에서만 관리하면 되므로, 수정이 필요할 때 어빌리티만 고치고 버전을 올리면 모든 워크플로에 반영할 수 있습니다.

A. 사전 어빌리티 만들기

먼저 어빌리티 노드 로 불러올 대상을 만듭니다. 여기서는 달러(USD)를 원화(KRW)로 환산하는 단순한 어빌리티 USD→KRW 환율 변환기를 만듭니다.

A-1단계: 인풋 변수 선언

새 어빌리티를 생성하고, 시작 노드(Start Node)를 더블 클릭하여 노드 편집기(Node Editor)를 엽니다.

입력 변수에 다음 변수를 추가합니다.

usd는 원화로 환산할 달러 금액이고, rate는 그날의 환율(1 USD당 원화)입니다. 환율은 매일 바뀌므로 고정값으로 두지 않고 입력으로 받습니다.

숫자 타입은 Float(실수)와 Integer(정수) 중 선택할 수 있습니다. 달러 금액과 환율은 소수점이 있을 수 있으므로(예: 19.99, 1352.5) Float로 선언합니다.

A-2단계: 파이썬 노드로 변환 로직 작성

+노드 추가(Add Node) → 코드(Code) 카테고리에서 파이썬(Python) 노드를 배치하고, 시작 노드와 엣지(Edge)로 연결합니다.

파이썬 노드를 더블 클릭하여 다음 코드를 작성합니다.

# 달러(usd)와 그날의 환율(rate)을 받아 원화(krw)로 환산합니다.
# usd, rate 는 실수(Float)로 입력됩니다. (예: usd=19.99, rate=1515.9)
usd = <em>{{usd 드래그 앤 드롭}}</em>
rate = <em>{{rate 드래그 앤 드롭}}</em>
krw = round(usd * rate)
return {"krw": krw}

# 달러(usd)와 그날의 환율(rate)을 받아 원화(krw)로 환산합니다.
# usd, rate 는 실수(Float)로 입력됩니다. (예: usd=19.99, rate=1515.9)
usd = <em>{{usd 드래그 앤 드롭}}</em>
rate = <em>{{rate 드래그 앤 드롭}}</em>
krw = round(usd * rate)
return {"krw": krw}

# 달러(usd)와 그날의 환율(rate)을 받아 원화(krw)로 환산합니다.
# usd, rate 는 실수(Float)로 입력됩니다. (예: usd=19.99, rate=1515.9)
usd = <em>{{usd 드래그 앤 드롭}}</em>
rate = <em>{{rate 드래그 앤 드롭}}</em>
krw = round(usd * rate)
return {"krw": krw}

코드를 작성한 뒤, 출력 영역(Output Section)에 return의 키와 동일한 이름의 출력 변수를 추가합니다.

코드 노드는 return {"키": 값} 형태로 결과를 반환하며, 반환한 키와 같은 이름의 출력 변수를 선언해야 합니다. 코드 노드의 작성 규칙(사용 가능한 라이브러리, 사용할 수 없는 함수 등)은 🔗코드 노드 사용하기 (Python)를 참고하시기 바랍니다.

A-3단계: 종료 노드 연결

파이썬 노드와 종료 노드(End Node)를 엣지로 연결합니다.

종료 노드를 더블 클릭하여 아웃풋 영역에 krw (Integer) 변수를 추가하고, 파이썬 노드의 krw 출력을 드래그 앤 드롭(Drag and drop)으로 연결합니다.

이로써 usd를 받아 krw를 반환하는 환율 변환기 어빌리티가 완성되었습니다.

A-4단계: 버전 생성 (필수)

어빌리티 노드는 버전이 생성된 어빌리티만 불러올 수 있습니다.

캔버스 우측 상단의 버전(Version) 버튼을 클릭하면 우측에 버전 히스토리 패널이 열립니다. + 아이콘을 클릭한 뒤, 버전 번호와 변경 내용(Change Log)을 입력하고 생성(Create)을 클릭합니다.

생성한 버전은 나중에 다시 선택해 롤백할 수도 있습니다. 버전 번호 기준과 롤백(Rollback) 방법은 🔗버전 관리하기를 참고하시기 바랍니다.

이제 어빌리티 노드 를 사용할 준비가 끝났습니다.

B. 어빌리티 노드 사용하기

이제 새 어빌리티를 만들어, 방금 만든 USD→KRW 환율 변환기를 어빌리티 노드로 불러옵니다.

워크플로 개요

전체 흐름: 시작 노드 → 어빌리티 노드 → 종료 노드

이 튜토리얼의 핵심은 어빌리티 노드입니다.

어빌리티 노드는 선택한 어빌리티를 내부적으로 실행하고, 그 아웃풋을 현재 워크플로로 전달합니다. 노드 편집기에서 불러올 어빌리티와 버전을 선택하고, 바인딩을 통해 현재 워크플로의 변수를 어빌리티의 인풋 변수에 연결합니다.

B-1단계: 인풋 변수 선언 (시작 노드)

새 어빌리티를 생성하고, 시작 노드를 더블 클릭하여 입력 변수에 다음 변수를 추가합니다.

price_usd는 달러로 표시된 상품 가격이고, rate는 그날의 환율입니다.

B-2단계: 어빌리티 노드 추가

캔버스 좌측 노드 목록에서 나의 어빌리티(My Ability) 카테고리의 어빌리티 노드를 캔버스로 드래그 앤 드롭 합니다.

어빌리티 노드 생성 팝업이 나타나면, 사용할 어빌리티 USD→KRW 환율 변환기 와 사전에 만들어둔 어빌리티 버전 0.0.1 을 선택합니다.

B-3단계: 노드 연결 및 어빌리티·버전 확인

시작 노드의 아웃 핀(Out-Pin)을 어빌리티 노드의 인 핀(In-Pin)과 엣지로 연결합니다.

어빌리티 노드를 더블 클릭하여 노드 편집기를 엽니다.

노드 편집기는 입력, 노드, 출력 세 영역으로 구성되며, 가운데 노드 영역에서 어빌리티 노드의 설정을 확인할 수 있습니다.

입력 영역에는 시작 노드에서 전달된 현재 워크플로의 변수(price_usd, rate)가, 출력 영역에는 어빌리티가 돌려주는 변수(krw)가 표시됩니다.

B-4단계: 변수 입력으로 변수 연결

노드 영역의 변수 입력에는 불러온 어빌리티의 인풋 변수(usd, rate)가 순서대로 표시됩니다.

각 변수 아래의 Select or Drag and Drop a Input Data 칸을 클릭하면, 현재 워크플로의 변수 목록(price_usd, rate)이 나타납니다. 여기서 연결할 변수를 선택하거나, 입력 영역에서 변수를 드래그 앤 드롭하여 연결합니다.

두 변수를 모두 연결해야 어빌리티가 정상적으로 실행됩니다.

연결을 마치면 노드 실행 시 price_usd와 rate의 값이 어빌리티 내부의 usd, rate로 전달됩니다. 어빌리티가 실행을 마치면 그 아웃풋 변수(krw)가 출력 영역에 나타나며, 어빌리티 노드의 아웃풋으로 전달됩니다.

변수 연결의 중요성 어빌리티 노드는 현재 워크플로와 불러온 어빌리티 사이의 '연결 통로' 역할을 합니다. 바깥(현재 워크플로)의 변수 이름과 안쪽(어빌리티)의 변수 이름이 달라도, 변수 입력에서 짝지어 주면 값이 정확히 전달됩니다.

B-5단계: 종료 노드 연결

어빌리티 노드의 아웃 핀(Out-Pin)을 종료 노드의 인 핀(In-Pin)과 엣지로 연결합니다.

종료 노드를 더블 클릭하여 아웃풋 영역에 price_krw (Integer) 변수를 추가하고, 어빌리티 노드의 아웃풋 변수 krw를 드래그 앤 드롭으로 연결합니다.

이로써 '상품 가격 원화 변환' 워크플로가 완성되었습니다.

B-6단계: 어빌리티 테스트로 워크플로 전체 실행

캔버스 우측 하단의 테스트 실행(RUN TEST) 버튼을 클릭하여 어빌리티 테스트(Ability Test)를 실행합니다.

price_usd 입력란에 금액(예: 20), rate 입력란에 환율(예: 1517.1)을 입력한 뒤 실행하면, 어빌리티 노드가 USD→KRW 환율 변환기를 실행하고 결과가 반환됩니다.

종료 노드의 아웃풋에서 price_krw 값이 정상적으로 반환되는 것을 확인합니다.

다음 단계

🎉 축하합니다! 에이전트리아를 사용해 '어빌리티 노드 활용' 워크플로를 완성했습니다.

어빌리티 노드는 자주 사용하는 기능을 어빌리티로 만들어 두고 여러 워크플로에서 노드로 재사용할 수 있게 해 줍니다. 어빌리티의 로직을 수정해야 할 때는 해당 어빌리티만 고쳐 새 버전을 생성하고, 어빌리티 노드에서 버전을 바꿔 주면 됩니다.

에이전트리아는 아이디어를 현실로 바꾸는 가능성의 공간입니다.

당신의 상상력으로 워크플로는 무한히 확장될 수 있습니다.

• 더 많은 어빌리티 예제가 궁금하다면 🔗어빌리티 가이드 페이지를 확인하세요.

• 에이전트 예제를 원한다면 🔗에이전트 가이드 페이지를 확인하세요.