Utilizzo di uno strumento per completare una risposta al modello Amazon Bedrock

È possibile utilizzare l’API Amazon Bedrock per consentire a un modello di accedere a strumenti che possono aiutarlo a generare risposte ai messaggi inviati al modello. Ad esempio, un’applicazione di chat potrebbe consentire agli utenti di scoprire la canzone più popolare trasmessa da una stazione radio. Per rispondere a una richiesta per la canzone più popolare, un modello ha bisogno di uno strumento in grado di fare query e restituire le informazioni sul brano.

In Amazon Bedrock, il modello non chiama direttamente lo strumento. Piuttosto, quando si invia un messaggio a un modello, viene fornita anche una definizione per uno o più strumenti che potrebbero aiutare il modello a generare una risposta. In questo esempio, occorre fornire una definizione per uno strumento che restituisce la canzone più popolare per una stazione radio specificata. Se il modello determina che è necessario lo strumento per generare una risposta al messaggio, il modello, a seconda dell'API utilizzata per richiamare il modello, può eseguire chiamate lato client o chiedere a Bedrock di chiamare lo strumento utilizzando la chiamata degli strumenti lato server. Analizziamo queste due opzioni in modo più dettagliato.

Chiamata di strumenti sul lato client

Se utilizzi l'API Responses, l'API Chat Completions, l'API Converse o l' InvokeModel API per inviare la richiesta, il modello utilizza la chiamata allo strumento lato client. Ciò significa che nel tuo codice, chiami lo strumento per conto del modello. In questo scenario, supponiamo che l’implementazione dello strumento sia un’API. Lo strumento potrebbe essere facilmente un database, una funzione Lambda o un altro tipo di software. È l’utente che decide come implementare lo strumento. Quindi si continua la conversazione con il modello fornendo un messaggio con il risultato ottenuto dallo strumento. Infine, il modello genera una risposta per il messaggio originale che include i risultati dell'utensile che avete inviato al modello.

Definiamo lo strumento che useremo per l'uso dello strumento. I seguenti esempi in Python mostrano come usare uno strumento che restituisce la canzone più popolare su una stazione radio immaginaria.

def get_most_popular_song(station_name: str) -> str:
    stations = {
        "Radio Free Mars": "Starman – David Bowie",
        "Neo Tokyo FM": "Plastic Love – Mariya Takeuchi",
        "Cloud Nine Radio": "Blinding Lights – The Weeknd",
    }
    return stations.get(station_name, "Unknown Station – No chart data available")

Utilizzo dell'API Responses per gli strumenti lato client

È possibile utilizzare la funzione di chiamata delle funzioni fornita da OpenAI per chiamare questo strumento. L'API Responses è l'API preferita di OpenAI. Ecco il codice Python per l'API Responses per gli strumenti lato client:

from openai import OpenAI
import json

client = OpenAI()

response = client.responses.create(
    model="oss-gpt-120b",
    input="What is the most popular song on Radio Free Mars?",
    tools=[
        {
            "type": "function",
            "name": "get_most_popular_song",
            "description": "Returns the most popular song on a radio station",
            "parameters": {
                "type": "object",
                "properties": {
                    "station_name": {
                        "type": "string",
                        "description": "Name of the radio station"
                    }
                },
                "required": ["station_name"]
            }
        }
    ]
)

if response.output and response.output[0].content:
    tool_call = response.output[0].content[0]
    args = json.loads(tool_call["arguments"])
    result = get_most_popular_song(args["station_name"])
    
    final_response = client.responses.create(
        model="oss-gpt-120b",
        input=[
            {
                "role": "tool",
                "tool_call_id": tool_call["id"],
                "content": result
            }
        ]
    )
    
    print(final_response.output_text)

Utilizzo dell'API Chat Completions per gli strumenti lato client

Puoi utilizzare anche l'API Chat Completions. Ecco il codice Python per usare Chat Completions:

    from openai import OpenAI
import json

client = OpenAI()

completion = client.chat.completions.create(
    model="oss-gpt-120b",
    messages=[{"role": "user", "content": "What is the most popular song on Neo Tokyo FM?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_most_popular_song",
            "description": "Returns the most popular song on a radio station",
            "parameters": {
                "type": "object",
                "properties": {
                   "station_name": {"type": "string", "description": "Name of the radio station"}
                },
                "required": ["station_name"]
            }
        }
    }]
)

message = completion.choices[0].message

if message.tool_calls:
    tool_call = message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    result = get_most_popular_song(args["station_name"])

    followup = client.chat.completions.create(
        model="oss-gpt-120b",
        messages=[
            {"role": "user", "content": "What is the most popular song on Neo Tokyo FM?"},
            message,
            {"role": "tool", "tool_call_id": tool_call.id, "content": result}
        ]
    )

    print(followup.choices[0].message.content)
    

Per maggiori dettagli sull'utilizzo dell'API Function Calling on Responses e dell'API Chat Completions, consulta Function Calling in OpenAI.

Utilizzo dell'API Converse per gli strumenti lato client

Puoi utilizzare l'API Converse per consentire a un modello di utilizzare uno strumento in una conversazione. I seguenti esempi in Python mostrano come usare uno strumento che restituisce la canzone più popolare su una stazione radio immaginaria.

# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""Shows how to use tools with the Converse API and the Cohere Command R model."""

import logging
import json
import boto3
from botocore.exceptions import ClientError


class StationNotFoundError(Exception):
    """Raised when a radio station isn't found."""
    pass


logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)


