A ferramenta de pesquisa 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 automaticamente cita fontes dos resultados de pesquisa como parte de sua resposta.
Por favor, entre em contato através do nosso formulário de feedback para compartilhar sua experiência com a ferramenta de pesquisa na web.

​
Modelos suportados

A pesquisa na web está disponível em:
  • Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 v2 (descontinuado) (claude-3-5-sonnet-latest)
  • Claude Haiku 4.5 (claude-haiku-4-5-20251001)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)
  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)

​
Como funciona a pesquisa na web

Quando você adiciona a ferramenta de pesquisa na web à sua solicitação de API:
  1. Claude decide quando pesquisar com base no prompt.
  2. A API executa as pesquisas e fornece ao Claude os resultados. Este processo pode se repetir várias vezes durante uma única solicitação.
  3. No final de sua vez, Claude fornece uma resposta final com fontes citadas.

​
Como usar a pesquisa na web

O administrador da sua organização deve habilitar a pesquisa na web no Console.
Forneça a ferramenta de pesquisa na web em sua solicitação de API: 
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Qual é o clima em NYC?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

​
Definição da ferramenta

A ferramenta de pesquisa na web suporta os seguintes parâmetros:
JSON
{
  "type": "web_search_20250305",
  "name": "web_search",

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

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

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

  // Opcional: Localizar resultados de pesquisa
  "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 pesquisas realizadas. Se Claude tentar mais pesquisas do que permitido, o web_search_tool_result será um erro com o código de erro max_uses_exceeded.

​
Filtragem de domínio

Ao usar filtros de domínio:
  • Os domínios não devem incluir o esquema HTTP/HTTPS (use example.com em vez de https://example.com)
  • Subdomínios são automaticamente incluídos (example.com cobre docs.example.com)
  • Subcaminhos são suportados (example.com/blog)
  • Você pode usar allowed_domains ou blocked_domains, mas não ambos na mesma solicitação.
As restrições de domínio no nível da solicitação devem ser compatíveis com as restrições de domínio no nível da organização configuradas no Console. Os domínios no nível da solicitação só podem 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 os resultados de pesquisa 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 pesquisar
    {
      "type": "text",
      "text": "Vou pesquisar quando Claude Shannon nasceu."
    },
    // 2. A consulta de pesquisa usada
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon data de nascimento"
      }
    },
    // 3. Resultados da pesquisa
    {
      "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": "30 de abril de 2025"
        }
      ]
    },
    {
      "text": "Com base nos resultados da pesquisa, ",
      "type": "text"
    },
    // 4. Resposta do Claude com citações
    {
      "text": "Claude Shannon nasceu em 30 de abril de 1916, em 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 (30 de abril de 1916 – 24 de fevereiro de 2001) foi um matemático americano, engenheiro elétrico, cientista da computação, criptógrafo e i..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 6039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_search_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

​
Resultados da pesquisa

Os resultados da pesquisa incluem:
  • url: A URL da página fonte
  • title: O título da página fonte
  • 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últiplas rodadas para citações

​
Citações

As citações estão sempre habilitadas para pesquisa 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últiplas rodadas.
  • cited_text: Até 150 caracteres do conteúdo citado
Os campos de citação da pesquisa 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 aos usuários finais, as citações devem ser incluídas à fonte original. Se você estiver fazendo modificações nas saídas da API, incluindo reprocessando e/ou combinando-as com seu próprio material antes de exibi-las aos usuários finais, exiba as citações conforme apropriado com base na consulta com sua equipe jurídica.

​
Erros

Quando a ferramenta de pesquisa na web encontra um erro (como atingir limites de taxa), a API 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": "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 pesquisa inválido
  • max_uses_exceeded: Máximo de usos da ferramenta de pesquisa na web excedido
  • query_too_long: Consulta excede o comprimento máximo
  • unavailable: Ocorreu um erro interno

​
Motivo de parada pause_turn

A resposta pode incluir um motivo de parada pause_turn, que indica que a API pausou uma rodada de longa duração. Você pode fornecer a resposta como está em uma solicitação subsequente para permitir que Claude continue sua rodada, ou modificar o conteúdo se desejar interromper a conversa.

​
Cache de prompt

A pesquisa 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 automaticamente fará 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 o conteúdo em cache. Por exemplo, para usar cache de prompt com pesquisa na web para uma conversa de múltiplas rodadas: 
import anthropic

client = anthropic.Anthropic()

# Primeira solicitação com pesquisa na web e ponto de interrupção de cache
messages = [
    {
        "role": "user",
        "content": "Qual é o clima atual em San Francisco hoje?"
    }
]

response1 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)

# Adicionar a resposta do Claude à conversa
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Segunda solicitação com ponto de interrupção de cache após os resultados da pesquisa
messages.append({
    "role": "user",
    "content": "Devo esperar chuva mais tarde esta semana?",
    "cache_control": {"type": "ephemeral"}  # Cache até este ponto
})

response2 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)
# A segunda resposta se beneficiará dos resultados de pesquisa em cache
# enquanto ainda pode realizar novas pesquisas se necessário
print(f"Tokens de leitura de cache: {response2.usage.get('cache_read_input_tokens', 0)}")

​
Streaming

Com streaming habilitado, você receberá eventos de pesquisa como parte do stream. Haverá uma pausa enquanto a pesquisa é 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 pesquisar

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 pesquisa transmitida
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"últimos avanços em computação quântica 2025\"}"}}

// Pausa enquanto a pesquisa é executada

// Resultados da pesquisa 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": "Avanços em Computação Quântica em 2025", "url": "https://example.com"}]}}

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

​
Solicitações em lote

Você pode incluir a ferramenta de pesquisa na web na API de Lotes de Mensagens. As chamadas da ferramenta de pesquisa 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.