Skip to content

에이전트 빌더

에이전트 빌더를 통해 여러 단계로 구성된 에이전트 워크플로우를 시각적으로 조립하고, 디버깅하고, 배포할 수 있습니다.

에이전트빌더_목록_화면

에이전트 속성

에이전트빌더_상세설정_화면

인사말

대화 시작 문구를 활성화하여 답답한 빈 채팅 화면을 없애세요. 사용자가 새로운 대화를 시작하면 에이전트가 능동적으로 자신을 소개하고 기능을 설명하도록 인사말을 구성하세요. 이를 통해 사용자는 자신이 무엇을 할 수 있는지 즉시 파악할 수 있습니다.

파일 첨부

에이전트에게 파일 입력을 허용할 경우 활성화시킵니다. 활성화 시 채팅창에 파일 첨부 메뉴가 추가됩니다.

트레이스 모드

에이전트 실행 과정을 추적 로그로 기록하는 기능입니다. 기본 정보 사이드바의 기능 영역에서 토글로 켜고 끌 수 있습니다.

  • 로그 기록: 트레이스 모드를 켜면 미리보기 실행 시 추적 로그가 함께 기록됩니다.
  • 추적 로그 확인: 미리보기에서 답변 생성이 완료되면 해당 답변에 트레이스 버튼이 표시되며, 클릭하면 추적 로그 화면이 새 창으로 열립니다.
  • 준비 대기: 답변 직후에는 로그 반영이 끝날 때까지 버튼이 "트레이스 준비 중..."으로 잠시 비활성화되며, 준비가 완료되면 자동으로 활성화됩니다.
  • 실행 이력에서 확인: 트레이스 모드로 실행된 건은 에이전트 모니터링의 실행 이력 페이지에서도 요청 항목에 추적 로그 아이콘이 표시되어, 클릭하면 해당 실행의 추적 로그를 확인할 수 있습니다.

    ⚠️ 답변 생성이 완료된 후 추적 로그가 표시되기까지 다소 시간이 소요될 수 있습니다. 로그가 즉시 표시되지 않는 경우 잠시 후 다시 확인해 주세요. (추적 로그 화면이 바로 열리지 않는 경우)

양식

채팅창에 프롬프트를 불러오는 메뉴가 추가됩니다. 이를 통해 매번 같은 형식의 질문을 직접 타이핑하지 않고 등록된 프롬프트를 불러와서 활용할 수 있습니다.

가드레일

개인 식별 정보(PII)를 마스킹하거나 유해 콘텐츠를 판별하여 원치 않는 입력을 감지하도록 입력 모니터를 설정하십시오.

워크플로우

유용한 에이전트를 구축하려면 에이전트용 워크플로우를 생성해야 합니다. 워크플로우는 에이전트, 도구, LLM 및 제어 흐름 로직의 조합입니다. 워크플로우는 작업을 처리하거나 채팅을 운영하는 데 필요한 모든 작업 및 단계들을 캡슐화하여 배포 후 실행할 수 있는 코드를 포함합니다.

에이전트빌더_플로우_화면

사용가능한 노드

에이전트 빌더에서 노드들을 삽입하고 연결하여 워크플로를 구성합니다. 사용 가능한 노드 타입은 아래와 같습니다.

기본 노드

기본 노드부터 시작하세요. 모든 워크플로는 시작 노드에서 시작합니다.

시작

워크플로를 시작하기 위해 사용자 입력을 수집합니다. 사용자의 직접적인 상호 작용(쿼리 입력 후 전송 버튼 클릭) 혹은 API 호출을 통해 시작합니다.

입력 변수

  • query string
  • 사용자의 최근 채팅 대화에서 자동으로 캡처된 텍스트 메시지입니다.
  • files array
  • 사용자 어플리케이션을 실행할 때 업로드한 파일입니다.

LLM

LLM 노드는 언어 모델을 호출하여 텍스트 및 문서를 처리합니다. 구성된 모델에 프롬프트를 전송하고 응답을 받아 텍스트 출력 혹은 구조화된 출력을 캡쳐할 수 있습니다.

프롬프트 구성
모델 동작 지침(지시어)과 필요 시 사용자 메시지를 추가하세요. 프롬프트에서 워크플로우 변수를 참조할 때는 이중 중괄호({{ variable_name }})를 사용하세요. 변수는 모델에 전달되기 전에 실제 값으로 대체됩니다.

