도구 정책

도구 정책 (Tool Policies)

Tool Policies는 프록시가 트래픽에서 본 모든 도구(OpenAI·Anthropic 요청의 tools , 응답의 도구 호출, MCP 도구 호출)를 등록하는 레지스트리예요. 도구마다 입력 정책(input policy)과 출력 정책(output policy)을 갖고 있죠. 요청이 프록시를 통과하면 도구가 자동으로 발견되고, 새로 발견된 도구는 input_policy: "untrusted" 와 output_policy: "untrusted" 로 시작해요. Tool Policy Guardrail이 이 레지스트리를 읽어 요청·응답에 정책을 적용해요.

레지스트리는 도구 이름, 출처(origin), 정책 값, 호출 횟수, 사용 가능할 때의 팀과 키, user agent, 그리고 최초·최종 확인 시각을 보관해요. 정책을 변경해도 호출 횟수는 절대 초기화되지 않고, 이후의 호출이 사용자가 설정한 정책을 절대 초기화하지 않아요.

출처: 문서

본문

도구 정책과 도구 권한 Guardrail (Tool Policies and the Tool Permission Guardrail)

Tool Policies는 도구 간의 신뢰 관계를 관리해요. 입력 정책은 신뢰할 수 없는(untrusted) 입력을 허용하거나, 신뢰할 수 있는(trusted) 입력을 요구하거나, 도구를 차단할 수 있어요. 출력 정책은 출력을 trusted 또는 untrusted로 표시하죠. 차단된 입력 정책이나 팀/키 오버라이드가 있으면 도구 호출을 거부해요. trusted 입력 정책은 대화에 untrusted 출력 정책을 가진 도구의 출력이 포함되어 있을 때 해당 도구를 거부해요.

untrusted 입력 정책은 untrusted 도구 출력의 데이터를 포함한 모든 입력을 받아들여요. trusted 입력 정책은 신뢰할 수 있는 입력을 요구해요. blocked 입력 정책은 도구 사용을 금지해요. untrusted 출력 정책은 안전하지 않은 콘텐츠를 포함할 수 있고 다운스트림 신뢰 체인 차단을 유발할 수 있어요. trusted 출력 정책은 검증된 안전한 것으로 취급되어 그런 차단이 발생하지 않아요.

도구 권한 Guardrail 은 별도의 규칙 기반 제어 기능이에요. 설정된 도구 이름과 (선택적으로) 도구 타입·인자를 매칭한 뒤 설정된 allow/deny 동작을 적용해요. 권한 부여가 설정된 패턴 매칭에 의존할 때는 Tool Permission Guardrail 규칙을 사용하고, 발견된 도구의 신뢰 분류와 도구 출력-입력 간 신뢰 체인에 기반한 제어일 때는 Tool Policies를 사용하세요. 두 guardrail 모두 같은 프록시에서 실행될 수 있고, 설정된 각각의 guardrail을 요청이 모두 통과해야 해요.

빠른 시작 (Quick start)

현재 Admin UI 경로는 http://localhost:4000/ui/tool-policies 예요. 레거시 URL http://localhost:4000/ui/?page=tool-policies 은 이 경로로 리다이렉트돼요.

Tool Policies는 프록시 관리자만 사용할 수 있어요. 다른 역할은 관리자 전용 페이지라는 메시지를 보게 돼요.

개요에는 오늘 발견된 도구 수, 발견된 전체 도구 수, 차단된 도구 수, 활성 팀 수가 표시돼요. 기본 untrusted 입력 정책을 아직 가진 새로 발견된 도구도 표시할 수 있어요. 테이블은 검색, 정책·팀·키 필터, 새로고침, 클라이언트 측 페이지네이션을 지원해요. 열에는 발견 시각, 도구 이름, 입력 정책, 출력 정책, 호출 횟수, 팀 이름, 키 해시, 키 이름, user agent가 포함돼요.

도구 이름을 선택하면 상세 보기가 열려요. 상세 보기에는 출처, 호출 횟수, user agent, 최초 발견 시각, 최종 사용 시각이 표시돼요. Input Policy와 Output Policy 선택기를 사용해 전역 정책 값을 저장하세요. 입력 정책은 untrusted , trusted , blocked 중 하나이고, 출력 정책은 untrusted 와 trusted 중 하나예요.

상세 보기에는 도구를 차단하는 팀·키 오버라이드도 표시돼요. 오버라이드를 추가하려면 팀이나 키를 선택하고 blocked 입력 정책을 저장하세요. 오버라이드를 제거하려면 해당 팀·키 옆의 Remove를 선택하면 돼요. 상세 보기에는 선택한 도구의 최근 사용 로그도 포함돼요.

