Utilizzo degli strumenti (chiamata di funzioni)

Gli strumenti estendono le funzionalità di Amazon Nova collegando il modello a funzionalità esterne come APIs database e ambienti di esecuzione del codice. L'uso degli strumenti consente ad Amazon Nova di accedere a informazioni in tempo reale, eseguire calcoli e interagire con sistemi esterni.

Comprendere il flusso di lavoro relativo all'utilizzo degli strumenti

L'uso dello strumento con Amazon Nova prevede tre fasi chiave:

Crea uno strumento

Definite gli utensili utilizzando una configurazione dell'utensile che include una serie di strumenti e, facoltativamente, un parametro di scelta dell'utensile. Le specifiche di ogni utensile devono includere:

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"]
                    }
                }
            }
        }
    ]
}

Migliori pratiche per le definizioni degli strumenti

Output strutturato con decodifica vincolata

I modelli Amazon Nova sfruttano la decodifica vincolata per garantire un'elevata affidabilità negli output generati. Questa tecnica utilizza la grammatica per limitare i possibili token in ogni fase della generazione, evitando chiavi non valide e applicando i tipi di dati corretti in base allo schema definito.

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"}
    }
}

Opzioni di scelta degli utensili

Amazon Nova supporta tre parametri di scelta degli strumenti:

Chiamate uno strumento

Quando Amazon Nova decide di chiamare uno strumento, restituisce un blocco di utilizzo dello strumento come parte del messaggio dell'assistente con stopReason impostato su «tool_use». Il blocco di strumenti contiene il nome dello strumento e i relativi input.

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']}")

Elaborazione delle chiamate agli strumenti

Estrai il nome e gli argomenti dello strumento dal messaggio, quindi richiama lo strumento:

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"])

Restituzione dei risultati dello strumento

Restituisci i risultati dello strumento utilizzando lo ToolResultBlock schema:

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}")

Gestione degli errori

Segnala gli errori ad Amazon Nova per consentire la modifica della richiesta e riprova:

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

Considerazioni relative alla sicurezza

Strumenti di sistema integrati

I modelli Amazon Nova 2.0 includono strumenti integrati completamente gestiti che non richiedono implementazioni personalizzate. Abilita questi strumenti con un semplice interruttore nell'API Converse.

Interprete di codice

Code Interpreter consente a Nova di eseguire in modo sicuro il codice Python in ambienti sandbox isolati. Questo strumento è progettato per calcoli matematici, operazioni logiche e algoritmi iterativi.

Abilita Code Interpreter specificando il parametro 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'interprete esegue il codice in una sandbox e restituisce i risultati in uno schema standard:

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

Web grounding

Il Web grounding consente ad Amazon Nova di accedere a informazioni in tempo reale da Internet, fornendo up-to-date risposte e riducendo le allucinazioni. Abilita specificando lo strumento di sistema nova_grounding:

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

Per informazioni dettagliate su Web Grounding, vedere. Web grounding

Model Context Protocol (MCP)

Il Model Context Protocol (MCP) è uno standard aperto che consente connessioni sicure e bidirezionali tra fonti di dati e strumenti basati sull'intelligenza artificiale. Invece di scrivere adattatori personalizzati per ogni API o servizio, esegui un server MCP e consenti ad Amazon Nova di scoprire automaticamente i suoi strumenti tramite un bridge client.

Una volta connesso, Amazon Nova tratta gli strumenti MCP come qualsiasi altra integrazione esterna: decide quando chiamarli, invia i parametri richiesti e incorpora i risultati nelle risposte. L'uso di Amazon Nova con Strands semplifica questa operazione grazie a un sistema integrato MCPClient che gestisce automaticamente il rilevamento, la connessione e la mappatura dei risultati.