Utilisation d'outils (appel de fonctions)

Les outils étendent les fonctionnalités d'Amazon Nova en connectant le modèle à des fonctionnalités externes telles que APIs les bases de données et les environnements d'exécution de code. L'utilisation d'outils permet à Amazon Nova d'accéder à des informations en temps réel, d'effectuer des calculs et d'interagir avec des systèmes externes.

Comprendre le flux de travail d'utilisation des outils

L'utilisation de l'outil avec Amazon Nova implique trois phases clés :

Requête utilisateur et définition de l'outil

Définissez les outils en fournissant des schémas JSON qui décrivent les fonctionnalités de chaque outil et les exigences d'entrée. La configuration de l'outil doit inclure des informations explicites sur le moment et le mode d'utilisation de chaque outil.

Sélection de l'outil

Lorsqu'un utilisateur envoie un message, Amazon Nova l'analyse pour déterminer si un outil est nécessaire. Ce choix d'outil automatique examine le contexte et décide quel outil (le cas échéant) invoquer. Si Amazon Nova identifie un outil approprié, il renvoie le nom de l'outil et les paramètres requis.

Vous êtes responsable de l'exécution de l'outil en fonction de la demande du modèle. Cela implique d'écrire du code qui invoque les fonctionnalités de l'outil et traite les paramètres d'entrée fournis par le modèle.

Retourner les résultats

Après avoir exécuté l'outil, renvoyez les résultats à Amazon Nova dans un format structuré à l'aide de JSON ou d'une combinaison de texte et d'images. Amazon Nova intègre les résultats de l'outil dans la réponse finale. Si des erreurs se produisent pendant l'exécution, indiquez-le dans la réponse de l'outil pour permettre à Amazon Nova de s'ajuster en conséquence.

Création d'un outil

Définissez les outils à l'aide d'une configuration d'outils qui inclut un ensemble d'outils et éventuellement un paramètre de choix d'outil. Chaque spécification d'outil doit inclure :

• Nom : identifiant clair de l'outil

• Description : explication concise des fonctionnalités de l'outil

• Schéma d'entrée : schéma JSON définissant les paramètres obligatoires et facultatifs

Exemple Exemple de configuration d'outil

tool_config = {
    "tools": [
        {
            "toolSpec": {
                "name": "calculator",
                "description": "A calculator tool that can execute a math equation",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "properties": {
                            "equation": {
                                "type": "string",
                                "description": "The full equation to evaluate"
                            }
                        },
                        "required": ["equation"]
                    }
                }
            }
        }
    ]
}

Bonnes pratiques pour les définitions d'outils

• Assurez-vous que le nom et la description décrivent clairement les fonctionnalités exactes de l'outil ; évitez les outils trop similaires sur le plan sémantique

• Incluez les principaux facteurs de différenciation dans la description pour aider le modèle à faire la distinction entre des outils similaires

• Limitez les schémas JSON à deux couches d'imbrication pour de meilleures performances

• Limitez les entrées à l'aide de types de schéma (par exemple, enum, int, float) plutôt que de décrire la structure en texte brut

• Indiquez les paramètres obligatoires par rapport aux paramètres facultatifs à l'aide de la notation de schéma JSON (par exemple, « required » : ["param1 », « param2 »])

• Validez votre schéma JSON à l'aide d'un validateur standard avant de le soumettre

• Placez les arguments de chaîne longue en dernier dans le schéma et évitez de les imbriquer

Sortie structurée avec décodage contraint

Les modèles Amazon Nova exploitent le décodage restreint pour garantir une fiabilité élevée des sorties générées. Cette technique utilise la grammaire pour limiter les jetons possibles à chaque étape de génération, en empêchant les clés non valides et en appliquant les types de données corrects en fonction du schéma que vous avez défini.

Exemple Exemple de sortie structurée

