Ferramenta de pesquisa na web

A ferramenta de pesquisa 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 de sua data de corte de conhecimento. A resposta inclui citações das fontes extraídas dos resultados da pesquisa.

Com web_search_20260209 e versões posteriores, o Claude pode escrever e executar código que filtra os resultados da pesquisa antes que eles cheguem à “context window” (janela de contexto) (“dynamic filtering” (filtragem dinâmica)), mantendo apenas as informações relevantes. A filtragem dinâmica está disponível com o Claude 4.6 e modelos posteriores e com o Claude Mythos Preview.

Três versões da ferramenta de pesquisa na web estão disponíveis:

• web_search_20250305: pesquisa na web básica
• web_search_20260209: adiciona filtragem dinâmica
• web_search_20260318: adiciona controle de inclusão na resposta para fluxos de trabalho agênticos

Os exemplos nesta página usam web_search_20250305 para pesquisa básica e web_search_20260318 para filtragem dinâmica.

Para a elegibilidade da pesquisa na web para retenção zero de dados e a configuração relacionada allowed_callers, consulte Ferramentas de servidor.

Para suporte de modelos, consulte a Referência de ferramentas.

Para verificar se um modelo aceita pesquisa na web antes de enviar uma solicitação, leia o valor capabilities.server_tools.web_search.supported na Models API. Usando a Models API descreve o campo.

Como a pesquisa na web funciona

Quando você adiciona a ferramenta de pesquisa na web à sua solicitação de API:

1. O Claude determina quando pesquisar com base no prompt.
2. A API executa as pesquisas e fornece os resultados ao Claude. Esse processo pode se repetir várias vezes ao longo de uma única solicitação.
3. No final do seu turno, o Claude fornece uma resposta final com fontes citadas.

Quando o Claude pesquisa

O Claude pesquisa quando a solicitação depende de informações atuais, em mudança ou fora de 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 pesquisar ou consultar algo

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

• Fatos estabelecidos, matemática, fundamentos de ciências ou conceitos de programação
• Escrita criativa ou brainstorming
• Análise de conteúdo já fornecido na conversa
• Turnos de conversa e saudações

O acionamento pode ser direcionado pelo seu “system prompt” (prompt do sistema): você pode incentivar o Claude a pesquisar com mais facilidade ou a preferir responder diretamente. Para impor um limite, use max_uses para limitar o número de pesquisas em um turno.

Filtragem dinâmica

Com a pesquisa na web básica, todos os resultados da pesquisa são carregados na janela de contexto do Claude, e grande parte desse conteúdo pode ser irrelevante para a solicitação. Com web_search_20260209 ou posterior, o Claude, em vez disso, escreve e executa código que filtra os resultados primeiro, de modo que apenas o conteúdo relevante chega à janela de contexto. Isso reduz o uso de tokens em solicitações com muitas pesquisas.

A filtragem dinâmica executa a pesquisa na web de dentro da execução de código: em web_search_20260209 e posteriores, o campo allowed_callers da ferramenta tem como padrão ["code_execution_20260120"], e quando a filtragem dinâmica é executada, a API provisiona automaticamente a execução de código de que precisa para a solicitação. Você não precisa adicionar a ferramenta de execução de código a tools por conta própria. Não há cobranças adicionais pelas chamadas de execução de código feitas dessa forma além dos custos padrão de tokens.

Para chamar a pesquisa na web diretamente, sem filtragem dinâmica, defina allowed_callers: ["direct"]. Modelos que não suportam chamada programática de ferramentas exigem essa configuração. Sem ela, a API retorna um erro 400 que informa para defini-la.

Os exemplos a seguir usam web_search_20260318:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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_20260318", "name": "web_search"}],
)
print(response)

Como usar a pesquisa na web

Para saber como as configurações de pesquisa na web da sua organização se aplicam em sessões do Claude Managed Agents, consulte Restringir domínios de pesquisa na web e web fetch.

Forneça a ferramenta de pesquisa na web em sua solicitação de API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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 pesquisa na web suporta os seguintes parâmetros:

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

  // Optional: Limit the number of searches
  "max_uses": 5,

  // Optional: Only include results from these domains.
  // Use allowed_domains or blocked_domains, not both.
  "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"
  }
}

Todas as versões da ferramenta de pesquisa na web aceitam allowed_callers, que controla se o Claude chama a pesquisa na web diretamente ou a partir da execução de código por meio da filtragem dinâmica. Em web_search_20260209 e posteriores, o padrão é ["code_execution_20260120"] em vez de ["direct"]. Consulte ZDR e allowed_callers para saber como configurá-lo. web_search_20260318 e posteriores também aceitam response_inclusion.

Usos máximos

O parâmetro max_uses limita o número de pesquisas em um único turno. Consultas sobre um único fato normalmente usam de 1 a 3 pesquisas; pesquisas comparativas ou com múltiplas entidades podem usar 10 ou mais.

Pesquisas com falha contam para o limite. Se o Claude chamar a pesquisa na web diretamente mais vezes do que o permitido, o web_search_tool_result será um erro com o código de erro max_uses_exceeded. Se o Claude chamar a pesquisa na web a partir da execução de código mais vezes do que o permitido, a execução de código termina com um erro.

Um turno pode abranger várias solicitações. Uma solicitação continua um turno quando é retomada após pause_turn ou quando sua última mensagem contém apenas blocos tool_result. Pesquisas de solicitações anteriores nesse turno contam para o limite, a menos que o Claude as tenha executado a partir da execução de código por meio da filtragem dinâmica.

