A ferramenta de busca na web dá ao Claude acesso direto a conteúdo web em tempo real, permitindo que ele responda a perguntas com informações atualizadas além de seu limite de conhecimento. O Claude automaticamente cita 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 compatíveis

A busca na web está disponível em:

  • 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:

  1. Claude decide quando pesquisar com base no prompt.
  2. A API executa as buscas e fornece ao Claude os resultados. Este processo pode se repetir várias vezes durante uma única solicitação.
  3. Ao final de seu turno, 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:

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-opus-4-20250514",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Como atualizar um aplicativo web para TypeScript 5.5?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

​
Definição da ferramenta

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

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

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

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

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

  // Opcional: Localiza 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 fazer mais buscas do que o 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.

​
Localização

O parâmetro user_location permite localizar 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.

​
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 busca usada
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon data de nascimento"
      }
    },
    // 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": "Com base nos resultados da busca, ",
      "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 (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 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ú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 resultados da web ou informações contidas nos resultados da web para usuários finais, as citações em linha devem ser claramente visíveis e clicáveis em sua interface de usuário.

​
Erros

Se ocorrer um erro durante a busca na web, você receberá uma resposta que assume a seguinte forma:

{
  "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: A 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 um turno de longa duração. Você pode fornecer a resposta de volta como está em uma solicitação subsequente para permitir que Claude continue seu turno, 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 automaticamente armazenará em cache até o último bloco web_search_tool_result ao executar a ferramenta.

Para conversas de múltiplos turnos, 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 o cache de prompt com busca na web para uma conversa de múltiplos turnos:

import anthropic

client = anthropic.Anthropic()

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

response1 = client.messages.create(
    model="claude-opus-4-20250514",
    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"
        }
    }]
)

# Adiciona 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 busca
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-opus-4-20250514",
    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 busca em cache
# enquanto ainda pode realizar novas buscas, se necessário
print(f"Tokens de leitura de cache: {response2.usage.get('cache_read_input_tokens', 0)}")

​
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 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 busca 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 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": "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 busca na web na API de Lotes de Mensagens. As 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

O uso de busca 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 busca na web está disponível na API da Anthropic por $10 por 1.000 buscas, além dos custos padrão de tokens para conteúdo gerado pela busca. Os resultados de busca na web recuperados ao longo de uma conversa são contados como tokens de entrada, em iterações de busca executadas durante um único turno e em turnos de conversa subsequentes.

Cada busca na web conta como um uso, independentemente do número de resultados retornados. Se ocorrer um erro durante a busca na web, a busca na web não será cobrada.