Ferramentas de servidor

As ferramentas executadas no servidor compartilham estas mecânicas: o bloco server_tool_use, a continuação de pause_turn, turnos que misturam ferramentas de servidor e cliente, elegibilidade para "Zero Data Retention" (retenção zero de dados), ou ZDR, e filtragem de domínios. 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 no servidor é acionada. Seu campo id usa o prefixo srvtoolu_ para distingui-lo de chamadas de ferramentas de 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 de cliente, você não precisa responder com um tool_result. O bloco de resultado da ferramenta (por exemplo, web_search_tool_result para busca na web) segue o bloco server_tool_use no mesmo turno do assistente, pareado por tool_use_id. Se o Claude chamar uma de suas ferramentas de cliente ao mesmo tempo, o bloco server_tool_use aparece sem seu resultado, e a resposta termina com stop_reason: "tool_use". A API executa a ferramenta quando você retorna os blocos tool_result de cliente em sua próxima requisição.



O loop do lado do servidor e pause_turn

Ao usar ferramentas de servidor como busca na web, a API executa chamadas de ferramentas em um loop agêntico do lado do servidor. Em um turno de longa duração, a API pode pausar esse loop e retornar um stop reason pause_turn.

Veja como lidar com o stop reason pause_turn:

client = anthropic.Anthropic()

# Requisição inicial com busca na web
response = client.messages.create(
    model="claude-opus-4-8",
    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}],
)

# Verifica se a resposta tem stop_reason pause_turn
if response.stop_reason == "pause_turn":
    # Continua 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},
    ]

    # Envia a requisição de continuação
    continuation = client.messages.create(
        model="claude-opus-4-8",
        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 de volta como está em uma requisição subsequente para permitir que o Claude continue seu turno.
• Preserve o estado da ferramenta: Inclua as mesmas ferramentas na requisição de continuação. Um turno pausado pode terminar com um bloco server_tool_use cuja ferramenta ainda não foi executada, e a API retorna um erro de validação se essa ferramenta estiver ausente na continuação.
• Repita conforme necessário: Um turno continuado pode pausar novamente. Verifique stop_reason em cada resposta e continue até obter um stop reason diferente, limitando o número de continuações como faria com qualquer loop de retry.

Para os outros valores de stop_reason e padrões gerais de tratamento, consulte Stop reasons e fallback.



Misturando ferramentas de servidor e ferramentas de cliente em um turno

O Claude pode chamar uma ferramenta de servidor e uma ferramenta de cliente no mesmo grupo de chamadas de ferramentas paralelas, por exemplo, web_fetch junto com uma ferramenta definida pelo usuário. Uma ferramenta de cliente é qualquer ferramenta que seu código executa e que produz um bloco tool_use, seja ela definida pelo usuário ou uma ferramenta de cliente com esquema da Anthropic, como a ferramenta Bash. Quando isso acontece, a API não executa a ferramenta de servidor. Ela retorna imediatamente para que você possa executar a ferramenta de cliente primeiro:

• stop_reason é "tool_use", não "pause_turn".
• content contém o bloco server_tool_use e o bloco tool_use de cliente, mas nenhum bloco de resultado para a ferramenta de servidor: essa chamada não foi concluída.
• Não há outro marcador. Detecte o estado procurando por um bloco server_tool_use cujo id não tenha um bloco de resultado correspondente na resposta. Um bloco mcp_tool_use do conector MCP se comporta da mesma forma. Chamadas de ferramentas de servidor que já têm seu bloco de resultado na mesma resposta estão completas e não precisam de nada de você.

{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "text",
      "text": "I'll fetch the article and check your system at the same time."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "name": "web_fetch",
      "input": { "url": "https://example.com/article" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "name": "run_command",
      "input": { "command": "uname -a" }
    }
  ]
}

Para continuar o turno, execute as ferramentas de cliente e envie uma mensagem de usuário cujo conteúdo seja apenas os blocos tool_result, um para cada bloco tool_use naquela resposta. Mantenha o mesmo array tools: uma requisição de retomada que não define mais a ferramenta de servidor em espera falha com um erro 400 cuja mensagem termina com but no `web_fetch` tool was provided.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
    }
  ]
}

A API anexa seus resultados ao turno do assistente ainda aberto, executa a ferramenta de servidor adiada (para execução de código pausada, a retoma) e então permite que o Claude continue. Para uma ferramenta de servidor que o Claude chamou diretamente, a próxima resposta começa com o bloco de resultado que responde ao id do server_tool_use da resposta anterior, seguido pelo conteúdo recém-gerado e um novo stop_reason:

{
  "stop_reason": "end_turn",
  "content": [
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          }
        }
      }
    },
    {
      "type": "text",
      "text": "The article argues that... and your machine is running Linux..."
    }
  ]
}

Um bloco server_tool_use e seu bloco de resultado são pareados por tool_use_id, não por posição: neste fluxo eles chegam em duas respostas diferentes, e o bloco server_tool_use não é repetido na segunda. Em requisições posteriores, mantenha toda a troca em seu array messages em ordem: a primeira resposta como uma mensagem assistant, a mensagem de usuário tool_result e então a próxima resposta como outra mensagem assistant, da mesma forma que você acumula qualquer outra troca de uso de ferramentas.

