View a markdown version of this page

Configuration de l'outil - Amazon Nova
Outils de définitionParamètres de choix de l'outilÉvénements liés à l'utilisation des outils de réception et de traitementBonnes pratiques

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Configuration de l'outil

Amazon Nova 2 Sonic prend en charge l'utilisation d'outils (également appelés appels de fonctions), ce qui permet au modèle de demander des informations ou des actions externes lors de conversations, telles que des appels d'API, des requêtes de base de données ou des fonctions de code personnalisées. Cela permet à votre assistant vocal d'effectuer des actions, de récupérer des informations et de s'intégrer à des services externes en fonction des demandes des utilisateurs.

Nova 2 Sonic propose des appels d'outils asynchrones, permettant à l'IA de continuer à converser naturellement pendant que les outils s'exécutent en arrière-plan, créant ainsi une expérience utilisateur plus fluide et réactive.

Voici des étapes simplifiées relatives à l'utilisation des outils :

  1. Définition des outils : spécifiez les outils disponibles avec leurs paramètres dans l'événement PromptStart

  2. L'utilisateur parle : l'utilisateur fait une demande qui nécessite un outil (tel que « Quel temps fait-il à Seattle ? »)

  3. Invocation d'outil : Nova 2 Sonic reconnaît le besoin et envoie un événement ToolUse

  4. Exécuter un outil : votre application exécute l'outil et renvoie les résultats

  5. Génération de réponses : Nova 2 Sonic intègre les résultats dans sa réponse vocale

Le schéma suivant illustre le fonctionnement de l'outil :

Outils de définition

Les outils sont définis à l'aide d'un schéma JSON qui décrit leur objectif, leurs paramètres et les entrées attendues.

Les composants et les explications de la définition de l'outil sont les suivants :

  • Nom : identifiant unique de l'outil (utilisez snake_case)

  • Description : Explication claire de ce que fait l'outil ; aide l'IA à décider quand l'utiliser

  • InputSchema: schéma JSON définissant les paramètres acceptés par l'outil

  • Propriétés : paramètres individuels avec types et descriptions

  • Obligatoire : tableau de noms de paramètres à fournir

Voici une définition simple de l'outil météo

{
  "toolSpec": {
    "name": "get_weather",
    "description": "Get current weather information for a specific location",
    "inputSchema": {
      "json": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name or zip code"
          },
          "units": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "Temperature units"
          }
        },
        "required": ["location"]
      }
    }
  }
}

La configuration de l'outil est transmise à Nova 2 Sonic lors de l'promptStartévénement, ainsi que les paramètres de sortie audio et texte :

{
    "event": {
        "promptStart": {
            "promptName": "<prompt-id>",
            "textOutputConfiguration": {
                "mediaType": "text/plain"
            },
            "audioOutputConfiguration": {
                "mediaType": "audio/lpcm",
                "sampleRateHertz": 16000,
                "sampleSizeBits": 16,
                "channelCount": 1,
                "voiceId": "matthew",
                "encoding": "base64",
                "audioType": "SPEECH"
            },
            "toolUseOutputConfiguration": {
                "mediaType": "application/json"
            },
            "toolConfiguration": {
                "tools": [
                    {
                        "toolSpec": {
                            "name": "get_weather",
                            "description": "Get current weather information for a specific location",
                            "inputSchema": {
                                "json": {
                                    "type": "object",
                                    "properties": {
                                        "location": {
                                            "type": "string",
                                            "description": "City name or zip code"
                                        },
                                        "units": {
                                            "type": "string",
                                            "enum": ["celsius", "fahrenheit"],
                                            "description": "Temperature units"
                                        }
                                    },
                                    "required": ["location"]
                                }
                            }
                        }
                    }
                ],
                "toolChoice": {
                    "auto": {}
                }
            }
        }
    }
}

Paramètres de choix de l'outil

Nova 2 Sonic prend en charge trois paramètres de choix d'outils pour contrôler quand et quels outils sont utilisés. Spécifiez le paramètre ToolChoice dans la configuration de votre outil :

  • Auto (par défaut) : le modèle décide si des outils sont nécessaires et peut appeler plusieurs outils si nécessaire. Offre une flexibilité maximale.

  • N'importe lequel : garantit qu'au moins un des outils disponibles est appelé au début de la réponse, le modèle sélectionnant le plus approprié. Utile lorsque vous disposez de plusieurs bases de connaissances ou outils et que vous souhaitez garantir qu'ils sont utilisés.

  • Outil : force un outil nommé spécifique à être appelé exactement une fois au début de la réponse. Par exemple, si vous spécifiez un outil de base de connaissances, le modèle l'interrogera avant de répondre, qu'il pense que l'outil est nécessaire ou non.

Exemples de choix d'outils

Auto (par défaut)

"toolChoice": { 
    "auto": {} 
}

N'importe lequel :

"toolChoice": {
    "any": {}
}

Outil spécifique :

"toolChoice": {
    "tool": {
        "name": "get_weather"
    }
}

Événements liés à l'utilisation des outils de réception et de traitement

Lorsqu'Amazon Nova 2 Sonic détermine qu'un outil est nécessaire, il envoie un toolUse événement contenant :

  1. toolUseID: identifiant unique pour l'invocation de cet outil

  2. ToolName: le nom de l'outil à exécuter

  3. Contenu : chaîne JSON contenant les paramètres extraits de la demande de l'utilisateur

  4. SessionId : identifiant de session en cours

  5. Rôle : défini sur « TOOL » pour les événements liés à l'utilisation de l'outil

Exemple d'événement d'utilisation d'un outil

{
    "event": {
        "toolUse": {
            "completionId": "<completion-id>",
            "content": "{\"location\": \"Seattle\", \"units\": \"fahrenheit\"}",
            "contentId": "<content-id>",
            "promptName": "<prompt-id>",
            "role": "TOOL",
            "sessionId": "<session-id>",
            "toolName": "get_weather",
            "toolUseId": "<tool-use-id>"
        }
    }
}

Étapes de traitement

  1. Recevez l'événement ToolUse de Nova 2 Sonic

  2. Extraire le nom et les paramètres de l'outil à partir de l'événement

  3. Exécutez la logique de votre outil (appel d'API, requête de base de données, etc.)

  4. Renvoie le résultat à l'aide d'un événement ToolResult

Exemple d' ToolResult événement

{
    "event": {
        "toolResult": {
            "promptName": "<prompt-id>",
            "contentName": "<content-id>",
            "content": "{\"temperature\": 72, \"condition\": \"sunny\", \"humidity\": 45}"
        }
    }
}

Bonnes pratiques

  • Descriptions claires : Rédigez des descriptions détaillées des outils pour aider Nova 2 Sonic à comprendre quand utiliser chaque outil.

  • Valider les paramètres : validez toujours les paramètres de l'outil avant l'exécution pour éviter les erreurs. Définissez les paramètres de l'outil à l'aide d'un schéma JSON approprié avec des types de données structurés (tels que des énumérations, des nombres ou des booléens) plutôt que des chaînes ouvertes dans la mesure du possible.

  • Gestion des erreurs : renvoie des messages d'erreur significatifs dans les événements ToolResult en cas de défaillance des outils.

  • Exécution asynchrone : profitez des appels d'outils asynchrones pour maintenir le flux de conversation.

  • Dénomination des outils : utilisez des noms descriptifs orientés vers l'action (tels que get_weather, search_database, send_email).