Ferramenta de busca na web
A ferramenta de busca na web dá ao Claude acesso direto ao conteúdo web em tempo real, permitindo que ele responda perguntas com informações atualizadas além de seu limite de conhecimento. Claude cita automaticamente fontes dos resultados de busca como parte de sua resposta.
Entre em contato através do nosso formulário de feedback para compartilhar sua experiência com a ferramenta de busca na web.
Modelos suportados
A busca na web está disponível em:
- Claude Opus 4.1 (
claude-opus-4-1-20250805
) - Claude Opus 4 (
claude-opus-4-20250514
) - Claude Sonnet 4 (
claude-sonnet-4-20250514
) - Claude Sonnet 3.7 (
claude-3-7-sonnet-20250219
) - Claude Sonnet 3.5 (novo) (
claude-3-5-sonnet-latest
) - Claude Haiku 3.5 (
claude-3-5-haiku-latest
)
Como funciona a busca na web
Quando você adiciona a ferramenta de busca na web à sua solicitação de API:
- Claude decide quando buscar com base no prompt.
- A API executa as buscas e fornece ao Claude os resultados. Este processo pode se repetir várias vezes durante uma única solicitação.
- No final de sua vez, Claude fornece uma resposta final com fontes citadas.
Como usar a busca na web
O administrador da sua organização deve habilitar a busca na web no Console.
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:
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
será um erro com o código de erro max_uses_exceeded
.
Filtragem de domínios
Ao usar filtros de domínio:
- Domínios não devem incluir o esquema HTTP/HTTPS (use
example.com
em vez dehttps://example.com
) - Subdomínios são automaticamente incluídos (
example.com
cobredocs.example.com
) - Subcaminhos são suportados (
example.com/blog
) - Você pode usar
allowed_domains
oublocked_domains
, mas não ambos na mesma solicitação.
Restrições de domínio no nível da solicitação devem ser compatíveis com restrições de domínio no nível da organização configuradas no Console. Domínios no nível da solicitação podem apenas restringir ainda mais os domínios, não substituir ou expandir além da lista no nível da organização. Se sua solicitação incluir domínios que conflitam com as configurações da organização, a API retornará um erro de validação.
Localização
O parâmetro user_location
permite localizar resultados de busca com base na localização de um usuário.
type
: O tipo de localização (deve serapproximate
)city
: O nome da cidaderegion
: A região ou estadocountry
: O paístimezone
: O ID de fuso horário IANA.
Resposta
Aqui está um exemplo de estrutura de resposta:
Resultados da busca
Os resultados da busca incluem:
url
: A URL da página fontetitle
: O título da página fontepage_age
: Quando o site foi atualizado pela última vezencrypted_content
: Conteúdo criptografado que deve ser passado de volta em conversas de múltiplas rodadas 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 citadatitle
: O título da fonte citadaencrypted_index
: Uma referência que deve ser passada de volta para conversas de múltiplas rodadas.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.
Ao exibir resultados da web ou informações contidas em resultados da web para usuários finais, citações inline devem ser claramente visíveis e clicáveis em sua interface de usuário.
Erros
Quando a ferramenta de busca na web encontra um erro (como atingir limites de taxa), a API Anthropic ainda retorna uma resposta 200 (sucesso). O erro é representado dentro do corpo da resposta usando a seguinte estrutura:
Estes são os possíveis códigos de erro:
too_many_requests
: Limite de taxa excedidoinvalid_input
: Parâmetro de consulta de busca inválidomax_uses_exceeded
: Máximo de usos da ferramenta de busca na web excedidoquery_too_long
: Consulta excede o comprimento máximounavailable
: Ocorreu um erro interno
Razão de parada pause_turn
A resposta pode incluir uma razão de parada pause_turn
, que indica que a API pausou uma rodada de longa duração. Você pode fornecer a resposta de volta como está em uma solicitação subsequente para deixar Claude continuar sua rodada, ou modificar o conteúdo se desejar interromper a conversa.
Cache de prompt
A busca na web funciona com cache de prompt. Para habilitar o cache de prompt, adicione pelo menos um ponto de interrupção cache_control
em sua solicitação. O sistema irá automaticamente fazer cache até o último bloco web_search_tool_result
ao executar a ferramenta.
Para conversas de múltiplas rodadas, defina um ponto de interrupção cache_control
no ou após o último bloco web_search_tool_result
para reutilizar conteúdo em cache.
Por exemplo, para usar cache de prompt com busca na web para uma conversa de múltiplas rodadas:
Streaming
Com streaming habilitado, você receberá eventos de busca como parte do stream. Haverá uma pausa enquanto a busca executa:
Solicitações em lote
Você pode incluir a ferramenta de busca na web na API de Lotes de Mensagens. Chamadas da ferramenta de busca na web através da API de Lotes de Mensagens são precificadas da mesma forma que aquelas em solicitações regulares da API de Mensagens.
Uso e preços
Web search usage is charged in addition to token usage:
Web search is available on the Anthropic 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.