지시어 프롬프트는 Jinja2 템플리트를 지원합니다. Jinja2 템플리트를 사용하면 다음과 같은 작업을 수행할 수 있습니다.


{% for item in results %}
[{{ item.title }}]({{ item.url }}): {{ item.content }}
{% endfor %}

Jinja2 변수는 일반 변수 치환과 별도로 처리되므로 프롬프트 내에서 반복문, 조건문 및 복잡한 데이터 변환이 가능합니다.

채팅 기록
채팅 흐름 내 여러 LLM이나 에이전트 호출에서 컨텍스트를 유지하려면 채팅 기록을 활성화하세요.

  • 채팅 기록을 포함
  • 채팅 기록은 사용자 입력과 이전 에이전트나 LLM 노드의 출력을 포함합니다. LLM이 이전 노드의 맥락을 이해하기 위해 실행 시 전체 대화 기록(또는 최소한 관련 있는 이전 대화 내용)을 포함시킵니다.
  • 채팅 기록에 추가
  • 후속 노드에서 맥락을 참조할 수 있도록 LLM의 생성 답변을 채팅 기록에 추가합니다.

⚠️ 채팅 기록에 추가하지 않은 LLM이나 에이전트 노드의 응답은 대화이력 열람 시 대화 내용에 표시되지 않습니다.

출력 변수

  • text string
  • 모델에 의해 생성된 응답 메시지입니다.
  • reasoning_content string
  • 추론 모드 활성화 시 모델이 생성한 추론 메시지입니다.
  • usage object
  • 토큰 개수와 같은 생성된 메시지에 대한 사용 통계입니다.
  • structured_output object
  • 츨력 변수 형식을 JSON으로 지정할 경우 모델이 설정한 JSON 스키마 형식에 맞게 반환하도록 강제합니다. 구조화된 출력를 참조하세요.

에이전트

에이전트 노드는 LLM에게 도구들에 대한 자율적인 제어 권한을 부여하여, 어떤 도구를 언제 사용할지 반복적으로 결정할 수 있도록 합니다. 모든 단계를 미리 계획하는 대신, 에이전트는 문제를 동적으로 추론하고 필요에 따라 도구를 호출하여 복잡한 작업을 완료합니다.

도구 추가
에이전트가 사용할 수 있는 도구들을 구성하세요.

도구 설명
계획 작성 복잡한 작업 요청의 경우 곧바로 실행에 들어가기보다는 먼저 계획(Plan) 을 수립한 후 이를 실행하는 구조를 갖는 것이 바람직합니다.
계획 작성 도구는 고수준 사용자 목표를 실행 가능한 여러 작업으로 나누어 단계 별(pending → in_progress → completed)로 처리합니다.
이를 통해 필요한 작업을 누락하거나 이미 끝난 작업을 반복하는 실수를 줄일 수 있습니다.
웹 검색 필요 시 인터넷을 검색하여 필요한 정보를 컨텍스트에 포함시킵니다.
문서 검색 검색엔진에 생성한 볼륨에서 콘텐츠를 검색합니다.
문서 불러오기 맥락을 파악하기 위해 선택된 파일 내용을 불러옵니다.
MCP 서버 MCP 서버를 통해 외부 서비스의 도구들을 사용할 수 있게 합니다.

채팅 기록
채팅 흐름 내 여러 LLM이나 에이전트 호출에서 컨텍스트를 유지하려면 채팅 기록을 활성화하세요.

  • 채팅 기록을 포함
  • 에이전트가 이전 노드의 맥락을 이해하기 위해 실행 시 전체 대화 기록(또는 최소한 관련 있는 이전 대화 내용)을 포함시킵니다.
  • 채팅 기록에 추가
  • 후속 노드에서 맥락을 참조할 수 있도록 이 에이전트가 생성하는 도구 호출이나 생성 답변을 채팅 기록에 추가합니다.

    ⚠️ 채팅 기록에 추가하지 않은 LLM이나 에이전트 노드의 응답은 대화이력 열람 시 대화 내용에 표시되지 않습니다.

출력 변수

⚠️ 출력 형식을 JSON으로 할 경우 반환 객체는 json 속성값으로 저장됩니다.

종료

