Ferramentas de servidor

As ferramentas executadas no servidor compartilham estes mecanismos: o bloco server_tool_use, a continuação com pause_turn, turnos que misturam ferramentas de servidor e de cliente, a elegibilidade para "Zero Data Retention" (retenção zero de dados), ou ZDR, e a "domain filtering" (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 de Claude quando uma ferramenta executada no servidor é executada. Seu campo id usa o prefixo srvtoolu_ para diferenciá-lo das 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 cuida da 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 a pesquisa na web) vem depois do bloco server_tool_use no mesmo turno do assistente, pareado por tool_use_id. Se Claude chamar uma das 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 na sua próxima solicitação.

O loop no servidor e pause_turn

Ao usar ferramentas de servidor, como a pesquisa na web, a API executa as chamadas de ferramentas em um "agentic loop" (loop agêntico) no servidor. Em um turno de longa duração, a API pode pausar esse loop e retornar o motivo de parada pause_turn.

Veja como lidar com o motivo de parada pause_turn:

client = anthropic.Anthropic()

# Requisição inicial com pesquisa na web
response = client.messages.create(
    model="claude-opus-5-5",
    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 o 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-5-5",
        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: Envie a resposta pausada de volta sem alterações em uma solicitação subsequente para permitir que Claude continue seu turno.
• Preserve o estado das ferramentas: Inclua as mesmas ferramentas na solicitaçã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 ser pausado novamente. Verifique o stop_reason em cada resposta e continue até obter um motivo de parada diferente, limitando o número de continuações como você faria em qualquer loop de novas tentativas.

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

Misturando ferramentas de servidor e ferramentas de cliente em um turno

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 o 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á nenhum outro marcador. Detecte esse estado procurando 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 concluídas e não precisam de nada da sua parte.

{
  "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 solicitação de retomada que não define mais a ferramenta de servidor pendente 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 (no caso de execução de código pausada, retoma-a) e então permite que Claude continue. Para uma ferramenta de servidor que 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 por 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 pela posição: nesse fluxo, eles chegam em duas respostas diferentes, e o bloco server_tool_use não é repetido na segunda. Nas solicitações posteriores, mantenha toda a troca no seu array messages, em ordem: a primeira resposta como uma mensagem assistant, a mensagem de usuário com tool_result e, em seguida, a próxima resposta como outra mensagem assistant, da mesma forma que você acumula qualquer outra troca de uso de ferramentas.

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 sem alterações. Uma resposta que deixa um bloco tool_use de cliente aguardando por você nunca tem stop_reason igual a pause_turn: quando Claude para para chamar suas ferramentas, o 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 solicitação.

O exemplo a seguir habilita o 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 terminou; o 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 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 nenhum bloco tool_result de cliente da sua parte: seus blocos de resultado normalmente já estão presentes, e um turno que retorna suspenso, como uma resposta pause_turn, é reenviado sem alterações.

ZDR e allowed_callers

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

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

Para usar uma ferramenta de servidor _20260209 ou posterior com ZDR, desative 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 por 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 usam por padrão apenas o chamador de execução de código; as versões anteriores usam ["direct"] por padrão. Em modelos que não oferecem suporte à chamada programática de ferramentas, essas versões exigem allowed_callers: ["direct"]; sem isso, a API retorna um erro de validação que pede para defini-lo.

Filtragem de domínio

As ferramentas de servidor que acessam a web aceitam os parâmetros allowed_domains e blocked_domains para controlar quais domínios 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:

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

Suporte a curingas:

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

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

O Claude Managed Agents usa os mesmos campos allowed_domains e blocked_domains nas entradas web_search e web_fetch do conjunto de ferramentas do agente. No Managed Agents, cada lista contém no máximo 64 entradas, os domínios listados para web_fetch não podem incluir um caminho, e campos específicos das ferramentas da Messages API, como max_uses, citations e cache_control, não estão disponíveis. Consulte Restringir domínios da pesquisa na web e do web fetch para ver as regras completas.

As configurações de pesquisa na web e de web fetch no nível da organização no Claude Console se aplicam apenas às solicitações da Messages API; elas não se aplicam às sessões do Managed Agents, que usam apenas as listas por ferramenta no conjunto de ferramentas do agente.

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

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

Eventos de streaming de ferramentas de servidor

Os eventos de ferramentas de servidor são transmitidos como parte do fluxo normal de "server-sent events" (eventos enviados pelo servidor), ou SSE. Um bloco server_tool_use que 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 ver a referência completa de eventos. As páginas de cada ferramenta documentam os nomes de eventos específicos da ferramenta quando eles diferem.

Solicitações em lote

Todas as ferramentas de servidor oferecem suporte a "batch processing" (processamento em lote). Em um lote, o loop agêntico é executado da mesma forma que nas solicitações síncronas, com um limite maior de iterações por turno. Se o loop atingir esse limite, a resposta termina com stop_reason: "pause_turn"; você pode continuá-la enviando uma solicitação de acompanhamento com o conteúdo retornado. Consulte Ferramentas de servidor e o loop agêntico para obter 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 em muitos arquivos.

Próximos passos