에이전트 루프 노드
노드 사용법 익히기 - 에이전트 루프(Agent Loop) 노드
에이전트 루프(Agent Loop) 노드는 사용자 요청을 이해하고, 연결된 도구(Tool) 중 지금 필요한 것을 스스로 판단해 호출하며, 필요한 순간 최종 답변을 생성하는 에이전트의 핵심 노드입니다. 어빌리티(Ability)가 아니라 에이전트(Agent) 컴포저에서만 사용할 수 있습니다.
이 튜토리얼에서는 웹 검색 도구와 슬립박스 질의 도구를 에이전트 루프 노드에 함께 연결해, 최신 웹 정보와 슬립박스에 저장된 사내 문서를 모두 활용해 답변하는 챗봇 워크플로를 만들고, 챗 테스트(CHAT TEST)로 직접 대화하며 결과를 확인합니다.
사전 준비
이 튜토리얼을 시작하기 전에 프로젝트에서 에이전트(Agent)를 생성하고 캔버스(Canvas)에 진입해야 합니다. 캔버스 진입 방법은 🔗3단계 핵심 가이드를 참고하시기 바랍니다.
또한 이 튜토리얼은 슬립박스에 질의하는 도구를 함께 사용하므로, 프로젝트에 슬립박스가 미리 구축되어 있어야 합니다. 슬립박스 구성 방법은 🔗슬립박스 가이드를 참고하시기 바랍니다.
이 튜토리얼을 완료하면 다음을 수행할 수 있습니다.
에이전트 루프 노드에 여러 도구(Tool)를 연결해, 에이전트가 상황에 맞는 도구를 스스로 선택하게 할 수 있습니다.
LLM Model·Fallback LLM Model연결 포인트에 LLM 노드를 연결하는 방법을 이해할 수 있습니다.챗 테스트(CHAT TEST)로 에이전트와 직접 대화하며 동작을 확인할 수 있습니다.
디버거로 에이전트가 어떤 도구를 몇 번 호출했는지 실행 과정을 추적할 수 있습니다.
워크플로 개요
이 튜토리얼의 핵심은 에이전트 루프 노드입니다.
에이전트 루프 노드는 사용자 입력(user_input)을 받아, Tools에 연결된 도구들의 설명을 읽고 지금 필요한 도구를 스스로 선택해 호출합니다. 도구 호출 결과를 근거로 필요하면 다른 도구를 추가로 호출하거나, 충분하다고 판단되면 최종 답변(final_answer)을 생성합니다.
Tools, LLM Model, Fallback LLM Model은 값을 입력하는 일반적인 입력란이 아니라, 다른 노드를 엣지로 연결하는 별도의 연결 포인트입니다. Tools에는 도구로 쓸 노드를, LLM Model에는 에이전트의 판단에 사용할 LLM 노드를 연결합니다.
함께 등장하는 도구 노드는 다음과 같은 역할을 합니다. 상세한 사용법은 각 문서를 참고하세요.
DuckDuckGo Web Search: 실시간 웹 검색을 수행하는 도구 노드입니다.슬립박스 질의 노드: 슬립박스에서 관련 문서를 검색해 답변에 활용하는 도구 노드입니다. 자세한 내용은 🔗슬립 탐색 노드 문서를 참고하세요.LLM 노드: 에이전트 루프와 슬립박스 질의 노드가 내부적으로 사용할 모델을 지정합니다. 자세한 내용은 🔗LLM 노드 문서를 참고하세요.
에이전트 루프 노드 기본 정보
에이전트 루프 노드는 아래 기본 입력을 제공합니다.
입력 | 필수 여부 | 설명 |
|---|---|---|
| 필수 | 에이전트에게 요청할 사용자 입력 텍스트입니다. |
최대 스텝 수 | 선택 | 에이전트 루프 최대 반복 횟수입니다 (기본값: 10). |
최대 실행 시간 | 선택 | 최대 실행 시간(초)입니다 (기본값: 120). |
최대 이전 대화 수 | 선택 | 컨텍스트에 포함할 최대 이전 대화 수입니다 (기본값: 10). |
최대 관찰 문자 수 | 선택 | 도구 결과당 최대 문자 수입니다. 초과 시 잘립니다 (기본값: 8000). |
프롬프트 내 최대 도구 수 | 선택 | 프롬프트에 포함할 최대 도구 수입니다. 초과 시 자동으로 지연 로딩되며 |
변수 추가 버튼을 누르면 아래 선택 입력을 추가로 연결할 수 있습니다.
선택 입력 | 설명 |
|---|---|
| 에이전트와 사용자의 이전 대화 리스트입니다. 오래된 대화부터 최신 순이며, 전달하지 않으면 Room Memory에서 자동으로 조회합니다. |
| 에이전트가 접근할 파일입니다. file_id·S3 URL·data URL·HTTPS URL 등을 받아 내부적으로 data URL로 정규화됩니다. |
| 에이전트의 역할과 성격을 정의합니다. |
| 에이전트의 행동 규칙과 지침입니다. 비어 있으면 기본 지침이 적용됩니다. |
| 응답 형식과 톤에 대한 가이드라인입니다. |
| 연결된 LLM 모델이 이미지 입력을 지원하는지 여부입니다. 모델이 지원하지 않는데 |
| 연결된 LLM 모델이 오디오 입력을 지원하는지 여부입니다. |
| 연결된 LLM 모델이 비디오 입력을 지원하는지 여부입니다. |
에이전트 루프 노드는 아래 항목을 출력합니다.
출력 | 설명 |
|---|---|
| 에이전트가 생성한 최종 답변입니다. |
| 에이전트가 판단하고 도구를 호출한 과정 데이터입니다. |
| 실제로 호출된 도구 목록입니다. |
| 실행 관련 지표입니다. |
이 튜토리얼에서는 user_input만 연결하고, 나머지 기본 입력은 기본값을 그대로 사용하며, 선택 입력은 추가하지 않습니다.
1단계: 에이전트 생성
새 에이전트를 생성합니다. 이름에 에이전트 루프 노드, 설명에 스스로 판단하고 행동하는 에이전트를 입력합니다.
Desk 에이전트로 설정 토글은 클라이언트 앱의 Desk 모드에서 실행되어 데스크톱 환경을 제어할 수 있게 하는 기능입니다. 이 튜토리얼에서는 꺼둔 상태로 둡니다.
2단계: 시작 노드(Agent Input) 확인
Agent Input 노드를 더블 클릭해 노드 편집기를 엽니다. input_message, input_files, metadata, session_id 네 가지 입력 변수가 고정되어 있으며, 직접 추가하거나 수정할 수 없습니다.
이 튜토리얼에서는 사용자가 채팅으로 입력한 메시지가 담기는 input_message를 그대로 사용합니다.
3단계: 에이전트 루프 노드 추가
+노드 추가(Add Node)로 에이전트 루프 노드를 캔버스에 배치합니다.
4단계: 도구 노드 추가 (DuckDuckGo Web Search, 슬립박스 질의)
+노드 추가로 DuckDuckGo Web Search 노드와 슬립박스 질의 노드를 각각 캔버스에 배치합니다. 두 노드 모두 에이전트 루프 노드 아래쪽에 배치하면 이후 도구 연결이 수월합니다.
슬립박스 질의 노드를 더블 클릭해 노드 편집기를 열고, 슬립박스 공개 UUID에서 질의할 슬립박스를 선택합니다. 이 튜토리얼에서는 Agentria Docs 슬립박스를 선택합니다.
두 노드 모두 query·search_query처럼 실행 시점에 채워지는 입력 변수는 따로 바인딩할 필요가 없습니다. 노드를 에이전트 루프의 도구로 연결하기만 하면, 에이전트가 상황에 맞는 값을 스스로 채워 호출합니다.
5단계: LLM 노드 추가 및 모델 선택
+노드 추가로 LLM 노드를 캔버스에 배치합니다. LLM 모델에서 Anthropic-claude-4.5-sonnet V1을 선택합니다. 나머지 항목(최대 토큰 수, Sampling Temperature 등)은 기본값을 사용합니다.
6단계: 도구를 에이전트 루프 노드에 연결
에이전트 루프 노드 하단의 Tools 연결 포인트에서 DuckDuckGo Web Search 노드의 인핀(In-Pin)으로 엣지를 연결합니다. 같은 방식으로 Tools에서 슬립박스 질의 노드로도 엣지를 연결합니다.
Tools에는 여러 도구를 연결할 수 있으며, 에이전트는 사용자 요청 내용에 따라 그중 적절한 도구를 자동으로 선택해 호출합니다.
7단계: LLM 노드를 에이전트 루프·슬립박스 질의 노드에 연결
LLM 노드를 에이전트 루프 노드의 LLM Model 연결 포인트에 연결합니다. 같은 LLM 노드를 슬립박스 질의 노드의 LLM Model 연결 포인트에도 연결합니다. 슬립박스 질의 노드는 관련 슬립을 찾는 과정에서 내부적으로 LLM을 사용하므로 별도의 모델 연결이 필요합니다.
Fallback LLM Model은 이 튜토리얼에서 연결하지 않습니다.
8단계: 종료 노드(Agent Output) 설정
Agent Output 노드를 더블 클릭해 노드 편집기를 엽니다. output_message 출력 변수에 에이전트 루프 노드의 final_answer를 드래그 앤 드롭으로 바인딩합니다. output_event_data에는 reasoning_steps를 바인딩합니다.
9단계: 채팅 테스트로 워크플로 실행
채팅 테스트(CHAT TEST) 버튼을 클릭하고, 채팅 입력창에 아래 메시지를 입력해 실행합니다.
에이전트가 웹 검색과 슬립박스 질의 결과를 종합해 "에이전트리아(Agentria)란?"으로 시작하는 답변을 생성하면 정상 동작하는 것입니다.
우측 디버거 패널에서는 에이전트가 실행한 과정을 순서대로 확인할 수 있습니다. 이 예시에서는 DuckDuckGo Web Search를 두 차례 호출해 웹 정보를 검색한 뒤, 슬립박스 질의를 한 차례 호출해 슬립박스에 저장된 문서를 참고하고, 그 결과를 종합해 최종 답변을 생성했습니다.
다음 단계
🎉 축하합니다! 에이전트리아를 사용해 '에이전트 루프' 워크플로를 완성했습니다.
Tools에 더 많은 도구를 연결하면, 하나의 에이전트가 검색·문서 조회·파일 작성 등 더 다양한 작업을 상황에 맞게 스스로 처리하도록 확장할 수 있습니다.
에이전트리아는 아이디어를 현실로 바꾸는 가능성의 공간입니다.
당신의 상상력으로 워크플로는 무한히 확장될 수 있습니다.
더 많은 노드 활용 예제가 궁금하다면 🔗노드 사용법 페이지를 확인하세요.
자주 묻는 질문
에이전트 루프 노드는 무엇을 하는 노드인가요?
에이전트 루프 노드는 사용자 요청을 이해하고, 연결된 도구 중 지금 필요한 도구를 스스로 판단해 호출하며, 충분한 정보가 모이면 최종 답변을 생성하는 에이전트의 핵심 노드입니다. 어빌리티가 아니라 에이전트 컴포저에서만 사용할 수 있습니다.
에이전트 루프 노드에는 도구를 몇 개까지 연결할 수 있나요?
정해진 개수 제한은 없습니다. 다만 프롬프트 내 최대 도구 수(기본값 10)를 넘는 도구를 연결하면, 초과분은 자동으로 지연 로딩되어 tool_search로 검색해 사용하는 방식으로 처리됩니다.
LLM Model과 Fallback LLM Model은 어떻게 다른가요?
LLM Model은 에이전트가 기본적으로 사용할 모델을 연결하는 자리입니다. Fallback LLM Model은 기본 모델 호출이 실패했을 때 대신 사용할 대체 모델을 연결하는 자리로, 반드시 연결할 필요는 없습니다.
슬립박스 질의 노드에도 LLM 노드를 따로 연결해야 하나요?
네, 그렇습니다. 슬립박스 질의 노드는 질의 내용을 바탕으로 관련 슬립을 찾는 과정에서 내부적으로 LLM을 사용하므로, 에이전트 루프 노드와는 별도로 LLM Model 연결 포인트에 LLM 노드를 연결해야 합니다. 같은 LLM 노드를 여러 곳에 함께 연결해도 됩니다.
챗 테스트와 노드 테스트는 어떻게 다른가요?
노드 테스트는 노드 하나를 단독으로 실행해 입력과 출력을 확인하는 방식입니다. 챗 테스트는 에이전트 워크플로 전체를 실제 대화 형태로 실행하는 방식으로, 여러 턴에 걸친 대화 흐름과 도구 호출 과정을 한 번에 확인할 수 있습니다.