노드 사용법 익히기 - 가드레일(Guardrail) 노드

가드레일 노드는 텍스트를 정책에 비춰 검사하는 노드입니다. 금지 키워드·시크릿 키·URL 허용 목록처럼 정규식으로 빠르게 검사할 수 있는 항목과, 프롬프트 인젝션·NSFW·주제 이탈처럼 LLM으로 판단해야 하는 항목을 하나의 노드에서 함께 다룹니다. 가드레일 노드는 텍스트를 바꾸지 않고 판정만 하며, 판정 결과에 따른 분기는 분기(Branch) 노드가 맡습니다.

이 튜토리얼에서는 고객 문의를 가드레일로 검사한 뒤, 통과한 문의는 LLM이 응답을 생성하고 위반한 문의는 안내 메시지로 차단하는 고객 지원 어빌리티를 만듭니다. 실제 테스트 실행 결과를 통해 정규식 검사와 LLM 기반 검사가 어떻게 다르게 동작하는지 확인합니다.

사전 준비

이 튜토리얼을 시작하기 전에 프로젝트에서 어빌리티(Ability)를 생성하고 캔버스(Canvas)에 진입해야 합니다. 캔버스 진입 방법은 🔗3단계 핵심 가이드를 참고하시기 바랍니다.

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

1. 가드레일 노드의 검사 항목을 설정해 정규식 검사와 LLM 기반 검사를 함께 구성할 수 있습니다.

2. 금지 키워드, 허용 주제 범위, 판정 임계값, 전수 검사 옵션의 역할을 이해하고 용도에 맞게 설정할 수 있습니다.

3. 가드레일 노드의 passed 출력값으로 분기해 통과/위반 경로를 다르게 처리할 수 있습니다.

4. 테스트 실행 결과에서 violations와 short_circuited를 보고 어떤 검사가 어떻게 동작했는지 확인할 수 있습니다.

워크플로 개요

이 튜토리얼의 핵심은 가드레일 노드입니다.

가드레일 노드는 검사할 텍스트를 검사 항목에 지정한 방식대로 검사합니다. keywords·secret_keys·url_allowlist는 정규식으로 동작해 무과금·즉시 판정되고, prompt_injection·nsfw·topical·custom은 LLM Model 엣지로 연결한 모델이 판단합니다. 검사 결과는 passed(통과 여부)와 violations(위반 상세 목록)로 출력되며, 정규식 검사에서 이미 위반이 발견되면 기본적으로 나머지 검사를 건너뛰고 즉시 종료합니다(short_circuited).

함께 등장하는 노드는 다음과 같은 역할을 합니다.

• 가드레일 전용 LLM: 가드레일 노드의 LLM 기반 검사를 수행하는 전용 모델입니다. 자세한 사용법은 🔗LLM 노드 가이드를 참고하시기 바랍니다.

• 통과/위반 분기: 가드레일 검사의 passed 값에 따라 흐름을 둘로 나눕니다.

• 고객 서비스 응답 생성: 통과한 텍스트를 바탕으로 LLM이 응답을 생성합니다. 🔗LLM 노드 가이드를 참고하시기 바랍니다.

• 차단 메시지 설정: 위반 시 안내 메시지를 전역 변수에 저장합니다. 🔗값 설정 노드 가이드를 참고하시기 바랍니다.

• 응답 결과 병합: 통과 경로와 위반 경로의 결과를 하나로 합칩니다. 🔗병합 노드 가이드를 참고하시기 바랍니다.

가드레일 노드 기본 정보

가드레일 노드는 다음 필드와 옵션을 제공합니다.

출력은 passed(통과 여부), violations(위반 목록 — 항목마다 name·score·reason), short_circuited(정규식 검사에서 위반이 발견되어 나머지 검사를 건너뛰었는지 여부), checked_text(실제로 검사한 원문)입니다.

이 튜토리얼에서는 검사할 텍스트, 검사 항목, 금지 키워드, 허용 주제 범위, 판정 임계값을 설정하고, 전수 검사는 기본값인 Off로 둡니다.

