Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Utilizzo dello strumento (chiamata delle funzioni) con Amazon Nova
**Nota**
Questa documentazione è per Amazon Nova versione 1. Per informazioni sull'uso degli strumenti con Amazon Nova 2, visita [Using tools (function calling)](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-tools.html).
Gli strumenti sono un modo per fornire funzionalità esterne ad Amazon Nova, come una chiamata API o una funzione di codice. Questa sezione illustrerà come definire e integrare gli strumenti quando lavori con i modelli Amazon Nova.
L’uso degli strumenti prevede tre fasi generali:
+ **Interrogazione dell’utente**: definisci gli strumenti che Amazon Nova può utilizzare fornendo uno schema JSON che descrive le funzionalità e i requisiti di input di ogni strumento.
+ **Selezione dello strumento**: quando un utente invia un messaggio, Amazon Nova lo analizza per determinare se è necessario uno strumento per generare una risposta. Questa operazione viene definita scelta dello strumento `Auto`. Per ulteriori informazioni, consulta [Choosing a tool](https://docs.aws.amazon.com/nova/latest/userguide/tool-choice.html). Se Amazon Nova identifica uno strumento adatto, “chiamerà” lo strumento e restituirà il nome dello strumento e i parametri da utilizzare.
In qualità di sviluppatore, tu sei responsabile dell’esecuzione dello strumento in base alla richiesta del modello. Ciò significa che devi scrivere il codice che invoca la funzionalità dello strumento e l’elaborazione dei parametri di input forniti dal modello.
**Nota**
Come tutte le risposte LLM, è possibile che Amazon Nova produca una chiamata dello strumento. È tua responsabilità, in qualità di sviluppatore, verificare che lo strumento esista, che gli input siano formattati correttamente e che le autorizzazioni appropriate siano già messe in atto.
+ **Restituzione dei risultati**: dopo aver eseguito lo strumento, devi inviare nuovamente i risultati ad Amazon Nova in un formato strutturato. I formati validi includono JSON o una combinazione di testo e immagini. Ciò consente ad Amazon Nova di incorporare l’output dello strumento nella risposta finale all’utente.
Se si verificano errori durante l’esecuzione dello strumento, puoi indicarlo nella risposta dello strumento ad Amazon Nova, consentendo ad Amazon Nova di modificare di conseguenza la sua risposta.
Prendiamo un esempio semplice di uno strumento di calcolo:
------
#### [ User query ]
Il primo passaggio del flusso di lavoro di chiamata dello strumento è la richiesta dell’utente ad Amazon Nova per il risultato di un’equazione matematica, 10 per 5. Questa query viene inviata come prompt ad Amazon Nova insieme a una specifica dello strumento che rappresenta la calcolatrice.
```
user_query = "10*5"
messages = [{
"role": "user",
"content": [{"text": user_query}]
}]
tool_config = {
"tools": [
{
"toolSpec": {
"name": "calculator", # Name of the tool
"description": "A calculator tool that can execute a math equation", # Concise description of the tool
"inputSchema": {
"json": {
"type": "object",
"properties": {
"equation": { # The name of the parameter
"type": "string", # parameter type: string/int/etc
"description": "The full equation to evaluate" # Helpful description of the parameter
}
},
"required": [ # List of all required parameters
"equation"
]
}
}
}
}
]
}
```
------
#### [ Tool selection ]
Amazon Nova utilizza il contesto dello strumento insieme al prompt dell’utente per determinare lo strumento necessario da utilizzare e la configurazione richiesta. Questo viene restituito come parte della risposta dell’API.
```
{
"toolUse": {
"toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
"name": "calculator",
"input": {
"equation": "10*5"
}
}
}
```
L’applicazione è responsabile dell’esecuzione dello strumento e della memorizzazione del risultato.
```
def calculator(equation: str):
return eval(equation)
tool_result = calculator("10*5")
```
------
#### [ Return results ]
Per restituire il risultato dello strumento ad Amazon Nova, il risultato dello strumento viene incluso in una nuova richiesta API. L’ID di utilizzo dello strumento è coerente con quello restituito da Amazon Nova nella risposta precedente.
```
{
"toolResult": {
"toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
"content": [
{
"json": {
"result": "50"
}
}
],
"status": "success"
}
}
```
+ Amazon Nova utilizzerà l’intero contesto dei messaggi, fra cui la query iniziale dell’utente, l’uso dello strumento e il risultato dello strumento per determinare la risposta finale all’utente. In questo caso, Amazon Nova risponderà all’utente che “10 per 5 fa 50”.
------
Amazon Nova consente l’uso di strumenti sia nell’API Invoke che nell’API Converse; tuttavia, per una gamma completa di funzionalità, consigliamo di utilizzare l’[API Converse](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use-inference-call.html) e in futuro utilizzeremo esempi con questa API.
**Topics**
+ [Definizione di uno strumento](tool-use-definition.md)
+ [Invocare uno strumento](tool-use-invocation.md)
+ [Scelta di uno strumento](tool-choice.md)
+ [Restituzione dei risultati dello strumento](tool-use-results.md)
+ [Utilizzo di strumenti integrati](tool-built-in.md)
+ [Segnalazione di un errore](tool-use-error.md)
+ [Riferimenti aggiuntivi](#tool-use-resources)
# Definizione di uno strumento
Una fase fondamentale del flusso di lavoro di chiamata dello strumento è la definizione dello strumento. La definizione dello strumento deve includere tutto il contesto necessario per guidare il modello nel momento in cui è opportuno invocare lo strumento.
Per definire uno strumento, crea una configurazione dello strumento e inseriscila insieme al messaggio dell’utente all’API. Lo schema di [configurazione dello strumento](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html) prevede una varietà di strumenti e, facoltativamente, un parametro di scelta dello strumento.
**Nota**
Amazon Nova supporta le opzioni `auto`, `any` e `tool` per `toolChoice`. Per ulteriori informazioni, consulta [ToolChoice](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolChoice.html)la documentazione dell'API Amazon Bedrock e [Usa uno strumento per completare una risposta del modello Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html).
Di seguito è riportato un esempio di come definire uno strumento:
```
tool_config = {
"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"
]
}
}
}
}
],
}
```
Il nome, la descrizione e lo schema di input devono essere espliciti con la funzionalità esatta dello strumento. Assicurati che tutti i principali fattori di differenziazione relativi all’utilizzo dello strumento siano riflessi nella configurazione dello strumento.
**Nota**
I modelli di comprensione di Amazon Nova attualmente supportano solo un sottoinsieme di JsonSchema funzionalità se utilizzati per definire l'API [ToolInputSchema](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolInputSchema.html)in Converse.
Lo schema di primo livello deve essere di tipo [Object](https://json-schema.org/understanding-json-schema/reference/object).
Nello schema Object di primo livello sono supportati solo tre campi: tipo (deve essere impostato su “object”), [https://json-schema.org/understanding-json-schema/reference/object#properties](https://json-schema.org/understanding-json-schema/reference/object#properties) e [https://json-schema.org/understanding-json-schema/reference/object#required](https://json-schema.org/understanding-json-schema/reference/object#required).
Per la chiamata dello strumento, consigliamo di impostare la temperatura su 0 per consentire la decodifica greedy.
Di seguito è riportato un esempio di chiamata di uno strumento con l’API Converse:
```
import json
import boto3
client = boto3.client("bedrock-runtime", region_name="us-east-1")
input_text = "What is the most popular song on WZPZ?"
messages = [{
"role": "user",
"content": [{"text": input_text}]
}]
inf_params = {"maxTokens": 1000, "temperature": 0}
response = client.converse(
modelId="us.amazon.nova-lite-v1:0",
messages=messages,
toolConfig=tool_config,
inferenceConfig=inf_params
)
messages.append(response["output"]["message"])
# Pretty print the response JSON.
print("[Full Response]")
print(json.dumps(response, indent=2))
# Print the tool content for easy readability.
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
print("\n[Tool Response]")
print(tool)
```
# Invocare uno strumento
Se Amazon Nova decide di chiamare uno strumento, verrà restituito un blocco sull’uso dello strumento come parte del messaggio dell’assistente e il motivo dell’interruzione sarà “tool\$1use”. Il blocco dello strumento conterrà il nome dello strumento e i relativi input.
**Nota**
Per migliorare la precisione delle chiamate agli strumenti, il comportamento predefinito dei modelli Amazon Nova consiste nell'utilizzare il chain-of-thought ragionamento per la chiamata agli strumenti. Il processo di pensiero verrà reso disponibile nel messaggio dell’assistente e sarà contenuto nei tag . È possibile avere molteplici chiamate degli strumenti e blocchi di pensiero, quindi l’applicazione deve tenerne conto.
Se la scelta dello strumento è configurata su `any` o`tool`, questo avrà la precedenza sul chain-of-thought comportamento e la risposta conterrà solo le chiamate allo strumento necessarie.
```
{
"toolUse":
{
"toolUseId": "tooluse_20Z9zl0BQWSXjFuLKdTJcA",
"name": "top_song",
"input": {
"sign": "WZPZ"
}
}
}
```
Per chiamare effettivamente lo strumento, è possibile estrarre il nome dello strumento e gli argomenti dal messaggio e l’applicazione può quindi invocarlo.
Ecco un esempio di come puoi elaborare una chiamata dello strumento.
```
def get_top_song(sign):
print(f"Getting the top song at {sign}")
return ("Espresso", "Sabrina Carpenter")
stop_reason = response["stopReason"]
tool, song, artist = None, None, None
if stop_reason == "tool_use":
thought_process = next(
block["text"]
for block in response["output"]["message"]["content"]
if "text" in block
)
print(thought_process)
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
if tool["name"] == "top_song":
song, artist = get_top_song(tool["input"]["sign"])
```
È importante tenere a mente la sicurezza quando si definiscono e si richiamano gli strumenti. LLMs come Amazon Nova non hanno accesso ai dettagli della sessione, quindi le autorizzazioni devono essere convalidate quando necessario prima di richiamare uno strumento. Basati sui dettagli utente della sessione invece di migliorare il prompt e consentire ad Amazon Nova di inserirlo nella chiamata dello strumento.
# Scelta di uno strumento
I modelli Amazon Nova supportano la funzionalità di *scelta degli strumenti*. La scelta dello strumento ti consente, in qualità di sviluppatore, di controllare il modo in cui viene chiamato uno strumento. Sono supportate tre opzioni di parametro per la scelta dello strumento: `tool`, `any` e `auto`.
+ **Tool**: verrà effettuata una chiamata allo strumento specificato.
+ **Any**: verrà effettuata almeno una chiamata a uno degli strumenti forniti.
+ **Auto**: il modello deciderà se richiamare uno strumento e, se necessario, verranno chiamati più strumenti.
------
#### [ Tool ]
L’utilizzo di `tool` come scelta dello strumento di controllare lo strumento specifico chiamato dal modello. L’esempio seguente evidenzia questo aspetto con un caso d’uso di output strutturato in cui la risposta deve essere formattata in modo coerente.
```
tool_config = {
"toolChoice": {
"tool": { "name" : "extract_recipe"}
},
"tools": [
{
"toolSpec": {
"name": "extract_recipe",
"description": "Extract recipe for cooking instructions",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the recipe"
},
"description": {
"type": "string",
"description": "Brief description of the dish"
},
"ingredients": {
"type": "array",
"items": {
"type": "string",
"description": "Name of ingredient"
}
}
},
"required": ["name", "description", "ingredients"]
}
}
}
}
]
}
```
------
#### [ Any ]
L’utilizzo di `any` come scelta dello strumento consente di garantire che venga chiamato almeno uno strumento ogni volta. Sebbene la decisione su quale strumento chiamare sia lasciata al modello, verrà sempre restituito uno strumento. L’esempio seguente evidenzia la scelta dello strumento “any” per un caso d’uso di un endpoint di selezione delle API. Questo è un esempio di quando è utile richiedere al modello di restituire uno strumento specifico.
```
tool_config = {
"toolChoice": {
"any": {}
},
"tools": [
{
"toolSpec": {
"name": "get_all_products",
"description": "API to retrieve multiple products with filtering and pagination options",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"sort_by": {
"type": "string",
"description": "Field to sort results by. One of: price, name, created_date, popularity",
"default": "created_date"
},
"sort_order": {
"type": "string",
"description": "Order of sorting (ascending or descending). One of: asc, desc",
"default": "desc"
},
},
"required": []
}
}
}
},
{
"toolSpec": {
"name": "get_products_by_id",
"description": "API to retrieve retail products based on search criteria",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Unique identifier of the product"
},
},
"required": ["product_id"]
}
}
}
}
]
}
```
------
#### [ Auto ]
L’utilizzo di `auto` come scelta dello strumento è la funzionalità predefinita del supporto degli strumenti e consente al modello di decidere quando chiamare uno strumento e quanti strumenti chiamare. Questo è il comportamento se non includi la scelta dello strumento nella richiesta.
**Nota**
Il comportamento predefinito della chiamata agli strumenti di Amazon Nova è quello di utilizzare chain-of-thought per la selezione degli strumenti. Quando si utilizza il comportamento predefinito o la scelta dello strumento `auto`, nei tag verrà visualizzato anche l’output del processo di pensiero.
L’esempio seguente evidenzia un caso d’uso di un chatbot in cui potresti voler consentire al modello di cercare su Internet informazioni recenti o di rispondere direttamente all’utente. Questa scelta dello strumento offre flessibilità e lascerà il ragionamento al modello.
```
tool_config = {
"toolChoice": {
"auto": {}
},
"tools": [
{
"toolSpec": {
"name": "search",
"description": "API that provides access to the internet",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Query to search by",
},
},
"required": ["query"]
}
}
}
}
]
}
```
------
**Nota**
Quando imposti il parametro di scelta dello strumento, potresti continuare a visualizzare il testo di output del modello o eseguire chiamate sequenziali dello strumento dopo la selezione dello strumento originale. Ti consigliamo di impostare qui una sequenza di arresto per limitare l’output al solo strumento:
```
“stopSequences”: [“”]
```
Per ulteriori informazioni, consulta la guida [InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_InferenceConfiguration.html)all'API di Amazon Bedrock.
# Restituzione dei risultati dello strumento
Una volta che lo strumento è stato invocato dall’applicazione, la fase finale prevede la fornitura del risultato dello strumento al modello. Questa operazione viene eseguita restituendo un risultato dello strumento con l’ID della chiamata dello strumento e il contenuto della risposta. Questo contenuto segue lo [ToolResultBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultBlock.html)schema:
```
{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}],
"status": "success"
}
}
```
Il contenuto del `ToolResultBlock` deve essere un singolo JSON o una combinazione di testo e immagini.
Il campo dello stato può essere utilizzato per indicare al modello lo stato dell’esecuzione dello strumento. Se l'esecuzione dello strumento non riesce, puoi indicare l'errore e Amazon Nova tenterà di modificare la chiamata allo strumento originale.
Per ulteriori dettagli sullo schema, consulta la [ToolResultContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolResultContentBlock.html)documentazione.
Di seguito è riportato un esempio di come utilizzare l’API Converse per restituire i risultati dello strumento:
```
messages.append({
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}],
"status": "success"
}
}
]
})
inf_params = {"maxTokens": 1000, "temperature": 0}
# Send the tool result to the model.
response = client.converse(
modelId="us.amazon.nova-lite-v1:0",
messages=messages,
toolConfig=tool_config,
inferenceConfig=inf_params
)
print(response['output']['message'])
```
Per ulteriori dettagli su come sfruttare gli strumenti, consulta la documentazione [Amazon Bedrock Tool Use](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html) o visita [gli esempi di utilizzo degli strumenti](https://github.com/aws-samples/amazon-nova-samples/blob/main/multimodal-understanding/repeatable-patterns/10-tool-calling-with-converse/10_tool_calling_with_converse.ipynb) nel repository degli esempi di Amazon Nova.
# Utilizzo di strumenti integrati
Gli strumenti integrati sono strumenti completamente gestiti e disponibili immediatamente, senza bisogno di implementazioni personalizzate. Questi possono essere abilitati nell'API Converse con un semplice interruttore.
## Interprete di codice
Code Interpreter consente a Nova di eseguire in modo sicuro il codice Python in ambienti sandbox isolati. Ciò consente la scrittura e l'esecuzione di codice, l'analisi dei dati, la creazione di visualizzazioni e la risoluzione di problemi matematici. Ad esempio, Code Interpreter può essere utilizzato per:
+ Generare report finanziari basati sui dati caricati
+ Analisi statistiche complete o simulazioni di algoritmi
+ Esegui script di migrazione del database in ambienti isolati
+ Esegui test unitari per il nuovo codice generato
Ecco un esempio di come abilitare Code Interpreter con l'API Converse:
```
{
"messages": [
{
"role": "user",
"content": [{"text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82")}]
}
],
"toolConfig": {
"tools": [
{
"systemTool": {
"name": "nova_code_interpreter"
}
}
]
},
```
In questo caso, il modello determinerà che la richiesta richiede un calcolo, quindi genera il codice Python richiesto e chiama lo strumento interprete del codice.
```
{
"toolUse": {
"input": {
"code": "'''Calculate the average of the given numbers.'''\nnumbers = [10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82]\nsum_numbers = sum(numbers)\ncount = len(numbers)\naverage = sum_numbers / count\n(sum_numbers, count, average)"
},
"name": "nova_code_interpreter",
"toolUseId": "tooluse_WytfF0g1S5qUeEPm0ptOdQ",
"type": "server_tool_use"
}
},
```
L'interprete esegue questo codice in una sandbox e acquisisce il risultato, restituito in uno schema standard:
```
{
"stdOut": String,
"stdErr": String,
"exitCode": int,
"isError": boolean
}
```
In questo caso, riceverai in cambio:
```
{
"toolResult": {
"content": [
{
"text": "{\"stdOut\":\"(1212, 12, 101.0)\",\"stdErr\":\"\",\"exitCode\":0,\"isError\":false}"
}
],
"status": "success",
"toolUseId": "tooluse_WytfF0g1S5qUeEPm0ptOdQ",
"type": "nova_code_interpreter_result"
}
}
```
## Model Context Protocol
Il Model Context Protocol (MCP) è uno standard aperto che consente agli sviluppatori di creare connessioni bidirezionali sicure tra le fonti di dati e gli strumenti basati sull'intelligenza artificiale. Invece di scrivere adattatori personalizzati per ogni API o servizio, puoi eseguire un server MCP e lasciare che Nova scopra automaticamente i suoi strumenti tramite un bridge client. Una volta connessa, Nova tratta questi strumenti come qualsiasi altra integrazione esterna: decide quando chiamarli, invia i parametri richiesti e incorpora i risultati nella sua risposta.
# Segnalazione di un errore
In alcuni casi, i parametri selezionati da Amazon Nova possono causare un errore esterno. Quindi, può essere utile comunicarlo ad Amazon Nova in modo tale che la richiesta possa essere modificata e ritentata. Per notificare gli errori, restituisci comunque il risultato di uno strumento ma modifica lo stato per segnalare l’errore e condividi il messaggio di eccezione.
Questo è un esempio che riporta un messaggio di stato di errore:
```
tool_result_message = {
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool["toolUseId"],
"content": [{"text": "A validation exception occured on field: sample.field"}],
"status": "error"
}
}
]
}
```
## Riferimenti aggiuntivi
1. [Utilizzo di uno strumento per completare una risposta al modello](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)
1. [Creazione di agenti IA con Amazon Nova](agents.md)
1. [Best practice di prompting per la comprensione del testo](prompting-text-understanding.md)
1. [Risoluzione dei problemi di chiamata agli strumenti](prompting-tool-troubleshooting.md)