서버 도구

이 페이지에서는 서버에서 실행되는 도구의 공유 메커니즘을 다룹니다: server_tool_use 블록, pause_turn 계속, ZDR 고려사항, 도메인 필터링. 개별 도구는 도구 참조를 참조하세요.

server_tool_use 블록

server_tool_use 블록은 서버에서 실행되는 도구가 실행될 때 Claude의 응답에 나타납니다. 해당 id 필드는 srvtoolu_ 접두사를 사용하여 클라이언트 도구 호출과 구별합니다:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01A2B3C4D5E6F7G8H9",
  "name": "web_search",
  "input": { "query": "latest quantum computing breakthroughs" }
}

API는 도구를 내부적으로 실행합니다. 호출과 그 결과를 응답에서 볼 수 있지만 실행을 처리하지는 않습니다. 클라이언트 tool_use 블록과 달리 tool_result로 응답할 필요가 없습니다. 결과 블록은 같은 어시스턴트 턴에서 server_tool_use 블록 바로 뒤에 나타납니다.

서버 측 루프 및 pause_turn

웹 검색과 같은 서버 도구를 사용할 때 API는 pause_turn 중지 이유를 반환할 수 있으며, 이는 API가 장시간 실행되는 턴을 일시 중지했음을 나타냅니다.

pause_turn 중지 이유를 처리하는 방법은 다음과 같습니다:

pause_turn을 처리할 때:

대화 계속: 일시 중지된 응답을 그대로 후속 요청에 전달하여 Claude가 턴을 계속하도록 합니다
필요시 수정: 대화를 중단하거나 리디렉션하려는 경우 계속하기 전에 선택적으로 콘텐츠를 수정할 수 있습니다
도구 상태 유지: 계속 요청에 동일한 도구를 포함하여 기능을 유지합니다

ZDR 및 allowed_callers

웹 검색(web_search_20250305)과 웹 가져오기(web_fetch_20250910)의 기본 버전은 Zero Data Retention (ZDR)에 적합합니다.

동적 필터링이 있는 _20260209 버전은 동적 필터링이 내부적으로 코드 실행에 의존하기 때문에 기본적으로 ZDR에 적합하지 않습니다.

ZDR과 함께 _20260209 서버 도구를 사용하려면 도구에서 "allowed_callers": ["direct"]를 설정하여 동적 필터링을 비활성화합니다:

{
  "type": "web_search_20260209",
  "name": "web_search",
  "allowed_callers": ["direct"]
}

이는 도구를 직접 호출만으로 제한하여 내부 코드 실행 단계를 우회합니다.

웹 가져오기 도구 자체는 ZDR에 적합하지만, 웹사이트 게시자는 Claude가 해당 사이트에서 콘텐츠를 가져올 때 URL에 전달된 모든 매개변수를 보유할 수 있습니다.

도메인 필터링

웹에 접근하는 서버 도구는 Claude가 도달할 수 있는 도메인을 제어하기 위해 allowed_domains 및 blocked_domains 매개변수를 허용합니다.

도메인 필터를 사용할 때:

도메인에는 HTTP/HTTPS 스키마가 포함되지 않아야 합니다 (https://example.com 대신 example.com 사용)
서브도메인이 자동으로 포함됩니다 (example.com은 docs.example.com을 포함)
특정 서브도메인은 결과를 해당 서브도메인만으로 제한합니다 (docs.example.com은 example.com 또는 api.example.com이 아닌 해당 서브도메인의 결과만 반환)
서브경로가 지원되며 경로 뒤의 모든 항목과 일치합니다 (example.com/blog는 example.com/blog/post-1과 일치)
allowed_domains 또는 blocked_domains 중 하나를 사용할 수 있지만 같은 요청에서 둘 다 사용할 수는 없습니다

와일드카드 지원:

도메인 항목당 하나의 와일드카드(*)만 허용되며 도메인 부분 뒤(경로에)에 나타나야 합니다
유효: example.com/*, example.com/*/articles
무효: *.example.com, ex*.com, example.com/*/news/*

잘못된 도메인 형식은 invalid_tool_input 도구 오류를 반환합니다.

요청 수준 도메인 제한은 Console에서 구성된 조직 수준 도메인 제한과 호환되어야 합니다. 요청 수준 도메인은 조직 수준 목록을 재정의하거나 확장할 수 없고 추가로만 제한할 수 있습니다. 요청에 조직 설정과 충돌하는 도메인이 포함된 경우 API는 유효성 검사 오류를 반환합니다.

도메인 이름의 유니코드 문자는 시각적으로 유사한 다양한 스크립트의 문자가 도메인 필터를 우회할 수 있는 동형 공격을 통해 보안 취약점을 만들 수 있습니다. 예를 들어 аmazon.com(키릴 문자 'а' 사용)은 amazon.com과 동일하게 보일 수 있지만 다른 도메인을 나타냅니다.

도메인 허용/차단 목록을 구성할 때:

가능하면 ASCII 전용 도메인 이름을 사용합니다
URL 파서가 유니코드 정규화를 다르게 처리할 수 있음을 고려합니다
잠재적 동형 변형으로 도메인 필터를 테스트합니다
의심스러운 유니코드 문자에 대해 도메인 구성을 정기적으로 감사합니다

코드 실행을 통한 동적 필터링

웹 검색 및 웹 가져오기의 _20260209 버전은 검색 결과에 대해 동적 필터를 적용하기 위해 내부적으로 코드 실행을 사용합니다.

_20260209 버전의 웹 도구와 함께 독립 실행형 code_execution 도구를 포함하면 두 개의 실행 환경이 생성되어 모델을 혼동할 수 있습니다. 하나 또는 다른 하나를 사용하거나 둘 다 동일한 버전으로 고정합니다.

서버 도구 이벤트 스트리밍

서버 도구 이벤트는 일반 SSE 흐름의 일부로 스트리밍됩니다. server_tool_use 블록과 그 결과는 텍스트 및 클라이언트 도구 호출과 동일한 방식으로 content_block_start 및 content_block_delta 이벤트로 도착합니다.

전체 이벤트 참조는 스트리밍을 참조하세요. 개별 도구 페이지는 도구별 이벤트 이름이 다른 경우 문서화합니다.

배치 요청

모든 서버 도구는 배치 처리를 지원합니다. 배치 처리를 참조하세요.

다음 단계

웹 검색

웹을 검색하고 결과를 인용합니다.

웹 가져오기

특정 URL에서 콘텐츠를 검색합니다.

코드 실행

샌드박스 컨테이너에서 Python을 실행합니다.

도구 검색

필요에 따라 도구를 발견하고 로드합니다.

# 웹 검색을 사용한 초기 요청
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        }
    ],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)

# 응답에 pause_turn 중지 이유가 있는지 확인
if response.stop_reason == "pause_turn":
    # 일시 중지된 콘텐츠로 대화 계속
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # 계속 요청 전송
    continuation = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)