Questo formato di utilizzo degli strumenti è obsoleto

Ti consigliamo vivamente di passare il prima possibile alla nostra struttura migliorata di utilizzo degli strumenti, che è più affidabile e consente prestazioni di qualità superiore, soprattutto per attività di utilizzo degli strumenti più complesse.

Questo formato di utilizzo degli strumenti non è ottimizzato per Claude 3 e potrebbe risultare in prestazioni inferiori rispetto al nostro formato aggiornato di utilizzo degli strumenti.

Nota: Il nuovo formato di utilizzo degli strumenti non è ancora disponibile su Vertex AI o Amazon Bedrock, ma arriverà presto su queste piattaforme.


Come funziona l’utilizzo di strumenti legacy

Con l’utilizzo di strumenti legacy, le funzioni sono definite all’interno del prompt stesso. Quando fornisci a Claude descrizioni di strumenti e funzioni che può utilizzare, Claude è in grado di decidere in modo intelligente quando e come utilizzare tali strumenti per aiutare a rispondere alle domande e completare le attività.

Ad esempio, supponiamo che tu fornisca a Claude (nel prompt) una funzione chiamata get_weather(location) che recupera le condizioni meteorologiche attuali per una determinata posizione. Se un utente chiede “Com’è il tempo a Londra in questo momento?”, Claude riconoscerà che può utilizzare la funzione get_weather che hai fornito per cercare la risposta.

Dietro le quinte, questo è un processo in più fasi:

  1. Le definizioni delle funzioni e la domanda dell’utente vengono passate a Claude in un unico prompt
    • Claude non solo ha bisogno degli strumenti e delle loro descrizioni per decidere con successo se utilizzare gli strumenti, ma probabilmente anche di esempi di accompagnamento di situazioni in cui tali strumenti dovrebbero essere utilizzati, a seconda della complessità del caso d’uso e degli strumenti.
  2. Claude valuta la domanda dell’utente e decide quali funzioni chiamare e con quali argomenti
  3. Claude costruisce una chiamata di funzione formattata correttamente
  4. La chiamata di funzione viene intercettata tramite il codice client con una chiara stop_sequence, e la funzione effettiva viene eseguita sul lato client
  5. Il risultato della funzione viene passato di nuovo a Claude
  6. Claude utilizza il risultato della funzione per formulare la sua risposta finale all’utente

Questa tecnica consente a Claude di sfruttare conoscenze e capacità esterne mantenendo comunque un’interfaccia conversazionale.


Definizione delle funzioni

Le funzioni vengono definite fornendo a Claude una descrizione della funzione racchiusa tra tag XML. La descrizione dovrebbe includere:

  • Il nome della funzione
  • Una spiegazione in testo semplice di ciò che fa la funzione
  • I parametri previsti, i loro tipi e le descrizioni
  • I valori di ritorno e i tipi
  • Eventuali eccezioni che possono essere sollevate

Ecco un esempio di definizione di funzione:

XML
<tool_description>
<tool_name>get_weather</tool_name>
<description>
Recupera le condizioni meteorologiche attuali per una posizione specificata.
Restituisce un dizionario con due campi:
- temperature: float, la temperatura attuale in Fahrenheit
- conditions: string, una breve descrizione delle condizioni meteorologiche attuali
Solleva ValueError se la posizione fornita non può essere trovata.
</description>
<parameters>
<parameter>
<name>location</name>
<type>string</type>
<description>La città e lo stato, ad esempio San Francisco, CA</description>
</parameter>
</parameters>
</tool_description>

Alcuni suggerimenti per scrivere buone descrizioni di funzioni:

  • Sii chiaro e conciso, ma fornisci abbastanza dettagli affinché Claude capisca quando la funzione dovrebbe essere utilizzata
  • Specifica i tipi dei parametri e dei valori di ritorno
  • Menziona eventuali eccezioni rilevanti che possono essere sollevate
  • Usa descrizioni in testo semplice, non sintassi di codice

Formato di utilizzo degli strumenti legacy

Affinché Claude possa chiamare una funzione, deve generare un blocco XML formattato in modo molto specifico. Il formato è il seguente:

XML
<function_calls>
<invoke>
<tool_name>function_name</tool_name>
<parameters>
<param1>value1</param1>
<param2>value2</param2>
</parameters>
</invoke>
</function_calls>

Il blocco <function_calls> può contenere più blocchi <invoke> se Claude sta chiamando più di una funzione contemporaneamente. Ogni <invoke> contiene il nome della funzione chiamata e i parametri passati.

Dovresti passare </function_calls> nella tua chiamata API come stop_sequence per assicurarti che Claude smetta di generare testo una volta chiamata una funzione.

Dopo un blocco <function_calls>, e supponendo che tu abbia la sequenza di stop corretta, Claude smetterà di generare e attenderà che il risultato della funzione venga passato in un blocco <function_results> che ha questo aspetto:

XML
<function_results>
<result>
<tool_name>function_name</tool_name>
<stdout>
qui va il risultato della funzione
</stdout>
</result>
</function_results>

