Ferramenta de busca na web

A ferramenta de busca na web ("web search tool") dá ao Claude acesso direto a conteúdo da web em tempo real, permitindo que ele responda a perguntas com informações atualizadas além de sua data de corte de conhecimento. A resposta inclui citações das fontes extraídas dos resultados de busca.

Com web_search_20260209 e versões posteriores, o Claude pode escrever e executar código que filtra os resultados de busca antes que eles cheguem à "context window" (janela de contexto) (filtragem dinâmica, ou "dynamic filtering"), mantendo apenas as informações relevantes. A filtragem dinâmica está disponível com os modelos Claude 4.6 e posteriores e com o Claude Mythos Preview.

Três versões da ferramenta de busca na web estão disponíveis:

• web_search_20250305: busca na web básica
• web_search_20260209: adiciona filtragem dinâmica
• web_search_20260318: adiciona controle de inclusão na resposta para fluxos de trabalho agênticos

Os exemplos nesta página usam web_search_20250305 para busca básica e web_search_20260318 para filtragem dinâmica.

Para a elegibilidade da busca na web para Zero Data Retention e a configuração relacionada de allowed_callers, consulte Ferramentas de servidor.

Para suporte de modelos, consulte a Referência de ferramentas.

Como a busca na web funciona

Quando você adiciona a ferramenta de busca na web à sua requisição de API:

1. O Claude determina quando buscar com base no prompt.
2. A API executa as buscas e fornece os resultados ao Claude. Esse processo pode se repetir várias vezes ao longo de uma única requisição.
3. Ao final de seu turno, o Claude fornece uma resposta final com fontes citadas.

Quando o Claude busca

O Claude busca quando a requisição depende de informações que são atuais, mutáveis ou que estão fora de seus dados de treinamento:

• Eventos, notícias ou anúncios recentes
• Preços, taxas, placares ou estatísticas atuais
• Informações sobre organizações, pessoas ou produtos específicos que podem ter mudado
• Solicitações explícitas para buscar ou pesquisar algo

O Claude responde diretamente sem buscar quando a requisição se baseia em conhecimento estável:

• Fatos estabelecidos, matemática, fundamentos de ciência ou conceitos de programação
• Escrita criativa ou brainstorming
• Análise de conteúdo já fornecido na conversa
• Turnos conversacionais e saudações

O acionamento é direcionável por meio do seu prompt do sistema: você pode incentivar o Claude a buscar com mais prontidão ou a preferir responder diretamente. Para uma restrição rígida, use max_uses para limitar o número de buscas em cada requisição.

Filtragem dinâmica

Com a busca na web básica, todo resultado de busca é carregado na janela de contexto do Claude, e grande parte desse conteúdo pode ser irrelevante para a requisição. Com web_search_20260209 ou posterior, o Claude, em vez disso, escreve e executa código que filtra os resultados primeiro, de modo que apenas o conteúdo relevante chegue à janela de contexto. Isso reduz o uso de tokens em requisições com muitas buscas.

A filtragem dinâmica executa a busca na web de dentro da execução de código: em web_search_20260209 e posteriores, o campo allowed_callers da ferramenta tem como padrão ["code_execution_20260120"], e quando a filtragem dinâmica é executada, a API provisiona automaticamente a execução de código necessária para a requisição. Você não precisa adicionar a ferramenta de execução de código a tools por conta própria. Não há cobranças adicionais por chamadas de execução de código feitas dessa forma além dos custos padrão de tokens.

Para chamar a busca na web diretamente, sem filtragem dinâmica, defina allowed_callers: ["direct"]. Modelos que não suportam chamada programática de ferramentas exigem essa configuração. Sem ela, a API retorna um erro 400 que informa que você deve defini-la.

Os exemplos a seguir usam web_search_20260318:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
        }
    ],
    tools=[{"type": "web_search_20260318", "name": "web_search"}],
)
print(response)

Como usar a busca na web

Essas configurações em nível de organização no Claude Console aplicam-se apenas a requisições da Messages API. Sessões do Claude Managed Agents usam apenas as listas allowed_domains e blocked_domains por ferramenta no conjunto de ferramentas do agente; consulte Restringir domínios de busca na web e web fetch.

Forneça a ferramenta de busca na web em sua requisição de API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)

