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 a perguntas com informações atualizadas além do seu limite de conhecimento. A resposta inclui citações das fontes extraídas dos resultados de busca.

A versão mais recente da ferramenta de busca na web (web_search_20260318) oferece suporte a filtragem dinâmica 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. O 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 restante. Isso leva a respostas mais precisas enquanto reduz o consumo de tokens. A versão web_search_20260318 também adiciona controle de inclusão de resposta para fluxos de trabalho agênticos. As versões anteriores (web_search_20260209 apenas para filtragem dinâmica, web_search_20250305 para busca básica) permanecem disponíveis.

Para elegibilidade de Zero Data Retention e a solução alternativa com 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 decide quando buscar com base no prompt.
2. A API executa as buscas e fornece ao Claude os resultados. Esse processo pode se repetir várias vezes ao longo de uma única requisição.
3. Ao final do 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 estão fora dos seus dados de treinamento:

• Eventos, notícias ou anúncios recentes
• Preços, taxas, pontuações 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 pode ser direcionado através do seu prompt do sistema: você pode incentivar o 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 em cada requisição.



Filtragem dinâmica

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

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

A filtragem dinâmica é particularmente eficaz para:

• Pesquisar em documentação técnica
• Revisão de literatura e verificação de citações
• Pesquisa técnica
• Fundamentação e verificação de respostas

Para habilitar a filtragem dinâmica, use web_search_20260209 ou qualquer versão posterior. Os exemplos a seguir usam web_search_20260209:

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_20260209", "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 oferece suporte aos 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
  "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"
  }
}



Max uses

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 consultas sensíveis à latência, max_uses: 3 limita o custo enquanto raramente trunca. Para agentes de pesquisa, defina max_uses entre 15 e 20 ou omita-o completamente.



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 os 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.



Inclusão de resposta

O parâmetro response_inclusion controla como os blocos de resultados 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 blocos 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 de 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 serem concluídas, 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"
}



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 deve ser passado de volta em conversas de múltiplos turnos 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 de volta para conversas de múltiplos turnos.
• 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 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"
  }
}

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: Número máximo de usos da ferramenta de busca na web excedido
• query_too_long: A consulta excede o comprimento máximo
• unavailable: Ocorreu um erro interno



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": ""}}

// 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 através 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, 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; entre em contato com vendas a partir dessa página para solicitar um limite maior. Cargas de trabalho típicas de busca na web em lote incluem enriquecer registros com dados atuais da web, pesquisar uma grande lista de entidades e fundamentar ou verificar um corpus de conteúdo em relação a fontes ativas.



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