`web_fetch` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_fetch_tool_result` block

`tool_use` ids were found without `tool_result` blocks immediately after: toolu_01PjgRJLbXrXEMZwDNYLnBqk. Each `tool_use` block must have a corresponding `tool_result` block in the next message.

Como isso difere de pause_turn: Uma resposta pause_turn também pode terminar com um bloco server_tool_use que não foi executado, mas ela nunca deixa um bloco tool_use de cliente aguardando por você, então você a continua reenviando o conteúdo do assistente como está. Uma resposta que deixa um bloco tool_use de cliente aguardando por você nunca tem um stop_reason de pause_turn: quando o Claude para para chamar suas ferramentas, stop_reason é tool_use, e você a continua enviando os blocos tool_result de cliente em vez de reenviar a resposta. Em ambos os casos, a API executa a ferramenta de servidor pendente no início da próxima requisição.

O exemplo a seguir habilita web fetch junto com uma ferramenta run_command definida pelo usuário e lida com a resposta mista:

client = anthropic.Anthropic()

tools = [
    {"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5},
    {
        "name": "run_command",
        "description": "Run a shell command on this computer and return its output.",
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "The command to run"}
            },
            "required": ["command"],
        },
    },
]
messages = [
    {
        "role": "user",
        "content": "Summarize https://example.com/article and run uname -a to tell me what system this is on.",
    }
]

response = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024, tools=tools, messages=messages
)

tool_results = [
    {
        "type": "tool_result",
        "tool_use_id": block.id,
        # Execute sua ferramenta aqui. Este exemplo retorna uma string fixa.
        "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux",
    }
    for block in response.content
    if block.type == "tool_use"
]

if response.stop_reason == "tool_use" and tool_results:
    # Um bloco server_tool_use sem bloco de resultado nesta resposta não está concluído; seu resultado chega em uma resposta posterior.
    # Envie de volta apenas os blocos tool_result do cliente, com as mesmas ferramentas.
    continuation = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        tools=tools,
        messages=[
            *messages,
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": tool_results},
        ],
    )
    # Se um web_fetch foi adiado, ele é executado nesta requisição e seu
    # web_fetch_tool_result é o primeiro bloco de continuation.content.
    print(continuation)
else:
    print(response)

Este código também está correto quando o Claude não mistura os dois tipos de chamada. Um turno com apenas blocos tool_use de cliente segue o mesmo caminho de continuação, e um turno com apenas chamadas de ferramentas de servidor não precisa de blocos tool_result de cliente de você: seus blocos de resultado normalmente já estão presentes, e um que volta suspenso, como uma resposta pause_turn, é reenviado como está.



ZDR e allowed_callers

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

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

Para usar uma ferramenta de servidor _20260209 ou posterior 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, ignorando a etapa interna de execução de código.

allowed_callers controla como uma ferramenta pode ser invocada: diretamente pelo Claude ("direct"), de dentro de um contêiner de execução de código (por exemplo, "code_execution_20260120"), ou ambos. As versões _20260209 das ferramentas web têm como padrão apenas o caller de execução de código; versões anteriores têm como padrão ["direct"]. Em modelos que não suportam chamada programática de ferramentas, essas versões exigem allowed_callers: ["direct"]; sem isso, a API retorna um erro de validação que diz para defini-lo.



Filtragem de domínios

Ferramentas de servidor que acessam a web aceitam os parâmetros allowed_domains e blocked_domains para controlar quais domínios o Claude pode acessar. Ambos são campos no objeto da ferramenta:

{
  "type": "web_search_20250305",
  "name": "web_search",
  "allowed_domains": ["example.com", "docs.python.org"]
}

Ao usar filtros de domínio:

• 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 àquele subdomínio (docs.example.com retorna apenas resultados desse subdomínio, não de example.com ou api.example.com).
• Subcaminhos são suportados para busca na web e correspondem a qualquer coisa após o caminho (example.com/blog corresponde a example.com/blog/post-1).
• Web fetch faz correspondência apenas no domínio: uma entrada que inclui um caminho nunca corresponde a uma URL de web fetch.
• Você pode usar allowed_domains ou blocked_domains, mas não ambos na mesma requisição.

Suporte a curingas:

• Curingas (*) não são permitidos no próprio domínio, apenas no caminho após ele.
• Válido: example.com/*, example.com/*/articles
• Inválido: *.example.com, ex*.com

Formatos de domínio inválidos são rejeitados no momento da requisição com um invalid_request_error 400.



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

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



Streaming de eventos de ferramentas de servidor

Eventos de ferramentas de servidor são transmitidos via streaming como parte do fluxo normal de "server-sent events" (eventos enviados pelo servidor), ou SSE. Um bloco server_tool_use que o Claude chama diretamente é transmitido como um bloco tool_use de cliente: um evento content_block_start seguido por eventos input_json_delta. O bloco de resultado chega completo em um único evento content_block_start, sem deltas.

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



Requisições em lote

Todas as ferramentas de servidor suportam processamento em lote. Em um lote, o loop agêntico é executado exatamente como em requisições síncronas, com um limite de iteração por turno mais alto. Se o loop atingir esse limite, a resposta termina com stop_reason: "pause_turn"; você pode continuá-la enviando uma requisição de acompanhamento com o conteúdo retornado. Consulte Ferramentas de servidor e o loop agêntico para detalhes.

Cargas de trabalho comuns em lote incluem enriquecer um conjunto de dados com informações da web, verificar um grande conjunto de documentos em relação a fontes atuais e executar código de análise sobre muitos arquivos.



Próximos passos