Ferramenta web fetch
Busque e leia conteúdo de URLs específicas para ampliar o contexto do Claude com conteúdo web ao vivo.
O uso varia conforme o produto
web_fetch às tools da requisição.max_uses, citations ou cache_control.A ferramenta 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 web fetch (web_fetch_20260318) oferece suporte a filtragem dinâmica: Claude pode escrever e executar código para filtrar o conteúdo buscado 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 mantendo a qualidade da resposta. A filtragem dinâmica está disponível com Claude 4.6 e modelos posteriores e com o Claude Mythos Preview. web_fetch_20260318 também adiciona controle de inclusão na resposta para fluxos de trabalho agênticos. As outras versões (web_fetch_20260309 para filtragem dinâmica e ignorar o cache, web_fetch_20260209 apenas para filtragem dinâmica, web_fetch_20250910 para busca básica) estão disponíveis.
O web fetch (com e sem filtragem dinâmica) está disponível na Claude API, na Claude Platform on AWS, no Claude Models on Google Cloud (Anthropic managed) e no Microsoft Foundry. No Microsoft Foundry, implantações hospedadas no Azure oferecem suporte apenas à ferramenta web fetch básica (web_fetch_20250910, sem filtragem dinâmica). Implantações hospedadas na Anthropic oferecem suporte a todas as versões.
Para a elegibilidade para retenção zero de dados e a solução alternativa com allowed_callers, consulte Ferramentas de servidor.
Para suporte a modelos, consulte a Referência de ferramentas.
Como o web fetch funciona
O 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 o 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, 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:
- Claude determina quando buscar conteúdo com base no prompt e nas URLs disponíveis.
- A API recupera o conteúdo de texto completo da URL especificada.
- Para PDFs, a API retorna o conteúdo como dados codificados em base64 e o processa como um documento PDF anexado diretamente.
- 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, 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 Claude possa localizá-lo primeiro (consulte Pesquisa na web e web fetch combinados)
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?” é 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-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 o web fetch
Para saber como as configurações de web fetch 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 web fetch na sua requisição de API:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
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
"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: Don't fetch URLs that appear only in client-side tool results
"url_sources": {
"client_tool_results": { "type": "none" }
},
// 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 Ignorar o cache), e response_inclusion requer web_fetch_20260318 ou posterior (consulte Inclusão na resposta).
Máximo de usos
O parâmetro max_uses limita o número de buscas web em um único turno. Buscas que falharam contam para o limite. Se Claude chamar o web fetch diretamente mais vezes do que o permitido, o web_fetch_tool_result será um erro com o código de erro max_uses_exceeded. Se Claude chamar o web fetch a partir da execução de código mais vezes do que o permitido, a execução de código termina com um erro. Não há limite padrão.
Um turno pode abranger várias requisições. Uma requisição continua um turno quando é retomada após pause_turn ou quando sua última mensagem contém apenas blocos tool_result. Buscas de requisições anteriores nesse turno contam para o limite, a menos que Claude as tenha executado a partir da execução de código por meio de filtragem dinâmica.
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; consulte Restringir domínios de pesquisa na web 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 é aproximado: o número real de tokens de entrada usados pode variar em uma pequena quantidade. O limite se aplica a conteúdo de texto, não a conteúdo binário como PDFs.
Se um PDF buscado fizer com que a requisição exceda os limites de páginas ou de tamanho de PDF, o web_fetch_tool_result será um erro com o código de erro content_too_large. PDFs e imagens já presentes na conversa contam para esses limites, portanto removê-los pode permitir que a busca seja bem-sucedida.
No Claude Managed Agents, a entrada web_fetch do conjunto de ferramentas do agente também aceita max_content_tokens; consulte as configurações da ferramenta web.
Ignorar o 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. Desative 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 na 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 na mesma resposta. 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 página. O uso de tokens não é afetado, porque 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 foram pausadas antes de serem concluídas, para que você possa enviá-los de volta na próxima requisição.
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"response_inclusion": "excluded"
}
]
}Citações
Diferentemente da pesquisa na web, em que as citações estão sempre habilitadas, as citações são opcionais para o 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 da busca
Os resultados da busca incluem:
url: A URL que foi buscadacontent: Um bloco de documento contendo o conteúdo buscadoretrieved_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. Claude recebe 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 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ínios (incluindo as configurações da sua organização) ou por restrições do lado da Anthropic, como endereços privados,robots.txte URLs que parecem conter uma credencial que você não forneceuurl_not_in_prior_context: A URL não apareceu anteriormente na conversa, ou apareceu apenas em fontes queurl_sourcesexclui (consulte Validação de URL)url_not_accessible: Falha ao buscar o conteúdo (erro HTTP)too_many_requests: Limite de taxa excedidounsupported_content_type: Tipo de conteúdo não suportado (apenas texto, HTML e PDF)content_too_large: O PDF buscado faria a requisição exceder os limites de páginas ou de tamanho de PDF (consulte Limites de conteúdo)max_uses_exceeded: Número máximo de usos da ferramenta web fetch excedidounavailable: Ocorreu um erro interno
Validação de URL
Por motivos de segurança, a ferramenta 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 pesquisa na web ou web fetch
A ferramenta não pode buscar URLs que aparecem apenas na própria saída de Claude ou apenas no prompt do sistema. Para tornar buscável uma URL do prompt do sistema, 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. Por padrão, resultados de ferramentas do lado do cliente são uma fonte permitida mesmo quando repetem texto que Claude produziu (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.
Fontes de URL
O parâmetro opcional url_sources permite desativar qualquer uma das três fontes permitidas ou limitar os resultados de ferramentas a determinadas ferramentas. Ele tem uma chave para cada fonte, e cada chave tem como padrão {"type": "all"}:
user_input: URLs em mensagens do usuário. Seutypeé"all"ou"none".client_tool_results: URLs em resultados de ferramentas do lado do cliente. Seutypeé"all","none"ou um filtro"only"ou"except"que nomeia ferramentas, como no exemplo a seguir.server_tool_results: URLs de resultados anteriores de pesquisa na web ou web fetch. Aceita os mesmos valores, e seus filtros nomeiamweb_searchouweb_fetch.
Por exemplo, uma ferramenta que executa código escrito por Claude retorna tudo o que esse código imprime, incluindo qualquer URL que Claude tenha colocado nele. Para impedir que os resultados dessa ferramenta contem como fonte, nomeie-a em um filtro "except":
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"url_sources": {
"client_tool_results": {
"type": "except",
"tools": [{ "type": "tool_reference", "name": "run_code" }]
}
}
},
{
"name": "run_code",
"description": "Run Python code and return its output",
"input_schema": {
"type": "object",
"properties": { "code": { "type": "string" } },
"required": ["code"]
}
}
]
}Um filtro lista ferramentas como objetos tool_reference. Cada nome deve corresponder a uma ferramenta no array tools da requisição: uma ferramenta de cliente para client_tool_results ou uma ferramenta de servidor para server_tool_results. Caso contrário, a requisição falha com um erro. Com "except", uma ferramenta que você adicionar a tools posteriormente conta como fonte. Com "only", não conta.
Ferramentas do lado do cliente diferentes de run_code também podem retornar texto escrito por Claude, por exemplo em uma mensagem de erro que o cita. Para excluir todos os resultados de ferramentas do lado do cliente, defina client_tool_results como {"type": "none"}.
Se uma URL apareceu apenas em fontes que url_sources exclui, buscá-la retorna o erro url_not_in_prior_context.
Pesquisa na web e web fetch combinados
Quando as ferramentas de pesquisa na web 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”), 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-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, Claude:
- Usa a pesquisa na web para encontrar artigos relevantes.
- Seleciona os resultados mais promissores.
- Usa o web fetch para recuperar o conteúdo completo.
- 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 busca 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 runs
// 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 Message Batches API. As chamadas da ferramenta web fetch por meio da Message Batches API têm o mesmo preço que as de requisições regulares à 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
Execute código Python e Bash em um contêiner isolado para analisar dados, gerar arquivos e iterar em soluções.
Trabalhe com ferramentas que a Anthropic executa: blocos server_tool_use, continuação com pause_turn e filtragem de domínios.
Diretório de ferramentas fornecidas pela Anthropic e referência para propriedades opcionais de definição de ferramentas.
Disponibilidade
Claude API
- APIs
- Messages API
- Managed Agents
- Modelos
- Todos os modelos
Claude Platform on AWS
- APIs
- Messages API
- Managed Agents
- Modelos
- Todos os modelos
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Modelos
- Todos os modelos
Microsoft Foundry (hosted on Azure)
- API
- Messages API
- Modelos
- Todos os modelos
- Observação
Implantações hospedadas no Azure são compatíveis somente com
web_fetch_20250910: sem filtragem dinâmica, inclusão de resposta ou bypass de cache.
Microsoft Foundry (hosted on Anthropic)
- API
- Messages API
- Modelos
- Todos os modelos
Tratamento de dados
Visão geral do tratamento de dadosEndpoints aplicáveis
/v1/messagescom a ferramentaweb_fetch
Exclui Modelos cobertos
Conteúdo web obtido e retornado na resposta da API. A filtragem dinâmica do web fetch não é elegível para ZDR nem para HIPAA. Os editores de sites podem reter dados das requisições (como URLs obtidas e metadados das requisições) de acordo com suas próprias políticas.
Esta página foi útil?