Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Uso de una herramienta para completar una respuesta modelo de Amazon Bedrock

Puede usar la API de Amazon Bedrock para dar a un modelo acceso a herramientas que pueden ayudarlo a generar respuestas para los mensajes que envíe al modelo. Por ejemplo, puede tener una aplicación de chat que permita a los usuarios encontrar la canción más popular que se reproduce en una emisora de radio. Para responder a una solicitud de la canción más popular, un modelo necesita una herramienta que pueda consultar y devolver la información de la canción.

En Amazon Bedrock, el modelo no llama directamente a la herramienta. Por el contrario, cuando envía un mensaje a un modelo, también proporciona una definición de una o más herramientas que podrían ayudar al modelo a generar una respuesta. En este ejemplo, usted proporcionaría una definición para una herramienta que devuelva la canción más popular de una emisora de radio específica. Si el modelo determina que necesita la herramienta para generar una respuesta para el mensaje, el modelo, según la API utilizada para invocar el modelo, puede realizar llamadas desde el lado del cliente o pedirle a Bedrock que llame a la herramienta mediante llamadas desde el lado del servidor. Analicemos estas dos opciones con más detalle.

Llamadas con herramientas del lado del cliente

Si utilizas la API de respuestas, la API de finalización de chat, la API de Converse o la InvokeModel API para enviar la solicitud, el modelo utiliza las llamadas a las herramientas del lado del cliente. Esto significa que en tu código, llamas a la herramienta en nombre del modelo. En este escenario, suponemos que la implementación de la herramienta es una API. La herramienta podría ser una base de datos, una función de Lambda o algún otro software. Usted decide cómo quiere implementar la herramienta. A continuación, continúa la conversación con el modelo proporcionando un mensaje con el resultado de la herramienta. Por último, el modelo genera una respuesta para el mensaje original que incluye los resultados de la herramienta que usted envió al modelo.

Vamos a definir la herramienta que utilizaremos para utilizarla. Los siguientes ejemplos de Python muestran cómo utilizar una herramienta que devuelve la canción más popular en una emisora de radio ficticia.

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

Uso de la API de respuestas para la creación de herramientas del lado del cliente

Puede utilizar la función de llamada a funciones proporcionada por OpenAI para llamar a esta herramienta. La API de respuestas es la API preferida de OpenAI. Este es el código de Python para la API de respuestas para las herramientas del lado del cliente:

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)

Uso de la API Chat Completions para la creación de herramientas del lado del cliente

También puedes usar la API Chat Completions. Este es el código de Python para usar 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)
    

Para obtener más información sobre el uso de la API Function Calling on Responses y la API Chat Completions, consulte Function Calling en OpenAI.

Uso de la API de Converse para la creación de herramientas del lado del cliente

Puede usar la API de Converse para permitir que un modelo use una herramienta en una conversación. Los siguientes ejemplos de Python muestran cómo utilizar una herramienta que devuelve la canción más popular en una emisora de radio ficticia.

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

Uso de Invoke APIs para el uso de herramientas del lado del cliente

Es posible utilizar herramientas con las operaciones de inferencia básicas (o). InvokeModelInvokeModelWithResponseStream Para encontrar los parámetros de inferencia que pasa en el cuerpo de la solicitud, consulte los parámetros de inferencia del modelo que desee usar.

Llamada a herramientas del lado del servidor

Si utilizas la API de respuestas para invocar el modelo, puedes utilizar las llamadas a las herramientas del lado del servidor, además de las llamadas a las herramientas del lado del cliente que mencionamos anteriormente. La llamada a herramientas desde el servidor es un mecanismo mediante el cual las herramientas (APIs, funciones y flujos de trabajo) se ejecutan en un entorno de back-end confiable, no en el cliente. Esto mejora la seguridad, la confiabilidad y la postura de gobierno de la aplicación. Antes de ejecutar la función Lambda que implementa el uso de la herramienta, Amazon Bedrock se asegura de que la función Lambda tenga la misma política de IAM que la aplicación que la llama. A medida que Amazon Bedrock impulsa la ejecución de las herramientas, los clientes pueden centrarse en implementar su lógica empresarial, en lugar de añadir la funcionalidad de las herramientas. Amazon Bedrock también cumple con los más altos estándares de gobierno, como los requisitos de ISO, SOC e HIPAA. Los clientes pueden enviar su propia función Lambda personalizada para ejecutar la herramienta o utilizar las herramientas predefinidas existentes, como notas y tareas. Las herramientas del lado del servidor que utilizan la API de respuestas están disponibles a partir de los modelos GPT OSS 20B/120B de OpenAI, y pronto serán compatibles con otros modelos. Puedes usar la API de modelos para descubrir los modelos disponibles que puedes usar con la API de Respuestas. Para obtener más información sobre la API de respuestas, consulta Generar respuestas con OpenAI APIs.