종료 노드에 도달하면 워크플로우를 종료합니다. 종료 전에 최종 사용자에게 전달될 콘텐츠를 정의할 수 있습니다. 이 노드를 사용하여 텍스트와 변수를 결합한 콘텐츠를 스트리밍할 수 있습니다.

논리 노드

논리 노드를 사용하면 사용자 지정 논리를 작성하고 제어 흐름을 정의할 수 있습니다.

IF/ELSE

IF/ELSE 노드는 사용자가 정의한 조건에 따라 실행 경로를 다르게 지정할 수 있도록 워크플로에 분기 로직을 추가합니다. 변수를 평가하고 워크플로가 따라야 할 분기를 결정합니다.

조건은 공통 표현 언어(CEL)를 사용하여 표현식을 만듭니다.

분류

분류 노드는 입력을 지능적으로 분류하여 대화를 다양한 워크플로 경로로 안내합니다. 복잡한 조건 논리를 구축하는 대신 범주를 정의하면 LLM이 의미론적 이해를 바탕으로 가장 적합한 범주를 결정합니다.

입력 변수
분류할 항목을 선택합니다. 일반적으로 사용자 질문(start_0.query)이 사용되지만, 이전 워크플로우 노드의 텍스트 변수라면 무엇이든 사용할 수 있습니다.

지시어
예외적인 경우, 모호한 시나리오 또는 특정 비즈니스 규칙을 처리하기 위해 지시어 필드 에 자세한 분류 지침을 추가하세요 . 이렇게 하면 LLM이 클래스 간의 미묘한 차이를 이해하는 데 도움이 됩니다.

분류 클래스
각 클래스에는 두 개의 독립적인 텍스트가 있습니다.

  • 클래스 이름
  • 캔버스에 표시되는 레이블입니다. 클래스 항목을 명확하게 표현할 수 있는 이름으로 작성하세요.
  • 클래스 설명
  • LLM이 분기를 선택할 때 읽는 내용입니다. 클래스에 속하는 항목을 정확하고 명확하게 설명하세요. 클래스가 겹치는 경우 "…와 관련된 모든 것" 또는 "…을 제외한 것"과 같은 경계 문구를 사용하면 도움이 됩니다.

도구 노드

도구 노드를 사용하면 에이전트에 도구와 외부 서비스를 장착할 수 있습니다. 데이터를 검색하고, 텍스트를 추출하고, 외부 서비스에 연결할 수 있습니다.

지식 검색

검색엔진에서 생성한 볼륨에서 콘텐츠를 검색합니다. 특정 볼륨에서 쿼리와 관련된 정보를 검색하여 하위 노드(예: LLM)에서 사용할 수 있도록 컨텍스트 콘텐츠 형태로 결과를 출력합니다.

검색엔진 볼륨 외 외부 문서를 검색하려면 MCP를 사용하세요.

검색 쿼리
지식 기반에서 검색해야 할 쿼리 텍스트를 선택하세요.

검색 컬렉션
쿼리와 관련된 콘텐츠를 검색할 수 있도록 하나 이상의 기존 지식 기반을 추가합니다.

출력 변수

  • results array
  • 검색된 문서의 청크 내용, 제목, 청크 아이디, URL을 포함하는 배열입니다.
  • content string 청크 내용
  • title string 제목
  • uuid string 청크 아이디
  • url string 청크 URL

문서 추출

업로드된 파일을 언어 모델이 처리할 수 있는 텍스트로 변환합니다. 언어 모델은 PDF나 DOCX와 같은 문서 형식을 직접 읽을 수 없기 때문에, 이 노드는 파일 업로드와 AI 분석 사이의 필수적인 연결 고리 역할을 합니다.

입력 파일
텍스트 추출할 파일 변수에서 가져온 파일 입력(일반적으로 시작노드의 파일 입력 start_0.files)

출력 변수

  • text string
  • 후속 처리를 위해 추출된 원시 텍스트 콘텐츠

HTTP

HTTP 요청 노드는 워크플로우를 외부 API 및 웹 서비스에 연결합니다. 이 노드를 사용하여 데이터를 가져오거나, 웹훅을 보내거나, 파일을 업로드하거나, HTTP 요청을 허용하는 모든 서비스와 통합할 수 있습니다.

