허용 목록 도구로 요청 범위 확인하기

에이전트에 여러 도구와 액터를 연결하면 어떤 작업을 허용할지 명확히 정해야 합니다. 이번 레슨에서는 normalize_text와 record_result 두 작업만 허용하는 course_check_scope 도구를 만듭니다.

기존 레슨에서 사용하던 LLM의 의도 분류와 confidence 값은 별도의 Agent Builder 기능이 아니며 결과도 매번 달라질 수 있습니다. 이번 실습은 같은 입력에 항상 같은 판정을 반환하는 Python 허용 목록을 사용합니다.

범위 확인 도구 만들기

1. 왼쪽 사이드바에서 AI → 도구를 선택합니다.
2. 오른쪽 위의 생성을 선택합니다.
3. 다음 기본 정보를 입력합니다.

입력 파라미터 추가하기

입력 파라미터 → 파라미터 추가를 선택하고 다음 값을 입력합니다.

허용 목록 코드 작성하기

소스 코드를 다음 내용으로 교체합니다.

ALLOWED_ACTIONS = {"normalize_text", "record_result"}


def execute(action: str) -> dict:
    """Check one explicit action code against the course allow-list."""
    normalized = action.strip().lower()
    allowed = normalized in ALLOWED_ACTIONS
    return {
        "action": normalized,
        "allowed": allowed,
        "reason": (
            "allowed action"
            if allowed
            else "action is outside the allowed scope"
        ),
    }

허용하지 않을 작업을 나열하는 거부 목록(deny list) 대신, 허용할 두 개의 작업만 코드에 명시합니다. 따라서 새 작업 코드가 추가되면 기본값은 자동으로 allowed: false가 적용됩니다.

세 가지 입력 테스트하기

테스트 실행에서 다음 입력을 하나씩 실행합니다.

문자열 정리 허용

{
  "action": "normalize_text"
}

예상 결과:

{
  "action": "normalize_text",
  "allowed": true,
  "reason": "allowed action"
}

결과 기록 허용

{
  "action": "record_result"
}

allowed가 true인지 확인합니다.

목록에 없는 삭제 작업 거부

{
  "action": "delete_data"
}

예상 결과:

{
  "action": "delete_data",
  "allowed": false,
  "reason": "action is outside the allowed scope"
}

세 실행이 모두 성공한 뒤 도구 호출 예시에 허용 예시와 거부 예시를 추가하고 저장을 선택합니다.

에이전트에 연결하기

1. AI → 에이전트에서 에이전트 빌더 실습을 엽니다.
2. 기능 구성 → 도구 → 전체 보기를 선택합니다.
3. 요청 범위 확인 도구를 선택합니다.
4. 레슨 4의 RAG 도구를 건너뛰었다면 도구 선택 수가 2인지, 연결했다면 3인지 확인합니다.
5. 시스템 지시문 끝에 다음 내용을 추가합니다.

다른 도구나 액터를 호출하기 전에 course_check_scope 도구로 작업 코드를 확인하세요.
allowed가 false면 다른 도구나 액터를 호출하지 말고 지원하는 작업을 안내하세요.

6. 상단의 저장을 선택합니다.

이 도구가 보장하는 것과 보장하지 않는 것

course_check_scope 함수의 결과는 결정론적입니다. 같은 action을 입력하면 항상 같은 allowed 값을 반환합니다. 다만 AI 에이전트 모드에서는 LLM이 이 도구를 반드시 먼저 호출하도록 강제할 수는 없습니다. 시스템 지시문은 행동을 유도하는 역할을 할 뿐, 접근 제어 정책 자체는 아니기 때문입니다.

실행 순서와 권한 검사를 확실하게 보장하려면 다음과 같은 방식을 함께 사용하는 것이 좋습니다.

• 에이전트 생성 시 워크플로우 모드를 선택하고, 범위 확인 노드 뒤에만 실행 노드를 연결합니다.
• 액터의 확인 정책을 확인 또는 거부로 설정합니다.
• 실제 API와 데이터 접근 권한은 서버의 역할 기반 권한 및 세분화된 접근 제어(RBAC 등)로 제한합니다.
• 허용 목록에 없는 작업은 실행 코드에서도 반드시 거부합니다.

자가 점검

• course_check_scope 도구를 같은 컬렉션에 만들었습니다.
• normalize_text와 record_result는 허용되고 delete_data는 거부됩니다.
• 허용하지 않은 새 작업이 기본적으로 거부됩니다.
• 에이전트의 기능 구성에 도구 2개와 액터 1개가 보입니다. RAG 도구도 연결했다면 도구는 3개입니다.
• 시스템 지시문과 강제 접근 제어의 차이를 이해했습니다.
• 고정 실행 순서가 필요할 때 워크플로우 모드를 사용해야 함을 이해했습니다.

다음 레슨

에이전트를 저장·배포하고 미리보기와 채팅 화면에서 실행 상태, 도구 호출, 액터 승인 흐름을 확인하는 방법을 알아봅니다.