---
title: Ferramenta de busca 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.
---
Para saber como a "zero data retention" (retenção zero de dados), ou ZDR, se aplica a este recurso, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).
A ferramenta de busca na web ("web search tool") 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 de busca.
Com `web_search_20260209` e versões posteriores, o Claude pode escrever e executar código que filtra os resultados de busca antes que eles cheguem à "context window" (janela de contexto) (**filtragem dinâmica**, ou "dynamic filtering"), mantendo apenas as informações relevantes. A filtragem dinâmica está disponível com os modelos Claude 4.6 e posteriores e com o [Claude Mythos Preview](https://anthropic.com/glasswing).
Três versões da ferramenta de busca na web estão disponíveis:
* `web_search_20250305`: busca 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 busca básica e `web_search_20260318` para filtragem dinâmica.
Para o [Claude Mythos Preview](https://anthropic.com/glasswing), a busca na web é suportada na Claude API, no Google Cloud e no Microsoft Foundry. A busca na web não está disponível para o Mythos Preview no Amazon Bedrock ou no [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws).
Para a elegibilidade da busca na web para Zero Data Retention e a configuração relacionada de `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 busca na web antes de enviar uma requisição, leia o valor de `capabilities.server_tools.web_search.supported` do modelo 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 busca na web funciona
Quando você adiciona a ferramenta de busca na web à sua requisição de API:
1. O Claude determina quando buscar com base no prompt.
2. A API executa as buscas e fornece os resultados ao Claude. Esse processo pode se repetir várias vezes ao longo de uma única requisição.
3. Ao final de seu turno, o Claude fornece uma resposta final com fontes citadas.
### Quando o Claude busca
O Claude busca quando a requisição depende de informações que são atuais, mutáveis ou que estão fora de seus dados de treinamento:
* Eventos, notícias ou anúncios recentes
* 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 buscar ou pesquisar algo
O Claude responde diretamente sem buscar quando a requisição se baseia em conhecimento estável:
* Fatos estabelecidos, matemática, fundamentos de ciência ou conceitos de programação
* Escrita criativa ou brainstorming
* Análise de conteúdo já fornecido na conversa
* Turnos conversacionais e saudações
O acionamento é direcionável por meio do seu prompt do sistema: você pode incentivar o Claude a buscar com mais prontidão ou a preferir responder diretamente. Para uma restrição rígida, use `max_uses` para limitar o número de buscas em cada requisição.
### Filtragem dinâmica
Com a busca na web básica, todo resultado de busca é carregado na janela de contexto do Claude, e grande parte desse conteúdo pode ser irrelevante para a requisiçã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 chegue à janela de contexto. Isso reduz o uso de tokens em requisições com muitas buscas.
A filtragem dinâmica executa a busca 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"]`. Quando a filtragem dinâmica é executada, a API provisiona automaticamente a execução de código necessária para a requisição. Você não precisa adicionar a ferramenta de execução de código a `tools`. As chamadas de execução de código feitas dessa forma não geram cobranças adicionais além dos custos padrão de tokens.
Para chamar a busca na web diretamente, sem filtragem dinâmica, defina `allowed_callers: ["direct"]`. Os modelos que não oferecem suporte à chamada programática de ferramentas exigem essa configuração. Sem ela, a API retorna um erro 400 que pede que você a defina.
A ferramenta de busca 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) 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) oferecem suporte apenas à ferramenta de busca na web básica (`web_search_20250305`, sem filtragem dinâmica). As implantações hospedadas na Anthropic oferecem suporte a todas as versões. No Google Cloud, apenas a ferramenta de busca na web básica (sem filtragem dinâmica) está disponível. A busca na web não está disponível no Amazon Bedrock.
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: 2023-06-01" \
-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() { Role = Role.User, 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: '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: "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 busca na web
A pesquisa na web está habilitada para a 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 quais domínios ela pesquisa. Se ela estiver desabilitada, uma solicitação que inclua a ferramenta falha com um erro 400 `invalid_request_error` 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.
Essas configurações no nível da organização no Claude Console se aplicam apenas a requisições da Messages API. As sessões do [Claude Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview) usam, em vez disso, as listas `allowed_domains` e `blocked_domains` por ferramenta no conjunto de ferramentas do agente; consulte [Restringir domínios de pesquisa na web e busca na web](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions). Para uma sessão em um ambiente de nuvem com rede `limited`, o `allowed_hosts` do ambiente também se aplica a `web_search` e `web_fetch`; consulte [Rede](https://platform.claude.com/docs/pt-BR/managed-agents/environments#networking). As listas por ferramenta restringem ainda mais essas ferramentas, dentro dos hosts que `allowed_hosts` permite.
Forneça a ferramenta de busca na web na sua requisição de API:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"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 1024 \
--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=1024,
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: 1024,
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 = 1024,
Messages = [new() { Role = Role.User, 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: 1024,
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(1024L)
.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: 1024,
messages: [
['role' => 'user', 'content' => "What's the weather in NYC?"],
],
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: "claude-opus-5-5",
max_tokens: 1024,
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 busca na web suporta os seguintes parâmetros:
```json JSON
{
"type": "web_search_20250305",
"name": "web_search",
// Optional: Limit the number of searches per request
"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 busca na web aceitam `allowed_callers`, que controla se o Claude chama a busca 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 [Ferramentas de servidor](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).
### Máximo de usos
O parâmetro `max_uses` limita o número de buscas realizadas. Se o Claude tentar mais buscas do que o permitido, o `web_search_tool_result` será um erro com o código de erro `max_uses_exceeded`.
Consultas factuais simples normalmente usam de 1 a 3 buscas; pesquisas comparativas ou com múltiplas entidades podem usar 10 ou mais. Para orientação sobre como escolher um valor, consulte [Ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools).
### Filtragem de domínios
Forneça `allowed_domains` ou `blocked_domains`, não ambos. Se uma requisiçã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 busca na web](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions).
### Localização
O parâmetro `user_location` permite localizar os resultados de busca 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 códigos de país não suportados 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 aceita um objeto `user_location` com os mesmos campos. A API rejeita um código `country` não suportado com um erro 400 quando você cria ou atualiza o agente, ou quando cria ou atualiza uma sessão que fornece a configuração. 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 resultado de busca aparecem na resposta da API quando o resultado foi consumido por 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 no mesmo turno. Defina `"response_inclusion": "excluded"` para remover completamente da resposta esses pares aninhados de `server_tool_use` e bloco 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 busca 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.
```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 busca direta. Quando uma busca é 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` identificando a chamada de execução de código que o originou.
### Resultados de busca
Os resultados de busca 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 busca, 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 turnos posteriores para restaurar os resultados de busca no contexto do Claude. Se `encrypted_content` estiver ausente ou modificado, a requisição falha com um erro de validação 400.
### Citações
As citações estão sempre habilitadas para a busca 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 busca na web `cited_text`, `title` e `url` não contam para o uso de tokens de entrada ou 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, inclusive reprocessando-as ou combinando-as 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 busca na web encontra um erro (como atingir limites de taxa), a Claude API ainda retorna uma resposta 200 (sucesso). O erro é representado dentro do 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 busca que é bem-sucedida mas 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 busca inválido
* `max_uses_exceeded`: Máximo de usos da ferramenta de busca na web excedido
* `query_too_long`: A consulta excede o comprimento máximo
* `request_too_large`: A requisição de busca é grande demais, normalmente devido a uma longa lista de filtros de domínio
* `unavailable`: Ocorreu um erro interno
### Motivo de parada `pause_turn`
A API pode pausar um turno de busca de longa duração e retornar `stop_reason: "pause_turn"`. Para continuar, envie a mensagem do assistente pausada de volta, sem alterações, em uma nova requisição.
Se o Claude chamar a busca 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 busca. Para continuar, retorne os resultados da ferramenta de cliente, e a API executa a busca na próxima requisição. Consulte [Misturando 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ê receberá eventos de busca como parte do stream. Haverá uma pausa enquanto a busca é 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 executes
// 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)
```
## Requisições em lote
Você pode incluir a ferramenta de busca na web na [Messages Batches API](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing). Chamadas da ferramenta de busca na web por meio da Messages Batches API têm o mesmo preço que aquelas em requisições regulares da Messages API.
Para proteger a capacidade compartilhada, a Batches API limita as requisições de busca na web por organização, portanto lotes grandes com muitas buscas podem levar mais tempo para serem concluídos. Você pode ver o limite de taxa de busca 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 a partir dessa 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 por 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 contados como 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. Se ocorrer um erro durante a pesquisa na web, a pesquisa na web não será cobrada.
## Próximos passos
Busque e leia conteúdo de URLs específicas para ampliar o contexto do Claude com conteúdo da web ao vivo.
Trabalhe com ferramentas executadas pela Anthropic: blocos server\_tool\_use, continuação de 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.