Gemma 4를 활용한 안전한 에이전트 도구 호출 구현

섹션별 상세

에이전트 아키텍처는 모델이 도구 호출 여부를 결정하고, 실행 결과를 다시 입력받아 최종 답변을 합성하는 2단계 오케스트레이션 루프를 사용한다.

Gemma 4를 활용한 에이전트 도구 호출의 전체 워크플로우를 보여주는 다이어그램. — Diagram이 이미지는 이해, 계획, 도구 호출, 결과 획득, 목표 달성으로 이어지는 에이전트의 순환 과정을 시각화한다. 기사에서 설명하는 2단계 오케스트레이션 루프의 핵심 단계를 요약하여 보여준다.

파일 시스템 도구는 os.path.abspath와 경로 접두사 검증을 통해 허용된 작업 공간 외부로의 접근을 원천 차단하는 안전한 파일 탐색기를 구현한다.

python

SAFE_BASE_DIR = os.path.abspath(os.getcwd())
def list_directory_contents(path: str = ".") -> str:
    try:
        requested = os.path.abspath(os.path.join(SAFE_BASE_DIR, path))
        if not (requested == SAFE_BASE_DIR or requested.startswith(SAFE_BASE_DIR + os.sep)):
            return ( f"Error: Access denied. The path '{path}' resolves outside the " f"permitted workspace ({SAFE_BASE_DIR})." )

파일 시스템 탐색 시 경로 탐색 공격을 방지하기 위해 절대 경로를 확인하고 작업 공간 외부 접근을 차단하는 로직

근거

파일 시스템 도구는 경로를 절대 경로로 변환하고 접두사를 확인하여 ../와 같은 경로 탐색 시도를 차단한다. — Tool 1: A Sandboxed Filesystem Explorer 섹션

파이썬 인터프리터 도구는 exec() 함수 실행 시 __builtins__를 화이트리스트 기반으로 교체하여 위험한 함수 접근을 방지하고, math와 statistics 모듈을 사전 로드하여 모델의 연산 정확도를 높인다.

python

safe_builtins = {
    "abs": abs, "all": all, "any": any, "bool": bool, "dict": dict, "divmod": divmod, "enumerate": enumerate, "filter": filter, "float": float, "int": int, "len": len, "list": list, "map": map, "max": max, "min": min, "pow": pow, "print": print, "range": range, "repr": repr, "reversed": reversed, "round": round, "set": set, "sorted": sorted, "str": str, "sum": sum, "tuple": tuple, "zip": zip,
}
restricted_globals = {
    "__builtins__": safe_builtins,
    "math": math,
    "statistics": statistics,
}

파이썬 인터프리터 도구에서 위험한 내장 함수 접근을 막기 위해 화이트리스트 기반으로 환경을 제한하는 설정

도구 호출 시 모델이 생성한 문자열을 신뢰하지 않고, 샌드박스 환경 내에서만 동작하도록 제약 조건을 설정하여 잠재적 보안 위협을 최소화한다.

용어 해설

에이전트 도구 호출(Agentic Tool Calling): — LLM이 외부 환경과 상호작용하기 위해 API나 로컬 함수를 스스로 선택하고 실행하는 과정. 단순 텍스트 생성을 넘어 시스템 상태를 조회하거나 코드를 실행하여 실질적인 작업을 수행하는 에이전트의 핵심 능력이다.
경로 탐색 공격(Path Traversal): — 파일 시스템 접근 시 상위 디렉토리로 이동하는 문자열(예: ../)을 사용하여 허용되지 않은 경로의 파일에 접근하는 보안 취약점. 에이전트가 로컬 파일을 다룰 때 반드시 차단해야 하는 위험 요소이다.
샌드박스(Sandbox): — 외부 코드나 프로세스를 격리된 환경에서 실행하여 시스템 전체에 영향을 미치지 않도록 하는 보안 기법. 에이전트가 실행하는 코드나 도구 호출이 호스트 시스템을 손상하지 않도록 제한하는 데 사용된다.
오케스트레이션 루프(Orchestration Loop): — 모델의 응답, 도구 실행, 결과 피드백을 반복적으로 처리하는 제어 흐름. 모델이 도구 호출을 결정하면 시스템이 이를 실행하고, 그 결과를 다시 모델에 전달하여 최종 답변을 도출하는 순환 구조이다.

근거 모음

근거

Gemma 4는 로컬 환경에서 실행 가능하며 구조화된 출력에 능숙하여 에이전트 루프를 안정적으로 구동한다. — From Conversation to Agency 섹션

기술

Gemma 4
Ollama
Python

활용 사례

로컬 파일 시스템 관리 에이전트
안전한 코드 실행 환경
데이터 분석 자동화