tool_config = {
    "tools": [
        {
            "toolSpec": {
                "name": "ProductAnalysis",
                "description": "Analyze product information from text.",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "description": "Product name"
                            },
                            "rating": {
                                "maximum": 5,
                                "description": "Customer rating 1-5",
                                "type": ["number", "null"],
                                "minimum": 1
                            },
                            "features": {
                                "description": "Key product features",
                                "type": "array",
                                "items": {"type": "string"}
                            },
                            "category": {
                                "type": "string",
                                "description": "Product category"
                            },
                            "price": {
                                "type": "number",
                                "description": "Price in USD"
                            }
                        },
                        "required": ["name", "category", "price", "features"]
                    }
                }
            }
        }
    ],
    "toolChoice": {
        "tool": {"name": "ProductAnalysis"}
    }
}

Options de choix d'outils

Amazon Nova prend en charge trois paramètres de choix d'outils :

Outil

L'outil spécifié ne sera appelé qu'une seule fois, ce qui est idéal pour les cas d'utilisation de sorties structurées

N’importe lequel

L'un des outils fournis sera appelé au moins une fois, ce qui est utile pour les scénarios de sélection d'API

Auto

Le modèle décide d'appeler ou non un outil et du nombre d'outils à appeler (comportement par défaut)

Appelez un outil

Lorsqu'Amazon Nova décide d'appeler un outil, il renvoie un bloc d'utilisation de l'outil dans le cadre du message d'assistant avec StopReason défini sur « tool_use ». Le bloc d'outils contient le nom de l'outil et ses entrées.

Note

