Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilisation d’un outil pour compléter une réponse au modèle Amazon Bedrock

Vous pouvez utiliser l’API Amazon Bedrock pour permettre à un modèle d’accéder à des outils qui peuvent l’aider à générer des réponses aux messages que vous lui envoyez. Par exemple, vous pouvez avoir une application de chat qui permet aux utilisateurs de trouver la chanson la plus populaire diffusée sur une station de radio. Pour répondre à une demande concernant la chanson la plus populaire, un modèle a besoin d’un outil capable d’interroger et de renvoyer les informations relatives à la chanson.

Dans Amazon Bedrock, le modèle n’appelle pas directement l’outil. Au contraire, lorsque vous envoyez un message à un modèle, vous fournissez également une définition pour un ou plusieurs outils susceptibles d’aider le modèle à générer une réponse. Dans cet exemple, vous devez fournir la définition d’un outil qui renvoie le titre le plus populaire pour une station de radio donnée. Si le modèle détermine qu'il a besoin de l'outil pour générer une réponse au message, le modèle, en fonction de l'API utilisée pour appeler le modèle, peut effectuer un appel côté client ou demander à Bedrock d'appeler l'outil en utilisant un appel d'outil côté serveur. Discutons de ces deux options plus en détail.

Appel d'outils côté client

Si vous utilisez l'API Responses, l'API Chat Completions, l'API Converse ou l' InvokeModel API pour envoyer la demande, le modèle utilise un appel d'outil côté client. Cela signifie que dans votre code, vous appelez l'outil au nom du modèle. Dans ce scénario, supposons que la mise en œuvre de l’outil soit une API. L’outil pourrait tout aussi bien être une base de données, une fonction Lambda ou un autre logiciel. Vous décidez de la manière dont vous souhaitez mettre en œuvre l’outil. Vous poursuivez ensuite la conversation avec le modèle en fournissant un message contenant le résultat de l’outil. Enfin, le modèle génère une réponse au message d'origine qui inclut les résultats de l'outil que vous avez envoyés au modèle.

Laissez-nous définir l'outil que nous utiliserons pour utiliser l'outil. Les exemples Python suivants montrent comment utiliser un outil qui renvoie la chanson la plus populaire sur une station de radio fictive.

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")

Utilisation de l'API Responses pour l'outillage côté client

Vous pouvez utiliser la fonction d'appel de fonctions fournie par OpenAI pour appeler cet outil. L'API Responses est l'API préférée d'OpenAI. Voici le code Python de l'API Responses pour l'outillage côté 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)

Utilisation de l'API Chat Completions pour l'outillage côté client

Vous pouvez également utiliser l'API Chat Completions. Voici le code Python pour utiliser 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)
    

Pour plus de détails sur l'utilisation de l'API Function Calling on Responses et de l'API Chat Completions, voir Function Calling in OpenAI.

Utilisation de l'API Converse pour l'outillage côté client

Vous pouvez utiliser l'API Converse pour permettre à un modèle d'utiliser un outil dans une conversation. Les exemples Python suivants montrent comment utiliser un outil qui renvoie la chanson la plus populaire sur une station de radio fictive.

# 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()

Utilisation d'Invoke APIs pour l'utilisation d'outils côté client

Il est possible d'utiliser des outils avec les opérations d'inférence de base (InvokeModelou InvokeModelWithResponseStream). Pour trouver les paramètres d’inférence que vous transmettez dans le corps de la demande, consultez les paramètres d’inférence du modèle que vous souhaitez utiliser.

Appel d'outils côté serveur

Si vous utilisez l'API Responses pour appeler le modèle, celui-ci peut utiliser l'appel d'outil côté serveur, en plus de l'appel d'outil côté client dont nous avons parlé précédemment. L'appel d'outils côté serveur est un mécanisme par lequel les outils (fonctionsAPIs, flux de travail) sont exécutés dans un environnement principal fiable, et non sur le client. Cela améliore la sécurité, la fiabilité et la posture de gouvernance de l'application. Avant qu'Amazon Bedrock n'exécute la fonction Lambda qui implémente l'utilisation de l'outil, il s'assure que la fonction Lambda possède la même politique IAM que celle de l'application qui l'appelle. Dans la mesure où Amazon Bedrock pilote l'exécution des outils, les clients peuvent se concentrer sur la mise en œuvre de leur logique métier, plutôt que sur l'ajout de fonctionnalités aux outils. Amazon Bedrock prend également en charge les normes de gouvernance les plus strictes, telles que les normes ISO, SOC et HIPAA éligibles. Les clients peuvent soit soumettre leur propre fonction Lambda personnalisée pour exécuter l'outil, soit utiliser des outils prédéfinis existants, tels que des notes et des tâches. Les outils côté serveur utilisant l'API Responses sont disponibles à partir des modèles GPT OSS 20B/120B d'OpenAI, et d'autres modèles seront bientôt pris en charge. Vous pouvez utiliser l'API Models pour découvrir les modèles disponibles que vous pouvez utiliser avec l'API Responses. Pour plus de détails sur l'API Responses, voir Générer des réponses à l'aide d'OpenAI APIs.

