콘텐츠로 이동

엄격한 도구 사용 (Strict Tool Use)

도구 정의에 strict: true를 설정하면, 모델의 토큰 샘플링을 스키마-유효한 출력으로 제약해서(이 기법을 문법 제약 샘플링(grammar-constrained sampling)이라고 불러요) Claude의 도구 입력이 반드시 여러분의 JSON Schema를 따르도록 보장합니다. 이 페이지에서는 에이전트에게 strict 모드가 왜 중요한지, 어떻게 켜는지, 어떤 경우에 쓰는지 다룹니다. 지원되는 JSON Schema 부분집합은 JSON Schema 제약 문서를, strict가 아닌 스키마 가이드는 도구 정의 문서를 참고하세요.

Strict 도구 사용은 도구 파라미터를 검증해서, Claude가 올바른 타입의 인수로 여러분의 함수를 호출하도록 합니다. 이런 경우에 엄격한 도구 사용을 써요.

  • 도구 파라미터 검증
  • 에이전틱 워크플로 구축
  • 타입 안전한 함수 호출 보장
  • 중첩 속성을 가진 복잡한 도구 처리

에이전트에게 strict 도구 사용이 중요한 이유

신뢰할 수 있는 에이전틱 시스템을 만들려면 스키마 준수가 보장되어야 합니다. strict 모드가 없으면 Claude가 호환되지 않는 타입(2 대신 "2")을 돌려주거나 필수 필드를 빼먹을 수 있고, 그 결과 함수가 깨지면서 런타임 오류가 나요.

엄격한 도구 사용은 타입 안전한 파라미터를 보장합니다.

  • 함수는 매번 올바른 타입의 인수를 받아요
  • 도구 호출을 검증하고 재시도할 필요가 없어요
  • 대규모에서 일관되게 동작하는 프로덕션급 에이전트가 돼요

예를 들어 예약 시스템이 passengers: int를 필요로 한다고 해볼게요. strict 모드가 없으면 Claude가 passengers: "two"나 passengers: "2"를 줄 수 있지만, strict: true를 켜면 응답에는 항상 passengers: 2가 들어와요.

빠른 시작

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "strict": True,  # Enable strict mode
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'",
                    },
                },
                "required": ["location"],
                "additionalProperties": False,
            },
        }
    ],
)
print(response.content)

응답 형식: response.content[x].input에 검증된 입력을 담은 도구 사용 블록이 옵니다.

{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

보장되는 것들:

  • 도구의 input은 input_schema를 엄격히 따릅니다
  • 도구의 name은 항상 유효합니다 (제공한 도구 또는 서버 도구에서)

어떻게 동작하나요

  1. 도구 스키마 정의하기 — 도구 input_schema를 위한 JSON Schema를 만듭니다. 표준 JSON Schema 형식을 따르되 일부 제약이 있어요 (JSON Schema 제약 참고).
  2. strict: true 추가하기 — 도구 정의의 최상위 속성으로 name, description, input_schema와 함께 "strict": true를 설정합니다.
  3. 도구 호출 처리하기 — Claude가 도구를 사용하면 tool_use 블록의 input 필드는 input_schema를 엄격히 따르고, name은 항상 유효합니다.

컴퓨터 사용과 브라우저 사용 도구셋 항목(computer_toolset_20260801과 browser_toolset_20260801)은 strict: true를 받지 않아요. 둘 중 어느 항목에 이걸 설정한 요청은 거부됩니다.

일반적인 사용 사례

데이터 보존

엄격한 도구 사용은 구조화된 출력과 같은 파이프라인으로 도구 input_schema 정의를 문법으로 컴파일합니다. 도구 스키마는 마지막 사용 이후 최대 24시간 동안 임시로 캐시됩니다. 프롬프트와 응답은 API 응답 이후로 보존되지 않습니다.

엄격한 도구 사용은 HIPAA 적격이지만, 보호 건강 정보(PHI)는 도구 스키마 정의에 포함하면 안 됩니다. API는 컴파일된 스키마를 메시지 콘텐츠와 별도로 캐시하며, 이 캐시된 스키마는 프롬프트와 응답과 같은 PHI 보호를 받지 못해요. input_schema 속성 이름, enum 값, const 값, pattern 정규식에 PHI를 포함하지 마세요. PHI는 HIPAA 보호 아래 있는 메시지 콘텐츠(프롬프트와 응답)에만 나타나야 합니다.

모든 기능에 대한 ZDR 및 HIPAA 적격성은 API 및 데이터 보존 문서를 참고하세요.

다음 단계

  • 특정 URL에서 콘텐츠를 가져와 읽어서, 실시간 웹 콘텐츠를 Claude의 컨텍스트로 가져옵니다.
  • 동일한 문법 제약 샘플링으로 검증된 JSON 응답을 얻습니다.
  • 도구 스키마를 지정하고, 효과적인 설명을 작성하며, Claude가 도구를 호출할 시점을 제어합니다.