Definição da ferramenta

A ferramenta de busca na web suporta os seguintes parâmetros:

{
  "type": "web_search_20250305",
  "name": "web_search",

  // Optional: Limit the number of searches per request
  "max_uses": 5,

  // Optional: Only include results from these domains.
  // Use allowed_domains or blocked_domains, not both.
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optional: Never include results from these domains
  "blocked_domains": ["untrustedsource.com"],

  // Optional: Localize search results
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

Todas as versões da ferramenta de busca na web aceitam allowed_callers, que controla se o Claude chama a busca na web diretamente ou a partir da execução de código por meio da filtragem dinâmica. Em web_search_20260209 e posteriores, o padrão é ["code_execution_20260120"] em vez de ["direct"]. Consulte Ferramentas de servidor para saber como configurá-lo. web_search_20260318 e posteriores também aceitam response_inclusion.

Máximo de usos

O parâmetro max_uses limita o número de buscas realizadas. Se o Claude tentar mais buscas do que o permitido, o web_search_tool_result será um erro com o código de erro max_uses_exceeded.

Consultas factuais simples normalmente usam de 1 a 3 buscas; pesquisas comparativas ou com múltiplas entidades podem usar 10 ou mais. Para orientação sobre como escolher um valor, consulte Ferramentas de servidor.

Filtragem de domínios

Forneça allowed_domains ou blocked_domains, não ambos. Se uma requisição incluir ambos, a API retorna um erro 400. As entradas são domínios simples com um caminho opcional, por exemplo example.com ou example.com/blog, sem esquema.

Para as regras completas de filtragem de domínios, consulte Filtragem de domínios no guia de Ferramentas de servidor.

No Claude Managed Agents, defina esses campos na entrada web_search do conjunto de ferramentas do agente; consulte Restringir domínios de busca na web e web fetch.

Localização

O parâmetro user_location permite localizar os resultados de busca com base na localização de um usuário. Forneça pelo menos um entre city, region, country ou timezone.

• type: O tipo de localização (deve ser approximate)
• city: O nome da cidade
• region: A região ou estado
• country: O código de país de duas letras ISO 3166-1 alpha-2. A API rejeita códigos de país não suportados com um erro 400.
• timezone: O ID de fuso horário IANA.

No Claude Managed Agents, a entrada web_search do conjunto de ferramentas do agente aceita um objeto user_location com os mesmos campos. A API rejeita um código country não suportado com um erro 400 quando você cria ou atualiza o agente, ou quando cria ou atualiza uma sessão que fornece a configuração. Consulte Restringir domínios de busca na web e web fetch.

Inclusão na resposta

O parâmetro response_inclusion controla como os blocos de resultado de busca aparecem na resposta da API quando o resultado foi consumido por uma chamada de execução de código concluída no mesmo turno. Defina "response_inclusion": "excluded" para remover completamente da resposta esses pares aninhados de server_tool_use e bloco de resultado, reduzindo os custos de tokens de saída para fluxos de trabalho agênticos que não precisam ecoar o conteúdo bruto da busca de volta ao cliente. O padrão é "full". Resultados de chamadas diretas, ou de chamadas de execução de código que pausaram antes de concluir, são sempre retornados integralmente para que possam ser enviados de volta no próximo turno.

{
  "tools": [
    {
      "type": "web_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}

Resposta

Aqui está um exemplo de estrutura de resposta:

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to search
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. The search query used
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Search results
    {
      "type": "web_search_tool_result",
      "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "content": [
        {
          "type": "web_search_result",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
          "page_age": "April 30, 2025"
        }
      ]
    },
    {
      "text": "Based on the search results, ",
      "type": "text"
    },
    // 4. Claude's response with citations
    {
      "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
      "type": "text",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
          "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 6039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_search_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

Este exemplo mostra uma busca direta. Quando uma busca é executada por meio da filtragem dinâmica, a resposta também contém os blocos de resultado da ferramenta de execução de código, e cada par aninhado de server_tool_use e web_search_tool_result carrega um campo caller identificando a chamada de execução de código que o originou.

Resultados de busca

Os resultados de busca incluem:

• url: A URL da página de origem
• title: O título da página de origem
• page_age: Quando o site foi atualizado pela última vez
• encrypted_content: Conteúdo criptografado que você deve enviar de volta em conversas de múltiplos turnos

Para continuar uma conversa que contém resultados de busca, envie os blocos de conteúdo do assistente de volta exatamente como você os recebeu, incluindo o encrypted_content de cada resultado. A API descriptografa esse conteúdo em turnos posteriores para restaurar os resultados de busca no contexto do Claude. Se encrypted_content estiver ausente ou modificado, a requisição falha com um erro de validação 400.

Citações

As citações estão sempre habilitadas para a busca na web, e cada web_search_result_location inclui:

• url: A URL da fonte citada
• title: O título da fonte citada
• encrypted_index: Uma referência que deve ser enviada de volta em conversas de múltiplos turnos
• cited_text: Até 150 caracteres do conteúdo citado

Os campos de citação da busca na web cited_text, title e url não contam para o uso de tokens de entrada ou saída.

Erros

Quando a ferramenta de busca na web encontra um erro (como atingir limites de taxa), a Claude API ainda retorna uma resposta 200 (sucesso). O erro é representado dentro do corpo da resposta usando a seguinte estrutura:

{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

Em caso de erro, content é um único objeto de erro em vez de uma lista de blocos de resultado. Uma busca que é bem-sucedida mas não encontra resultados retorna uma lista content vazia, não um erro.

Estes são os códigos de erro possíveis:

• too_many_requests: Limite de taxa excedido
• invalid_tool_input: Parâmetro de consulta de busca inválido
• max_uses_exceeded: Máximo de usos da ferramenta de busca na web excedido
• query_too_long: A consulta excede o comprimento máximo
• request_too_large: A requisição de busca é grande demais, normalmente devido a uma longa lista de filtros de domínio
• unavailable: Ocorreu um erro interno

Motivo de parada pause_turn

A API pode pausar um turno de busca de longa duração e retornar stop_reason: "pause_turn". Para continuar, envie a mensagem do assistente pausada de volta, sem alterações, em uma nova requisição.

Se o Claude chamar a busca na web e uma de suas ferramentas de cliente no mesmo grupo de chamadas de ferramentas paralelas, a API retorna stop_reason: "tool_use" em vez disso e ainda não executa a busca. Para continuar, retorne os resultados da ferramenta de cliente, e a API executa a busca na próxima requisição. Consulte Misturando ferramentas de servidor e ferramentas de cliente em um turno.

Para o loop do lado do servidor e o tratamento de pause_turn, consulte O loop do lado do servidor e pause_turn no guia de Ferramentas de servidor.

Cache de prompt

Para armazenar em cache definições de ferramentas entre turnos, consulte Uso de ferramentas com cache de prompt.

Streaming

Com o streaming habilitado, você receberá eventos de busca como parte do stream. Haverá uma pausa enquanto a busca é executada:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

// Claude's decision to search

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}

// Claude's response with citations (omitted in this example)

Requisições em lote

Você pode incluir a ferramenta de busca na web na Messages Batches API. Chamadas da ferramenta de busca na web por meio da Messages Batches API têm o mesmo preço que aquelas em requisições regulares da Messages API.

Para proteger a capacidade compartilhada, a Batches API limita as requisições de busca na web por organização, portanto lotes grandes com muitas buscas podem levar mais tempo para serem concluídos. Você pode ver o limite de taxa de busca na web da sua organização na página Limites de taxa no Claude Console. Para solicitar um limite maior, entre em contato com a equipe de vendas a partir dessa página.

Uso e preços

O uso da pesquisa na web é cobrado além do uso de tokens:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 6039,
    "cache_read_input_tokens": 7123,
    "cache_creation_input_tokens": 7345,
    "server_tool_use": {
      "web_search_requests": 1
    }
  }
}

A pesquisa na web está disponível na Claude API por $10 por 1.000 pesquisas, mais os custos padrão de tokens para o conteúdo gerado pela pesquisa. Os resultados de pesquisa na web recuperados ao longo de uma conversa são contados como tokens de entrada, tanto nas iterações de pesquisa executadas durante um único turno quanto nos turnos subsequentes da conversa.

Cada pesquisa na web conta como um uso, independentemente do número de resultados retornados. Se ocorrer um erro durante a pesquisa na web, a pesquisa na web não será cobrada.

Próximos passos