MensagensFerramentas

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_20260209) 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 e Claude Sonnet 4.6. O Claude pode escrever e executar código para filtrar os resultados de busca antes que eles cheguem à janela de contexto, mantendo apenas as informações relevantes e descartando o restante. Isso leva a respostas mais precisas e reduz o consumo de tokens. A versão anterior da ferramenta (web_search_20250305) continua disponível sem filtragem dinâmica.

Para o Claude Mythos Preview, a busca na web é compatível com a API do Claude, Microsoft Foundry e Vertex AI. A busca na web não está disponível para o Mythos Preview no Amazon Bedrock ou no Claude Platform on AWS.

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:

O Claude decide quando buscar com base no prompt.
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.
Ao final do seu turno, o Claude fornece uma resposta final com as fontes citadas.

Quando o Claude busca

O Claude busca quando a solicitação depende de informações atuais, em constante mudança ou 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

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

Fatos estabelecidos, matemática, fundamentos científicos 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 por meio 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. Muitas vezes, grande parte desse conteúdo é irrelevante, o que pode degradar a qualidade da resposta.

Com a versão web_search_20260209 da ferramenta, 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

A filtragem dinâmica requer que a ferramenta de execução de código esteja habilitada. A ferramenta de busca na web (com e sem filtragem dinâmica) está disponível na API do Claude, no Claude Platform on AWS e no Microsoft Foundry. No Vertex AI, apenas a ferramenta de busca na web básica (sem filtragem dinâmica) está disponível. A busca na web não está disponível no Amazon Bedrock.

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

Como usar a busca na web

O administrador da sua organização deve habilitar a busca na web no Claude Console.

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

Definição da ferramenta

A ferramenta de busca na web oferece suporte aos seguintes parâmetros:

JSON

{
  "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 fazer 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 e raramente causa truncamento. Para agentes de pesquisa, defina max_uses entre 15 e 20 ou omita-o completamente.

Filtragem de domínios

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

Localização

O parâmetro user_location permite localizar os resultados de busca com base na localização do 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:

Output

{
  "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.

Ao exibir saídas da API diretamente para usuários finais, as citações devem ser incluídas com a fonte original. Se você estiver fazendo modificações nas saídas da API, incluindo reprocessá-las e/ou combiná-las com seu próprio material antes de exibi-las aos usuários finais, exiba as citações conforme apropriado com base em consulta à sua equipe jurídica.

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:

Output

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

Output

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. As chamadas da ferramenta de busca na web por meio da Messages Batches API têm o mesmo preço das 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 a equipe de 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

Ferramentas de servidor

Mecânica compartilhada para ferramentas executadas pela Anthropic.

Referência de ferramentas

Diretório de todas as ferramentas fornecidas pela Anthropic.

Was this page helpful?

MensagensFerramentas

Ferramenta de busca na web

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:

O Claude decide quando buscar com base no prompt.
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.
Ao final do seu turno, o Claude fornece uma resposta final com as fontes citadas.

Quando o Claude busca

O Claude busca quando a solicitação depende de informações atuais, em constante mudança ou 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

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

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

Filtragem dinâmica

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 a versão web_search_20260209 da ferramenta:

Como usar a busca na web

O administrador da sua organização deve habilitar a busca na web no Claude Console.

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

Definição da ferramenta

A ferramenta de busca na web oferece suporte aos seguintes parâmetros:

JSON

{
  "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

Filtragem de domínios

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

Localização

O parâmetro user_location permite localizar os resultados de busca com base na localização do 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:

Output

{
  "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

Output

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

Output

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

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

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

Ferramentas de servidor

Mecânica compartilhada para ferramentas executadas pela Anthropic.

Referência de ferramentas

Diretório de todas as ferramentas fornecidas pela Anthropic.

Was this page helpful?

Como a busca na web funciona

Quando o Claude busca

Filtragem dinâmica

Como usar a busca na web

Definição da ferramenta

Max uses

Filtragem de domínios

Localização

Resposta

Resultados de busca

Citações

Erros

Motivo de parada pause_turn

Cache de prompt

Streaming

Requisições em lote

Uso e preços

Próximos passos

Como a busca na web funciona

Quando o Claude busca

Filtragem dinâmica

Como usar a busca na web

Definição da ferramenta

Max uses

Filtragem de domínios

Localização

Resposta

Resultados de busca

Citações

Erros

Motivo de parada pause_turn

Cache de prompt

Streaming

Requisições em lote

Uso e preços

Próximos passos

Como a busca na web funciona

Quando o Claude busca

Filtragem dinâmica

Como usar a busca na web

Definição da ferramenta

Max uses

Filtragem de domínios

Localização

Resposta

Resultados de busca

Citações

Erros

Motivo de parada `pause_turn`

Cache de prompt

Streaming

Requisições em lote

Uso e preços

Próximos passos

Como a busca na web funciona

Quando o Claude busca

Filtragem dinâmica

Como usar a busca na web

Definição da ferramenta

Max uses

Filtragem de domínios

Localização

Resposta

Resultados de busca

Citações

Erros

Motivo de parada `pause_turn`

Cache de prompt

Streaming

Requisições em lote

Uso e preços

Próximos passos