출력 변수

  • body string or object
  • HTTP 응답으로 반환되는 본문 텍스트입니다. 응답 콘텐츠 타입이 application/json 일 경우 JSON 오브젝트로 자동 변환됩니다.
  • status_code number
  • HTTP 상태 코드

코드

코드 노드는 워크플로우 중간에 Python 코드를 직접 실행하여 데이터를 가공합니다. 다른 노드만으로는 처리하기 어려운 계산, 문자열 가공, 응답 데이터 재구성 등을 코드로 작성하여 결과를 후속 노드에 전달할 수 있습니다.

입력 변수
코드에 전달할 값을 변수명 과 값 의 쌍으로 등록합니다. 등록한 변수명은 코드의 main 함수 매개변수로 그대로 전달됩니다.

  • 변수명은 영문자·숫자·밑줄(_)만 사용할 수 있고 숫자로 시작할 수 없으며, Python 예약어(for, class 등)와 이미 사용 중인 이름은 쓸 수 없습니다.
  • 값에는 고정 문자열을 입력하거나, 우측 변수 삽입 버튼으로 앞선 노드의 출력 변수(예: {{start_0.query}})를 참조할 수 있습니다.

코드
언어는 Python3 를 지원합니다. 코드는 main 함수에서 시작하며, 반환하는 딕셔너리의 키가 출력 변수로 전달됩니다.

def main(arg1: str, arg2: str):
    return {
        "result": arg1 + arg2,
    }

편집 영역 우측 상단의 아이콘으로 코드를 복사하거나, 전체 화면 편집 창을 열어 긴 코드를 편집한 뒤 [저장]할 수 있습니다.

출력 변수
코드가 반환하는 값을 워크플로우 변수로 선언합니다. 변수를 추가하면 var_1, var_2 와 같이 이름이 자동으로 지정되므로, 코드의 반환 키와 동일한 이름으로 변경해야 합니다. 선언한 변수는 후속 노드에서 {{code_0.result}} 형태로 참조할 수 있습니다.

지정 가능한 타입은 다음과 같습니다.

  • String / Number / Boolean / Object
  • Array[String] / Array[Number] / Array[Boolean] / Array[Object]

⚠️ 반환 딕셔너리의 키와 출력 변수 이름이 일치하지 않으면 후속 노드에서 값을 받을 수 없습니다.

재시도
코드 실행이 실패했을 때 자동으로 다시 시도할지 설정합니다. 기본값은 사용 안 함이며, 활성화하면 아래 항목을 지정할 수 있습니다.

  • 최대 재시도 횟수 : 1 ~ 10회 (기본 3회)
  • 간격 : 0 ~ 5,000ms (기본 100ms)

오류 처리
노드에서 예외가 발생했을 때 적용할 처리 전략을 선택합니다.

전략 설명
없음 예외가 발생하고 처리되지 않으면 노드 실행이 중지됩니다.
기본값 오류가 발생하면 출력 변수마다 미리 지정해 둔 정적 값을 대신 반환합니다.
Boolean, Array[Boolean] 타입의 출력 변수는 기본값 지정 대상에서 제외됩니다.
실패 분기 오류가 발생하면 예외 분기를 실행합니다. 선택 시 노드에 실패 분기 연결점이 추가되며, 캔버스에서 오류 발생 시 진행할 경로를 연결할 수 있습니다.

코드보기

좀 더 전문적으로 에이전트를 개발하고자 할 경우 상단 메뉴에서 [코드보기]를 클릭하세요. 워크플로우 코드를 복사하여 어디에서든 사용할 수 있습니다.

미리보기

워크플로우를 구축하는 동안 미리보기 기능을 사용하여 워크플로우를 테스트할 수 있습니다. 미리보기 기능을 통해 워크플로우를 대화형으로 실행하고, 샘플 파일을 첨부하고, 각 노드의 실행 과정을 확인할 수 있습니다.

배포

워크플로우가 만족스러우면 배포하여 사용자들이 접근할 수 있는 새로운 버전을 생성하세요. 배포된 에이전트는 채팅 페이지의 에이전트 목록에 추가됩니다.

에이전트 버전 관리

에이전트 빌더 화면에서는 작업 중인 Flow 에이전트의 그래프를 버전으로 저장해 두고, 언제든지 이전 버전으로 되돌릴 수 있습니다.

