--- title: Ferramenta de pesquisa na web url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool description: Dê ao Claude acesso a conteúdo atual da web com fontes citadas, filtragem dinâmica opcional e controles de domínio. featureMetadata: status: stable zdr: eligibility: eligible note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Resultados de busca na web em tempo real retornados na resposta da API. A filtragem dinâmica da busca na web não é elegível para ZDR nem para HIPAA. supportedModels: - claude-fable-5-2 - claude-mythos-5-2 - claude-fable-5-1 - claude-mythos-5-1 - claude-fable-5 - claude-mythos-5 - claude-mythos-preview - claude-opus-5-5 - claude-opus-5 - claude-sonnet-5-5 - claude-sonnet-5 - claude-haiku-5-5 - claude-haiku-4-5-20251001 - claude-opus-4-8 - claude-opus-4-7 - claude-opus-4-6 - claude-sonnet-4-6 - claude-opus-4-5-20251101 - claude-sonnet-4-5-20250929 supportedPlatforms: Claude API: stable Claude Platform on AWS: stable Claude Models on Google Cloud (Anthropic managed): stable Claude Models on Google Cloud (Google managed): availability: stable note: Somente a ferramenta básica de busca na web (`web_search_20250305`), sem filtragem dinâmica. Microsoft Foundry: availability: stable note: Somente a ferramenta básica de busca na web (`web_search_20250305`), sem filtragem dinâmica. --- **Suporte da API**: O uso varia conforme o produto. * **Messages API**: Adicione uma ferramenta `web_search` às `tools` da requisição. Configurações como `max_uses`, listas de domínios e `user_location` ficam nessa ferramenta. * **Managed Agents**: Ativada por padrão no conjunto de ferramentas do agente, sem `max_uses`, `citations` ou `cache_control`. A ferramenta de pesquisa na web dá ao Claude acesso direto a conteúdo da web em tempo real, permitindo que ele responda a perguntas com informações atualizadas além de sua data de corte de conhecimento. A resposta inclui citações das fontes extraídas dos resultados da pesquisa. Com `web_search_20260209` e versões posteriores, o Claude pode escrever e executar código que filtra os resultados da pesquisa antes que eles cheguem à “context window” (janela de contexto) (**“dynamic filtering” (filtragem dinâmica)**), mantendo apenas as informações relevantes. A filtragem dinâmica está disponível com o Claude 4.6 e modelos posteriores e com o [Claude Mythos Preview](https://anthropic.com/glasswing). Três versões da ferramenta de pesquisa na web estão disponíveis: * `web_search_20250305`: pesquisa na web básica * `web_search_20260209`: adiciona [filtragem dinâmica](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#dynamic-filtering) * `web_search_20260318`: adiciona controle de [inclusão na resposta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#response-inclusion) para fluxos de trabalho agênticos Os exemplos nesta página usam `web_search_20250305` para pesquisa básica e `web_search_20260318` para filtragem dinâmica. Para o [Claude Mythos Preview](https://anthropic.com/glasswing), a pesquisa na web é suportada na Claude API, no Claude Models on Google Cloud (Google managed) e no Microsoft Foundry. Para a elegibilidade da pesquisa na web para retenção zero de dados e a configuração relacionada `allowed_callers`, consulte [Ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers). Para suporte de modelos, consulte a [Referência de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference). Para verificar se um modelo aceita pesquisa na web antes de enviar uma solicitação, leia o valor `capabilities.server_tools.web_search.supported` na Models API. [Usando a Models API](https://platform.claude.com/docs/pt-BR/models/overview#using-the-models-api) descreve o campo. ## Como a pesquisa na web funciona Quando você adiciona a ferramenta de pesquisa na web à sua solicitação de API: 1. O Claude determina quando pesquisar com base no prompt. 2. A API executa as pesquisas e fornece os resultados ao Claude. Esse processo pode se repetir várias vezes ao longo de uma única solicitação. 3. No final do seu turno, o Claude fornece uma resposta final com fontes citadas. ### Quando o Claude pesquisa O Claude pesquisa quando a solicitação depende de informações atuais, em mudança ou fora de seus dados de treinamento: * Eventos recentes, notícias ou anúncios * Preços, taxas, placares ou estatísticas atuais * Informações sobre organizações, pessoas ou produtos específicos que podem ter mudado * Solicitações explícitas para pesquisar ou consultar algo O Claude responde diretamente sem pesquisar quando a solicitação se baseia em conhecimento estável: * Fatos estabelecidos, matemática, fundamentos de ciências ou conceitos de programação * Escrita criativa ou brainstorming * Análise de conteúdo já fornecido na conversa * Turnos de conversa e saudações O acionamento pode ser direcionado pelo seu “system prompt” (prompt do sistema): você pode incentivar o Claude a pesquisar com mais facilidade ou a preferir responder diretamente. Para impor um limite, use [`max_uses`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#max-uses) para limitar o número de pesquisas em um turno. ### Filtragem dinâmica Com a pesquisa na web básica, todos os resultados da pesquisa são carregados na janela de contexto do Claude, e grande parte desse conteúdo pode ser irrelevante para a solicitação. Com `web_search_20260209` ou posterior, o Claude, em vez disso, escreve e executa código que filtra os resultados primeiro, de modo que apenas o conteúdo relevante chega à janela de contexto. Isso reduz o uso de tokens em solicitações com muitas pesquisas. A filtragem dinâmica executa a pesquisa na web de dentro da [execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool): em `web_search_20260209` e posteriores, o campo `allowed_callers` da ferramenta tem como padrão `["code_execution_20260120"]`, e quando a filtragem dinâmica é executada, a API provisiona automaticamente a execução de código de que precisa para a solicitação. Você não precisa adicionar a ferramenta de execução de código a `tools` por conta própria. Não há cobranças adicionais pelas chamadas de execução de código feitas dessa forma além dos custos padrão de tokens. Para chamar a pesquisa na web diretamente, sem filtragem dinâmica, defina `allowed_callers: ["direct"]`. Modelos que não suportam chamada programática de ferramentas exigem essa configuração. Sem ela, a API retorna um erro 400 que informa para defini-la. A ferramenta de pesquisa na web (com e sem filtragem dinâmica) está disponível na Claude API, no [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), no [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed) e no [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry). No Microsoft Foundry, as implantações [hospedadas no Azure](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure) suportam apenas a ferramenta de pesquisa na web básica (`web_search_20250305`, sem filtragem dinâmica). As implantações hospedadas na Anthropic suportam todas as versões. No Claude Models on Google Cloud (Google managed), apenas a ferramenta de pesquisa na web básica (sem filtragem dinâmica) está disponível. Os exemplos a seguir usam `web_search_20260318`: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2026-10-21" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." } ], "tools": [{ "type": "web_search_20260318", "name": "web_search" }] }' ``` ```bash CLI ant messages create <<'YAML' model: claude-opus-5-5 max_tokens: 4096 messages: - role: user content: >- Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio. tools: - type: web_search_20260318 name: web_search YAML ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-5-5", max_tokens=4096, messages=[ { "role": "user", "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.", } ], tools=[{"type": "web_search_20260318", "name": "web_search"}], ) print(response) ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 4096, messages: [ { role: "user", content: "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." } ], tools: [{ type: "web_search_20260318", name: "web_search" }] }); console.log(response); ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = [new UserMessageParam { Content = "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." }], Tools = [new ToolUnion(new WebSearchTool20260318())] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.")), }, Tools: []anthropic.ToolUnionParam{ {OfWebSearchTool20260318: &anthropic.WebSearchTool20260318Param{}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```java Java import com.anthropic.models.messages.WebSearchTool20260318; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addUserMessage("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.") .addTool(WebSearchTool20260318.builder().build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP $client = new Client(); $message = $client->messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => 'Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.'], ], model: Model::CLAUDE_OPUS_5_5, tools: [ [ 'type' => 'web_search_20260318', 'name' => 'web_search', ], ], ); echo $message; ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: Anthropic::Model::CLAUDE_OPUS_5_5, max_tokens: 4096, messages: [ { role: "user", content: "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." } ], tools: [{ type: "web_search_20260318", name: "web_search" }] ) puts message ``` ## Como usar a pesquisa na web A pesquisa na web está habilitada para sua organização, a menos que um administrador a tenha desabilitado no [Claude Console](https://platform.claude.com/settings/capabilities), onde também é possível restringir em quais domínios ela pesquisa. Se estiver desabilitada, uma solicitação da Messages API que inclua a ferramenta falha com um `invalid_request_error` 400 informando que a pesquisa na web não está habilitada, em vez de um [código de erro](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#errors) dentro de um resultado de pesquisa. Para saber como as configurações de pesquisa na web da sua organização se aplicam em sessões do Claude Managed Agents, consulte [Restringir domínios de pesquisa na web e web fetch](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions). Forneça a ferramenta de pesquisa na web em sua solicitação de API: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2026-10-21" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "What is the weather in NYC?" } ], "tools": [{ "type": "web_search_20250305", "name": "web_search", "max_uses": 5 }] }' ``` ```bash CLI ant messages create \ --model claude-opus-5-5 \ --max-tokens 4096 \ --message '{role: user, content: What is the weather in NYC?}' \ --tool '{type: web_search_20250305, name: web_search, max_uses: 5}' ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-5-5", max_tokens=4096, messages=[{"role": "user", "content": "What's the weather in NYC?"}], tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}], ) print(response) ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 4096, messages: [ { role: "user", content: "What's the weather in NYC?" } ], tools: [ { type: "web_search_20250305", name: "web_search", max_uses: 5 } ] }); console.log(response); ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 4096, Messages = [new UserMessageParam { Content = "What's the weather in NYC?" }], Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 5 })] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 4096, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in NYC?")), }, Tools: []anthropic.ToolUnionParam{ {OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{ MaxUses: anthropic.Int(5), }}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```java Java import com.anthropic.models.messages.WebSearchTool20250305; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(4096L) .addUserMessage("What's the weather in NYC?") .addTool(WebSearchTool20250305.builder() .maxUses(5L) .build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP $client = new Client(); $message = $client->messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => "What's the weather in NYC?"], ], model: Model::CLAUDE_OPUS_5_5, tools: [ [ 'type' => 'web_search_20250305', 'name' => 'web_search', 'max_uses' => 5, ], ], ); echo $message; ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: Anthropic::Model::CLAUDE_OPUS_5_5, max_tokens: 4096, messages: [ { role: "user", content: "What's the weather in NYC?" } ], tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 5 }] ) puts message ``` ## Definição da ferramenta A ferramenta de pesquisa na web suporta os seguintes parâmetros: ```json JSON { "type": "web_search_20250305", "name": "web_search", // Optional: Limit the number of searches "max_uses": 5, // Optional: Only include results from these domains. // Use allowed_domains or blocked_domains, not both. "allowed_domains": ["example.com", "trusteddomain.org"], // Optional: Never include results from these domains "blocked_domains": ["untrustedsource.com"], // Optional: Localize search results "user_location": { "type": "approximate", "city": "San Francisco", "region": "California", "country": "US", "timezone": "America/Los_Angeles" } } ``` Todas as versões da ferramenta de pesquisa na web aceitam `allowed_callers`, que controla se o Claude chama a pesquisa na web diretamente ou a partir da execução de código por meio da [filtragem dinâmica](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#dynamic-filtering). Em `web_search_20260209` e posteriores, o padrão é `["code_execution_20260120"]` em vez de `["direct"]`. Consulte [ZDR e allowed\_callers](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers) para saber como configurá-lo. `web_search_20260318` e posteriores também aceitam [`response_inclusion`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#response-inclusion). ### Usos máximos O parâmetro `max_uses` limita o número de pesquisas em um único turno. Consultas sobre um único fato normalmente usam de 1 a 3 pesquisas; pesquisas comparativas ou com múltiplas entidades podem usar 10 ou mais. Pesquisas com falha contam para o limite. Se o Claude chamar a pesquisa na web diretamente mais vezes do que o permitido, o `web_search_tool_result` será um erro com o código de erro `max_uses_exceeded`. Se o Claude chamar a pesquisa na web a partir da execução de código mais vezes do que o permitido, a execução de código termina com um erro. Um turno pode abranger várias solicitações. Uma solicitação continua um turno quando é retomada após [`pause_turn`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn) ou quando sua última mensagem contém apenas blocos `tool_result`. Pesquisas de solicitações anteriores nesse turno contam para o limite, a menos que o Claude as tenha executado a partir da execução de código por meio da [filtragem dinâmica](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#dynamic-filtering). ### Filtragem de domínios Forneça `allowed_domains` ou `blocked_domains`, não ambos. Se uma solicitação incluir ambos, a API retorna um erro 400. As entradas são domínios simples com um caminho opcional, por exemplo `example.com` ou `example.com/blog`, sem esquema. Para as regras completas de filtragem de domínios, consulte [Filtragem de domínios](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#domain-filtering) no guia de Ferramentas de servidor. No [Claude Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview), defina esses campos na entrada `web_search` do conjunto de ferramentas do agente; consulte [Restringir domínios de pesquisa na web e web fetch](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions). ### Localização O parâmetro `user_location` permite localizar os resultados da pesquisa com base na localização de um usuário. Forneça pelo menos um entre `city`, `region`, `country` ou `timezone`. * `type`: O tipo de localização (deve ser `approximate`) * `city`: O nome da cidade * `region`: A região ou estado * `country`: O código de país de duas letras [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (a API rejeita um código não suportado com um erro 400) * `timezone`: O [ID de fuso horário IANA](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) No Claude Managed Agents, a entrada `web_search` do conjunto de ferramentas do agente também aceita `user_location`; consulte as [configurações das ferramentas web](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#settings). ### Inclusão na resposta Requer `web_search_20260318` ou posterior. O parâmetro `response_inclusion` controla como os blocos de resultados de pesquisa aparecem na resposta da API quando uma chamada de [execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool) concluída na mesma resposta consumiu o resultado. 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 pesquisa. O uso de tokens não é afetado, porque o 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 pausaram antes de serem concluídas, para que você possa enviá-los de volta na próxima solicitação. ```json JSON { "tools": [ { "type": "web_search_20260318", "name": "web_search", "response_inclusion": "excluded" } ] } ``` ## Resposta Aqui está um exemplo de estrutura de resposta: ```json Output { "role": "assistant", "content": [ // 1. Claude's decision to search { "type": "text", "text": "I'll search for when Claude Shannon was born." }, // 2. The search query used { "type": "server_tool_use", "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE", "name": "web_search", "input": { "query": "claude shannon birth date" } }, // 3. Search results { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE", "content": [ { "type": "web_search_result", "url": "https://en.wikipedia.org/wiki/Claude_Shannon", "title": "Claude Shannon - Wikipedia", "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...", "page_age": "April 30, 2025" } ] }, { "text": "Based on the search results, ", "type": "text" }, // 4. Claude's response with citations { "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan", "type": "text", "citations": [ { "type": "web_search_result_location", "url": "https://en.wikipedia.org/wiki/Claude_Shannon", "title": "Claude Shannon - Wikipedia", "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..", "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..." } ] } ], "id": "msg_a930390d3a", "usage": { "input_tokens": 6039, "output_tokens": 931, "server_tool_use": { "web_search_requests": 1 } }, "stop_reason": "end_turn" } ``` Este exemplo mostra uma pesquisa direta. Quando uma pesquisa é executada por meio da [filtragem dinâmica](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool#dynamic-filtering), a resposta também contém os blocos de resultado da [ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool), e cada par aninhado de `server_tool_use` e `web_search_tool_result` carrega um campo `caller` que identifica a chamada de execução de código que o gerou. ### Resultados da pesquisa Os resultados da pesquisa incluem: * `url`: A URL da página de origem * `title`: O título da página de origem * `page_age`: Quando o site foi atualizado pela última vez * `encrypted_content`: Conteúdo criptografado que você deve enviar de volta em conversas de múltiplos turnos Para continuar uma conversa que contém resultados de pesquisa, envie os blocos de conteúdo do assistente de volta exatamente como você os recebeu, incluindo o `encrypted_content` de cada resultado. A API descriptografa esse conteúdo em solicitações posteriores para restaurar os resultados da pesquisa no contexto do Claude. Se `encrypted_content` estiver ausente ou modificado, a solicitação falha com um erro de validação 400. ### Citações As citações estão sempre habilitadas para a pesquisa na web, e cada `web_search_result_location` inclui: * `url`: A URL da fonte citada * `title`: O título da fonte citada * `encrypted_index`: Uma referência que deve ser enviada de volta em conversas de múltiplos turnos * `cited_text`: Até 150 caracteres do conteúdo citado Os campos de citação da pesquisa na web `cited_text`, `title` e `url` não contam para o uso de tokens de entrada ou de saída. Ao exibir saídas da API diretamente para usuários finais, as citações da fonte original devem ser incluídas. Se você estiver fazendo modificações nas saídas da API, incluindo reprocessá-las ou combiná-las com seu próprio material antes de exibi-las aos usuários finais, exiba as citações conforme apropriado com base em consulta à sua equipe jurídica. ### Erros Quando a ferramenta de pesquisa na web encontra um erro (como atingir limites de taxa), a Claude API ainda retorna uma resposta 200 (sucesso). O erro é representado no corpo da resposta usando a seguinte estrutura: ```json Output { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_a93jad", "content": { "type": "web_search_tool_result_error", "error_code": "max_uses_exceeded" } } ``` Em caso de erro, `content` é um único objeto de erro em vez de uma lista de blocos de resultado. Uma pesquisa bem-sucedida que não encontra resultados retorna uma lista `content` vazia, não um erro. Estes são os códigos de erro possíveis: * `too_many_requests`: Limite de taxa excedido * `invalid_tool_input`: Parâmetro de consulta de pesquisa inválido * `max_uses_exceeded`: Número máximo de usos da ferramenta de pesquisa na web excedido * `query_too_long`: A consulta excede o comprimento máximo * `request_too_large`: A solicitação de pesquisa é grande demais, normalmente devido a uma lista longa de filtros de domínio * `unavailable`: Ocorreu um erro interno ### Motivo de parada `pause_turn` A API pode pausar um turno de pesquisa de longa duração e retornar `stop_reason: "pause_turn"`. Para continuar, envie a mensagem pausada do assistente de volta, sem alterações, em uma nova solicitação. Se o Claude chamar a pesquisa na web e uma de suas ferramentas de cliente no mesmo grupo de chamadas de ferramentas paralelas, a API retorna `stop_reason: "tool_use"` em vez disso e ainda não executa a pesquisa. Para continuar, retorne os resultados das ferramentas de cliente, e a API executa a pesquisa na próxima solicitação. Consulte [Combinando ferramentas de servidor e ferramentas de cliente em um turno](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn). Para o loop do lado do servidor e o tratamento de `pause_turn`, consulte [O loop do lado do servidor e pause\_turn](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn) no guia de Ferramentas de servidor. ## Cache de prompt Para armazenar em cache definições de ferramentas entre turnos, consulte [Uso de ferramentas com cache de prompt](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-use-with-prompt-caching). ## Streaming Com o streaming habilitado, você recebe eventos de pesquisa como parte do stream. Há uma pausa enquanto a pesquisa é executada: ```sse Output 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 search event: content_block_start data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}} // Search query streamed event: content_block_delta data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}} // Pause while search runs // Search results streamed event: content_block_start data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}} // Claude's response with citations (omitted in this example) ``` ## Solicitações em lote Você pode incluir a ferramenta de pesquisa na web na [Message Batches API](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing). As chamadas da ferramenta de pesquisa na web por meio da Message Batches API têm o mesmo preço que as de solicitações regulares da Messages API. Para proteger a capacidade compartilhada, a Batches API limita as solicitações de pesquisa na web de cada organização, portanto lotes grandes com muitas pesquisas podem levar mais tempo para serem concluídos. Você pode ver o limite de taxa de pesquisa na web da sua organização na página [Limites de taxa](https://platform.claude.com/usage/limits) no Claude Console. Para solicitar um limite maior, entre em contato com a equipe de vendas nessa página. ## Uso e preços O uso da pesquisa na web é cobrado além do uso de tokens: ```json { "usage": { "input_tokens": 105, "output_tokens": 6039, "cache_read_input_tokens": 7123, "cache_creation_input_tokens": 7345, "server_tool_use": { "web_search_requests": 1 } } } ``` A pesquisa na web está disponível na Claude API por **$10 USD a cada 1.000 pesquisas**, mais os custos padrão de tokens para o conteúdo gerado pela pesquisa. Os resultados de pesquisa na web recuperados ao longo de uma conversa são contabilizados como “input tokens” (tokens de entrada), tanto nas iterações de pesquisa executadas durante um único turno quanto nos turnos subsequentes da conversa. Cada pesquisa na web conta como um uso, independentemente do número de resultados retornados. Uma pesquisa na web que falha com um erro não é cobrada. ## Próximos passos Busque e leia conteúdo de URLs específicas para ampliar o contexto do Claude com conteúdo da web em tempo real. 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 Ferramenta de pesquisa na web está disponível em todos os modelos e é elegível para retenção zero de dados e prontidão para HIPAA. ### Suporte da API #### [Messages API](https://platform.claude.com/docs/pt-BR/build-with-claude/working-with-messages) * Disponibilidade: Disponível * Uso: Adicione uma ferramenta `web_search` às `tools` da requisição. Configurações como `max_uses`, listas de domínios e `user_location` ficam nessa ferramenta. | Status | Plataformas de nuvem | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Disponível | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry) | | Disponível1 | [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry (hosted on Azure)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry) | 1. Somente a ferramenta básica de busca na web (`web_search_20250305`), sem filtragem dinâmica. #### [Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview) * Disponibilidade: Disponível * Uso: Faz parte do conjunto de ferramentas do agente e fica ativada por padrão depois que o conjunto de ferramentas é adicionado. As listas de domínios e `user_location` ficam na entrada `web_search` do conjunto de ferramentas; `max_uses`, `citations` e `cache_control` não estão disponíveis. | Status | Plataformas de nuvem | | ---------- | --------------------------------------------------------------------------------------------------------------------- | | Disponível | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws) | ### Tratamento de dados [Visão geral do tratamento de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#feature-eligibility) | Item | Retenção zero de dados | HIPAA | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | Status | Elegível (exclui [Modelos cobertos](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Elegível | | Detalhes | Resultados de busca na web em tempo real retornados na resposta da API. A filtragem dinâmica da busca na web não é elegível para ZDR nem para HIPAA. | A filtragem dinâmica da busca na web não é elegível para ZDR nem para HIPAA. | Endpoints aplicáveis: * `/v1/messages` com a ferramenta `web_search`