1단계: 시작 노드 설정

시작 노드를 더블 클릭해 노드 편집기를 엽니다. user_text라는 String 입력 변수를 추가합니다. 이 변수에는 가드레일 검사 대상이 되는 사용자 입력 텍스트가 들어옵니다.

2단계: 가드레일 노드 추가

+노드 추가(Add Node) → 보안 / 개인정보 카테고리에서 가드레일 노드를 캔버스에 배치하고, 더블 클릭해 노드 편집기를 엽니다.

3단계: 가드레일 노드 설정

• 검사할 텍스트에는 시작 노드의 user_text를 드래그 앤 드롭으로 바인딩합니다.

• 검사 항목에는 keywords, nsfw, prompt_injection, topical 네 가지를 모두 추가합니다. 정규식 검사(keywords)와 LLM 기반 검사(nsfw, prompt_injection, topical)를 함께 구성하는 예제입니다.

• 옵션 변수의 금지 키워드에는 폭탄, 해킹, 불법, 마약을 추가합니다.

• 허용 주제 범위에는 고객 서비스 및 제품 문의를 입력합니다. topical 검사는 이 범위를 벗어난 텍스트를 위반으로 판단합니다.

• 판정 임계값은 0.7로 둡니다.

• 전수 검사는 기본값인 Off로 둡니다. 이 예제에서는 정규식 검사에서 위반이 발견되면 LLM 검사를 생략하고 바로 종료합니다.

LLM Model 엣지 포트에는 prompt_injection·nsfw·topical 검사를 수행할 LLM 노드를 연결해야 합니다. +노드 추가로 LLM 노드를 배치해 가드레일 전용 LLM이라는 이름으로 바꾸고, LLM Model 엣지로 가드레일 노드와 연결합니다.

참고 — LLM Model 엣지로 연결한 노드는 프롬프트를 비워 둡니다

4단계: 통과/위반 분기 노드 추가 및 설정

+노드 추가로 분기(Branch) 노드를 캔버스에 배치하고, 가드레일 노드 뒤에 연결합니다. 더블 클릭해 노드 편집기를 엽니다.

• 브랜치 이름을 통과 브랜치로 바꾸고, 조건식에 가드레일 노드의 passed를 드래그 앤 드롭으로 바인딩한 뒤 passed == true로 설정합니다.

• 조건을 만족하지 않는 나머지는 Else 브랜치로 흐릅니다.

5단계: 고객 서비스 응답 생성 노드 추가 및 연결

+노드 추가로 LLM 노드를 배치해 고객 서비스 응답 생성이라는 이름으로 바꾸고, 분기 노드의 통과 브랜치 핀에 연결합니다.

• 시스템 프롬프트에 고객 서비스 상담원 역할과 답변 지침을 작성합니다. 이 튜토리얼에서는 "당신은 친절한 고객 서비스 상담원입니다. 고객의 문의에 성실하고 간결하게 답변하세요." 로 시작해 Markdown 형식 활용, 간결하되 충분한 정보 포함 같은 지침을 덧붙입니다.

• 사용자 프롬프트에는 가드레일 노드의 checked_text를 드래그 앤 드롭으로 바인딩합니다. 원문 user_text가 아니라 가드레일 노드가 실제로 검사한 텍스트를 그대로 전달하는 것이 핵심입니다.

• 모델은 필요에 맞게 선택하며, 이 튜토리얼에서는 Anthropic-claude-4.5-sonnet V1, 최대 토큰 수 1024, Sampling Temperature 0.7을 사용합니다.

6단계: 차단 메시지 설정 노드 추가 및 연결

먼저 전역 변수 탭에서 block_message라는 String 전역 변수를 추가합니다. 그다음 +노드 추가로 값 설정(Set Value) 노드를 배치해 차단 메시지 설정이라는 이름으로 바꾸고, 분기 노드의 Else 핀에 연결합니다.

• 전역 변수에는 block_message를 선택합니다.

• 설정 값에는 '죄송합니다. 입력하신 내용이 서비스 정책에 위반되어 처리할 수 없습니다.'를 입력합니다.

