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 utilizzi l'API Responses per richiamare il modello, può utilizzare la chiamata allo strumento lato server, oltre alla chiamata allo strumento lato client di cui abbiamo discusso in precedenza. Server-side la chiamata agli strumenti è un meccanismo in cui gli strumenti (API, funzioni, flussi di lavoro) vengono eseguiti in un ambiente 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 di quella dell'applicazione che la chiama. Poiché Amazon Bedrock gestisce l'esecuzione degli strumenti, i clienti possono concentrarsi sull'implementazione della logica aziendale, anziché sull'aggiunta delle funzionalità degli strumenti. Amazon Bedrock supporta anche gli standard di governance più elevati, come quelli idonei a ISO, SOC e HIPAA. Puoi inviare la tua 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, con il supporto per altri 20B/120B modelli in arrivo a breve. 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 Amazon Bedrock. Questa sezione spiega come creare uno strumento Lambda personalizzato con l'API Responses. Le sezioni seguenti descrivono ogni tipo in dettaglio.

Strumenti personalizzati che utilizzano Lambda nell'API Responses

Utilizzando una funzione Lambda come strumento personalizzato in Amazon Bedrock, puoi estendere le funzionalità dell'agente integrando funzioni Lambda personalizzate come strumenti. In questo modo, puoi 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 ad Amazon Bedrock di utilizzare lo strumento e di inviare 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 bedrock/latest/userguide/bedrock-mantle.html Responses.

Come funziona

Passo 1: Definisci 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: Implementa la funzione Lambda

Quindi, usa il tuo ruolo IAM per distribuire questa funzione Lambda per ottenere un ARN. Puoi saperne di più in Guida introduttiva a Lambda nella Lambda Developer Guide.

# 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: Definisci il messaggio e la definizione dello strumento nella tua richiesta di inferenza

Per inviare il messaggio e la definizione dello strumento, utilizzi le operazioni dell'API Responses. Amazon Bedrock utilizza i connettori e le funzionalità dei server MCP remoti dell'API Responses per fornire funzionalità di utilizzo degli strumenti. La definizione dello strumento è uno schema JSON che si passa nel parametro di richiesta mcp all'operazione Create. Nel connector_id campo dell'API Responses connectors, puoi passare il Lambda ARN che hai creato nel passaggio precedente. Non è necessario fornire credenziali di autorizzazione perché Amazon Bedrock utilizza gli stessi ruoli e 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 trasmette la risposta al modello

La possibilità di utilizzare lo strumento di connessione è disponibile nei modelli che supportano l'API https://platform.openai.com/docs/api-reference/responses/create Responses. Verifica quali strumenti supportano il tuo modello in Genera risposte utilizzando le API OpenAI. 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 si specifica una funzione Lambda nel tools parametro, l'API tenterà di ottenere un elenco di strumenti dal server. Se si riesce a recuperare l'elenco degli strumenti, 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 correttamente. Dopo che il modello avrà accesso a queste definizioni degli strumenti, potrebbe scegliere di chiamarle a seconda del contesto del modello. Quando il modello decide di chiamare uno strumento Lambda, l'API richiederà alla funzione Lambda di chiamare lo strumento e inserirne l'output nel contesto del modello. Puoi leggere ulteriori informazioni sull'elenco degli strumenti e degli strumenti di chiamata nella documentazione di OpenAI. Nota che la tua funzione Lambda deve avere gli stessi ruoli e policy IAM associati a quelli dell'applicazione che chiama il modello in Amazon 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 AWS forniti nell'API Responses

Sono AWS disponibili due strumenti 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 in 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 cosa ho detto sulle preferenze relative alle riunioni») oppure puoi utilizzare chiamate telefoniche dirette nel prompt («Usa lo strumento note per archiviare la mia email come john@example.com «, «Controlla le note per il mio indirizzo email»).

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à nella pila e farle apparire, il che lo rende 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 delle attività, 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 un 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», «Ottieni l'ultima attività dal mio stack») oppure puoi chiamare lo strumento direttamente nel prompt («Usa lo strumento delle attività per premere 'termina la presentazione'», «Apri un'attività dallo stack», «Aggiungi 'pianifica riunione' al mio elenco delle 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 e. 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 tipo di integrazione delle chiamate di strumenti sul lato server. Con questa funzionalità, puoi connettere i tuoi modelli direttamente agli endpoint AgentCore Gateway per un accesso senza interruzioni agli strumenti gestiti tramite l'infrastruttura del gateway.

L'integrazione del AgentCore Gateway segue lo stesso schema dell'integrazione delle funzioni Lambda, con una differenza fondamentale.

Integrazione Lambda:

AgentCore Integrazione del gateway:

Configurazione

Struttura della richiesta

Quando configuri AgentCore Gateway come sorgente 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 completa

{
  "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, assicurati di avere:

Vantaggi dell'integrazione del 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