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 Mythos Preview, Claude Opus 4.7, Claude Opus 4.6 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 informações relevantes e descartando o resto. Isso reduz o consumo de tokens mantendo a qualidade da resposta. A versão anterior da ferramenta (web_fetch_20250910) permanece disponível sem filtragem dinâmica.

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

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

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

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 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:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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-7",
    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 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 é 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ído no contexto. Se o conteúdo buscado exceder este limite, a ferramenta o trunca. 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 busca na web. Defina "citations": {"enabled": true} para permitir que Claude cite passagens específicas de documentos buscados.

Resposta

Aqui está um exemplo de estrutura de resposta:

{
  "role": "assistant",
  "content": [
    // 1. Decisão do 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 do 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 é 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 Claude API 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 de 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: 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 buscar apenas 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 busca na web para coleta de informações abrangente:

client = anthropic.Anthropic()

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

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

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 do 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 da 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..."}}}}}

// A resposta do Claude continua...

Requisições em lote

Você pode incluir a ferramenta de busca na web na API de Lotes de Mensagens. Chamadas de ferramenta 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

Próximas etapas