Strumenti server

Gli strumenti eseguiti lato server condividono queste meccaniche: il blocco server_tool_use, la continuazione pause_turn, i turni che combinano strumenti server e client, l'idoneità alla "Zero Data Retention" (conservazione zero dei dati), o ZDR, e il filtraggio dei domini. Per i singoli strumenti, consulta il riferimento agli strumenti.



Il blocco server_tool_use

Il blocco server_tool_use appare nella risposta di Claude quando viene eseguito uno strumento lato server. Il suo campo id utilizza il prefisso srvtoolu_ per distinguerlo dalle chiamate agli strumenti client:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01A2B3C4D5E6F7G8H9",
  "name": "web_search",
  "input": { "query": "latest quantum computing breakthroughs" }
}

L'API esegue lo strumento internamente. Vedi la chiamata e il suo risultato nella risposta, ma non gestisci l'esecuzione. A differenza dei blocchi tool_use client, non devi rispondere con un tool_result. Il blocco del risultato dello strumento (ad esempio, web_search_tool_result per la ricerca web) segue il blocco server_tool_use nello stesso turno dell'assistente, abbinato tramite tool_use_id. Se Claude chiama contemporaneamente uno dei tuoi strumenti client, il blocco server_tool_use appare senza il suo risultato e la risposta termina con stop_reason: "tool_use". L'API esegue lo strumento quando restituisci i blocchi tool_result client nella tua richiesta successiva.



Il loop lato server e pause_turn

Quando si utilizzano strumenti server come la ricerca web, l'API esegue le chiamate agli strumenti in un loop agentico lato server. In un turno di lunga durata, l'API potrebbe mettere in pausa quel loop e restituire uno stop reason pause_turn.

Ecco come gestire lo stop reason pause_turn:

client = anthropic.Anthropic()

# Richiesta iniziale con ricerca web
response = client.messages.create(
    model="claude-opus-4-8",
    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 la risposta ha stop_reason pause_turn
if response.stop_reason == "pause_turn":
    # Continua la conversazione con il contenuto in pausa
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Invia la richiesta di continuazione
    continuation = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)

Quando gestisci pause_turn:

• Continua la conversazione: Passa la risposta in pausa così com'è in una richiesta successiva per permettere a Claude di continuare il suo turno.
• Preserva lo stato degli strumenti: Includi gli stessi strumenti nella richiesta di continuazione. Un turno in pausa può terminare con un blocco server_tool_use il cui strumento non è ancora stato eseguito, e l'API restituisce un errore di validazione se quello strumento manca dalla continuazione.
• Ripeti secondo necessità: Un turno continuato può andare nuovamente in pausa. Controlla stop_reason su ogni risposta e continua finché non ottieni uno stop reason diverso, limitando il numero di continuazioni come faresti con qualsiasi loop di retry.

Per gli altri valori di stop_reason e i pattern generali di gestione, consulta Stop reason e fallback.



Combinare strumenti server e strumenti client in un unico turno

Claude può chiamare uno strumento server e uno strumento client nello stesso gruppo di chiamate parallele agli strumenti, ad esempio web_fetch insieme a uno strumento definito dall'utente. Uno strumento client è qualsiasi strumento che il tuo codice esegue e che produce un blocco tool_use, sia esso definito dall'utente o uno strumento client con schema Anthropic come lo strumento Bash. Quando ciò accade, l'API non esegue lo strumento server. Restituisce immediatamente in modo che tu possa eseguire prima lo strumento client:

• stop_reason è "tool_use", non "pause_turn".
• content contiene il blocco server_tool_use e il blocco tool_use client, ma nessun blocco di risultato per lo strumento server: quella chiamata non è terminata.
• Non c'è nessun altro indicatore. Rileva lo stato cercando un blocco server_tool_use il cui id non ha un blocco di risultato corrispondente nella risposta. Un blocco mcp_tool_use dal connettore MCP si comporta allo stesso modo. Le chiamate agli strumenti server che hanno già il loro blocco di risultato nella stessa risposta sono complete e non richiedono nulla da parte tua.

