LiteLLM 도구 권한 가드레일

LiteLLM 도구 권한 가드레일 (LiteLLM Tool Permission Guardrail)

LiteLLM 도구 권한 가드레일은 모델이 호출할 수 있는 도구를 구성 가능한 allow/deny 규칙으로 제어하게 해 줘요. 도구 실행에 대해 세밀하고 프로바이더에 구애받지 않는 제어를 제공해요 (예: OpenAI Chat Completions tool_calls, Anthropic Messages tool_use, MCP 도구).

출처: 문서

본문

빠른 시작 (Quick Start)

LiteLLM UI

1단계: 도구 권한 가드레일 선택하기

LiteLLM 대시보드를 열고 Add New Guardrail을 클릭한 뒤 LiteLLM Tool Permission Guardrail을 선택해요. 규칙 빌더 UI가 로드돼요.

2단계: Regex 규칙 정의하기

3단계: 도구 인자 제한하기 (선택)

• Restrict tool arguments를 선택해 중첩 경로(dot + [] 표기법)에 regex 검증을 연결해요. 이렇게 하면 arguments.to[] 같은 민감한 파라미터가 사전 승인된 형식을 따르도록 강제할 수 있어요.

4단계: 기본값과 조치 선택하기

LiteLLM Config.yaml 설정

guardrails:
  - guardrail_name: "tool-permission-guardrail"
    litellm_params:
      guardrail: tool_permission
      mode: "post_call"
      rules:
        - id: "allow_bash"
          tool_name: "Bash"
          decision: "allow"
        - id: "allow_github_mcp"
          tool_name: "^mcp__github_.*$"
          decision: "allow"
        - id: "allow_aws_documentation"
          tool_name: "^mcp__aws-documentation_.*_documentation$"
          decision: "allow"
        - id: "deny_read_commands"
          tool_name: "Read"
          decision: "deny"
        - id: "mail-domain"
          tool_name: "^send_email$"
          tool_type: "^function$"
          decision: "allow"
          allowed_param_patterns:
            "to[]": "^.+@berri\\.ai$"
            "cc[]": "^.+@berri\\.ai$"
            "subject": "^.{1,120}$"
      default_action: "deny"  # Fallback when no rule matches: "allow" or "deny"
      on_disallowed_action: "block"  # How to handle disallowed tools: "block" or "rewrite"

규칙 구조 (Rule Structure)

- id: "unique_rule_id"           # Unique identifier for the rule
  tool_name: "^regex$"           # Regex for tool name (optional, at least one of name/type required)
  tool_type: "^function$"        # Regex for tool type (optional)
  decision: "allow"              # "allow" or "deny"
  allowed_param_patterns:         # Optional - regex map for argument paths (dot + [] notation)
    "path.to[].field": "^regex$"

mode에서 지원하는 값

on_disallowed_action 동작

커스텀 거부 메시지

브랜드화된 오류를 반환하려면 violation_message_template을 설정해요 (예: "this violates our org policy…"). LiteLLM은 거부된 도구의 플레이스홀더를 대체해요.

예시:

guardrails:
  - guardrail_name: "tool-permission-guardrail"
    litellm_params:
      guardrail: tool_permission
      mode: "post_call"
      violation_message_template: "this violates our org policy, we don't support executing {tool_name} commands"
      rules:
        - id: "allow_bash"
          tool_name: "Bash"
          decision: "allow"
        - id: "deny_read"
          tool_name: "Read"
          decision: "deny"
      default_action: "deny"
      on_disallowed_action: "block"

요청이 Read를 호출하려 하면 프록시는 기본 오류 텍스트 대신 "this violates our org policy, we don't support executing Read commands"를 반환해요. 필드를 생략하면 기본 메시지를 유지해요.

2. 프록시 시작하기

litellm --config config.yaml --port 4000

예시 (Examples)

차단 요청(on_disallowed_action: block):

# Test
curl -X POST "http://localhost:4000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-m...here" \
  -d '{ "model": "gpt-5.6-luna", "messages": [{"role": "user","content": "What is the weather like in Tokyo today?"}], "tools": [ { "type":"function", "function": { "name":"get_current_weather", "description": "Get the current weather in a given location" } } ] }'

예상 응답(거부됨):

{ "error" : { "message" : "Guardrail raised an exception, Guardrail: tool-permission-guardrail, Message: Tool 'get_current_weather' denied by default action" , "type" : "None" , "param" : "None" , "code" : "500" } }

재작성 요청(on_disallowed_action: rewrite):

# Test
curl -X POST "http://localhost:4000/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-m...here" \
  -d '{ "model": "gpt-5.6-luna", "messages": [{"role": "user","content": "What is the weather like in Tokyo today?"}], "tools": [ { "type":"function", "function": { "name":"get_current_weather", "description": "Get the current weather in a given location" } } ] }'

예상 응답(도구 제거, 완성 계속):

{ "id" : "chatcmpl-xxxxxxxxxxxxxxx" , "created" : 1757716050 , "model" : "gpt-5.6-luna" , "object" : "chat.completion" , "choices" : [ { "finish_reason" : "stop" , "index" : 0 , "message" : { "content" : "I can't fetch live weather — I don't have real-time internet access." , "role" : "assistant" , "annotations" : [ ] } , "provider_specific_fields" : { } } ] , "usage" : { "prompt_tokens" : 112 , "total_tokens" : 735 , "completion_tokens_details" : { "reasoning_tokens" : 384 } } , "service_tier" : "default" }

도구 인자 제한하기 (Constrain Tool Arguments)

도구를 허용하되 사용 방식을 제한하고 싶을 때가 있어요. 규칙에 allowed_param_patterns를 추가해 특정 인자 경로(dot 표기법, 배열은 [])에 regex 패턴을 적용해요.

guardrails:
  - guardrail_name: "tool-permission-mail"
    litellm_params:
      guardrail: tool_permission
      mode: "post_call"
      rules:
        - id: "mail-domain"
          tool_name: "send_email"
          decision: "allow"
          allowed_param_patterns:
            "to[]": "^.+@berri\\.ai$"
            "cc[]": "^.+@berri\\.ai$"
            "subject": "^.{1,120}$"
      default_action: "deny"
      on_disallowed_action: "block"

이 예시에서 LLM은 여전히 send_email을 호출할 수 있지만, @berri.ai 밖의 사람에게 메일을 보내거나 regex에 실패하는 subject를 만들려 하면 가드레일이 호출을 차단해요(on_disallowed_action에 따라 재작성할 수도 있어요). 인자 값이 중요한 도구(메일 발송, 에스컬레이션 워크플로, 티켓 생성 등)에 이 패턴을 사용하세요.

더 알아보기 (Learn more)

• 가드레일 문서