Definire gli strumenti

Scelta di un modello

Usa il modello Claude Opus (4.7) più recente per strumenti complessi e query ambigue; gestisce meglio più strumenti e chiede chiarimenti quando necessario.

Usa i modelli Claude Haiku per strumenti semplici, ma tieni presente che potrebbero dedurre parametri mancanti.

Specifica degli strumenti client

Gli strumenti client (sia schema Anthropic che definiti dall'utente) sono specificati nel parametro tools di livello superiore della richiesta API. Ogni definizione di strumento include:

Per l'insieme completo di proprietà facoltative disponibili su qualsiasi definizione di strumento, incluse cache_control, strict, defer_loading e allowed_callers, vedi il riferimento degli strumenti.

Prompt di sistema per l'uso dello strumento

Quando chiami l'API Claude con il parametro tools, l'API costruisce un prompt di sistema speciale dalle definizioni degli strumenti, dalla configurazione dello strumento e da qualsiasi prompt di sistema specificato dall'utente. Il prompt costruito è progettato per istruire il modello a usare gli strumenti specificati e fornire il contesto necessario affinché lo strumento funzioni correttamente:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

Best practice per le definizioni degli strumenti

Per ottenere le migliori prestazioni da Claude quando usi gli strumenti, segui queste linee guida:

• Fornisci descrizioni estremamente dettagliate. Questo è di gran lunga il fattore più importante nelle prestazioni dello strumento. Le tue descrizioni dovrebbero spiegare ogni dettaglio dello strumento, incluso:
  • Cosa fa lo strumento
  • Quando deve essere usato (e quando non deve)
  • Cosa significa ogni parametro e come influisce sul comportamento dello strumento
  • Eventuali avvertenze o limitazioni importanti, come quali informazioni lo strumento non restituisce se il nome dello strumento non è chiaro. Più contesto puoi dare a Claude sui tuoi strumenti, meglio sarà nel decidere quando e come usarli. Mira a almeno 3-4 frasi per descrizione dello strumento, di più se lo strumento è complesso.
• Dai priorità alle descrizioni, ma considera l'uso di input_examples per strumenti complessi. Le descrizioni chiare sono più importanti, ma per strumenti con input complessi, oggetti annidati o parametri sensibili al formato, puoi usare il campo input_examples per fornire esempi convalidati dallo schema. Vedi Fornire esempi di uso dello strumento per i dettagli.
• Consolida le operazioni correlate in meno strumenti. Invece di creare uno strumento separato per ogni azione (, , ), raggruppali in un singolo strumento con un parametro . Meno strumenti, più capaci, riducono l'ambiguità della selezione e rendono la tua superficie di strumenti più facile da navigare per Claude.

La buona descrizione spiega chiaramente cosa fa lo strumento, quando usarlo, quali dati restituisce e cosa significa il parametro ticker. La descrizione scadente è troppo breve e lascia Claude con molte domande aperte sul comportamento e l'uso dello strumento.

Fornire esempi di uso dello strumento

Puoi fornire esempi concreti di input di strumenti validi per aiutare Claude a capire come usare i tuoi strumenti in modo più efficace. Questo è particolarmente utile per strumenti complessi con oggetti annidati, parametri facoltativi o input sensibili al formato.

Utilizzo di base

Aggiungi un campo facoltativo input_examples alla tua definizione di strumento con un array di oggetti di input di esempio. Ogni esempio deve essere valido secondo lo input_schema dello strumento:

Gli esempi sono inclusi nel prompt insieme al tuo schema dello strumento, mostrando a Claude modelli concreti per chiamate di strumenti ben formate. Questo aiuta Claude a capire quando includere parametri facoltativi, quali formati usare e come strutturare input complessi.

Requisiti e limitazioni

• Convalida dello schema - Ogni esempio deve essere valido secondo lo input_schema dello strumento. Gli esempi non validi restituiscono un errore 400
• Non supportato per strumenti lato server - Gli esempi di input funzionano su strumenti client definiti dall'utente e schema Anthropic, ma non su strumenti server come ricerca web o esecuzione di codice
• Costo del token - Gli esempi si aggiungono ai token del prompt: ~20-50 token per esempi semplici, ~100-200 token per oggetti annidati complessi

Controllo dell'output di Claude

Forzare l'uso dello strumento

In alcuni casi, potresti voler che Claude usi uno strumento specifico per rispondere alla domanda dell'utente, anche se Claude altrimenti risponderebbe direttamente senza chiamare uno strumento. Puoi farlo specificando lo strumento nel campo tool_choice come segue:

tool_choice = {"type": "tool", "name": "get_weather"}

Quando si lavora con il parametro tool_choice, ci sono quattro opzioni possibili:

• auto consente a Claude di decidere se chiamare uno qualsiasi degli strumenti forniti o meno. Questo è il valore predefinito quando vengono forniti tools.
• any dice a Claude che deve usare uno degli strumenti forniti, ma non forza uno strumento particolare.
• tool forza Claude a usare sempre uno strumento particolare.
• none impedisce a Claude di usare qualsiasi strumento. Questo è il valore predefinito quando non vengono forniti tools.

Questo diagramma illustra come funziona ogni opzione:

Nota che quando hai tool_choice come any o tool, l'API precompila il messaggio dell'assistente per forzare l'uso di uno strumento. Ciò significa che i modelli non emetteranno una risposta in linguaggio naturale o una spiegazione prima dei blocchi di contenuto tool_use, anche se esplicitamente richiesto di farlo.

I test hanno dimostrato che questo non dovrebbe ridurre le prestazioni. Se desideri che il modello fornisca contesto in linguaggio naturale o spiegazioni mentre richiedi comunque che il modello usi uno strumento specifico, puoi usare {"type": "auto"} per tool_choice (il valore predefinito) e aggiungere istruzioni esplicite in un messaggio user. Ad esempio: What's the weather like in London? Use the get_weather tool in your response.

Risposte del modello con strumenti

Quando usi gli strumenti, Claude spesso commenterà quello che sta facendo o risponderà naturalmente all'utente prima di invocare gli strumenti.

Ad esempio, data la richiesta "What's the weather like in San Francisco right now, and what time is it there?", Claude potrebbe rispondere con:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

Questo stile di risposta naturale aiuta gli utenti a capire cosa sta facendo Claude e crea un'interazione più conversazionale. Puoi guidare lo stile e il contenuto di queste risposte attraverso i tuoi prompt di sistema e fornendo <examples> nei tuoi prompt.

È importante notare che Claude può usare varie frasi e approcci quando spiega le sue azioni. Il tuo codice dovrebbe trattare queste risposte come qualsiasi altro testo generato dall'assistente e non fare affidamento su convenzioni di formattazione specifiche.

Passaggi successivi