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à. # Server-side uso dello strumento Se si utilizza l'API Responses per richiamare il modello, è possibile utilizzare la chiamata allo strumento dal lato server, oltre alla chiamata allo strumento lato client di cui abbiamo parlato in precedenza. Server-side la chiamata agli strumenti è un meccanismo in cui gli strumenti (API, funzioni, flussi di lavoro) vengono eseguiti in un ambiente di backend affidabile, non sul client. Ciò migliora la sicurezza, l'affidabilità e la posizione di governance dell'applicazione. Prima che Amazon Bedrock esegua la funzione Lambda che implementa l'uso dello strumento, si assicura che la funzione Lambda abbia la stessa policy IAM dell'applicazione che la chiama. Poiché Amazon Bedrock sta guidando l'esecuzione degli strumenti, i clienti possono concentrarsi sull'implementazione della loro logica di business, piuttosto che sull'aggiunta di funzionalità degli strumenti. Amazon Bedrock supporta anche i più elevati standard di governance come ISO, SOC e HIPAA. I clienti possono inviare la propria funzione Lambda personalizzata per eseguire lo strumento o utilizzare strumenti predefiniti esistenti, come note e attività. Server-side gli strumenti che utilizzano l'API Responses sono disponibili a partire dai modelli GPT OSS di OpenAI, mentre il supporto per altri 20B/120B modelli sarà presto disponibile. Puoi utilizzare l'API Models per scoprire i modelli disponibili che puoi utilizzare con l'API Responses. Per maggiori dettagli sull'API Responses, consulta [Generare risposte utilizzando le API OpenAI](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html). Esistono due tipi di strumenti che puoi utilizzare con Amazon Bedrock: strumenti personalizzati che utilizzano Lambda o strumenti predefiniti supportati da Bedrock. In questa sezione esamineremo come creare uno strumento Lambda personalizzato con l'API Responses. Parliamo di entrambi in dettaglio. **Strumenti personalizzati che utilizzano Lambda nell'API Responses** Utilizzando una funzione Lambda come strumento personalizzato in Bedrock, puoi estendere le funzionalità dell'agente integrando funzioni AWS Lambda personalizzate come strumenti. Ciò consente di creare strumenti scalabili e senza server che possono essere richiamati dagli assistenti AI e da altre applicazioni tramite il Model Context Protocol (MCP). Ecco i vantaggi di questa funzionalità: + Estendi la funzionalità: aggiungi logica aziendale personalizzata, integrazioni API o funzionalità di elaborazione dei dati. + Esegui gli strumenti in modo sicuro: Lambda consente agli strumenti di accedere alle risorse all'interno di un VPC senza dover concedere l'accesso completo al VPC. + Architettura serverless: nessuna gestione dell'infrastruttura, Lambda gestisce la scalabilità automaticamente. + Conveniente: paga solo per i tempi di esecuzione, non per le risorse inutilizzate. + Integrazione semplice: le funzioni Lambda vengono visualizzate senza problemi insieme agli strumenti integrati. Per consentire a un modello in Amazon Bedrock di utilizzare uno strumento per completare una risposta a un messaggio, devi inviare il messaggio e le definizioni di uno o più strumenti al modello. In base al prompt dell'applicazione, se il modello determina che uno degli strumenti può contribuire a generare una risposta, restituisce una richiesta a Bedrock di utilizzare lo strumento e invia i risultati dello strumento al modello. Il modello utilizza quindi il risultato dello strumento per generare una risposta al messaggio originale. I passaggi seguenti mostrano come utilizzare uno strumento con l'API [Responses](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html). **Come funziona** 1. Funzione **Lambda: crea la tua funzione** Lambda che implementa il protocollo MCP 1. **Tool Discovery**: Bedrock chiama la funzione Lambda per scoprire gli strumenti disponibili 1. **Registrazione degli strumenti**: i tuoi strumenti sono registrati con Bedrock 1. **Esecuzione dello strumento**: quando l'agente richiede lo strumento, Bedrock richiama la funzione Lambda 1. **Gestione delle risposte**: i risultati vengono restituiti all'agente tramite l'interfaccia standard **Fase 1: Definire la funzione Lambda per ottenere la canzone più popolare** Crea una funzione Lambda che implementa il protocollo MCP. Ecco un semplice esempio in Python: ``` import json def lambda_handler(event, context): # Parse JSON-RPC request method = event.get('method') params = event.get('params', {}) request_id = event.get('id') if method == 'tools/list': return { "jsonrpc": "2.0", "id": request_id, "result": { "tools": [ { "name": "my_custom_tool", "description": "My custom business logic tool", "inputSchema": { "type": "object", "properties": { "input": { "type": "string", "description": "Input text to process" } }, "required": ["input"] } } ] } } elif method == 'tools/call': tool_name = params.get('name') arguments = params.get('arguments', {}) if tool_name == 'my_custom_tool': # Your custom logic here result = f"Processed: {arguments.get('input', '')}" return { "jsonrpc": "2.0", "id": request_id, "result": { "content": [ { "type": "text", "text": result } ] } } # Error response for unsupported methods return { "jsonrpc": "2.0", "id": request_id, "error": { "code": -32601, "message": "Method not found" } } ``` **Fase 2: Implementazione della funzione Lambda** Successivamente, usa il tuo ruolo IAM per implementare questa funzione Lambda per ottenere un ARN. [Puoi leggere ulteriori informazioni sull'implementazione di una funzione Lambda qui.](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) ``` # Example using AWS CLI aws lambda create-function \ --function-name my-custom-tool \ --runtime python3.14 \ --role arn:aws:iam::YOUR-ACCOUNT:role/lambda-execution-role \ --handler lambda_function.lambda_handler \ --zip-file fileb://function.zip ``` Supponiamo che il tuo ARN sia: `arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool` **Fase 3: Definizione del messaggio e dello strumento nella richiesta di inferenza** Per inviare il messaggio e la definizione dello strumento, si utilizzano le operazioni dell'[API Responses](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html). Amazon Bedrock utilizza i [connettori e la funzionalità dei server MCP remoti dell'API Responses per fornire funzionalità di utilizzo](https://platform.openai.com/docs/guides/tools-connectors-mcp) degli strumenti. La definizione dello strumento è uno schema JSON che passi il parametro di richiesta mcp all'operazione Create. Nel `connector_id` campo dell'API dei connettori di Responses, puoi passare l'ARN Lambda che hai creato nel passaggio precedente. Non è necessario fornire le credenziali di autorizzazione poiché Bedrock utilizza gli stessi ruoli e le stesse policy IAM utilizzati per l'applicazione che richiama il modello. L’esempio seguente mostra uno schema per uno strumento che restituisce i brani più popolari trasmessi da una stazione radio. ``` from openai import OpenAI client = OpenAI() resp = client.responses.create( model="oss-gpt-120b", tools=[ { "type": "mcp", "server_label": "xamzn_arn", "connector_id": "arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool", "require_approval": "never", }, ], input="My custom prompt.", ) print(resp.output_text) ``` **Fase 4: Bedrock chiama lo strumento e restituisce la risposta al modello** La possibilità di utilizzare lo strumento di connessione è disponibile nei modelli che supportano l'[API Responses](https://platform.openai.com/docs/api-reference/responses/create). Controlla quali strumenti supportano il tuo modello [qui](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html). Quando utilizzi strumenti che utilizzano l'API Responses, paghi solo [i token](https://platform.openai.com/docs/pricing) utilizzati per importare le definizioni degli strumenti o effettuare chiamate agli strumenti. Non sono previsti costi aggiuntivi per ogni chiamata allo strumento. Quando specifichi una funzione Lambda nel `tools` parametro, l'API tenterà di ottenere un elenco di strumenti dal server. Se il recupero dell'elenco degli strumenti ha successo, nell'`mcp_list_tools`output della risposta del modello verrà visualizzato un nuovo elemento di output. La `tools` proprietà di questo oggetto mostrerà gli strumenti che sono stati importati con successo. Una volta che il modello ha accesso a queste definizioni di utensili, può scegliere di chiamarle a seconda del contesto del modello. Quando il modello decide di chiamare uno strumento Lambda, l'API invia una richiesta alla funzione Lambda per richiamare lo strumento e inserirne l'output nel contesto del modello. Puoi leggere di più sugli strumenti di elenco e sugli strumenti di chiamata nella documentazione di [OpenAI](https://platform.openai.com/docs/guides/tools-connectors-mcp?quickstart-panels=connector). Tieni presente che la tua funzione Lambda deve avere gli stessi ruoli e policy IAM associati a quella dell'applicazione che chiama il modello in Bedrock, altrimenti la funzione Lambda fallirà. Di seguito è riportata la definizione dell'errore. ``` { "jsonrpc": "2.0", "id": 1, "error": { "code": -32000, "message": "Tool execution failed", "data": "Additional error details" } } ``` **Utilizzo degli strumenti forniti da AWS nell'API Responses** Esistono due strumenti forniti da AWS integrati nei `openai.gpt-oss-120b` modelli `openai.gpt-oss-20b` and: Note-taking funzionalità (strumento per le note) e gestione delle attività (strumento per le attività). Questi strumenti sono disponibili automaticamente: non è necessario definirli nel `tools` parametro. **Panoramica dello strumento Notes** Lo `notes` strumento consente al modello di memorizzare note all'interno della stessa sessione di conversazione. Ciò fornisce un semplice meccanismo di memoria per mantenere il contesto tra più interazioni. La memoria è limitata solo alla conversazione corrente. Quando il modello utilizza lo strumento per le note, emette un `mcp_call` output `name` impostato su. `"notes"` Il modello determina gli argomenti appropriati in base alla richiesta. Puoi usare entrambi i linguaggi naturali (ad esempio «Ricorda che il mio colore preferito è il blu», «Cosa ti ho detto del mio colore preferito?» , «Memorizza il fatto che preferisco le riunioni mattutine», «Ricorda ciò che ho detto sulle preferenze relative alle riunioni») oppure puoi utilizzare le chiamate telefoniche dirette quando ti viene richiesto («Usa lo strumento per le note per memorizzare la mia email come john@example.com «, «Controlla le note per il mio indirizzo e-mail»). **Panoramica dello strumento Tasks** Lo `tasks` strumento fornisce uno stack per la gestione delle attività all'interno di una sessione di conversazione. Puoi inserire le attività nello stack e disattivarle, rendendolo utile per la gestione dei flussi di lavoro, dei promemoria o della gestione gerarchica delle attività. Le attività persistono per tutta la sessione di conversazione. La memoria è limitata solo alla conversazione corrente. Quando il modello utilizza lo strumento Tasks, emette un `mcp_call` output `name` impostato su. `"tasks"` Il modello determina gli argomenti appropriati (ad esempio `method``task.title`, e`task.description`) in base alla richiesta. Puoi chiamare lo strumento Tasks utilizzando il linguaggio naturale (ad esempio «Aggiungi un'attività per rivedere il budget», «Invia un promemoria per chiamare il cliente», «Qual è la prossima attività che devo fare?» , «Inserisci l'attività più recente», «Scarica l'ultima attività dal mio stack») oppure puoi chiamare lo strumento direttamente nel tuo prompt («Usa lo strumento delle attività per premere 'finisci presentazione'», «Inserisci un'attività dalla pila», «Aggiungi 'pianifica riunione' al mio elenco di attività»). **Esempio di codice: utilizzo degli strumenti per le note e le attività** Gli strumenti per le note e le attività sono integrati nei `openai.gpt-oss-120b` modelli `openai.gpt-oss-20b` and. Non è necessario definirli esplicitamente nel `tools` parametro: è sufficiente farvi riferimento nel prompt: ``` from openai import OpenAI client = OpenAI( base_url="https://bedrock-mantle.us-east-1.api.aws/v1" ) # The notes tool is built-in — just ask the model to use it resp = client.responses.create( model="openai.gpt-oss-120b", input="Use the notes tool to store that my preferred language is Python.", ) print(resp.output) # The model automatically calls the notes tool via mcp_call # Use the tasks tool to push a task resp = client.responses.create( model="openai.gpt-oss-120b", input="Use the tasks tool to push a task: review the API documentation", ) print(resp.output) ``` ## Server-side integrazione dell'uso degli strumenti con Gateway AgentCore Amazon Bedrock ora supporta [AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html) come strumento lato server che chiama tipo di integrazione. Questa funzionalità consente di connettere i modelli direttamente agli endpoint AgentCore Gateway, permettendo un accesso senza interruzioni agli strumenti gestiti tramite l'infrastruttura gateway. L'integrazione AgentCore Gateway segue lo stesso schema dell'integrazione delle funzioni Lambda, con una differenza fondamentale. **Integrazione Lambda:** + Utilizza gli ARN della funzione Lambda + Richiama direttamente le funzioni AWS Lambda **AgentCore Integrazione con gateway:** + Utilizza AgentCore Gateway ARN + Instrada le chiamate agli strumenti attraverso l'infrastruttura AgentCore Gateway + Fornisce la gestione e l'individuazione centralizzate degli strumenti ### Configurazione **Struttura della richiesta** Quando configuri AgentCore Gateway come fonte di strumenti, utilizza la seguente struttura nell'`tools`array nella richiesta dell'API Responses. ``` { "type":"mcp", "server_label":"agentcore_tools", "connector_id":"arn:aws:bedrock-agentcore:us-west-2:342789630635:gateway/agentcore-intro-gateway-v2-swvq44sovp", "server_description":"AgentCore Gateway providing custom tools", "require_approval":"never" } ``` **Parametri** | Parametro | Tipo | Campo obbligatorio | Descrizione | | --- | --- | --- | --- | | type | stringa | Sì | Deve essere impostato su mcp | | server\_label | stringa | Sì | Un identificatore univoco per questo connettore dello strumento all'interno della richiesta | | connector\_id | stringa | Sì | L'ARN del tuo gateway AgentCore | | server\_description | stringa | No | Human-readable descrizione degli strumenti forniti da questo gateway | | require\_approval | stringa | Sì | Il campo deve essere "never" | **Esempio di richiesta completo** ``` { "model":"openai.gpt-oss-120b", "stream":true, "background":false, "store":false, "tools": [ { "type":"mcp", "server_label":"agentcore_tools", "connector_id":"arn:aws:bedrock-agentcore:us-west-2:342789630635:gateway/agentcore-intro-gateway-v2-swvq44sovp", "server_description":"AgentCore Gateway providing custom tools", "require_approval":"never" } ], "input": [ { "type":"message", "role":"user", "content": [ { "type":"input_text", "text":"What is the weather in Seattle?" } ] } ] } ``` ### Prerequisiti Prima di utilizzare l'integrazione con AgentCore Gateway, assicuratevi di avere: 1. **Creazione di un AgentCore gateway** con obiettivi configurati (funzioni Lambda, fasi API Gateway, schemi OpenAPI o server MCP) 1. **Autorizzazioni IAM configurate** che consentono al ruolo del servizio Bedrock di richiamare il gateway. Tieni presente che Bedrock supporta solo i gateway con autenticazione IAM. 1. **Gateway ARN** nel formato corretto ### Vantaggi dell'integrazione con AgentCore Gateway + **Gestione centralizzata degli strumenti**: gestisci tutti gli strumenti tramite un unico endpoint gateway + **Tool Discovery**: gli agenti possono scoprire dinamicamente gli strumenti disponibili tramite il gateway + **Sicurezza**: Built-in autenticazione e autorizzazione tramite IAM e policy di gateway + **Osservabilità**: monitoraggio e registrazione completi delle chiamate degli strumenti + **Flessibilità**: Supporto per più tipi di destinazione (Lambda, API Gateway, OpenAPI, server MCP) ### Autorizzazioni IAM Il tuo ruolo di esecuzione Bedrock richiede l'autorizzazione per richiamare il Gateway: AgentCore ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "bedrock-agentcore:InvokeGateway" ], "Resource": "arn:aws:bedrock-agentcore:us-west-2:342789630635:gateway/agentcore-intro-gateway-v2-swvq44sovp" } ] } ``` ### Fasi successive + [Scopri di più sulla creazione di gateway AgentCore ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-create.html) + Esplora i tipi di [target dei gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-targets.html) + Esamina le [migliori pratiche di sicurezza del gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-security.html)