Web Request 노드 가이드의 튜토리얼은 에이전트리아(Agentria) 입문자를 위한 외부 API 연동의 기초 과정을 다룹니다.

본 튜토리얼에서는 공개 날씨 API에 HTTP 요청을 보내고, 응답 데이터를 워크플로에서 활용하는 어빌리티를 직접 만들고 실행합니다.

사전 준비

시작을 위해, 에이전트리아에서 프로젝트(Project)를 생성한 후, 어빌리티 캔버스(Canvas)로 진입합니다.

캔버스 진입 절차는 🔗3단계 핵심 가이드의 1단계(프로젝트 생성 및 컴포저 선택)를 참고하시기 바랍니다.

본 튜토리얼을 완료하면 다음과 같은 작업을 수행할 수 있습니다.

1. Web Request 노드 추가하기

2. 요청 메서드(Method)와 URL 설정하기

3. 헤더(Header) 구성하기

4. 선택 파라미터 추가하기

5. 타임아웃(Timeout) 설정하기

6. 노드 테스트(Node Test)를 통해 응답 확인하기

7. 응답 데이터를 다음 노드로 전달하기

1단계: Web Request 노드 추가

캔버스 좌측 패널의 +노드 추가(Add Node) 버튼을 클릭합니다.

웹 도구(Web Tools) 카테고리에서 Web Request 노드를 드래그 앤 드롭(Drag and Drop) 방식으로 캔버스에 배치합니다.

노드를 더블 클릭하면 노드 편집기가 팝업 형태로 열립니다.

2단계: 요청 메서드 설정

노드 편집기 상단의 요청 메서드(Request Method) 필드에서 HTTP 메서드를 선택합니다.

• GET— 데이터를 조회할 때 사용합니다.

• POST — 데이터를 서버에 전송하거나 새 리소스를 생성할 때 사용합니다.

• PUT — 기존 데이터를 수정할 때 사용합니다.

• DELETE — 데이터를 삭제할 때 사용합니다.

본 튜토리얼에서는 날씨 데이터를 조회하기 위해 GET을 사용합니다.

3단계: 요청 URL 설정

요청 URL(Request URL) 필드에 요청을 보낼 대상 서버의 주소를 입력합니다.

예시:

https://api.open-meteo.com/v1/forecast?latitude=37.5&longitude=127.0¤t_weather=true

URL에 동적 값(변수)을 포함하려면 이후 단계에서 선택 파라미터의 path 또는 query_params 옵션을 활용하세요.

4단계: 헤더 설정

헤더 내용(Header) 필드에는 요청 헤더에 포함할 정보를 JSON 형식으로 입력합니다.

인증이 필요한 API의 경우 아래와 같이 Authorization 정보를 추가합니다.

예시:

{ "Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json" }

인증이 필요 없는 공개 API를 사용하는 경우 이 필드는 비워 두어도 됩니다.

5단계: 선택 파라미터 추가

옵션 변수에서 추가할 변수 선택 버튼을 클릭하면 선택 파라미터를 추가할 수 있습니다.

필요에 따라 파라미터를 선택하여 활성화합니다.

• query_params — URL에 추가할 쿼리 파라미터입니다.

• body — 요청 본문에 포함할 텍스트 데이터입니다. POST · PUT 요청 시 활용합니다.

• files — 요청에 첨부할 파일 데이터입니다. [{name: bytes}] 형태로 입력합니다.

• path — 요청 URL의 동적 경로(Path)를 지정합니다.

• request_type — HTTP 요청 시 사용할 바디 타입입니다. Default / RAW / Form Data / Form URL Encoded 중 선택합니다.

• content_type — Content-Type 헤더에 대응하는 MIME 타입을 입력합니다. 기본값은 자동 감지입니다.

이전 노드에서 전달된 변수를 파라미터에 연결하려면, 드래그 앤 드롭 방식으로 변수를 해당 필드에 바인딩합니다.

6단계: 타임아웃 설정

요청 타임아웃(Request Timeout) 필드에서 요청 대기 시간을 초 단위로 설정합니다.

기본값은 5초이며, 응답이 느린 외부 API를 호출할 경우 값을 늘려 Timeout Error를 방지할 수 있습니다.

7단계: 노드 테스트 실행

설정을 완료한 뒤 인풋 영역의 테스트(TEST) 버튼을 눌러 노드 테스트를 실행합니다.

🔗노드 테스트란 노드 편집기에서 개별적으로 진행할 수 있는 점검 작업입니다.

이를 통해 노드가 올바르게 구성되어 있음을 확인한 후 다른 노드와 연결하면 오류를 최소화하고 흐름을 안정적으로 이어나갈 수 있습니다.

테스트가 성공하면 출력 영역의 response 변수에 응답 데이터가 표시됩니다.

예시:

Output:

8단계: 다음 노드와 연결

테스트를 통해 올바른 응답을 확인했다면, 캔버스로 돌아와 Web Request 노드의 아웃 핀(Out-Pin)을 다음 노드의 인 핀(In-Pin)과 엣지(Edge)로 연결합니다.

응답 데이터는 response 변수에 담겨 다음 노드로 전달됩니다.

엔드 노드에 result 변수를 선언하고 response 값을 바인딩합니다.

(해당 튜토리얼에서는 인풋 노드에 변수 선언을 하지 않아도 됩니다.)

이제 날씨 정보 API 호출값이 엔드 노드로 전달됩니다.

이로써 “날씨 정보 호출” 워크플로가 완성되었습니다.

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

캔버스 우측 하단에서 테스트 실행(RUN TEST) 버튼을 클릭하여 완성된 전체 워크플로를 실행할 수 있습니다.

노드 테스트와 마찬가지로, result 결과에 날씨 API 호출 정보가 표시됩니다.

다음 단계

🎉 축하합니다! 에이전트리아를 사용해 외부 API와 연동하는 워크플로를 완성했습니다.

이제 응답 데이터를 LLM 노드와 연결해 요약하거나, 조건 분기 노드와 조합해 워크플로를 확장해 보세요.

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

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

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

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