Ferramenta de busca na web

A ferramenta de busca na web (web fetch) permite que o Claude recupere o conteúdo completo de páginas da web e documentos PDF especificados.

A versão mais recente da ferramenta de busca na web (web_fetch_20260318) 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, Claude Sonnet 5 e Claude Sonnet 4.6. O Claude pode escrever e executar código para filtrar o conteúdo buscado antes que ele chegue à janela de contexto, mantendo apenas as informações relevantes e descartando o restante. Isso reduz o consumo de tokens enquanto mantém a qualidade da resposta. A web_fetch_20260318 também adiciona controle de inclusão de resposta para fluxos de trabalho agênticos. As versões anteriores (web_fetch_20260309 para filtragem dinâmica e bypass de cache, web_fetch_20260209 apenas para filtragem dinâmica, web_fetch_20250910 para busca básica) permanecem disponíveis.

A 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 Microsoft Foundry, a busca na web requer uma implantação Hosted on Anthropic. Atualmente, não está disponível no Amazon Bedrock ou no Google Cloud.

Para elegibilidade de Zero Data Retention e a solução alternativa allowed_callers, consulte Ferramentas de servidor.

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



Como a busca na web funciona

A busca na web é uma ferramenta de servidor: a API busca o conteúdo durante a requisição e insere os resultados na conversa. Você não executa nada nem retorna um tool_result. A exceção é quando o Claude chama a busca na web e uma de suas ferramentas de cliente no mesmo grupo de chamadas de ferramentas paralelas: a API retorna a resposta com stop_reason: "tool_use" antes que essa busca seja executada e, em seguida, executa a busca quando você envia de volta os blocos tool_result do cliente. Consulte Combinando ferramentas de servidor e ferramentas de cliente em um turno.

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

1. O Claude decide quando buscar conteúdo com base no prompt e nas URLs disponíveis.
2. A API recupera o conteúdo de texto completo da URL especificada.
3. Para PDFs, a API retorna o conteúdo como dados codificados em base64 e o processa como um documento PDF anexado diretamente.
4. O Claude analisa o conteúdo buscado e fornece uma resposta com citações opcionais.



Quando o Claude busca

O Claude busca quando a requisição aponta para uma página ou documento específico:

• Uma URL é fornecida na conversa (ou em um resultado de ferramenta anterior)
• O usuário nomeia um recurso específico (um artigo, README, página de preços ou seção de documentação em particular) sem uma URL, e a ferramenta de pesquisa na web também está habilitada para que o Claude possa localizá-lo primeiro (consulte Pesquisa e busca combinadas)

O Claude não busca para perguntas de conhecimento geral ou abertas que não fazem referência a uma página específica. "Resuma este artigo: <url>" aciona uma busca. "Quais são as melhores práticas para design de API REST?" é respondido diretamente.



Filtragem dinâmica

Buscar páginas da web e PDFs completos pode consumir tokens rapidamente, especialmente quando apenas informações específicas são necessárias de documentos grandes. Com web_fetch_20260209 ou posterior, o Claude pode escrever e executar código para filtrar o conteúdo buscado antes de carregá-lo no contexto.

Essa filtragem dinâmica é particularmente útil para:

• Extrair seções específicas de documentos longos
• Processar dados estruturados de páginas da web
• Filtrar informações relevantes de PDFs
• Reduzir custos de tokens ao trabalhar com documentos grandes

Para habilitar a filtragem dinâmica, use web_fetch_20260209 ou qualquer versão posterior. Os exemplos a seguir usam web_fetch_20260209:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Fetch the content at https://example.com/research-paper and extract the key findings.",
        }
    ],
    tools=[{"type": "web_fetch_20260209", "name": "web_fetch"}],
)
print(response)



Como usar a busca na web

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Please analyze the content at https://example.com/article",
        }
    ],
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5}],
)
print(response)



Definição da ferramenta

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

