Ferramentas de servidor

Esta página cobre a mecânica compartilhada de ferramentas executadas pelo servidor: o bloco server_tool_use, continuação pause_turn, considerações de ZDR e filtragem de domínio. Para ferramentas individuais, consulte a referência de ferramentas.

O bloco server_tool_use

O bloco server_tool_use aparece na resposta do Claude quando uma ferramenta executada pelo servidor é executada. Seu campo id usa o prefixo srvtoolu_ para distingui-lo das chamadas de ferramentas do cliente:

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

A API executa a ferramenta internamente. Você vê a chamada e seu resultado na resposta, mas não lida com a execução. Diferentemente dos blocos tool_use do cliente, você não precisa responder com um tool_result. O bloco de resultado aparece imediatamente após o bloco server_tool_use no mesmo turno do assistente.

O loop do lado do servidor e pause_turn

Ao usar ferramentas de servidor como busca na web, a API pode retornar um motivo de parada pause_turn, indicando que a API pausou um turno de longa duração.

Aqui está como lidar com o motivo de parada pause_turn:

# Solicitação inicial com busca na web
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}],
)

# Verifique se a resposta tem motivo de parada pause_turn
if response.stop_reason == "pause_turn":
    # Continue a conversa com o conteúdo pausado
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Envie a solicitação de continuação
    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)

Ao lidar com pause_turn:

• Continue a conversa: Passe a resposta pausada como está em uma solicitação subsequente para permitir que Claude continue seu turno
• Modifique se necessário: Você pode opcionalmente modificar o conteúdo antes de continuar se quiser interromper ou redirecionar a conversa
• Preserve o estado da ferramenta: Inclua as mesmas ferramentas na solicitação de continuação para manter a funcionalidade

ZDR e allowed_callers

As versões básicas de busca na web (web_search_20250305) e busca na web (web_fetch_20250910) são elegíveis para Zero Data Retention (ZDR).

As versões _20260209 com filtragem dinâmica não são elegíveis para ZDR por padrão porque a filtragem dinâmica depende da execução de código internamente.

Para usar uma ferramenta de servidor _20260209 com ZDR, desabilite a filtragem dinâmica definindo "allowed_callers": ["direct"] na ferramenta:

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

Isso restringe a ferramenta apenas à invocação direta, contornando a etapa de execução de código interno.

Filtragem de domínio

Ferramentas de servidor que acessam a web aceitam parâmetros allowed_domains e blocked_domains para controlar quais domínios Claude pode alcançar.

Ao usar filtros de domínio:

• Os domínios não devem incluir o esquema HTTP/HTTPS (use example.com em vez de https://example.com)
• Subdomínios são incluídos automaticamente (example.com cobre docs.example.com)
• Subdomínios específicos restringem os resultados apenas a esse subdomínio (docs.example.com retorna apenas resultados desse subdomínio, não de example.com ou api.example.com)
• Subcaminhos são suportados e correspondem a qualquer coisa após o caminho (example.com/blog corresponde a example.com/blog/post-1)
• Você pode usar allowed_domains ou blocked_domains, mas não ambos na mesma solicitação

Suporte a caracteres curinga:

• Apenas um caractere curinga (*) é permitido por entrada de domínio, e deve aparecer após a parte do domínio (no caminho)
• Válido: example.com/*, example.com/*/articles
• Inválido: *.example.com, ex*.com, example.com/*/news/*

Formatos de domínio inválidos retornam um erro de ferramenta invalid_tool_input.

Filtragem dinâmica com execução de código

As versões _20260209 de busca na web e busca na web usam execução de código internamente para aplicar filtros dinâmicos contra resultados de busca.

Transmissão de eventos de ferramentas de servidor

Eventos de ferramentas de servidor são transmitidos como parte do fluxo SSE normal. O bloco server_tool_use e seu resultado chegam como eventos content_block_start e content_block_delta, da mesma forma que texto e chamadas de ferramentas do cliente são transmitidos.

Consulte Streaming para a referência completa de eventos. Páginas de ferramentas individuais documentam nomes de eventos específicos da ferramenta onde diferem.

Solicitações em lote

Todas as ferramentas de servidor suportam processamento em lote. Consulte Processamento em lote.

Próximas etapas