Appelez un outil avec la Converse API

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 les résultats pour générer une réponse au message d'origine.

Les étapes suivantes montrent comment utiliser un outil avec la Converse. API Pour obtenir un exemple de code, consultez Exemples d'utilisation de API l'outil 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 continu).

Note

Meta contient des recommandations spécifiques pour créer des invites utilisant des outils avec Llama Modèles 3.1 (ou ultérieurs). Pour plus d'informations, consultez la section Appel d'outils JSON basé dans le Meta .

La définition de l'outil est un JSON schéma dans lequel vous transmettez le paramètre de requête toolConfig (ToolConfiguration) à l'Converseopération. Pour plus d'informations sur le schéma, voir JSONschéma. Voici un exemple de schéma d'un outil permettant de diffuser la chanson la plus populaire sur 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 Anthropic Claude Modèle 3, vous pouvez forcer l'utilisation d'un outil en spécifiant le champ toolChoice (ToolChoice) dans le paramètre de toolConfig demande. 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 transmettre, consultezMener une conversation avec Converse.

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

Lorsque vous appelez l'Converseopération 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 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 stopReason réponse surtool_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 toolUseId champ pour identifier la demande d'outil lors d'appels ultérieurs.

L'exemple suivant montre la réponse Converse lorsque vous avez transmis 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_hbTgdi0CSLq_hM4P8csZJA",
                        "name": "top_song",
                        "input": {
                            "sign": "WZPZ"
                        }
                    }
                }
            ]
        }
    },
    "stopReason": "tool_use"
}

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

Dans le toolUse champ de la réponse du modèle, name utilisez-le 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 input champ.

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 toolResult sur le terrain. Pour indiquer une erreur, error spécifiez-le dans le status champ. 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 (Quel est le titre le plus populaire WZPZ ? ) avec les informations que vous avez fournies dans le toolResult champ du message.

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