관리 API (Management API)

모든 Tool Policy 관리 경로는 프록시 인증이 필요해요. 프록시 마스터 키를 Authorization 헤더에 보내세요.

도구 목록 (List tools)

GET /v1/tool/list 는 tools 와 total 을 가진 객체를 반환해요. 각 도구 행에는 정책과 레지스트리 메타데이터가 포함돼요. input_policy 쿼리 파라미터로 입력 정책별로 필터링할 수 있어요.

curl "http://localhost:4000/v1/tool/list" \
  -H "Authorization: Bearer $LITEL..._KEY"

차단된 도구만 나열하려면:

curl "http://localhost:4000/v1/tool/list?input_policy=blocked" \
  -H "Authorization: Bearer $LITEL..._KEY"

도구 하나 조회 (Get one tool)

GET /v1/tool/{tool_name} 은 단일 도구 행을 반환해요. URL에서 의미를 갖는 문자가 포함된 도구 이름은 URL 인코딩하세요.

curl "http://localhost:4000/v1/tool/example_tool" \
  -H "Authorization: Bearer $LITEL..._KEY"

GET /v1/tool/{tool_name}/detail 은 도구 행과 함께 overrides 목록을 반환해요. detail 경로는 Admin UI가 사용해요.

curl "http://localhost:4000/v1/tool/example_tool/detail" \
  -H "Authorization: Bearer $LITEL..._KEY"

detail 응답의 형태는 다음과 같아요.

{
  "tool": {
    "tool_id": "tool-id",
    "tool_name": "example_tool",
    "input_policy": "untrusted",
    "output_policy": "untrusted"
  },
  "overrides": []
}

완전한 도구 행에는 다음도 포함될 수 있어요: origin , call_count , assignments , key_hash , team_id , key_alias , user_agent , last_used_at , created_at , updated_at , created_by , updated_by .

정책 옵션 조회 (Get policy options)

GET /v1/tool/policy/options 는 지원되는 입력·출력 정책 값과 그 레이블·설명을 반환해요.

curl "http://localhost:4000/v1/tool/policy/options" \
  -H "Authorization: Bearer $LITEL..._KEY"

응답에는 input_policies 와 output_policies 배열이 있어요. 각 옵션은 value , label , description 을 포함해요:

{
  "input_policies": [
    {
      "value": "untrusted",
      "label": "Untrusted",
      "description": "Tool accepts any input, including data from untrusted tool outputs. Default for newly discovered tools."
    }
  ],
  "output_policies": [
    {
      "value": "trusted",
      "label": "Trusted",
      "description": "Tool output is verified safe. Will not trigger trust-chain blocks on downstream tools."
    }
  ]
}

전역 정책 업데이트 (Update a global policy)

POST /v1/tool/policy 는 tool_name 과 함께 input_policy 또는 output_policy 중 하나 이상을 포함한 JSON 본문을 받아요. 입력 정책은 trusted , untrusted , blocked 를 받고, 출력 정책은 trusted 또는 untrusted 를 받아요.

curl -X POST "http://localhost:4000/v1/tool/policy" \
  -H "Authorization: Bearer $LITEL..._KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "example_tool",
    "input_policy": "blocked",
    "output_policy": "untrusted"
  }'

이 엔드포인트는 필요 시 레지스트리 행을 upsert하고 tool_name , 제출된 정책 필드, updated: true 을 반환해요. 두 정책 필드를 모두 생략하면 HTTP 400과 함께 At least one of input_policy or output_policy must be provided 를 반환해요.

팀/키 오버라이드 추가 또는 제거 (Add or remove a team or key override)

같은 update 경로로 한 팀 또는 한 키에 대한 차단을 추가하거나 제거할 수 있어요. team_id 또는 key_hash 중 정확히 하나를 포함하세요. 오버라이드를 추가하려면 input_policy 를 blocked 로 설정하세요.

curl -X POST "http://localhost:4000/v1/tool/policy" \
  -H "Authorization: Bearer $LITEL..._KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "example_tool",
    "input_policy": "blocked",
    "team_id": "team-id"
  }'

키 오버라이드에는 team_id 대신 key_hash 를 사용하세요. 요청 모델은 update 경로가 반환하는 키 메타데이터용 key_alias 도 받아요.

curl -X POST "http://localhost:4000/v1/tool/policy" \
  -H "Authorization: Bearer $LITEL..._KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "example_tool",
    "input_policy": "blocked",
    "key_hash": "key-hash",
    "key_alias": "production-key"
  }'