Hay dos tipos de herramientas que puede utilizar con Amazon Bedrock: herramientas personalizadas que utilizan Lambda o herramientas predefinidas compatibles con Bedrock. En esta sección, analizaremos cómo crear una herramienta Lambda personalizada con la API de respuestas. Analicemos ambas en detalle.

Herramientas personalizadas que utilizan Lambda en la API de respuestas

Al utilizar una función de Lambda como herramienta personalizada en Bedrock, puede ampliar las capacidades del agente mediante la integración de funciones de AWS Lambda personalizadas como herramientas. Esto le permite crear herramientas escalables y sin servidor a las que puedan acceder los asistentes de IA y otras aplicaciones mediante el Protocolo de contexto de modelos (MCP). Estas son las ventajas de esta función:

Para permitir que un modelo de Amazon Bedrock utilice una herramienta para completar la respuesta a un mensaje, debe enviar el mensaje y las definiciones de una o más herramientas al modelo. Según la solicitud de la aplicación, si el modelo determina que una de las herramientas puede ayudar a generar una respuesta, devuelve una solicitud para que Bedrock utilice la herramienta y envía los resultados de la herramienta al modelo. En su respuesta, el modelo utiliza los resultados para generar una respuesta para el mensaje original.

Los siguientes pasos muestran cómo usar una herramienta con la API de respuestas.

Cómo funciona

Paso 1: Defina la función Lambda para obtener la canción más popular

Cree una función Lambda que implemente el protocolo MCP. He aquí un ejemplo sencillo de 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"
        }
    }

Paso 2: Implementar la función Lambda

A continuación, utilice su función de IAM para implementar esta función de Lambda y obtener un ARN. Puede obtener más información sobre la implementación de una función Lambda aquí.

# 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

Supongamos que su ARN es: arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool

Paso 3: Defina el mensaje y la definición de la herramienta en su solicitud de inferencia

Para enviar el mensaje y la definición de la herramienta, utiliza las operaciones de la API de respuestas. Amazon Bedrock utiliza los conectores y la funcionalidad de los servidores MCP remotos de la API de respuestas para proporcionar la capacidad de uso de herramientas. La definición de la herramienta es un esquema JSON en el que se pasa el parámetro de solicitud mcp a la operación Create. En el connector_id campo de la API de conectores de respuestas, puede pasar el ARN de Lambda que creó en el paso anterior. No necesita proporcionar credenciales de autorización, ya que Bedrock utiliza las mismas funciones y políticas de IAM que se utilizan para la aplicación que invoca el modelo. El siguiente es un esquema de ejemplo para una herramienta que obtiene la canción más popular de una emisora 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)

Paso 4: Bedrock llama a la herramienta y devuelve la respuesta al modelo

La posibilidad de utilizar la herramienta de conexión está disponible en los modelos que admiten la API de respuestas. Comprueba qué herramientas son compatibles con tu modelo aquí. Cuando utilizas herramientas que utilizan la API de respuestas, solo pagas por los tokens que se utilizan al importar definiciones de herramientas o realizar llamadas a herramientas. No se cobran cargos adicionales por cada uso de herramienta.

