Appel d’un outil à l’aide de l’API Converse

Pour permettre à un modèle d’utiliser un outil pour répondre à un message, vous devez envoyer le message et les définitions d’un ou de plusieurs outils au modèle. Si le modèle détermine que l’un des outils peut aider à générer une réponse, il vous demande d’utiliser l’outil et de renvoyer les résultats de l’outil au modèle. Le modèle utilise ensuite le résultat de l’outil pour générer une réponse pour le message d’origine.

Les étapes suivantes montrent comment utiliser un outil avec l’API Converse. Pour obtenir un exemple de code, consultez Exemples d’utilisation de l’outil d’API Converse.

Étape 1 : envoyer le message et la définition de l’outil

Pour envoyer le message et la définition de l’outil, vous utilisez les opérations Converse ou ConverseStream (pour les réponses en streaming).

La définition de l’outil est un schéma JSON que vous transmettez le paramètre de demande toolConfig (ToolConfiguration) à l’opération Converse. Pour plus d’informations sur le schéma, consultez Schéma JSON. L’exemple de schéma suivant concerne un outil qui permet d’obtenir les chansons les plus populaires d’une station de 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"
                        ]
                    }
                }
            }
        }
    ]
}

Dans la même demande, vous transmettez également un message utilisateur dans le paramètre de demande messages (Message).

[
    {
        "role": "user",
        "content": [
            {
                "text": "What is the most popular song on WZPZ?"
            }
        ]
    }
]

Si vous utilisez un modèle Anthropic Claude 3, vous pouvez forcer l’utilisation d’un outil en spécifiant le champ toolChoice (ToolChoice) dans le paramètre de demande toolConfig. Il est utile de forcer l’utilisation d’un outil pour tester votre outil pendant le développement. L’exemple suivant montre comment forcer l’utilisation d’un outil appelé top_song.

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

Pour plus d’informations sur les autres paramètres que vous pouvez utiliser, consultez Mener une conversation avec les opérations d’API Converse.

Étape 2 : obtenir la demande d’outil à partir du modèle

Lorsque vous invoquez l’opération Converse avec le message et la définition de l’outil, le modèle utilise la définition de l’outil pour déterminer si l’outil est nécessaire pour répondre au message. Par exemple, si l’utilisateur de votre application de chat envoie le message Quelle est la chanson la plus populaire sur WZPZ ?, le modèle fait correspondre le message au schéma de la définition de l’outil top_song et détermine si l’outil peut aider à générer une réponse.

Lorsque le modèle décide qu’il a besoin d’un outil pour générer une réponse, il définit le champ de réponse stopReason sur tool_use. La réponse identifie également l’outil (top_song) que le modèle souhaite que vous exécutiez et la station de radio (WZPZ) qu’il souhaite que vous interrogiez avec l’outil. Les informations relatives à l’outil demandé se trouvent dans le message renvoyé par le modèle dans le champ output (ConverseOutput). Plus précisément, le champ toolUse (ToolUseBlock). Vous utilisez le champ toolUseId pour identifier la demande d’outil lors d’appels ultérieurs.

L’exemple suivant montre la réponse de Converse lorsque vous transmettez le message décrit dans Étape 1 : envoyer le message et la définition de l’outil.

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

Étape 3 : faire la demande d’outil pour le modèle

Dans le champ toolUse de la réponse du modèle, utilisez name pour identifier le nom de l’outil. Appelez ensuite votre implémentation de l’outil et transmettez les paramètres d’entrée depuis le champ input.

Ensuite, créez un message utilisateur qui inclut un bloc de contenu toolResult (ToolResultBlock). Dans le bloc de contenu, incluez la réponse de l’outil et l’ID de la demande d’outil que vous avez reçue à l’étape précédente.

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "json": {
                            "song": "Elemental Hotel",
                            "artist": "8 Storey Hike"
                        }
                    }
                ]
            }
        }
    ]
}

En cas d’erreur dans l’outil, telle qu’une demande concernant une station radio inexistante, vous pouvez envoyer des informations d’erreur au modèle dans le champ toolResult. Pour indiquer une erreur, spécifiez error dans le champ status. L’exemple d’erreur suivant se produit lorsque l’outil ne trouve pas la station de radio.

{
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
                "content": [
                    {
                        "text": "Station WZPA not found."
                    }
                ],
                "status": "error"
            }
        }
    ]
}

Étape 4 : obtenir la réponse du modèle

Poursuivez la conversation avec le modèle en incluant le message utilisateur que vous avez créé à l’étape précédente dans un appel à Converse. Le modèle génère ensuite une réponse qui répond au message original (Quelle est la chanson la plus populaire sur WZPZ ?) avec les informations que vous avez fournies dans le champ toolResult du message.

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