Ferramenta de busca na web

A ferramenta de busca na web permite que Claude recupere 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_20260209) suporta filtragem dinâmica com Claude Opus 4.6 e 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 resto. Isso reduz o consumo de tokens enquanto mantém a qualidade da resposta. A versão anterior da ferramenta (web_fetch_20250910) permanece disponível sem filtragem dinâmica.

Modelos suportados

A busca na web está disponível em:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (descontinuado) (claude-3-7-sonnet-20250219)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Haiku 3.5 (descontinuado) (claude-3-5-haiku-latest)

Como a busca na web funciona

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

1. Claude decide quando buscar conteúdo com base no prompt e URLs disponíveis.
2. A API recupera o conteúdo de texto completo da URL especificada.
3. Para PDFs, a extração automática de texto é realizada.
4. Claude analisa o conteúdo buscado e fornece uma resposta com citações opcionais.

Filtragem dinâmica com Opus 4.6 e Sonnet 4.6

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

Esta 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 a versão da ferramenta web_fetch_20260209 com o cabeçalho beta code-execution-web-tools-2026-02-09:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-web-tools-2026-02-09" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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"
        }]
    }'

Como usar a busca na web

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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
        }]
    }'

Definição da ferramenta

A ferramenta de busca na web suporta os seguintes parâmetros:

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

  // Opcional: Limitar o número de buscas por requisição
  "max_uses": 10,

  // Opcional: Buscar apenas destes domínios
  "allowed_domains": ["example.com", "docs.example.com"],

  // Opcional: Nunca buscar destes domínios
  "blocked_domains": ["private.example.com"],

  // Opcional: Habilitar citações para conteúdo buscado
  "citations": {
    "enabled": true
  },

  // Opcional: Comprimento máximo de conteúdo em tokens
  "max_content_tokens": 100000
}

Max uses

O parâmetro max_uses limita o número de buscas na web realizadas. Se Claude tentar mais buscas do que 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

Ao usar filtros de domínio:

• Os domínios não devem incluir o esquema HTTP/HTTPS (use example.com em vez de https://example.com)
• Subdomínios são incluídos automaticamente (example.com cobre docs.example.com)
• Subcaminhos são suportados (example.com/blog)
• Você pode usar allowed_domains ou blocked_domains, mas não ambos na mesma requisição.

Limites de conteúdo

O parâmetro max_content_tokens limita a quantidade de conteúdo que será incluída no contexto. Se o conteúdo buscado exceder este limite, será truncado. Isso ajuda a controlar o uso de tokens ao buscar documentos grandes.

Citações

Diferentemente da busca na web onde as citações estão sempre habilitadas, as citações são opcionais para a busca na web. Defina "citations": {"enabled": true} para habilitar Claude a citar passagens específicas de documentos buscados.

Resposta

Aqui está um exemplo de estrutura de resposta:

{
  "role": "assistant",
  "content": [
    // 1. Decisão de Claude de buscar
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. A requisição de busca
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Resultados da busca
    {
      "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. Análise de Claude com citações (se habilitado)
    {
      "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 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 será 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 Claude retorna uma resposta 200 (sucesso) com o erro representado no corpo da resposta:

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

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

• invalid_input: Formato de URL inválido
• url_too_long: URL excede comprimento máximo (250 caracteres)
• url_not_allowed: URL bloqueada por regras de filtragem de domínio e restrições do modelo
• 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 e PDF)
• max_uses_exceeded: Número máximo de usos da ferramenta de busca na web excedido
• unavailable: Um erro interno ocorreu

Validação de URL

Por razões de segurança, a ferramenta de busca na web pode apenas 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 busca na web ou busca na web

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

Busca e busca combinadas

A busca na web funciona perfeitamente com a busca na web para coleta de informações abrangente:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    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},
        },
    ],
)

Neste fluxo de trabalho, Claude irá:

1. Usar busca na web para encontrar artigos relevantes
2. Selecionar os resultados mais promissores
3. Usar busca na web para recuperar conteúdo completo
4. Fornecer análise detalhada com citações

Cache de prompt

A busca na web funciona com cache de prompt. Para habilitar o cache de prompt, adicione pontos de interrupção cache_control em sua requisição. Os resultados de busca em cache podem ser reutilizados em turnos de conversa.

import anthropic

client = anthropic.Anthropic()

# Primeira requisição com busca na web
messages = [
    {
        "role": "user",
        "content": "Analyze this research paper: https://arxiv.org/abs/2024.12345",
    }
]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch"}],
)

# Adicionar resposta de Claude à conversa
messages.append({"role": "assistant", "content": response1.content})

# Segunda requisição com ponto de interrupção de cache
messages.append(
    {
        "role": "user",
        "content": "What methodology does the paper use?",
        "cache_control": {"type": "ephemeral"},
    }
)

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch"}],
)

# A segunda resposta se beneficia dos resultados de busca em cache
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

Streaming

Com streaming habilitado, 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": ""}}

// Decisão de Claude de buscar

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

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

// Pausa enquanto a busca é executada

// Resultados de busca transmitidos
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..."}}}}}

// Resposta de Claude continua...

Requisições em lote

Você pode incluir a ferramenta de busca na web na API de Lotes de Mensagens. Chamadas de ferramentas de busca na web através da API de Lotes de Mensagens são precificadas da mesma forma que aquelas em requisições regulares da API de Mensagens.

Uso e preços

Web fetch usage has no additional charges beyond standard token costs:

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

The web fetch tool is available on the Claude API at no additional cost. You only pay standard token costs for the fetched content that becomes part of your conversation context.

To protect against inadvertently fetching large content that would consume excessive tokens, use the max_content_tokens parameter to set appropriate limits based on your use case and budget considerations.

Example token usage for typical content:

• Average web page (10 kB): ~2,500 tokens
• Large documentation page (100 kB): ~25,000 tokens
• Research paper PDF (500 kB): ~125,000 tokens