7단계: 응답 결과 병합 및 종료 노드 설정

+노드 추가로 병합(Merge) 노드를 배치해 응답 결과 병합이라는 이름으로 바꾸고, 고객 서비스 응답 생성 노드와 차단 메시지 설정 노드 뒤에 모두 연결합니다. 병합할 변수에 고객 서비스 응답 생성의 output과 전역 변수 block_message를 각각 드래그 앤 드롭으로 추가합니다.

종료 노드를 더블 클릭해 노드 편집기를 엽니다. 결과를 확인하고 싶은 값을 출력 변수로 추가하고 드래그 앤 드롭으로 바인딩합니다.

• violations: 가드레일 노드의 violations

• passed: 가드레일 노드의 passed

• result: 응답 결과 병합 노드의 merged

참고 — result 배열의 항목 수는 실행마다 다를 수 있습니다

8단계: 테스트 실행

테스트 실행(RUN TEST) 버튼을 클릭하고 user_text에 아래 두 문장을 각각 입력해 통과·위반 두 경로를 모두 확인합니다.

통과 케이스

가드레일 검사는 6.7초가 걸렸습니다. 정규식 검사(keywords)에서 위반이 발견되지 않아 prompt_injection·nsfw·topical LLM 검사까지 모두 수행했기 때문입니다.

위반 케이스

가드레일 검사는 0.14초 만에 끝났습니다. 금지 키워드인 해킹이 즉시 발견되어 short_circuited가 true가 되고, 나머지 LLM 기반 검사와 고객 서비스 응답 생성 노드는 실행되지 않았습니다.

다음 단계

🎉 축하합니다! 에이전트리아를 사용해 '가드레일 검사' 워크플로를 완성했습니다.

외부에 공개하는 챗봇이나 고객 응대 워크플로 앞에 이 노드를 붙이면, 금지어·프롬프트 인젝션·주제 이탈 같은 위험을 LLM 응답 생성 전에 걸러낼 수 있습니다. 검증이 끝난 텍스트만 다음 노드로 전달하는 패턴은 다른 워크플로에도 그대로 적용해 볼 수 있습니다.

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

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

• 더 많은 노드 활용 예제가 궁금하다면 🔗노드 사용법 페이지를 확인하세요.

자주 묻는 질문

가드레일 노드는 무엇을 하는 노드인가요?

가드레일 노드는 텍스트를 정책에 비춰 검사하는 노드입니다. 금지 키워드·시크릿 키·URL 허용 목록은 정규식으로, 프롬프트 인젝션·NSFW·주제 이탈은 LLM으로 판단하며, 검사 결과를 passed(통과 여부)와 violations(위반 상세)로 출력합니다. 텍스트 자체를 바꾸지는 않고 판정만 합니다.

가드레일 노드는 언제 사용해야 하나요?

외부 사용자의 입력을 LLM에 전달하기 전이나, LLM이 생성한 응답을 사용자에게 보여주기 전에 위험한 내용을 걸러내고 싶을 때 사용합니다. 고객 챗봇, 공개 폼 입력, 에이전트 도구 호출 전후 등 신뢰할 수 없는 텍스트가 오가는 지점에 배치합니다.

정규식 검사와 LLM 기반 검사는 어떻게 다른가요?

keywords·secret_keys·url_allowlist는 정규식으로 동작해 무과금으로 즉시 판정됩니다. prompt_injection·nsfw·topical·custom은 LLM Model 엣지로 연결한 모델이 판단하므로 비용과 시간이 더 듭니다. 전수 검사를 꺼두면(기본값) 정규식 검사에서 위반이 발견되는 즉시 LLM 검사를 생략하고 종료합니다.

가드레일 노드가 위반을 판정하면 자동으로 요청을 차단하나요?

아니요. 가드레일 노드는 판정만 하고 분기는 직접 하지 않습니다. passed 출력값을 분기(Branch) 노드의 조건으로 연결해, 통과(true)와 위반(false) 경로를 워크플로에서 직접 구성해야 합니다.