Ferramenta de busca na web

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

A versão mais recente da ferramenta de busca na web (web_search_20260209) suporta filtragem dinâmica com Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6. Claude pode escrever e executar código para filtrar resultados de busca antes que eles cheguem à janela de contexto, mantendo apenas informações relevantes e descartando o resto. Isso leva a respostas mais precisas enquanto reduz o consumo de tokens. A versão anterior da ferramenta (web_search_20250305) permanece disponível sem filtragem dinâmica.

Para elegibilidade de Retenção Zero de Dados e a solução alternativa allowed_callers, consulte Ferramentas de servidor.

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

Como a busca na web funciona

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

1. Claude decide quando fazer a busca com base no prompt.
2. A API executa as buscas e fornece os resultados ao Claude. Este processo pode se repetir várias vezes durante uma única solicitação.
3. No final de seu turno, Claude fornece uma resposta final com fontes citadas.

Filtragem dinâmica

A busca na web é uma tarefa intensiva em tokens. Com a busca na web básica, Claude precisa extrair resultados de busca para o contexto, buscar HTML completo de vários sites e raciocinar sobre tudo antes de chegar a uma resposta. Frequentemente, muito desse conteúdo é irrelevante, o que pode degradar a qualidade da resposta.

Com a versão da ferramenta web_search_20260209, Claude pode escrever e executar código para pós-processar resultados de consulta. Em vez de raciocinar sobre arquivos HTML completos, Claude filtra dinamicamente os resultados de busca antes de carregá-los no contexto, mantendo apenas o que é relevante e descartando o resto.

A filtragem dinâmica é particularmente eficaz para:

• Pesquisar através de documentação técnica
• Revisão de literatura e verificação de citações
• Pesquisa técnica
• Fundamentação e verificação de resposta

Para habilitar a filtragem dinâmica, use a versão da ferramenta web_search_20260209:

Como usar a busca na web

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

Definição da ferramenta

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

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

  // Opcional: Limitar o número de buscas por solicitação
  "max_uses": 5,

  // Opcional: Incluir apenas resultados desses domínios
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Opcional: Nunca incluir resultados desses domínios
  "blocked_domains": ["untrustedsource.com"],

  // Opcional: Localizar resultados de busca
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

Máximo de usos

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

Filtragem de domínio

Para filtragem de domínio com allowed_domains e blocked_domains, consulte Ferramentas de servidor.

Localização

O parâmetro user_location permite que você localize resultados de busca com base na localização de um usuário.

• type: O tipo de localização (deve ser approximate)
• city: O nome da cidade
• region: A região ou estado
• country: O país
• timezone: O ID de fuso horário IANA.

Resposta

Aqui está um exemplo de estrutura de resposta:

{
  "role": "assistant",
  "content": [
    // 1. Decisão do Claude de fazer a busca
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. A consulta de busca usada
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Resultados da busca
    {
      "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. Resposta do Claude com citações
    {
      "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"
}

Resultados da busca

Os resultados da 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 deve ser passado novamente em conversas multi-turno para citações

Citações

As citações estão sempre habilitadas para 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 novamente para conversas multi-turno.
• cited_text: Até 150 caracteres do conteúdo citado

Os campos de citação de 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 no corpo da resposta usando a seguinte estrutura:

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

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

• too_many_requests: Limite de taxa excedido
• invalid_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: Consulta excede o comprimento máximo
• unavailable: Um erro interno ocorreu

Motivo de parada pause_turn

Para continuar após um motivo de parada pause_turn, consulte 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": ""}}

// Decisão do Claude de fazer a busca

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

// Consulta de busca transmitida
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Pausa enquanto a busca é executada

// Resultados da busca transmitidos
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"}]}}

// Resposta do Claude com citações (omitida neste exemplo)

Solicitações em lote

Você pode incluir a ferramenta de busca na web na API de Lotes de Mensagens. Chamadas de ferramentas de busca na web através da API de Lotes de Mensagens têm o mesmo preço que aquelas em solicitações regulares da API de Mensagens.

Uso e preços

Web search usage is charged in addition to token usage:

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

Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

Próximas etapas