{
  "type": "web_fetch_20250910",
  "name": "web_fetch",

  // Optional: Limit the number of fetches per request
  "max_uses": 10,

  // Optional: Only fetch from these domains
  "allowed_domains": ["example.com", "docs.example.com"],

  // Optional: Never fetch from these domains (cannot be combined with allowed_domains)
  "blocked_domains": ["private.example.com"],

  // Optional: Enable citations for fetched content
  "citations": {
    "enabled": true
  },

  // Optional: Maximum content length in tokens
  "max_content_tokens": 100000
}

Versões posteriores da ferramenta adicionam mais dois parâmetros opcionais: use_cache requer web_fetch_20260309 ou posterior (consulte Bypass de cache), e response_inclusion requer web_fetch_20260318 ou posterior (consulte Inclusão de resposta).



Máximo de usos

O parâmetro max_uses limita o número de buscas na web realizadas. Buscas com falha contam para o limite. Se o Claude tentar mais buscas do que o permitido, o web_fetch_tool_result será um erro com o código de erro max_uses_exceeded. Atualmente, não há limite padrão.



Filtragem de domínio

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



Limites de conteúdo

O parâmetro max_content_tokens limita a quantidade de conteúdo incluída no contexto. Se o conteúdo buscado exceder esse limite, a ferramenta o trunca. Isso ajuda a controlar o uso de tokens ao buscar documentos grandes. O limite se aplica ao conteúdo de texto, não ao conteúdo binário, como PDFs.



Bypass de cache

O parâmetro use_cache controla se o conteúdo em cache pode ser retornado. Defina "use_cache": false para ignorar o cache e buscar conteúdo atualizado. O padrão é true. Desabilite o cache apenas quando o usuário solicitar explicitamente conteúdo atualizado ou ao buscar fontes que mudam rapidamente, porque ignorar o cache aumenta a latência.

{
  "tools": [
    {
      "type": "web_fetch_20260309",
      "name": "web_fetch",
      "use_cache": false
    }
  ]
}



Inclusão de resposta

O parâmetro response_inclusion controla como os blocos de resultado de busca aparecem na resposta da API quando o resultado foi consumido por uma chamada de execução de código concluída no mesmo turno. Defina "response_inclusion": "excluded" para remover completamente esses pares aninhados de blocos server_tool_use e de resultado da resposta, reduzindo os custos de tokens de saída para fluxos de trabalho agênticos que não precisam ecoar o conteúdo bruto da página de volta ao cliente. O padrão é "full". Resultados de chamadas diretas, ou de chamadas de execução de código que pausaram antes de serem concluídas, são sempre retornados na íntegra para que possam ser enviados de volta no próximo turno.

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "response_inclusion": "excluded"
    }
  ]
}



Citações

Ao contrário da pesquisa na web, onde as citações estão sempre habilitadas, as citações são opcionais para a busca na web e desabilitadas por padrão. Defina "citations": {"enabled": true} para permitir que o Claude cite passagens específicas de documentos buscados.



Resposta

Aqui está um exemplo de estrutura de resposta:

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to fetch
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. The fetch request
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Fetch results
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01234567890abcdef",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          },
          "title": "Article Title",
          "citations": { "enabled": true }
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Claude's analysis with citations (if enabled)
    {
      "text": "Based on the article, ",
      "type": "text"
    },
    {
      "text": "the main argument presented is that artificial intelligence will transform healthcare",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Article Title",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "Artificial intelligence is poised to revolutionize healthcare delivery..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  },
  "stop_reason": "end_turn"
}



Resultados de busca

Os resultados de busca incluem:

• url: A URL que foi buscada
• content: Um bloco de documento contendo o conteúdo buscado
• retrieved_at: Timestamp de quando o conteúdo foi recuperado

Para documentos PDF, o conteúdo é retornado como dados codificados em base64:

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_02",
  "content": {
    "type": "web_fetch_result",
    "url": "https://example.com/paper.pdf",
    "content": {
      "type": "document",
      "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..."
      },
      "citations": { "enabled": true }
    },
    "retrieved_at": "2025-08-25T10:30:02Z"
  }
}