Exécutez les sections de code suivantes de manière séquentielle (Appel d'un outil → Appel d'outil de traitement → Retour des résultats de l'outil) au cours d'une seule session Python. Pour réexécuter les exemples, redémarrez votre session Python.

Exemple Appeler un outil

import boto3
import json

# Create Bedrock client
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

# Complex calculation that benefits from precise computation
messages = [{
    "role": "user",
    "content": [{
        "text": "Calculate the compound interest on $10,000 invested at 4.75% annual rate for 7 years, compounded quarterly. Use the formula A = P(1 + r/n)^(nt) where P=10000, r=0.0475, n=4, t=7"
    }]
}]

# Define tool configuration with calculator
tool_config = {
    "tools": [{
        "toolSpec": {
            "name": "calculator",
            "description": "Perform mathematical calculations",
            "inputSchema": {
                "json": {
                    "type": "object",
                    "properties": {
                        "expression": {
                            "type": "string",
                            "description": "Mathematical expression to evaluate"
                        }
                    },
                    "required": ["expression"]
                }
            }
        }
    }]
}

# Invoke Model
response = bedrock.converse(
    modelId="us.amazon.nova-2-lite-v1:0",
    messages=messages,
    toolConfig=tool_config
)

# Extract tool use from response
tool = next(
    block["toolUse"]
    for block in response["output"]["message"]["content"]
    if "toolUse" in block
)

print(f"Tool: {tool['name']}")
print(f"Expression: {tool['input']['expression']}")

Traitement des appels aux outils

Extrayez le nom et les arguments de l'outil du message, puis invoquez l'outil :

def calculate(expression):
    """Evaluate mathematical expression"""
    print(f"Calculating: {expression}")
    P = 10000
    r = 0.0475
    n = 4
    t = 7
    result = P * (1 + r/n) ** (n*t)
    return result

stop_reason = response["stopReason"]

if stop_reason == "tool_use":
    if tool["name"] == "calculator":
        result = calculate(tool["input"]["expression"])

Renvoi des résultats de l’outil

Renvoie les résultats de l'outil à l'aide du ToolResultBlock schéma suivant :

messages.append(response["output"]["message"])

# Add the tool result
messages.append({
    "role": "user",
    "content": [{
        "toolResult": {
            "toolUseId": tool['toolUseId'],
            "content": [{"json": {"result": result}}],
            "status": "success"
        }
    }]
})

# Send the tool result to the model
response = bedrock.converse(
    modelId="us.amazon.nova-2-lite-v1:0",
    messages=messages,
    toolConfig=tool_config
)

# Extract and display final response
final_text = next(
    block["text"]
    for block in response["output"]["message"]["content"]
    if "text" in block
)

print(f"\nFinal Response:\n{final_text}")

Gestion des erreurs

Signalez les erreurs à Amazon Nova pour autoriser la modification de la demande et réessayez :

tool_result_message = {
    "role": "user",
    "content": [
        {
            "toolResult": {
                "toolUseId": tool["toolUseId"],
                "content": [{"text": "A validation exception occurred on field: sample.field"}],
                "status": "error"
            }
        }
    ]
}

Considérations sur la sécurité

• Vérifiez que les outils existent avant de les invoquer

• Assurez-vous que les entrées sont correctement formatées

• Vérifiez que les autorisations appropriées sont en place avant l'exécution de l'outil

• Fiez-vous aux détails de session plutôt que de permettre à Amazon Nova d'injecter des informations utilisateur dans les appels d'outils

• N'oubliez pas que cela LLMs peut faire halluciner les appels aux outils ; validez toujours avant l'exécution

Outils du système intégrés

Les modèles Amazon Nova 2.0 incluent des outils intégrés entièrement gérés qui ne nécessitent aucune implémentation personnalisée. Activez ces outils à l'aide d'une simple bascule dans l'API Converse.

Interprète de code

L'interpréteur de code permet à Nova d'exécuter du code Python en toute sécurité dans des environnements sandbox isolés. Cet outil est conçu pour les calculs mathématiques, les opérations logiques et les algorithmes itératifs.

Note

L'interpréteur de code est disponible dans les régions IAD, PDX et AWS NRT. Pour vous assurer que vos demandes sont acheminées vers une région prise en charge, utilisez Global CRIS. Lorsque vous utilisez les clés d'API Bedrock, vous devez ajouter manuellement InvokeTool des autorisations aux définitions des politiques. Le rôle Bedrock par défaut n'autorise pas l'InvokeToolaction.

Activez l'interpréteur de code en spécifiant le paramètre SystemTool :

import boto3
import json

bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')

tool_config = {
    "tools": [{
        "systemTool": {
            "name": "nova_code_interpreter"
        }
    }]
}

response = bedrock.converse(
    modelId="us.amazon.nova-2-lite-v1:0",
    messages=[{
        "role": "user",
        "content": [{
            "text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82"
        }]
    }],
    toolConfig=tool_config,
    inferenceConfig={"maxTokens": 10000, "temperature": 0}
)

# Pretty print the response
for block in response["output"]["message"]["content"]:
    if "toolUse" in block:
        print("=== Tool Use ===")
        print(f"Tool: {block['toolUse']['name']}")
        print(f"Code:\n{block['toolUse']['input']['snippet']}\n")
    
    elif "toolResult" in block:
        print("=== Tool Result ===")
        result = block['toolResult']['content'][0]['json']
        print(f"Output: {result['stdOut']}")
        if result['stdErr']:
            print(f"Error: {result['stdErr']}")
        print(f"Exit Code: {result['exitCode']}\n")
    
    elif "text" in block:
        print("=== Final Answer ===")
        print(block["text"])

L'interpréteur exécute le code dans un sandbox et renvoie les résultats dans un schéma standard :

{
    "stdOut": "String",
    "stdErr": "String",
    "exitCode": "int",
    "isError": "boolean"
}

Ancrage Web

Le Web Grounding permet à Amazon Nova d'accéder à des informations en temps réel sur Internet, de fournir des up-to-date réponses et de réduire les hallucinations. Activez en spécifiant l'outil système nova_grounding :

tool_config = {
    "tools": [{
        "systemTool": {"name": "nova_grounding"}
    }]
}

Pour des informations détaillées sur le Web Grounding, consultezAncrage Web.

Protocole de contexte du modèle (MCP)

Le Model Context Protocol (MCP) est un standard ouvert qui permet des connexions bidirectionnelles sécurisées entre les sources de données et les outils basés sur l'IA. Au lieu d'écrire des adaptateurs personnalisés pour chaque API ou service, exécutez un serveur MCP et laissez Amazon Nova découvrir ses outils automatiquement via un pont client.

Une fois connecté, Amazon Nova traite les outils MCP comme toute autre intégration externe : il décide quand les appeler, envoie les paramètres requis et intègre les résultats dans les réponses. L'utilisation d'Amazon Nova avec Strands facilite cette tâche grâce à une fonctionnalité intégrée MCPClient qui gère automatiquement la découverte, la connexion et le mappage des résultats.