{
  "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" }
    }
  ]
}

Per continuare il turno, esegui gli strumenti client e invia un messaggio utente il cui contenuto è costituito solo dai blocchi tool_result, uno per ogni blocco tool_use in quella risposta. Mantieni lo stesso array tools: una richiesta di ripresa che non definisce più lo strumento server in attesa fallisce con un errore 400 il cui messaggio termina con 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"
    }
  ]
}

L'API allega i tuoi risultati al turno dell'assistente ancora aperto, esegue lo strumento server differito (per l'esecuzione di codice in pausa, la riprende), e poi lascia che Claude continui. Per uno strumento server che Claude ha chiamato direttamente, la risposta successiva inizia con il blocco di risultato che risponde all'id del server_tool_use della risposta precedente, seguito dal contenuto appena generato e da un nuovo 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..."
    }
  ]
}

Un blocco server_tool_use e il suo blocco di risultato si abbinano tramite tool_use_id, non per posizione: in questo flusso arrivano in due risposte diverse, e il blocco server_tool_use non viene ripetuto nella seconda. Nelle richieste successive, mantieni l'intero scambio nel tuo array messages in ordine: la prima risposta come messaggio assistant, il messaggio utente tool_result, e poi la risposta successiva come un altro messaggio assistant, nello stesso modo in cui accumuli qualsiasi altro scambio di uso degli strumenti.