Erros

Quando a ferramenta de busca na web encontra um erro, a API do Claude retorna uma resposta 200 (sucesso) com o erro representado no corpo da resposta. O Claude vê o resultado do erro e continua o turno. Por exemplo:

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_fetch_tool_result_error",
    "error_code": "url_not_accessible"
  }
}

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

• invalid_tool_input: Entrada de ferramenta inválida, como uma URL malformada ou um esquema não HTTP(S)
• url_too_long: A URL excede o comprimento máximo (250 caracteres)
• url_not_allowed: URL bloqueada por regras de filtragem de domínio (incluindo as configurações da sua organização) ou por restrições do lado da Anthropic, como endereços privados e robots.txt
• url_not_in_prior_context: A URL não apareceu anteriormente na conversa (consulte Validação de URL)
• url_not_accessible: Falha ao buscar conteúdo (erro HTTP)
• too_many_requests: Limite de taxa excedido
• unsupported_content_type: Tipo de conteúdo não suportado (apenas texto, HTML e PDF)
• max_uses_exceeded: Máximo de usos da ferramenta de busca na web excedido
• unavailable: Ocorreu um erro interno



Validação de URL

Por razões de segurança, a ferramenta de busca na web só pode buscar URLs que apareceram anteriormente no contexto da conversa. Isso inclui:

• URLs em mensagens do usuário
• URLs em resultados de ferramentas do lado do cliente
• URLs de resultados anteriores de pesquisa na web ou busca na web

A ferramenta não pode buscar URLs arbitrárias que o Claude gera ou URLs de ferramentas de servidor baseadas em contêiner (Execução de Código, Bash, etc.).



Pesquisa e busca combinadas

Quando as ferramentas de pesquisa na web e busca na web estão habilitadas, e o usuário nomeia uma página ou documento específico sem fornecer uma URL (por exemplo, "leia o README do repositório anthropics/anthropic-sdk-python"), o Claude usa a pesquisa na web para localizá-lo e, em seguida, busca o resultado. O exemplo a seguir solicita uma pesquisa e uma análise em uma única requisição:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Find recent articles about quantum computing and analyze the most relevant one in detail",
        }
    ],
    tools=[
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
        {
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5,
            "citations": {"enabled": True},
        },
    ],
)
print(response)

Neste fluxo de trabalho, o Claude:

1. Usa a pesquisa na web para encontrar artigos relevantes.
2. Seleciona os resultados mais promissores.
3. Usa a busca na web para recuperar o conteúdo completo.
4. Fornece análise detalhada com citações.



Cache de prompt

Para armazenar definições de ferramentas em cache entre turnos, consulte Uso de ferramentas com cache de prompt.



Streaming

Com o streaming habilitado, os eventos de busca fazem parte do stream com uma pausa durante a recuperação de conteúdo:

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 fetch

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}

// Fetch URL streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Pause while fetch executes

// Fetch results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Article content..."}}}}}

// Claude's response continues...



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.



Uso e preços

O uso do web fetch não tem cobranças adicionais além dos custos padrão de tokens:

{
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  }
}

A ferramenta web fetch está disponível na API do Claude sem custo adicional. Você paga apenas os custos padrão de tokens pelo conteúdo buscado que se torna parte do contexto da sua conversa.

Para se proteger contra a busca inadvertida de conteúdo grande que consumiria tokens excessivos, use o parâmetro max_content_tokens para definir limites apropriados com base no seu caso de uso e considerações de orçamento.

Exemplo de uso de tokens para conteúdo típico:

• Página web média (10 kB): ~2.500 tokens
• Página de documentação grande (100 kB): ~25.000 tokens
• PDF de artigo de pesquisa (500 kB): ~125.000 tokens



Próximos passos