Filtragem de domínios

Forneça allowed_domains ou blocked_domains, não ambos. Se uma solicitação incluir ambos, a API retorna um erro 400. As entradas são domínios simples com um caminho opcional, por exemplo example.com ou example.com/blog, sem esquema.

Para as regras completas de filtragem de domínios, consulte Filtragem de domínios no guia de Ferramentas de servidor.

No Claude Managed Agents, defina esses campos na entrada web_search do conjunto de ferramentas do agente; consulte Restringir domínios de pesquisa na web e web fetch.

Localização

O parâmetro user_location permite localizar os resultados da pesquisa com base na localização de um usuário. Forneça pelo menos um entre city, region, country ou timezone.

• type: O tipo de localização (deve ser approximate)
• city: O nome da cidade
• region: A região ou estado
• country: O código de país de duas letras ISO 3166-1 alpha-2 (a API rejeita um código não suportado com um erro 400)
• timezone: O ID de fuso horário IANA

No Claude Managed Agents, a entrada web_search do conjunto de ferramentas do agente também aceita user_location; consulte as configurações das ferramentas web.

Inclusão na resposta

O parâmetro response_inclusion controla como os blocos de resultados de pesquisa aparecem na resposta da API quando uma chamada de execução de código concluída na mesma resposta consumiu o resultado. Defina "response_inclusion": "excluded" para remover completamente da resposta esses pares aninhados de blocos server_tool_use e de resultado, para fluxos de trabalho agênticos que não precisam do conteúdo bruto da pesquisa. O uso de tokens não é afetado, porque o Claude lê a saída do código em vez desses blocos. O padrão é "full". A API sempre retorna por completo os resultados de chamadas diretas, ou de chamadas de execução de código que pausaram antes de serem concluídas, para que você possa enviá-los de volta na próxima solicitação.

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

Este exemplo mostra uma pesquisa direta. Quando uma pesquisa é executada por meio da filtragem dinâmica, a resposta também contém os blocos de resultado da ferramenta de execução de código, e cada par aninhado de server_tool_use e web_search_tool_result carrega um campo caller que identifica a chamada de execução de código que o gerou.

Resultados da pesquisa

Os resultados da pesquisa 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 você deve enviar de volta em conversas de múltiplos turnos

Para continuar uma conversa que contém resultados de pesquisa, envie os blocos de conteúdo do assistente de volta exatamente como você os recebeu, incluindo o encrypted_content de cada resultado. A API descriptografa esse conteúdo em solicitações posteriores para restaurar os resultados da pesquisa no contexto do Claude. Se encrypted_content estiver ausente ou modificado, a solicitação falha com um erro de validação 400.

Citações

As citações estão sempre habilitadas para a 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 enviada de volta em conversas de múltiplos turnos
• 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 de saída.

Erros

Quando a ferramenta de pesquisa na web encontra um erro (como atingir limites de taxa), a Claude API ainda retorna uma resposta 200 (sucesso). O erro é representado no 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"
  }
}

Em caso de erro, content é um único objeto de erro em vez de uma lista de blocos de resultado. Uma pesquisa bem-sucedida que não encontra resultados retorna uma lista content vazia, não um erro.

Estes são os códigos de erro possíveis:

• too_many_requests: Limite de taxa excedido
• invalid_tool_input: Parâmetro de consulta de pesquisa inválido
• max_uses_exceeded: Número máximo de usos da ferramenta de pesquisa na web excedido
• query_too_long: A consulta excede o comprimento máximo
• request_too_large: A solicitação de pesquisa é grande demais, normalmente devido a uma lista longa de filtros de domínio
• unavailable: Ocorreu um erro interno

Motivo de parada pause_turn

A API pode pausar um turno de pesquisa de longa duração e retornar stop_reason: "pause_turn". Para continuar, envie a mensagem pausada do assistente de volta, sem alterações, em uma nova solicitação.

Se o Claude chamar a pesquisa na web e uma de suas ferramentas de cliente no mesmo grupo de chamadas de ferramentas paralelas, a API retorna stop_reason: "tool_use" em vez disso e ainda não executa a pesquisa. Para continuar, retorne os resultados das ferramentas de cliente, e a API executa a pesquisa na próxima solicitação. Consulte Combinando ferramentas de servidor e ferramentas de cliente em um turno.

Para o loop do lado do servidor e o tratamento de pause_turn, consulte O loop do lado do servidor e pause_turn no guia de 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ê recebe eventos de pesquisa como parte do stream. Há 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": ""}}

// 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 runs

// 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)

Solicitações em lote

Você pode incluir a ferramenta de pesquisa na web na Message Batches API. As chamadas da ferramenta de pesquisa na web por meio da Message Batches API têm o mesmo preço que as de solicitações regulares da Messages API.

Para proteger a capacidade compartilhada, a Batches API limita as solicitações de pesquisa na web de cada organização, portanto lotes grandes com muitas pesquisas podem levar mais tempo para serem concluídos. Você pode ver o limite de taxa de pesquisa na web da sua organização na página Limites de taxa no Claude Console. Para solicitar um limite maior, entre em contato com a equipe de vendas nessa página.

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 Claude API por $10 USD a cada 1.000 pesquisas, mais os custos padrão de tokens para o conteúdo gerado pela pesquisa. Os resultados de pesquisa na web recuperados ao longo de uma conversa são contabilizados como “input tokens” (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. Uma pesquisa na web que falha com um erro não é cobrada.

Próximos passos

Disponibilidade