Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
As ferramentas executadas no servidor compartilham estas mecânicas: o bloco server_tool_use, a continuação com pause_turn, turnos que misturam ferramentas de servidor e de cliente, elegibilidade para Zero Data Retention (ZDR) e filtragem de domínios. Para ferramentas individuais, consulte a referência de ferramentas.
O bloco server_tool_use aparece na resposta de Claude quando uma ferramenta executada no servidor é executada. Seu campo id usa o prefixo srvtoolu_ para distingui-lo de chamadas de ferramentas de cliente:
{
"type": "server_tool_use",
"id": "srvtoolu_01A2B3C4D5E6F7G8H9",
"name": "web_search",
"input": { "query": "latest quantum computing breakthroughs" }
}A API executa a ferramenta internamente. Você vê a chamada e seu resultado na resposta, mas não lida com a execução. Diferentemente dos blocos tool_use de cliente, você não precisa responder com um tool_result. O bloco de resultado da ferramenta (por exemplo, web_search_tool_result para busca na web) segue o bloco server_tool_use no mesmo turno do assistente, pareado por tool_use_id. Se Claude chamar uma de suas ferramentas de cliente ao mesmo tempo, o bloco server_tool_use aparece sem seu resultado, e a resposta termina com stop_reason: "tool_use". A API executa a ferramenta quando você retorna os blocos tool_result de cliente em sua próxima solicitação.
Ao usar ferramentas de servidor como busca na web, a API executa chamadas de ferramentas em um loop agêntico do lado do servidor. Em um turno de longa duração, a API pode pausar esse loop e retornar um motivo de parada pause_turn.
Veja como lidar com o motivo de parada pause_turn:
client = anthropic.Anthropic()
# Requisição inicial com busca na web
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
}
],
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)
# Verifica se a resposta tem o stop reason pause_turn
if response.stop_reason == "pause_turn":
# Continua a conversa com o conteúdo pausado
messages = [
{
"role": "user",
"content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
},
{"role": "assistant", "content": response.content},
]
# Envia a requisição de continuação
continuation = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=messages,
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)
print(continuation)
else:
print(response)Ao lidar com pause_turn:
server_tool_use cuja ferramenta ainda não foi executada, e a API retorna um erro de validação se essa ferramenta estiver ausente na continuação.stop_reason em cada resposta e continue até obter um motivo de parada diferente, limitando o número de continuações como faria com qualquer loop de nova tentativa.Para os outros valores de stop_reason e padrões gerais de tratamento, consulte Motivos de parada e fallback.
Claude pode chamar uma ferramenta de servidor e uma ferramenta de cliente no mesmo grupo de chamadas de ferramentas paralelas, por exemplo, web_fetch junto com uma ferramenta definida pelo usuário. Uma ferramenta de cliente é qualquer ferramenta que seu código executa e que produz um bloco tool_use, seja ela definida pelo usuário ou uma ferramenta de cliente com esquema da Anthropic, como a ferramenta Bash. Quando isso acontece, a API não executa a ferramenta de servidor. Ela retorna imediatamente para que você possa executar a ferramenta de cliente primeiro:
stop_reason é "tool_use", não "pause_turn".content contém o bloco server_tool_use e o bloco tool_use de cliente, mas nenhum bloco de resultado para a ferramenta de servidor: essa chamada não está concluída.server_tool_use cujo id não tenha um bloco de resultado correspondente na resposta. Um bloco mcp_tool_use do conector MCP se comporta da mesma forma. Chamadas de ferramentas de servidor que já têm seu bloco de resultado na mesma resposta estão completas e não precisam de nada de você.{
"stop_reason": "tool_use",
"content": [
{
"type": "text",
"text": "I'll fetch the article and check your system at the same time."
},
{
"type": "server_tool_use",
"id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
"name": "web_fetch",
"input": { "url": "https://example.com/article" }
},
{
"type": "tool_use",
"id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
"name": "run_command",
"input": { "command": "uname -a" }
}
]
}Para continuar o turno, execute as ferramentas de cliente e envie uma mensagem de usuário cujo conteúdo seja apenas os blocos tool_result, um para cada bloco tool_use naquela resposta. Mantenha o mesmo array tools: uma solicitação de retomada que não define mais a ferramenta de servidor em espera falha com um 400 cuja mensagem termina com but no `web_fetch` tool was provided.
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
"content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
}
]
}A API anexa seus resultados ao turno do assistente ainda aberto, executa a ferramenta de servidor adiada (para execução de código pausada, a retoma) e então permite que Claude continue. Para uma ferramenta de servidor que Claude chamou diretamente, a próxima resposta começa com o bloco de resultado que responde ao id do server_tool_use da resposta anterior, seguido pelo conteúdo recém-gerado e um novo stop_reason:
{
"stop_reason": "end_turn",
"content": [
{
"type": "web_fetch_tool_result",
"tool_use_id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
"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..."
}
}
}
},
{
"type": "text",
"text": "The article argues that... and your machine is running Linux..."
}
]
}Um bloco server_tool_use e seu bloco de resultado se emparelham por tool_use_id, não por posição: neste fluxo eles chegam em duas respostas diferentes, e o bloco server_tool_use não é repetido na segunda. Em solicitações posteriores, mantenha toda a troca em seu array messages em ordem: a primeira resposta como uma mensagem assistant, a mensagem de usuário com tool_result e, em seguida, a próxima resposta como outra mensagem assistant, da mesma forma que você acumula qualquer outra troca de uso de ferramentas.
Como isso difere de pause_turn: Uma resposta pause_turn também pode terminar com um bloco server_tool_use que não foi executado, mas ela nunca deixa um bloco tool_use de cliente aguardando você, então você a continua reenviando o conteúdo do assistente como está. Uma resposta que deixa um bloco tool_use de cliente aguardando você nunca tem um stop_reason de pause_turn: quando Claude para para chamar suas ferramentas, stop_reason é tool_use, e você a continua enviando os blocos tool_result de cliente em vez de reenviar a resposta. Em ambos os casos, a API executa a ferramenta de servidor pendente no início da próxima solicitação.
O exemplo a seguir habilita a busca web (web fetch) junto com uma ferramenta run_command definida pelo usuário e lida com a resposta mista:
client = anthropic.Anthropic()
tools = [
{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5},
{
"name": "run_command",
"description": "Run a shell command on this computer and return its output.",
"input_schema": {
"type": "object",
"properties": {
"command": {"type": "string", "description": "The command to run"}
},
"required": ["command"],
},
},
]
messages = [
{
"role": "user",
"content": "Summarize https://example.com/article and run uname -a to tell me what system this is on.",
}
]
response = client.messages.create(
model="claude-opus-4-8", max_tokens=1024, tools=tools, messages=messages
)
tool_results = [
{
"type": "tool_result",
"tool_use_id": block.id,
# Execute sua ferramenta aqui. Este exemplo retorna uma string fixa.
"content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux",
}
for block in response.content
if block.type == "tool_use"
]
if response.stop_reason == "tool_use" and tool_results:
# Um bloco server_tool_use sem bloco de resultado nesta resposta não está concluído; seu resultado chega em uma resposta posterior.
# Envie de volta apenas os blocos tool_result do cliente, com as mesmas ferramentas.
continuation = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
tools=tools,
messages=[
*messages,
{"role": "assistant", "content": response.content},
{"role": "user", "content": tool_results},
],
)
# Se um web_fetch foi adiado, ele é executado nesta requisição e seu
# web_fetch_tool_result é o primeiro bloco de continuation.content.
print(continuation)
else:
print(response)Este código também está correto quando Claude não mistura os dois tipos de chamada. Um turno com apenas blocos tool_use de cliente segue o mesmo caminho de continuação, e um turno com apenas chamadas de ferramentas de servidor não precisa de blocos tool_result de cliente de você: seus blocos de resultado normalmente já estão presentes, e um que volta suspenso, como uma resposta pause_turn, é reenviado como está.
As versões básicas de busca na web (web_search_20250305) e busca de páginas web (web_fetch_20250910) são elegíveis para Zero Data Retention (ZDR).
As versões _20260209 e posteriores com filtragem dinâmica não são elegíveis para ZDR por padrão porque a filtragem dinâmica depende de execução de código internamente.
Para usar uma ferramenta de servidor _20260209 ou posterior com ZDR, desabilite a filtragem dinâmica definindo "allowed_callers": ["direct"] na ferramenta:
{
"type": "web_search_20260209",
"name": "web_search",
"allowed_callers": ["direct"]
}Isso restringe a ferramenta apenas à invocação direta, ignorando a etapa interna de execução de código.
allowed_callers controla como uma ferramenta pode ser invocada: diretamente por Claude ("direct"), de dentro de um contêiner de execução de código (por exemplo, "code_execution_20260120"), ou ambos. As versões _20260209 das ferramentas web usam por padrão apenas o chamador de execução de código; versões anteriores usam por padrão ["direct"]. Em modelos que não suportam chamada programática de ferramentas, essas versões exigem allowed_callers: ["direct"]; sem isso, a API retorna um erro de validação que indica para defini-lo.
Ferramentas de servidor que acessam a web aceitam os parâmetros allowed_domains e blocked_domains para controlar quais domínios Claude pode alcançar. Ambos são campos no objeto da ferramenta:
{
"type": "web_search_20250305",
"name": "web_search",
"allowed_domains": ["example.com", "docs.python.org"]
}Ao usar filtros de domínio:
example.com em vez de https://example.com).example.com cobre docs.example.com).docs.example.com retorna apenas resultados desse subdomínio, não de example.com ou api.example.com).example.com/blog corresponde a example.com/blog/post-1).allowed_domains ou blocked_domains, mas não ambos na mesma solicitação.Suporte a curingas:
*) não são permitidos no próprio domínio, apenas no caminho após ele.example.com/*, example.com/*/articles*.example.com, ex*.comFormatos de domínio inválidos são rejeitados no momento da solicitação com um 400 invalid_request_error.
As versões _20260209 e posteriores de busca na web e busca de páginas web usam execução de código internamente para aplicar filtros dinâmicos aos resultados de busca.
Os eventos de ferramentas de servidor são transmitidos via streaming como parte do fluxo normal de "server-sent events" (eventos enviados pelo servidor), ou SSE. Um bloco server_tool_use que Claude chama diretamente é transmitido como um bloco tool_use de cliente: um evento content_block_start seguido por eventos input_json_delta. O bloco de resultado chega completo em um único evento content_block_start, sem deltas.
Consulte Streaming para a referência completa de eventos. As páginas de ferramentas individuais documentam nomes de eventos específicos de cada ferramenta quando eles diferem.
Todas as ferramentas de servidor suportam processamento em lote. Em um lote, o loop agêntico é executado exatamente como nas solicitações síncronas, com um limite de iteração por turno mais alto. Se o loop atingir esse limite, a resposta termina com stop_reason: "pause_turn"; você pode continuá-la enviando uma solicitação de acompanhamento com o conteúdo retornado. Consulte Ferramentas de servidor e o loop agêntico para detalhes.
Cargas de trabalho em lote comuns incluem enriquecer um conjunto de dados com informações da web, verificar um grande conjunto de documentos em relação a fontes atuais e executar código de análise sobre muitos arquivos.
Corrija os erros mais comuns de uso de ferramentas com tabelas de diagnóstico de sintoma para correção.
Pesquise na web e cite resultados.
Busque e leia conteúdo de URLs específicas para aumentar o contexto de Claude com conteúdo web ao vivo.
Execute código Python e bash em um contêiner isolado (sandbox) para analisar dados, gerar arquivos e iterar em soluções.
Descubra e carregue ferramentas sob demanda.
Was this page helpful?