Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Chiama uno strumento con Converse API
Per consentire a un modello di utilizzare uno strumento per completare una risposta a un messaggio, inviate il messaggio e le definizioni di uno o più strumenti al modello. Se il modello determina che uno degli strumenti può contribuire a generare una risposta, restituisce una richiesta di utilizzo dello strumento e invia i risultati dello strumento al modello. Il modello utilizza quindi i risultati per generare una risposta al messaggio originale.
I passaggi seguenti mostrano come utilizzare uno strumento con Converse. API Per il codice di esempio, consulta Esempi di utilizzo API dello strumento Converse.
Argomenti
Fase 1: Inviare il messaggio e la definizione dello strumento
Per inviare il messaggio e la definizione dello strumento, utilizzate le operazioni Converse o ConverseStream(per le risposte in streaming).
Nota
Meta contiene raccomandazioni specifiche per la creazione di prompt che utilizzano strumenti con Llama modelli 3.1 (o successivi). Per ulteriori informazioni, vedere JSONBased Tool Calling
La definizione dello strumento è uno JSON schema che viene passato all'Converse
operazione toolConfig
tramite il parametro di richiesta (ToolConfiguration). Per informazioni sullo schema, vedete JSONschema
{ "tools": [ { "toolSpec": { "name": "top_song", "description": "Get the most popular song played on a radio station.", "inputSchema": { "json": { "type": "object", "properties": { "sign": { "type": "string", "description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP." } }, "required": [ "sign" ] } } } } ] }
Nella stessa richiesta, si passa anche un messaggio utente nel parametro di richiesta messages
(Message).
[ { "role": "user", "content": [ { "text": "What is the most popular song on WZPZ?" } ] } ]
Se stai usando un Anthropic Claude Modello 3, è possibile forzare l'uso di uno strumento specificando il campo toolChoice
(ToolChoice) nel parametro di toolConfig
richiesta. Forzare l'uso di uno strumento è utile per testare lo strumento durante lo sviluppo. L'esempio seguente mostra come forzare l'uso di uno strumento chiamato top_song.
{"tool" : {"name" : "top_song"}}
Per informazioni sugli altri parametri che potete passare, consultate. Effettua una conversazione con le operazioni di Converse API
Fase 2: Ottenete la richiesta dell'utensile dal modello
Quando richiamate l'Converse
operazione con il messaggio e la definizione dell'utensile, il modello utilizza la definizione dell'utensile per determinare se l'utensile è necessario per rispondere al messaggio. Ad esempio, se l'utente dell'app di chat invia il messaggio Qual è la canzone più popolare? WZPZ , il modello abbina il messaggio allo schema nella definizione dello strumento top_song e determina che lo strumento può contribuire a generare una risposta.
Quando il modello decide di aver bisogno di uno strumento per generare una risposta, imposta il campo di stopReason
risposta su. tool_use
La risposta identifica anche lo strumento (top_song) che il modello vuole che tu esegua e la stazione radio (WZPZ) che desidera che tu interroghi con lo strumento. Le informazioni sullo strumento richiesto si trovano nel messaggio che il modello restituisce nel campo output
() ConverseOutput. In particolare, il campo toolUse
(ToolUseBlock). Il toolUseId
campo viene utilizzato per identificare la richiesta dello strumento nelle chiamate successive.
L'esempio seguente mostra la risposta ottenuta Converse
quando si passa il messaggio discusso inFase 1: Inviare il messaggio e la definizione dello strumento.
{ "output": { "message": { "role": "assistant", "content": [ { "toolUse": { "toolUseId": "tooluse_hbTgdi0CSLq_hM4P8csZJA", "name": "top_song", "input": { "sign": "WZPZ" } } } ] } }, "stopReason": "tool_use" }
Fase 3: Effettuare la richiesta dell'utensile per il modello
Dal toolUse
campo della risposta del modello, utilizzate il name
campo per identificare il nome dello strumento. Quindi richiamate l'implementazione dello strumento e passate i parametri di input dal input
campo.
Quindi, costruisci un messaggio utente che includa un blocco di contenuto toolResult
(ToolResultBlock). Nel blocco di contenuto, includi la risposta dello strumento e l'ID per la richiesta dello strumento che hai ricevuto nel passaggio precedente.
{ "role": "user", "content": [ { "toolResult": { "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q", "content": [ { "json": { "song": "Elemental Hotel", "artist": "8 Storey Hike" } } ] } } ] }
Se si verifica un errore nello strumento, ad esempio una richiesta di una stazione radio inesistente, puoi inviare informazioni sull'errore al modello presente sul toolResult
campo. Per indicare un errore, specificare error
nel status
campo. L'errore di esempio seguente si riferisce al caso in cui lo strumento non riesce a trovare la stazione radio.
{ "role": "user", "content": [ { "toolResult": { "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q", "content": [ { "text": "Station WZPA not found." } ], "status": "error" } } ] }
Fase 4: Ottenere la risposta del modello
Continua la conversazione con la modella includendo il messaggio utente creato nel passaggio precedente in una chiamata aConverse
. Il modello genera quindi una risposta che risponde al messaggio originale (Qual è la canzone più popolare in ondaWZPZ? ) con le informazioni fornite nel toolResult
campo del messaggio.
{ "output": { "message": { "role": "assistant", "content": [ { "text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike." } ] } }, "stopReason": "end_turn"