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.

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à:

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.

Come funziona

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.

# 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. Amazon Bedrock utilizza i connettori e la funzionalità dei server MCP remoti dell'API Responses per fornire funzionalità di utilizzo 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. Controlla quali strumenti supportano il tuo modello qui. Quando utilizzi strumenti che utilizzano l'API Responses, paghi solo i token 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_toolsoutput 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. 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 methodtask.title, etask.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 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:

AgentCore Integrazione con gateway:

Configurazione

Struttura della richiesta

Quando configuri AgentCore Gateway come fonte di strumenti, utilizza la seguente struttura nell'toolsarray 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

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:

Vantaggi dell'integrazione con AgentCore Gateway

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