Il existe deux types d'outils que vous pouvez utiliser avec Amazon Bedrock : des outils personnalisés utilisant Lambda ou des outils prédéfinis pris en charge par Bedrock. Dans cette section, nous verrons comment créer un outil Lambda personnalisé avec l'API Responses. Discutons des deux en détail.

Outils personnalisés utilisant Lambda dans l'API Responses

En utilisant une fonction Lambda comme outil personnalisé dans Bedrock, vous pouvez étendre les capacités de l'agent en intégrant des fonctions AWS Lambda personnalisées en tant qu'outils. Cela vous permet de créer des outils évolutifs sans serveur qui peuvent être appelés par des assistants d'intelligence artificielle et d'autres applications via le protocole MCP (Model Context Protocol). Voici les avantages de cette fonctionnalité :

Pour autoriser un modèle dans Amazon Bedrock à utiliser un outil pour répondre à un message, vous devez envoyer le message et les définitions d'un ou de plusieurs outils au modèle. En fonction de l'invite de votre application, si le modèle détermine que l'un des outils peut aider à générer une réponse, il renvoie une demande pour que Bedrock utilise l'outil et renvoie les résultats de l'outil au modèle. Le modèle utilise ensuite le résultat de l’outil pour générer une réponse pour le message d’origine.

Les étapes suivantes montrent comment utiliser un outil avec l'API Responses.

Fonctionnement

Étape 1 : Définissez la fonction Lambda pour obtenir la chanson la plus populaire

Créez une fonction Lambda qui implémente le protocole MCP. Voici un exemple simple en 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"
        }
    }

Étape 2 : Déploiement de la fonction Lambda

Utilisez ensuite votre rôle IAM pour déployer cette fonction Lambda afin d'obtenir un ARN. Pour en savoir plus sur le déploiement d'une fonction Lambda, cliquez ici.

# 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

Supposons que votre ARN soit : arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool

Étape 3 : Définissez le message et la définition de l'outil dans votre demande d'inférence

Pour envoyer le message et la définition de l'outil, vous utilisez les opérations de l'API Responses. Amazon Bedrock utilise les connecteurs et les fonctionnalités des serveurs MCP distants de l'API Responses pour fournir des fonctionnalités d'utilisation d'outils. La définition de l'outil est un schéma JSON que vous transmettez le paramètre de requête mcp à l'opération Create. Dans le connector_id champ de l'API des connecteurs Responses, vous pouvez transmettre l'ARN Lambda que vous avez créé à l'étape précédente. Vous n'avez pas besoin de fournir d'informations d'identification d'autorisation puisque Bedrock utilise les mêmes rôles et politiques IAM que ceux utilisés pour votre application qui invoque le modèle. L’exemple de schéma suivant concerne un outil qui permet d’obtenir les chansons les plus populaires d’une station de 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)

Étape 4 : Bedrock appelle l'outil et renvoie la réponse au modèle

La possibilité d'utiliser l'outil de connecteur est disponible dans les modèles qui prennent en charge l'API Responses. Vérifiez ici quels outils sont compatibles avec votre modèle. Lorsque vous utilisez des outils utilisant l'API Responses, vous ne payez que pour les jetons utilisés lors de l'importation de définitions d'outils ou lors des appels d'outils. Il n'y a pas de frais supplémentaires par appel d'outil.

