gemma 4 같은 로컬 모델에 도구 호출(tool calling)을 붙이면 단순 응답 생성기를 작업 환경을 관찰하는 에이전트로 확장할 수 있다. 이 글은 gemma4:e2b와 Ollama를 기준으로 파일 목록 조회와 계산 도구를 연결하는 패턴을 설명한다. 핵심은 모델이 만든 도구 호출을 곧바로 신뢰하지 않고 애플리케이션이 실행 경계를 강제하는 것이다.

기본 에이전트 루프

사용자 요청 -> Gemma 4 + 도구 스키마
             -> tool_calls가 있으면 앱이 검증·실행
             -> tool 결과를 message history에 추가
             -> Gemma 4가 최종 답변 생성

모델은 무엇을 실행할지 제안하고, 애플리케이션은 허용 목록, 인자, 권한을 검증한 뒤 실제 실행을 맡는다.

1. 파일 도구는 작업공간 바깥을 보지 못하게 한다

파일 목록 도구는 상대 경로를 절대 경로로 정규화한 뒤, 안전한 루트 디렉터리 안에 남아 있는지 확인해야 한다.

import os

SAFE_BASE_DIR = os.path.abspath(os.getcwd())

def list_directory_contents(path: str = ".") -> str:
    requested = os.path.abspath(os.path.join(SAFE_BASE_DIR, path))
    allowed = requested == SAFE_BASE_DIR or requested.startswith(SAFE_BASE_DIR + os.sep)
    if not allowed:
        return "Error: permitted workspace 밖의 경로에는 접근할 수 없다."
    return "\n".join(sorted(os.listdir(requested)))

이 검사는 ../../etc나 /Users/.../.env처럼 모델이 만든 경로 탈출(path traversal) 입력을 실제 파일 접근 전에 거부한다.

2. 계산 도구는 학습용 sandbox와 운영용 격리를 구분한다

작은 모델은 산술, 문자열 처리, 통계 계산을 직접 답하기보다 결정적 코드로 실행하는 편이 정확하다. 예제 수준에서는 허용 built-in만 노출한 exec()로 동작을 확인할 수 있다.

safe_builtins = {"print": print, "len": len, "sum": sum, "round": round}
restricted_globals = {"__builtins__": safe_builtins}
exec(code, restricted_globals, {})

그러나 Python exec() built-in 제한은 강한 보안 경계가 아니다. 외부 사용자 입력을 받는 서비스에서는 컨테이너, 별도 프로세스, 네트워크 차단, CPU·메모리·시간 제한을 갖춘 실행 환경을 사용해야 한다.

3. 도구 설명이 모델의 행동을 결정한다

도구 스키마의 설명은 모델이 언제 관찰하고 언제 추측할지를 좌우한다. 파일 도구에는 “로컬 파일에 관한 질문에 답하기 전에 사용한다”, 계산 도구에는 “정밀 계산이 필요할 때 사용한다”처럼 발동 조건을 포함한다.

검증할 테스트

관련 문서

• gemma-tutorial-tool-calling – 함수 호출 루프의 기본 구조
• local-slm-tips-tool-calling-models – 도구 호출용 소형 모델 비교

참고 자료

• Easy Agentic Tool Calling with Gemma 4 – KDnuggets (2026-05-22)