⚠️ 버전 관리는 Flow 에이전트에서 제공되며, 내부 에이전트 위임 유형에는 제공되지 않습니다.

빌더 상단에는 [버전] 버튼이 있으며, 버튼에는 현재 편집 중인 버전 번호(v1, v2, …)가 배지로 표시됩니다. 배지 옆에는 해당 버전이 마지막으로 저장된 시각이 "저장됨" 문구와 함께 표시됩니다.

버전 저장

상단의 [저장] 버튼을 클릭하면 두 가지 저장 방식을 선택할 수 있습니다.

  • 변경사항 저장
  • 현재 작업 내용을 지금 선택되어 있는 버전에 그대로 반영합니다. 새 버전은 만들어지지 않으며, 버전 번호도 바뀌지 않습니다. 아직 저장된 버전이 없는 에이전트는 처음 저장할 때 첫 버전(v1)이 자동으로 만들어집니다.
  • 새 버전으로 저장
  • 현재 작업 내용을 새로운 버전으로 저장합니다. 클릭하면 저장 창이 열리며, 저장될 버전 번호가 안내됩니다.
    • 버전 이름 : 버전을 구분할 이름을 입력합니다. (최대 50자, 비워두면 "버전 N"으로 저장)
    • 변경 내용 (선택) : 이번 버전에서 무엇이 바뀌었는지 기록합니다. (최대 500자)
  • [저장]을 누르면 "버전 N이(가) 저장되었습니다" 안내와 함께 새 버전이 만들어지고, 상단 버전 배지가 새 버전 번호로 바뀝니다.

미리보기나 배포를 실행할 때도 현재 작업 내용이 자동으로 저장됩니다.

버전 목록

상단의 [버전] 버튼을 클릭하면 화면 우측에 버전 관리 패널이 열립니다. 저장된 버전들이 최신순으로 카드 형태로 나열되며, 각 카드에는 다음 정보가 표시됩니다.

  • 버전 번호(vN)와 버전 이름
  • 배지 : 배포 중인 버전에는 "배포됨", 현재 편집 중인 버전에는 "선택된 버전" 배지가 표시됩니다.
  • 변경 내용 : 저장 시 기록한 변경 내용이 2줄로 접혀 표시되며, 길이가 긴 경우 [더보기]로 전체를 펼쳐 볼 수 있습니다.
  • 마지막 변경 시각과 노드/연결 수

아직 저장된 버전이 없는 경우 "저장하면 첫 버전(v1)이 만들어집니다" 안내가 표시됩니다.

버전 복원

버전 카드의 [복원] 버튼을 클릭하면 확인창이 표시되고, [확인]을 누르면 해당 버전의 그래프가 편집기로 불러와집니다.

  • 복원은 그래프(노드/연결)만 불러오며, 에이전트 이름·설명·설정은 현재 상태가 유지됩니다.
  • 복원 시 현재 작업 중인 그래프 변경 사항은 덮어쓰여지므로, 남겨야 할 변경이 있다면 먼저 저장해야 합니다.
  • 복원한 내용은 저장해야 서버에 반영됩니다. 저장 전까지는 편집기에서만 열린 상태입니다.
  • 현재 편집 중인 내용과 동일한 버전은 [복원] 버튼이 비활성화됩니다. (편집으로 내용이 달라진 경우에는 같은 버전이라도 되돌릴 수 있습니다)

⚠️ 읽기 전용으로 접근한 사용자에게는 [복원] 대신 [보기] 버튼이 표시되며, 해당 버전의 그래프를 편집기에서 열람만 할 수 있고 저장은 되지 않습니다.

버전 삭제

버전 카드의 [삭제] 버튼을 클릭하고 확인창에서 [확인]을 누르면 해당 버전이 삭제됩니다. 단, 다음 버전은 삭제할 수 없습니다.

  • 최초 버전(v1)
  • 배포 중인 버전 ("배포됨" 배지가 표시된 버전)
  • 현재 선택된 버전 (편집 중인 버전)

배포와 버전

배포를 실행하면 현재 편집 중인 버전이 배포 버전이 되며, 버전 목록에서 해당 버전에 "배포됨" 배지가 표시됩니다. 배포 중인 버전은 삭제할 수 없으므로, 배포 이력이 있는 구성은 항상 버전 목록에 보존됩니다.