Lorsque vous spécifiez une fonction Lambda dans le tools paramètre, l'API tente d'obtenir une liste d'outils auprès du serveur. Si vous parvenez à récupérer la liste des outils, un nouvel élément mcp_list_tools de sortie apparaîtra dans la sortie de réponse du modèle. La tools propriété de cet objet affichera les outils qui ont été importés avec succès. Une fois que le modèle a accès à ces définitions d'outils, il peut choisir de les appeler en fonction du contexte du modèle. Lorsque le modèle décide d'appeler un outil Lambda, l'API demande à la fonction Lambda d'appeler l'outil et de placer sa sortie dans le contexte du modèle. Vous pouvez en savoir plus sur les outils de liste et les outils d'appel dans la documentation OpenAI. Notez que votre fonction Lambda doit être associée aux mêmes rôles et politiques IAM que ceux de l'application qui appelle le modèle dans Bedrock, sinon la fonction Lambda échouera. Voici la définition de l'erreur.

{
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
        "code": -32000,
        "message": "Tool execution failed",
        "data": "Additional error details"
    }
}

Utilisation des outils fournis par AWS dans l'API Responses

Deux outils fournis par AWS sont disponibles dans Bedrock : la fonctionnalité de prise de notes (outil de notes) et la gestion des tâches (outil de tâches). Passons en revue les deux en détail.

Présentation de l'outil Notes

L'notesoutil vous permet de stocker et de récupérer des paires clé-valeur au cours d'une même session de conversation. Cela fournit un mécanisme de mémoire simple pour maintenir le contexte lors de multiples interactions. Les clés sont des chaînes qui distinguent les majuscules des minuscules et il n'y a aucune limite quant à la longueur des clés ou aux conventions de dénomination. Le système remplace les valeurs précédentes pour la même clé. Les valeurs sont stockées sous forme de chaînes (JSON, URLs etc.) et aucune limite de taille n'est imposée au niveau de l'outil. Les valeurs sont conservées tout au long de la session de conversation. La mémoire est limitée à la conversation en cours uniquement.

Paramètres

Opérations valides

Vous pouvez utiliser l'un ou l'autre langage naturel (par exemple « Souviens-toi que ma couleur préférée est le bleu », « Que t'ai-je dit à propos de ma couleur préférée ? » , « Mémorisez le fait que je préfère les réunions matinales », « Souvenez-vous de ce que j'ai dit à propos des préférences en matière de réunions ») ou vous pouvez utiliser les outils directs (« Utilisez l'outil de notes pour enregistrer mon e-mail sous le nom john@example.com », « Vérifiez les notes relatives à mon adresse e-mail »).

Présentation de l'outil Tâches

L'tasksoutil fournit une pile Last-In-First-Out (LIFO) pour gérer les tâches au cours d'une session de conversation. Cela vous permet de placer des tâches sur une pile et de les afficher dans l'ordre inverse, ce qui le rend parfait pour gérer des flux de travail imbriqués, des rappels temporaires ou la gestion hiérarchique des tâches. Les tâches persistent tout au long de la session de conversation. L'état de la pile est maintenu lors de multiples interactions. La mémoire est limitée à la conversation en cours uniquement.

Vous pouvez appeler l'outil Tâches en utilisant un langage naturel (par exemple, « Ajouter une tâche pour revoir le budget », « Envoyer un rappel pour appeler le client », « Quelle est la prochaine tâche que je dois effectuer ? » , « Afficher la tâche la plus récente », « Obtenir la dernière tâche de ma pile ») ou vous pouvez appeler l'outil directement lorsque vous le souhaitez (« Utiliser l'outil des tâches pour appuyer sur « Terminer la présentation » », « Extraire une tâche de la pile », « Ajouter « planifier une réunion » à ma liste de tâches »).

Intégration de l'utilisation des outils côté serveur avec Gateway AgentCore

Amazon Bedrock prend désormais en charge AgentCore Gateway en tant qu'outil côté serveur appelant un type d'intégration. Cette fonctionnalité vous permet de connecter vos modèles directement aux points de terminaison de AgentCore Gateway, permettant ainsi un accès fluide aux outils gérés via l'infrastructure de passerelle.

L'intégration de AgentCore Gateway suit le même schéma que l'intégration de la fonction Lambda, avec une différence essentielle.

Intégration Lambda :

AgentCore Intégration de la passerelle :

Configuration

Structure de la demande

Lorsque vous configurez AgentCore Gateway en tant que source d'outil, utilisez la structure suivante dans votre tools tableau dans votre demande d'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"
}

Paramètres

Exemple de demande complète

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

Conditions préalables

Avant d'utiliser l'intégration de AgentCore Gateway, assurez-vous de disposer des éléments suivants :

Avantages de l'intégration de AgentCore la passerelle

Autorisations IAM

Votre rôle d'exécution de Bedrock a besoin d'une autorisation pour invoquer la AgentCore passerelle :

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

Étapes suivantes