Strumenti server

Questa pagina copre la meccanica condivisa degli strumenti eseguiti dal server: il blocco server_tool_use, la continuazione pause_turn, considerazioni ZDR e filtri di dominio. Per i singoli strumenti, vedi il riferimento degli strumenti.

Il blocco server_tool_use

Il blocco server_tool_use appare nella risposta di Claude quando uno strumento eseguito dal server viene eseguito. Il suo campo id utilizza il prefisso srvtoolu_ per distinguerlo dalle chiamate di 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 hai bisogno di rispondere con un tool_result. Il blocco dei risultati appare immediatamente dopo il blocco server_tool_use nello stesso turno dell'assistente.

Il ciclo lato server e pause_turn

Quando si utilizzano strumenti server come la ricerca web, l'API può restituire un motivo di arresto pause_turn, indicando che l'API ha messo in pausa un turno di lunga durata.

Ecco come gestire il motivo di arresto pause_turn:

# Initial request with web search
response = client.messages.create(
    model="claude-opus-4-7",
    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}],
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Send the continuation request
    continuation = client.messages.create(
        model="claude-opus-4-7",
        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
• Modifica se necessario: Puoi facoltativamente modificare il contenuto prima di continuare se vuoi interrompere o reindirizzare la conversazione
• Preserva lo stato dello strumento: Includi gli stessi strumenti nella richiesta di continuazione per mantenere la funzionalità

ZDR e allowed_callers

Le versioni di base della ricerca web (web_search_20250305) e del recupero web (web_fetch_20250910) sono idonee per Zero Data Retention (ZDR).

Le versioni _20260209 con filtri dinamici non sono idonee per ZDR per impostazione predefinita perché il filtro dinamico si basa sull'esecuzione del codice internamente.

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

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

Questo limita lo strumento solo all'invocazione diretta, bypassando il passaggio di esecuzione del codice interno.

Filtri di dominio

Gli strumenti server che accedono al web accettano parametri allowed_domains e blocked_domains per controllare quali domini Claude può raggiungere.

Quando si utilizzano 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 percorsi secondari sono supportati e corrispondono a qualsiasi cosa dopo il percorso (example.com/blog corrisponde a example.com/blog/post-1)
• Puoi usare allowed_domains o blocked_domains, ma non entrambi nella stessa richiesta

Supporto dei caratteri jolly:

• Solo un carattere jolly (*) è consentito per voce di dominio e deve apparire dopo la parte del dominio (nel percorso)
• Valido: example.com/*, example.com/*/articles
• Non valido: *.example.com, ex*.com, example.com/*/news/*

I formati di dominio non validi restituiscono un errore di strumento invalid_tool_input.

Filtri dinamici con esecuzione del codice

Le versioni _20260209 della ricerca web e del recupero web utilizzano l'esecuzione del codice internamente per applicare filtri dinamici ai risultati della ricerca.

Streaming di eventi degli strumenti server

Gli eventi degli strumenti server vengono trasmessi come parte del flusso SSE normale. Il blocco server_tool_use e il suo risultato arrivano come eventi content_block_start e content_block_delta, nello stesso modo in cui il testo e le chiamate di strumenti client vengono trasmessi.

Vedi Streaming per il riferimento completo degli 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. Vedi Elaborazione batch.

Passaggi successivi