Chiamare uno strumento con l’API Converse

Per consentire a un modello di utilizzare uno strumento per completare una risposta a un messaggio, è necessario inviare 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 il risultato dello strumento per generare una risposta al messaggio originale.

I passaggi seguenti illustrano come utilizzare uno strumento con l’API Converse. Per il codice di esempio, consulta Esempi di utilizzo dello strumento API Converse.

Fase 1: inviare il messaggio e la definizione dello strumento

Per inviare il messaggio e la definizione dello strumento, utilizza le operazioni Converse o ConverseStream (per inviare in streaming le risposte).

La definizione dello strumento è uno schema JSON che si passa nel parametro della richiesta toolConfig (ToolConfiguration) all’operazione Converse. Per ulteriori informazioni sullo schema, consulta JSON schema. L’esempio seguente mostra uno schema per uno strumento che restituisce i brani più popolari trasmessi da 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 si utilizza un modello Anthropic Claude 3, è possibile forzare l’uso di uno strumento specificando il campo toolChoice (ToolChoice) nel parametro della richiesta toolConfig. 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 denominato top_song.

{"tool" : {"name" : "top_song"}}

Per ulteriori informazioni sugli altri parametri che si possono passare, consulta Avvio di una conversazione con le operazioni dell’API Converse.

Fase 2: recuperare la richiesta dello strumento dal modello

Quando si invoca l’operazione Converse con il messaggio e la definizione dello strumento, il modello utilizza quest’ultima per determinare se lo strumento è necessario per rispondere al messaggio. Ad esempio, se l’utente dell’app di chat invia il messaggio Qual è la canzone più popolare su 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 risposta stopReason su tool_use. La risposta identifica anche lo strumento (top_song) che il modello di cui il modello desidera l’esecuzione e la stazione radio (WZPZ) su cui eseguire la query con lo strumento. Le informazioni sullo strumento richiesto si trovano nel messaggio che il modello restituisce nel campo output (ConverseOutput), in particolare nel campo toolUse (ToolUseBlock). Il campo toolUseId viene utilizzato per identificare la richiesta dello strumento nelle chiamate successive.

L’esempio seguente mostra la risposta ottenuta da Converse quando si passa il messaggio discusso in Fase 1: inviare il messaggio e la definizione dello strumento.

{
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "toolUse": {
                        "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                        "name": "top_song",
                        "input": {
                            "sign": "WZPZ"
                        }
                    }
                }
            ]
        }
    },
    "stopReason": "tool_use"
}

Fase 3: eseguire la richiesta dello strumento dal modello

Nel campo toolUse della risposta del modello, usa il campo name per identificare il nome dello strumento, quindi chiama l’implementazione dello strumento e passa i parametri di input dal campo input.

Crea quindi un messaggio utente che includa un blocco di contenuto toolResult (ToolResultBlock). Nel blocco di contenuto, includi la risposta dallo strumento e l’ID per la richiesta dello strumento 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 la richiesta di una stazione radio inesistente, puoi inviare informazioni sull’errore al modello presente nel campo toolResult. Per indicare un errore, specifica error nel campo status. L’esempio seguente mostra l’errore che si verifica quando 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 il modello 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 su WZPZ?) con le informazioni fornite nel campo toolResult del messaggio.

{
     "output": {
        "message": {
            "role": "assistant",
            "content": [
                {
                    "text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike."
                }
            ]
        }
    },
    "stopReason": "end_turn"