오버라이드를 제거하려면 정확히 하나의 쿼리 파라미터와 함께 DELETE /v1/tool/{tool_name}/overrides 를 사용하세요.

curl -X DELETE "http://localhost:4000/v1/tool/example_tool/overrides?team_id=team-id" \
  -H "Authorization: Bearer $LITEL..._KEY"

delete 경로는 오버라이드가 제거되면 {"deleted": true, "tool_name": "example_tool"} 을 반환해요. team_id 와 key_hash 를 모두 전달하면 Provide either team_id or key_hash, not both 오류로 거부돼요.

사용 로그 조회 (Get usage logs)

상세 보기는 GET /v1/tool/{tool_name}/logs 에서 도구 호출 로그를 읽어요. page , page_size , start_date , end_date 쿼리 파라미터를 지원하고, 날짜 값은 YYYY-MM-DD 형식을 사용해요.

curl "http://localhost:4000/v1/tool/example_tool/logs?page=1&page_size=50" \
  -H "Authorization: Bearer $LITEL..._KEY"

응답에는 logs , total , page , page_size 가 포함돼요. 로그 항목에는 요청 ID, 시각, 모델, 지출, 총 토큰 수, 입력 스니펫이 포함될 수 있어요.

적용 (Enforcement)

정책 적용을 활성화하려면 프록시 설정에 Tool Policy Guardrail을 추가하세요.

guardrails:
  - guardrail_name: "tool_policy"
    litellm_params:
      guardrail: tool_policy
      mode: post_call

guardrail은 pre_call , post_call , during_call 이벤트 훅을 지원해요. 요청 시에는 요청 도구에서 도구 이름을 읽고, 도구 목록이 없으면 요청 경로에서 읽어요. 응답 시에는 응답 도구 호출에서 도구 이름을 읽어요.

도구가 input_policy: "blocked" 이거나 팀/키 오버라이드가 차단하면 guardrail이 HTTP 400을 발생시켜요. 호출자에게 보이는 예외 상세는 다음과 같아요.

{
  "detail": {
    "error": "Violated tool policy",
    "blocked_tools": ["example_tool"],
    "message": "Tool(s) ['example_tool'] are blocked by policy."
  }
}

도구가 input_policy: "trusted" 인데 대화에 output_policy: "untrusted" 인 도구의 출력이 포함되어 있으면 guardrail도 HTTP 400을 발생시켜요. 상세에는 blocked_tools , untrusted_sources , 그리고 trusted 입력 도구가 trusted 입력을 요구한다는 메시지가 포함돼요.

HTTP 400 응답의 형태는 다음과 같아요.

{
  "detail": {
    "error": "Violated tool policy",
    "blocked_tools": ["trusted_tool"],
    "untrusted_sources": ["untrusted_tool"],
    "message": "trusted_tool requires trusted input but conversation contains untrusted output from untrusted_tool."
  }
}

인메모리 정책 레지스트리가 초기화되지 않았다면 guardrail은 Tool Policies를 적용하지 않고 입력을 그대로 반환해요. 프록시는 도구 데이터베이스 객체가 로드될 때 데이터베이스에서 레지스트리를 초기화하고, 정책 업데이트는 레지스트리가 이미 초기화된 경우 이를 재동기화해요.

설정 (Configuration)

TOOL_POLICY_CACHE_TTL_SECONDS 는 기본값이 60 인 환경 변수예요. 설정 참조에서는 Tool Policy Guardrail 결과를 캐싱하는 TTL(초)로 설명해요.

export TOOL_POLICY_CACHE_TTL_SECONDS=60

전체 환경 변수 참조는 프록시 설정 안내 를 확인하세요.

발견 동작 (Discovery behavior)

도구는 요청이 완료된 후, 지출을 기록하는 것과 동일한 백그라운드 flush의 일부로 비동기적으로 등록돼요. 그래서 도구가 레지스트리에 나타나는 데 몇 초 걸릴 수 있어요. 도구 이름은 MCP 도구 호출 메타데이터, OpenAI 형식 요청의 tools , Anthropic Messages 요청의 tools , 그리고 응답 도구 호출에서 가져와요. 도구 상세 페이지의 사용 로그에는 모델이 실제로 그 도구를 호출한 요청만 포함돼요.

더 알아보기 (Learn more)

• 도구 권한 Guardrail (Tool Permission Guardrail)
• Guardrails
• 프록시 설정 안내 (Proxy config settings)