def get_top_song(call_sign):
    """Returns the most popular song for the requested station.

    Args:
        call_sign (str): The call sign for the station for which you want
            the most popular song.

    Returns:
        response (json): The most popular song and artist.
    """
    song = ""
    artist = ""

    if call_sign == 'WZPZ':
        song = "Elemental Hotel"
        artist = "8 Storey Hike"
    else:
        raise StationNotFoundError(f"Station {call_sign} not found.")

    return song, artist


def generate_text(bedrock_client, model_id, tool_config, input_text):
    """Generates text using the supplied Amazon Bedrock model. If necessary,
    the function handles tool use requests and sends the result to the model.

    Args:
        bedrock_client: The Boto3 Bedrock runtime client.
        model_id (str): The Amazon Bedrock model ID.
        tool_config (dict): The tool configuration.
        input_text (str): The input text.

    Returns:
        Nothing.
    """
    logger.info("Generating text with model %s", model_id)

    # Create the initial message from the user input.
    messages = [{"role": "user",
                 "content": [{"text": input_text}]}]

    response = bedrock_client.converse(modelId=model_id,
                                       messages=messages,
                                       toolConfig=tool_config)

    output_message = response['output']['message']
    messages.append(output_message)

    stop_reason = response['stopReason']

    if stop_reason == 'tool_use':
        # Tool use requested. Call the tool and send the result to the model.
        tool_requests = response['output']['message']['content']

        for tool_request in tool_requests:
            if 'toolUse' in tool_request:
                tool = tool_request['toolUse']
                logger.info("Requesting tool %s. Request: %s",
                            tool['name'], tool['toolUseId'])

                if tool['name'] == 'top_song':
                    tool_result = {}
                    try:
                        song, artist = get_top_song(tool['input']['sign'])
                        tool_result = {"toolUseId": tool['toolUseId'],
                                       "content": [{"json": {"song": song, "artist": artist}}]}
                    except StationNotFoundError as err:
                        tool_result = {"toolUseId": tool['toolUseId'],
                                       "content": [{"text": err.args[0]}],
                                       "status": 'error'}

                    tool_result_message = {"role": "user",
                                           "content": [{"toolResult": tool_result}]}
                    messages.append(tool_result_message)

        # Send the tool result to the model.
        response = bedrock_client.converse(modelId=model_id,
                                           messages=messages,
                                           toolConfig=tool_config)

        output_message = response['output']['message']

    # print the final response from the model.
    for content in output_message['content']:
        print(json.dumps(content, indent=4))


def main():
    """Entrypoint for tool use example."""
    logging.basicConfig(level=logging.INFO,
                        format="%(levelname)s: %(message)s")

    model_id = "cohere.command-r-v1:0"
    input_text = "What is the most popular song on WZPZ?"

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

    bedrock_client = boto3.client(service_name='bedrock-runtime')

    try:
        print(f"Question: {input_text}")
        generate_text(bedrock_client, model_id, tool_config, input_text)
    except ClientError as err:
        message = err.response['Error']['Message']
        logger.error("A client error occurred: %s", message)
        print(f"A client error occured: {message}")
    else:
        print(f"Finished generating text with model {model_id}.")


if __name__ == "__main__":
    main()

Utilizzo di Invoke APIs per l'utilizzo dello strumento lato client

È possibile utilizzare strumenti con le operazioni di inferenza di base (or). InvokeModelInvokeModelWithResponseStream Per trovare i parametri di inferenza passati nel corpo della richiesta, consulta i parametri di inferenza per il modello da utilizzare.

Chiamata di strumenti lato server

Se si utilizza l'API Responses per richiamare il modello, è possibile utilizzare le chiamate agli strumenti sul lato server, oltre alla chiamata allo strumento sul lato client di cui abbiamo parlato in precedenza. La chiamata agli strumenti dal lato server è un meccanismo in cui gli strumenti (APIs, 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à. Gli strumenti lato server che utilizzano l'API Responses sono disponibili a partire dai modelli GPT OSS 20B/120B di OpenAI, mentre il supporto per altri 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 APIs 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. In caso di successo nel recupero dell'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 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

In Bedrock sono disponibili due strumenti forniti da AWS: funzionalità per prendere appunti (strumento per appunti) e gestione delle attività (strumento per le attività). Esaminiamoli entrambi in dettaglio.

Panoramica dello strumento Notes

Lo notes strumento consente di archiviare e recuperare coppie chiave-valore all'interno della stessa sessione di conversazione. Ciò fornisce un semplice meccanismo di memoria per mantenere il contesto tra più interazioni. Le chiavi fanno distinzione tra maiuscole e minuscole e non ci sono limiti alla lunghezza delle chiavi o alle convenzioni di denominazione. Il sistema sovrascrive i valori precedenti per la stessa chiave. I valori vengono memorizzati come stringhe (JSON, URLs ecc.) e non vengono applicati limiti di dimensione a livello di strumento. I valori vengono mantenuti per tutta la sessione di conversazione. La memoria è limitata solo alla conversazione corrente.

Parametri

Operazioni valide

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 gli strumenti diretti per le chiamate nel prompt («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 Last-In-First-Out (LIFO) per la gestione delle attività all'interno di una sessione di conversazione. Ciò consente di inserire le attività in una pila e disporle in ordine inverso, rendendolo perfetto per la gestione di flussi di lavoro annidati, promemoria temporanei o gestione gerarchica delle attività. Le attività persistono per tutta la sessione di conversazione. Lo stato dello stack viene mantenuto attraverso più interazioni. La memoria è limitata solo alla conversazione corrente.

Puoi richiamare lo strumento Attività 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à»).