Ferramenta de busca de páginas web

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

A versão mais recente da ferramenta de web fetch (web_fetch_20260318) suporta 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. 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. 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.

Web fetch (com e sem filtragem dinâmica) está disponível na Claude API, Claude Platform na AWS e Microsoft Foundry. No Microsoft Foundry, web fetch requer uma implantação Hosted on Anthropic. Atualmente não está disponível no Amazon Bedrock ou Google Cloud.

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

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



Como o web fetch funciona

Web fetch é 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 Claude chama web fetch 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 tenha sido executada, e então executa a busca quando você envia de volta os blocos tool_result do cliente. Consulte Misturando ferramentas de servidor e ferramentas de cliente em um turno.

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

1. Claude determina 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. Claude analisa o conteúdo buscado e fornece uma resposta com citações opcionais.



Quando Claude busca

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 em particular, README, página de preços ou seção de documentação) sem uma URL, e a ferramenta de web search também está habilitada para que Claude possa localizá-lo primeiro (consulte Busca e fetch combinados)

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



Filtragem dinâmica

Buscar páginas 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, 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 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_20260318:

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_20260318", "name": "web_fetch"}],
)
print(response)



Como usar web fetch

Forneça a ferramenta de web fetch na 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 web fetch suporta os 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 web fetches realizados. Buscas com falha contam para o limite. Se 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ínios

Para filtragem de domínios 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 a conteúdo de texto, não a conteúdo binário como PDFs.



Bypass de cache

O parâmetro use_cache controla se 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 fetch 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 descartar 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 para o cliente. O padrão é "full". Resultados de chamadas diretas, ou de chamadas de execução de código que pausaram antes de concluir, 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

Diferentemente do web search, onde as citações estão sempre habilitadas, as citações são opcionais para web fetch e desabilitadas por padrão. Defina "citations": {"enabled": true} para permitir que Claude cite trechos específicos dos 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 fetch

Os resultados de fetch 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 web fetch encontra um erro, a Claude API retorna uma resposta 200 (sucesso) com o erro representado no corpo da resposta. 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 códigos de erro possíveis:

• invalid_tool_input: Entrada de ferramenta inválida, como uma URL malformada ou um esquema não HTTP(S)
• url_too_long: URL excede o comprimento máximo (250 caracteres)
• url_not_allowed: URL bloqueada por regras de filtragem de domínios (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 web fetch excedido
• unavailable: Ocorreu um erro interno



Validação de URL

Por razões de segurança, a ferramenta de web fetch 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 web search ou web fetch

A ferramenta não pode buscar URLs arbitrárias que Claude gera ou URLs de ferramentas de servidor baseadas em contêiner (como Code Execution e Bash).



Busca e fetch combinados

Quando as ferramentas de web search e web fetch 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"), Claude usa web search 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, Claude:

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



Cache de prompt

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



Streaming

Com streaming habilitado, os eventos de fetch fazem parte do stream com uma pausa durante a recuperação do 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 web fetch na API de Lotes de Mensagens. Chamadas da ferramenta de web fetch através da API de Lotes de Mensagens têm o mesmo preço das chamadas em requisições regulares da API de Mensagens.



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