Ferramenta de busca na web (web fetch)

A ferramenta "web fetch" (busca de conteúdo na web) 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 web fetch (web_fetch_20260318) oferece suporte a "dynamic filtering" (filtragem dinâmica): Claude pode escrever e executar código para filtrar o conteúdo obtido antes que ele chegue à "context window" (janela de contexto), mantendo apenas as informações relevantes e descartando o restante. Isso reduz o consumo de tokens e mantém a qualidade das respostas. A filtragem dinâmica está disponível com Claude 4.6 e modelos posteriores e com o Claude Mythos Preview. A web_fetch_20260318 também adiciona o controle de "response inclusion" (inclusão de resposta) para fluxos de trabalho agênticos. As versões anteriores (web_fetch_20260309 para filtragem dinâmica e "cache bypass" (ignorar o cache), web_fetch_20260209 apenas para filtragem dinâmica, web_fetch_20250910 para busca básica) continuam disponíveis.

A web fetch (com e sem filtragem dinâmica) está disponível na Claude API, na Claude Platform on AWS e no Microsoft Foundry. No Microsoft Foundry, as implantações hospedadas no Azure oferecem suporte apenas à ferramenta web fetch básica (web_fetch_20250910, sem filtragem dinâmica). As implantações hospedadas na Anthropic oferecem suporte a todas as versões. A web fetch não está disponível atualmente no Amazon Bedrock nem no Google Cloud.

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

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

Como a web fetch funciona

A web fetch é uma "server tool" (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 web fetch e uma das 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, em seguida, 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 web fetch à sua requisição de API:

1. O 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. 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 web search também está habilitada para que o Claude possa localizá-lo primeiro (consulte Busca e fetch combinados)

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 APIs REST?" é respondida 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_20260318:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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 a web fetch

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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 web fetch 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ínios

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

No Claude Managed Agents, defina esses campos na entrada web_fetch do conjunto de ferramentas do agente, onde cada domínio listado deve ser um hostname simples sem caminho; consulte Restringir domínios de web search e web fetch.

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 a conteúdo binário como PDFs.

No Claude Managed Agents, a entrada web_fetch do conjunto de ferramentas do agente também aceita max_content_tokens; consulte Restringir domínios de web search e web fetch.

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, pois ignorar o cache aumenta a "latency" (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 remover completamente da resposta esses pares aninhados de server_tool_use e blocos de resultado, 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 concluir, são sempre retornados integralmente 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 da web search, onde as citações estão sempre habilitadas, as citações são opcionais para a web fetch e desabilitadas por padrão. Defina "citations": {"enabled": true} para permitir que o Claude cite passagens específicas 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 web fetch encontra um erro, a Claude API retorna uma resposta 200 (sucesso) com o erro representado no corpo da resposta. O Claude vê o resultado de 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 que não seja 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ínios (incluindo as configurações da sua organização) ou por restrições do lado da Anthropic, como endereços privados, robots.txt e URLs que parecem conter uma credencial que você não forneceu
• url_not_in_prior_context: A URL não apareceu anteriormente na conversa (consulte Validação de URL)
• url_not_accessible: Falha ao buscar o 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 web fetch excedido
• unavailable: Ocorreu um erro interno

Validação de URL

Por motivos de segurança, a ferramenta web fetch só pode buscar URLs que tenham aparecido 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 que aparecem apenas na própria saída de Claude ou apenas no "system prompt" (prompt do sistema). Para tornar uma URL do prompt do sistema buscável, inclua-a também em uma mensagem do usuário. Resultados de outras ferramentas do lado do servidor, como execução de código, o conector MCP ou a pesquisa de ferramentas, também não são uma fonte permitida. Resultados de ferramentas do lado do cliente são uma fonte permitida mesmo quando repetem texto produzido por Claude (por exemplo, um comando que imprime sua entrada ou uma mensagem de erro que a cita).

A ferramenta também recusa uma URL que pareça conter uma credencial, como uma chave de API ou uma senha, a menos que essa credencial apareça no prompt do sistema ou no texto de uma mensagem do usuário. Uma credencial que aparece apenas em um resultado de ferramenta não conta. O resultado é um erro url_not_allowed. Para buscar uma URL desse tipo, inclua-a em uma mensagem do usuário.

Busca e fetch combinados

Quando as ferramentas web search e web fetch estão ambas 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 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-5-5",
    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 web search para encontrar artigos relevantes.
2. Seleciona os resultados mais promissores.
3. Usa a web fetch para recuperar o conteúdo completo.
4. Fornece uma análise detalhada com citações.

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, 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 web fetch na Messages Batches API. As chamadas da ferramenta web fetch por meio da Messages Batches API têm o mesmo preço que as 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 Claude API 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 em excesso, use o parâmetro max_content_tokens para definir limites apropriados com base no seu caso de uso e em 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