Il risultato della funzione dovrebbe essere inserito all’interno dei tag <stdout>. Se la funzione ha sollevato un’eccezione, dovrebbe essere restituita così:

XML
<function_results>
<error>
qui va il messaggio di errore
</error>
</function_results>

Il risultato completo della funzione dovrebbe essere passato di nuovo a Claude come messaggio che continua la conversazione precedente. Dopo aver ricevuto i risultati della funzione, Claude continuerà a generare per incorporare i risultati nella sua risposta.


Esempio di prompt di utilizzo di strumenti legacy

Ecco un esempio completo di prompt che fornisce a Claude due funzioni e una domanda che richiede il loro utilizzo:

Content
SystemIn questo ambiente hai accesso a un set di strumenti che puoi utilizzare per rispondere alla domanda dell’utente.

Puoi chiamarli in questo modo:
<function_calls>
<invoke>
<tool_name>$TOOL_NAME</tool_name>
<parameters>
<$PARAMETER_NAME>$PARAMETER_VALUE</$PARAMETER_NAME>

</parameters>
</invoke>
</function_calls>

Ecco gli strumenti disponibili:
<tools>
<tool_description>
<tool_name>get_current_stock_price
</tool_name><description>Ottiene il prezzo azionario corrente per un’azienda. Restituisce float: Il prezzo azionario corrente.
Solleva ValueError: se il simbolo di input non è valido/sconosciuto.</description>
<parameters>
<parameter>
<name>symbol</name>
<type>string</type>
<description>Il simbolo azionario dell’azienda per cui ottenere il prezzo.</description>
</parameter>
</parameters>
</tool_description>

<tool_description>
<tool_name>get_ticker_symbol</tool_name>
<description>Ottiene il simbolo del ticker azionario per un’azienda cercata per nome. Restituisce str: Il simbolo del ticker per l’azione dell’azienda. Solleva TickerNotFound: se non viene trovato alcun simbolo del ticker corrispondente.
</description>
<parameters>
<parameter>
<name>company_name</name>
<type>string</type>
<description>Il nome dell’azienda.</description>
</parameter>
</parameters>
</tool_description></tools>
UserQual è il prezzo azionario attuale di General Motors?

Ecco come risponderebbe Claude:

Content
Assistant<scratchpad>
Per rispondere a questa domanda, dovrò:

1. Ottenere il simbolo del ticker per General Motors utilizzando la funzione get_ticker_symbol().
2. Utilizzare il simbolo del ticker restituito per ottenere il prezzo azionario corrente utilizzando la funzione get_current_stock_price().</scratchpad>

<function_calls>
<invoke>
<tool_name>get_ticker_symbol</tool_name>
<parameters>
<company_name>General Motors</company_name>
</parameters>
</invoke>
</function_calls>

Claude prima chiama get_ticker_symbol per recuperare il simbolo del ticker per General Motors. Possiamo riconoscere che Claude vuole chiamare una funzione tramite la sequenza di stop </function calls>. Estraiamo i dati rilevanti tra i tag XML pertinenti ed eseguiamo la funzione per conto di Claude. Quindi passiamo i risultati di nuovo a Claude nei tag <function_results>.

Content
User<function_results>
<result>
<tool_name>get_ticker_symbol</tool_name>
<stdout>
GM
</stdout>
</result>
</function_results>

Ora che conosce il simbolo del ticker, Claude deciderà successivamente che deve chiamare get_current_stock_price e ottenere il prezzo corrente.

Content
Assistant<function_calls>
<invoke>
<tool_name>get_current_stock_price</tool_name>
<parameters>
<symbol>GM</symbol>
</parameters>
</invoke>
</function_calls>

Passiamo anche questi risultati.

Content
User<function_results>
<result>
<tool_name>get_current_stock_price</tool_name>
<stdout>
38.50
</stdout>
</result>
</function_results>

Con questa intera catena di conversazione che fornisce a Claude tutti i dettagli necessari, Claude sarà in grado di fornire all’utente una risposta come output finale.

Content
<answer>
Il prezzo azionario attuale di General Motors è $38,50.
</answer>

FAQ sull’utilizzo di strumenti legacy

Quanti strumenti posso passare a Claude in una determinata interazione?

Puoi definire qualsiasi numero di strumenti e funzioni che Claude può utilizzare, anche se attualmente consigliamo di non superare 3-5 per questa struttura di utilizzo di strumenti legacy, a seconda della complessità del tuo caso d’uso e delle funzioni in questione.

Claude ha degli strumenti integrati che conosce?

No. Qualsiasi strumento che desideri che Claude utilizzi, dovrai definirlo tu stesso all’interno di un prompt di utilizzo degli strumenti. Claude non ha un elenco predeterminato di funzioni e definizioni che funzionano meglio.

Quando arriverà il nuovo formato di utilizzo degli strumenti su Vertex AI o Amazon Bedrock?

Nel prossimo futuro!