Was this page helpful?
이 페이지에서는 서버에서 실행되는 도구의 공유 메커니즘을 다룹니다: server_tool_use 블록, pause_turn 계속, ZDR 고려사항, 도메인 필터링. 개별 도구는 도구 참조를 참조하세요.
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 블록 바로 뒤에 나타납니다.
웹 검색과 같은 서버 도구를 사용할 때 API는 pause_turn 중지 이유를 반환할 수 있으며, 이는 API가 장시간 실행되는 턴을 일시 중지했음을 나타냅니다.
pause_turn 중지 이유를 처리하는 방법은 다음과 같습니다:
pause_turn을 처리할 때:
웹 검색(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 매개변수를 허용합니다.
도메인 필터를 사용할 때:
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과 동일하게 보일 수 있지만 다른 도메인을 나타냅니다.
도메인 허용/차단 목록을 구성할 때:
웹 검색 및 웹 가져오기의 _20260209 버전은 검색 결과에 대해 동적 필터를 적용하기 위해 내부적으로 코드 실행을 사용합니다.
_20260209 버전의 웹 도구와 함께 독립 실행형 code_execution 도구를 포함하면 두 개의 실행 환경이 생성되어 모델을 혼동할 수 있습니다. 하나 또는 다른 하나를 사용하거나 둘 다 동일한 버전으로 고정합니다.
서버 도구 이벤트는 일반 SSE 흐름의 일부로 스트리밍됩니다. server_tool_use 블록과 그 결과는 텍스트 및 클라이언트 도구 호출과 동일한 방식으로 content_block_start 및 content_block_delta 이벤트로 도착합니다.
전체 이벤트 참조는 스트리밍을 참조하세요. 개별 도구 페이지는 도구별 이벤트 이름이 다른 경우 문서화합니다.
모든 서버 도구는 배치 처리를 지원합니다. 배치 처리를 참조하세요.
# 웹 검색을 사용한 초기 요청
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)