AI 에이전트 가드레일
AI 에이전트는 사용자 질문, 쿼리 결과 같은 로그프레소 데이터를 모델로 보냅니다. AIM Starfort 앱을 설치하면 AI 에이전트 앱에 가드레일로 등록되어, 모델로 가는 내용을 보내기 전에 Starfort로 검사합니다. 개인정보는 가려서 보내고, BLOCK 판정이나 검사 실패 시에는 실행을 중단합니다.
사전 준비
- AI 에이전트 앱 - AI 어시스턴트 또는 에이전틱 SOC 앱 1.13 이상이 설치되어 있어야 합니다
- AIM Starfort 접속 프로파일 - 하나 이상 등록되어 있어야 합니다
별도의 설정은 없습니다. 위 두 가지가 갖춰지면 가드레일이 켜지고, 앱을 삭제하거나 접속 프로파일을 모두 삭제하면 꺼집니다. 접속 프로파일이 여러 개이면 식별자 순으로 첫 번째 프로파일을 사용합니다.
활성화 상태 확인
AI 에이전트 메뉴의 가드레일 탭에서 오른쪽 위 톱니바퀴를 클릭하면 가드레일 활성화 상태 창이 열립니다.
- 상단 배지가 활성이면 가드레일이 켜진 상태입니다
- 등록된 가드레일마다 검사 단계, 준비됨 여부, 사용 중인 접속 프로파일이 표시됩니다
- 준비 안 됨이면 사유가 함께 표시됩니다. 예)
aim-starfort 접속 프로파일이 없습니다.
검사 대상
가드레일이 켜져 있으면 모델로 가는 다음 내용을 모두 검사합니다.
| 대상 | 내용 |
|---|---|
| 사용자 입력 | 채팅 메시지와 이전 대화, 에이전트 실행 입력 |
| 도구 결과 | 에이전트가 실행한 쿼리의 결과 |
| 단발 명령어 | sonar-ai-ask, sonar-ai-ask-batch, sonar-ai-explain-result, 보고서 생성, 이벤트 상관분석, 에이전트 DM 채팅 |
| 모델 출력 | 에이전트의 최종 답변. 현재 Starfort는 입력 검사만 지원하므로 호출하지 않습니다 |
마스킹과 복원
Starfort가 마스킹한 값은 모델로 보내기 전에 {{PHONE_NUMBER_1}}, {{EMAIL_2}} 같은 자리표시자로 바뀝니다. 같은 값은 한 실행 안에서 항상 같은 자리표시자를 사용합니다. 모델에는 자리표시자를 바꾸지 말고 그대로 사용하라는 안내가 함께 전달됩니다.
모델이 자리표시자로 작성한 내용은 실제로 사용되기 직전에 원래 값으로 되돌립니다.
- 쿼리를 실행하기 직전 - 원래 값으로 검색합니다
- 승인 요청 화면 - 승인자는 실제로 실행될 쿼리를 확인합니다
- 서브 에이전트 입력, HTML 보고서
- 최종 답변 - 사용자는 원래 값이 들어간 답변을 받습니다
실패 처리
다음 경우 에이전트 실행은 실패로 끝나며, 일반 실패와 구분되는 사유가 표시됩니다.
| 사유 | 경우 |
|---|---|
| 가드레일이 내용을 차단하여 실행을 중단했습니다 | Starfort 판정이 BLOCK |
| 가드레일 검사를 수행할 수 없어 실행을 중단했습니다 | 판정을 받지 못함(접속 프로파일 오류, HTTP 4xx, 5xx, 연결 실패) |
검사를 하지 못한 내용을 그대로 모델로 보내지 않기 위해, 검사 실패도 항상 실행을 중단합니다. 쿼리 명령어 (sonar-ai-ask 등)에서는 420050(차단), 420051(검사 불가) 오류로 표시됩니다.
실행 세부 단계
에이전트 실행 상세의 각 턴에는 가드레일 기록이 표시됩니다.
- 가드레일 · N회 검사 · 마스킹 값 N건 · 복원 N건 - 해당 턴의 검사 횟수와 자리표시자 수
- 원문 / LLM 전달 형태 전환 - 기본은 원문입니다. LLM 전달 형태를 선택하면 모델이 실제로 받은 자리표시자 형태로 표시됩니다. 사고 내용, 확인된 사실, 도구 쿼리, 도구 결과에 모두 적용됩니다
- 차단되거나 검사에 실패한 턴은 BLOCK 또는 오류 유형이 빨간색으로 표시됩니다
가드레일 기록이 있는 실행은 상단의 가드레일 로그 버튼으로 해당 실행의 감사 로그로 이동할 수 있습니다.
가드레일 감사 로그
가드레일 API를 호출할 때마다 성공, 실패와 관계없이 감사 로그가 1건씩 기록됩니다. 탐지된 원문이 포함되므로 관리자만 조회할 수 있습니다.
화면
AI 에이전트 메뉴의 가드레일 탭에서 조회합니다.
- 상단에서 기간, 에이전트 코드, 대상, 판정, 실패만 여부로 필터링합니다
- 목록에는 시각, 에이전트, 실행, 대상, 프로바이더(접속 프로파일), 판정, 탐지 건수, 지연 시간이 표시됩니다. 실패한 호출은 판정 대신 오류 유형이 표시됩니다
- 행을 클릭하면 탐지 항목(원문, 모델 전달 값, 유형, 규칙, 메시지), 요청 ID, 오류 내용이 펼쳐집니다
- 실행 열을 클릭하면 해당 에이전트 실행 상세로 이동합니다
쿼리
sonar-ai-guardrail-logs 명령어로 같은 로그를 조회합니다. 회사별 감사 로그 테이블을 조회하며, 이후 파이프로 일반 테이블처럼 검색하고 집계할 수 있습니다.
sonar-ai-guardrail-logs duration=7d | search isnotnull(error_kind) | stats count by provider, error_code
error_kind가 없는 행이 성공한 호출입니다. 필드 설명은 쿼리 화면의 명령어 도움말을 참고하십시오.