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.

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 nel Meta documentazione.

La definizione dello strumento è uno JSON schema che viene passato all'Converseoperazione toolConfig tramite il parametro di richiesta (ToolConfiguration). Per informazioni sullo schema, vedete JSONschema. Di seguito è riportato uno schema di esempio per uno strumento che consente di riprodurre la canzone più popolare su una stazione radio.

{
    "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'Converseoperazione 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"