Al especificar una función Lambda en el tools parámetro, la API intentará obtener una lista de herramientas del servidor. Si se recupera correctamente la lista de herramientas, aparecerá un nuevo elemento de mcp_list_tools salida en el resultado de la respuesta del modelo. La tools propiedad de este objeto mostrará las herramientas que se importaron correctamente. Una vez que el modelo tiene acceso a estas definiciones de herramientas, puede optar por llamarlas en función del contexto del modelo. Cuando el modelo decide llamar a una herramienta de Lambda, la API realizará una solicitud a la función de Lambda para que llame a la herramienta y coloque su resultado en el contexto del modelo. Puede obtener más información sobre la lista de herramientas y herramientas de llamada en la documentación de OpenAI. Tenga en cuenta que la función Lambda debe tener asociadas las mismas funciones y políticas de IAM que las de la aplicación que llama al modelo en Bedrock; de lo contrario, la función Lambda fallará. La siguiente es la definición de error.

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

Uso de las herramientas proporcionadas por AWS en la API de respuestas

Hay dos herramientas proporcionadas por AWS que están disponibles en Bedrock: la funcionalidad de toma de notas (herramienta de notas) y la administración de tareas (herramienta de tareas). Repasemos ambas en detalle.

Descripción general de la herramienta de notas

La notes herramienta le permite almacenar y recuperar pares clave-valor en la misma sesión de conversación. Esto proporciona un mecanismo de memoria simple para mantener el contexto en múltiples interacciones. Las claves son cadenas que distinguen mayúsculas de minúsculas y no hay límite en cuanto a la longitud de las claves ni a las convenciones de nomenclatura. El sistema sobrescribe los valores anteriores de la misma clave. Los valores se almacenan como cadenas (JSON, URLs etc.) y no se imponen límites de tamaño a nivel de herramienta. Los valores se conservan durante toda la sesión de conversación. La memoria se limita únicamente a la conversación actual.

Parámetros

Operaciones válidas

Puedes usar cualquier lenguaje natural (por ejemplo, «Recuerda que mi color favorito es el azul», «¿Qué te dije sobre mi color favorito?» , «Guarde el hecho de que prefiero las reuniones matutinas», «Recuerde lo que dije sobre las preferencias de reunión») o puede utilizar las herramientas directas de llamadas en su mensaje («Utilice la herramienta de notas para guardar mi correo electrónico como john@example.com «, «Compruebe las notas para ver mi dirección de correo electrónico»).

Descripción general de la herramienta de tareas

La tasks herramienta proporciona una pila Last-In-First-Out (LIFO) para gestionar las tareas dentro de una sesión de conversación. Esto te permite agrupar las tareas en una pila y separarlas en orden inverso, lo que la hace perfecta para gestionar flujos de trabajo anidados, recordatorios temporales o gestionar tareas jerárquicas. Las tareas persisten durante toda la sesión de conversación. El estado de la pila se mantiene en varias interacciones. La memoria se limita únicamente a la conversación actual.

Puedes utilizar lenguajes naturales para utilizar la herramienta Tareas (por ejemplo, «Añade una tarea para revisar el presupuesto», «Envía un recordatorio para llamar al cliente» o «¿Cuál es la siguiente tarea que debo hacer?» , «Selecciona la tarea más reciente», «Obtén la última tarea de mi lista») o puedes llamar a la herramienta directamente en el mensaje («Usa la herramienta de tareas para presionar «finalizar la presentación», «Saca una tarea de la pila», «Agrega 'programar reunión' a mi lista de tareas»).

Integración del uso de herramientas del lado del servidor con Gateway AgentCore

Amazon Bedrock ahora admite AgentCore Gateway como un tipo de integración de llamadas con herramientas del lado del servidor. Esta función le permite conectar sus modelos directamente a los puntos finales de AgentCore Gateway, lo que permite un acceso sin problemas a las herramientas administradas a través de la infraestructura de la puerta de enlace.

La integración de AgentCore Gateway sigue el mismo patrón que la integración de funciones de Lambda, con una diferencia clave.

Integración Lambda:

AgentCore Integración de pasarelas:

Configuración

Estructura de solicitudes

Al configurar AgentCore Gateway como fuente de herramientas, usa la siguiente estructura en tu tools matriz en tu solicitud de API de respuestas.

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

Parámetros

Ejemplo de solicitud 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?"
        }
      ]
    }
  ]
}

Requisitos previos

Antes de usar la integración con AgentCore Gateway, asegúrese de tener:

Ventajas de la integración de la AgentCore puerta de enlace

Permisos de IAM

Su función de ejecución en Bedrock necesita permiso para invocar el 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"
    }
  ]
}

Siguientes pasos