서버 도구

이 페이지에서는 서버에서 실행되는 도구의 공유 메커니즘을 다룹니다: 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 중지 이유를 처리하는 방법은 다음과 같습니다:

# 웹 검색을 사용한 초기 요청
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)

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"]
}

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

도메인 필터링

웹에 접근하는 서버 도구는 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 도구 오류를 반환합니다.

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

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

서버 도구 이벤트 스트리밍

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

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

배치 요청

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

다음 단계