Ferramenta de busca na web

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

Com web_search_20260209 e versões posteriores, 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), mantendo apenas informações relevantes. A filtragem dinâmica está disponível com Claude Fable 5, Claude Opus 4.8, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6.

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 de Zero Data Retention da busca na web 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. 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 do seu turno, Claude fornece uma resposta final com fontes citadas.



Quando Claude busca

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

• Eventos recentes, notícias ou anúncios
• 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

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 através do seu prompt do sistema: você pode encorajar Claude a buscar com mais frequência ou a preferir responder diretamente. Para uma restrição rígida, use max_uses para limitar o número de buscas para 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, Claude em vez disso escreve e executa código que filtra os resultados primeiro, de modo que apenas 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 para 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 informando que você deve defini-la.

Os exemplos a seguir usam web_search_20260318:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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 Claude chama a busca na web diretamente ou a partir da execução de código. 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 Claude tentar mais buscas do que o permitido, o web_search_tool_result é 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 consultas sensíveis à latência, max_uses: 3 limita o custo e raramente trunca. Para agentes de pesquisa, defina max_uses entre 15 e 20 ou omita-o completamente.



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 um esquema.

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



Localização

O parâmetro user_location permite que você localize 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.



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 esses pares aninhados de blocos server_tool_use e de resultado da resposta, 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 na íntegra 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 através 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 fez.



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 passar 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 passada 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 API do Claude 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 um 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 é muito grande, normalmente por causa de uma lista longa de filtros de domínio
• unavailable: Ocorreu um erro interno



Razão 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 Claude chamar a busca na web e uma das 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 das ferramentas 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 Ferramentas de servidor.



Cache de prompt

Para fazer cache de 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 API de Lotes de Mensagens. As chamadas da ferramenta de busca na web através da API de Lotes de Mensagens têm o mesmo preço daquelas em requisições regulares da API de Mensagens.

Para proteger a capacidade compartilhada, a API de Lotes limita as requisições de busca na web por organização, então 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 Limits 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 API do Claude por US$ 10 por 1.000 pesquisas, além dos custos padrão de tokens para conteúdo gerado por 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, ela não será cobrada.



Próximos passos