`web_fetch` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_fetch_tool_result` block

`tool_use` ids were found without `tool_result` blocks immediately after: toolu_01PjgRJLbXrXEMZwDNYLnBqk. Each `tool_use` block must have a corresponding `tool_result` block in the next message.

In cosa differisce da pause_turn: Anche una risposta pause_turn può terminare con un blocco server_tool_use che non è stato eseguito, ma non lascia mai un blocco tool_use client in attesa da parte tua, quindi la continui reinviando il contenuto dell'assistente così com'è. Una risposta che lascia un blocco tool_use client in attesa da parte tua non ha mai uno stop_reason di pause_turn: quando Claude si ferma per chiamare i tuoi strumenti, stop_reason è tool_use, e la continui inviando i blocchi tool_result client anziché reinviando la risposta. In entrambi i casi l'API esegue lo strumento server in sospeso all'inizio della richiesta successiva.

L'esempio seguente abilita web fetch insieme a uno strumento run_command definito dall'utente e gestisce la risposta 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,
        # Esegui qui il tuo strumento. Questo esempio restituisce una stringa fissa.
        "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:
    # Un blocco server_tool_use senza blocco di risultato in questa risposta non è terminato; il suo risultato arriva in una risposta successiva.
    # Rinvia solo i blocchi tool_result del client, con gli stessi strumenti.
    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 una web_fetch è stata differita, viene eseguita in questa richiesta e il suo
    # web_fetch_tool_result è il primo blocco di continuation.content.
    print(continuation)
else:
    print(response)

Questo codice è corretto anche quando Claude non combina i due tipi di chiamata. Un turno con solo blocchi tool_use client segue lo stesso percorso di continuazione, e un turno con solo chiamate a strumenti server non richiede blocchi tool_result client da parte tua: i suoi blocchi di risultato sono normalmente già presenti, e uno che torna sospeso, come una risposta pause_turn, viene invece reinviato così com'è.



ZDR e allowed_callers

Le versioni base di web search (web_search_20250305) e web fetch (web_fetch_20250910) sono idonee alla Zero Data Retention (ZDR).

Le versioni _20260209 e successive con filtraggio dinamico non sono idonee alla ZDR per impostazione predefinita perché il filtraggio dinamico si basa internamente sull'esecuzione di codice.

Per utilizzare uno strumento server _20260209 o successivo con ZDR, disabilita il filtraggio dinamico impostando "allowed_callers": ["direct"] sullo strumento:

{
  "type": "web_search_20260209",
  "name": "web_search",
  "allowed_callers": ["direct"]
}

Questo limita lo strumento alla sola invocazione diretta, bypassando il passaggio interno di esecuzione del codice.

allowed_callers controlla come uno strumento può essere invocato: direttamente da Claude ("direct"), dall'interno di un container di esecuzione del codice (ad esempio, "code_execution_20260120"), o entrambi. Le versioni _20260209 degli strumenti web hanno come impostazione predefinita solo il caller di esecuzione del codice; le versioni precedenti hanno come impostazione predefinita ["direct"]. Sui modelli che non supportano il programmatic tool calling, queste versioni richiedono allowed_callers: ["direct"]; senza di esso l'API restituisce un errore di validazione che indica di impostarlo.



Filtraggio dei domini

Gli strumenti server che accedono al web accettano i parametri allowed_domains e blocked_domains per controllare quali domini Claude può raggiungere. Entrambi sono campi sull'oggetto strumento:

{
  "type": "web_search_20250305",
  "name": "web_search",
  "allowed_domains": ["example.com", "docs.python.org"]
}

Quando utilizzi i filtri di dominio:

• I domini non devono includere lo schema HTTP/HTTPS (usa example.com invece di https://example.com).
• I sottodomini sono inclusi automaticamente (example.com copre docs.example.com).
• I sottodomini specifici limitano i risultati solo a quel sottodominio (docs.example.com restituisce solo risultati da quel sottodominio, non da example.com o api.example.com).
• I sottopercorsi sono supportati per la ricerca web e corrispondono a qualsiasi cosa dopo il percorso (example.com/blog corrisponde a example.com/blog/post-1).
• Web fetch effettua la corrispondenza solo sul dominio: una voce che include un percorso non corrisponde mai a un URL di web fetch.
• Puoi usare allowed_domains o blocked_domains, ma non entrambi nella stessa richiesta.

Supporto per i caratteri jolly:

• I caratteri jolly (*) non sono consentiti nel dominio stesso, solo nel percorso dopo di esso.
• Valido: example.com/*, example.com/*/articles
• Non valido: *.example.com, ex*.com

I formati di dominio non validi vengono rifiutati al momento della richiesta con un errore 400 invalid_request_error.



Filtraggio dinamico con esecuzione di codice

Le versioni _20260209 e successive di web search e web fetch utilizzano internamente l'esecuzione di codice per applicare filtri dinamici ai risultati di ricerca.



Streaming degli eventi degli strumenti server

Gli eventi degli strumenti server vengono trasmessi in streaming come parte del normale flusso di "server-sent events" (eventi inviati dal server), o SSE. Un blocco server_tool_use che Claude chiama direttamente viene trasmesso in streaming come un blocco tool_use client: un evento content_block_start seguito da eventi input_json_delta. Il blocco di risultato arriva completo in un singolo evento content_block_start, senza delta.

Consulta Streaming per il riferimento completo agli eventi. Le pagine dei singoli strumenti documentano i nomi degli eventi specifici dello strumento dove differiscono.



Richieste batch

Tutti gli strumenti server supportano l'elaborazione batch. In un batch, il loop agentico viene eseguito esattamente come per le richieste sincrone, con un limite di iterazioni per turno più alto. Se il loop raggiunge quel limite, la risposta termina con stop_reason: "pause_turn"; puoi continuarla inviando una richiesta di follow-up con il contenuto restituito. Consulta Strumenti server e il loop agentico per i dettagli.

I carichi di lavoro batch comuni includono l'arricchimento di un dataset con informazioni dal web, la verifica di un ampio insieme di documenti rispetto a fonti attuali e l'esecuzione di codice di analisi su molti file.



Passaggi successivi