As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Use uma ferramenta para concluir uma resposta do modelo do Amazon Bedrock

Você pode usar a API do Amazon Bedrock para fornecer acesso a um modelo a ferramentas que podem ajudar você a gerar respostas a mensagens que você envia ao modelo. Por exemplo, você pode ter uma aplicação de chat que permita que os usuários descubram a música mais tocada em uma estação de rádio. Para responder a uma solicitação da música mais tocada, um modelo precisa de uma ferramenta que possa consultar e retornar as informações da música.

No Amazon Bedrock, o modelo não chama a ferramenta diretamente. Em vez disso, ao enviar uma mensagem a um modelo, você também fornece uma definição para uma ou mais ferramentas que podem ajudar o modelo a gerar uma resposta. Neste exemplo, você forneceria uma definição para uma ferramenta que retorna a música mais tocada de uma estação de rádio específica. Se o modelo determinar que precisa da ferramenta para gerar uma resposta para a mensagem, o modelo, dependendo da API usada para invocar o modelo, pode realizar chamadas do lado do cliente ou pedir à Bedrock que chame a ferramenta usando a chamada de ferramenta do lado do servidor. Vamos discutir essas duas opções com mais detalhes.

Chamada de ferramentas do lado do cliente

Se você usar a API de respostas, a API de conclusão de bate-papo, a API Converse ou a InvokeModel API para enviar a solicitação, o modelo usará a chamada de ferramentas do lado do cliente. Isso significa que, em seu código, você chama a ferramenta em nome do modelo. Nesse cenário, suponha que a implementação da ferramenta seja uma API. A ferramenta poderia facilmente ser um banco de dados, uma função do Lambda ou algum outro software. Você decide como deseja implementar a ferramenta. Você continua a conversa com o modelo fornecendo uma mensagem com o resultado da ferramenta. Por fim, o modelo gera uma resposta para a mensagem original que inclui os resultados da ferramenta que você enviou ao modelo.

Vamos definir a ferramenta que usaremos para uso da ferramenta. Os exemplos de Python a seguir mostram como usar uma ferramenta que retorna a música mais popular em uma estação de rádio fictícia.

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

Usando a API de respostas para ferramentas do lado do cliente

Você pode usar o recurso de chamada de função fornecido pela OpenAI para chamar essa ferramenta. A API de respostas é a API preferida da OpenAI. Aqui está o código Python para a API de respostas para ferramentas do lado do 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)

Usando a API Chat Completions para ferramentas do lado do cliente

Você também pode usar a API Chat Completions. Aqui está o código Python para usar o 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 obter mais detalhes sobre o uso da Function Calling na API Responses e da API Chat Completions, consulte Function Calling na OpenAI.

Usando a API Converse para ferramentas do lado do cliente

É possível usar a API Converse para permitir que um modelo use uma ferramenta em uma conversa. Os exemplos de Python a seguir mostram como usar uma ferramenta que retorna a música mais popular em uma estação de rádio fictícia.

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

Usando o Invoke APIs para uso de ferramentas do lado do cliente

É possível usar ferramentas com as operações de inferência de base (InvokeModelou InvokeModelWithResponseStream). Para encontrar os parâmetros de inferência que você passa no corpo da solicitação, consulte os parâmetros de inferência do modelo que deseja usar.

Chamada de ferramentas do lado do servidor

Se você usar a API de respostas para invocar o modelo, ela poderá usar a chamada de ferramenta do lado do servidor, além da chamada de ferramenta do lado do cliente que discutimos anteriormente. A chamada de ferramentas do lado do servidor é um mecanismo em que as ferramentas (APIs, funções, fluxos de trabalho) são executadas em um ambiente de back-end confiável, não no cliente. Isso melhora a postura de segurança, confiabilidade e governança do aplicativo. Antes de o Amazon Bedrock executar a função Lambda que implementa o uso da ferramenta, ele garante que a função Lambda tenha a mesma política de IAM do aplicativo que a chama. Como o Amazon Bedrock está impulsionando a execução das ferramentas, os clientes podem se concentrar na implementação de sua lógica de negócios, em vez de adicionar a funcionalidade da ferramenta. O Amazon Bedrock também suporta os mais altos padrões de governança, como ISO, SOC e HIPAA qualificados. Os clientes podem enviar sua própria função personalizada do Lambda para executar a ferramenta ou usar ferramentas predefinidas existentes, como notas e tarefas. As ferramentas do lado do servidor que usam a API de respostas estão disponíveis a partir dos modelos GPT OSS 20B/120B da OpenAI, com suporte para outros modelos em breve. Você pode usar a API de modelos para descobrir os modelos disponíveis que podem ser usados com a API de respostas. Para obter mais detalhes sobre a API de respostas, consulte Gerar respostas usando o OpenAI APIs.

Há dois tipos de ferramentas que você pode usar com o Amazon Bedrock: ferramentas personalizadas usando Lambda ou ferramentas predefinidas suportadas pelo Bedrock. Nesta seção, analisaremos como criar uma ferramenta Lambda personalizada com a API de respostas. Vamos discutir os dois em detalhes.

Ferramentas personalizadas usando o Lambda na API de respostas

Ao usar uma função Lambda como ferramenta personalizada no Bedrock, você pode ampliar os recursos do agente integrando funções personalizadas do AWS Lambda como ferramentas. Isso permite criar ferramentas escaláveis e sem servidor que podem ser chamadas por assistentes de IA e outros aplicativos por meio do Model Context Protocol (MCP). Aqui estão as vantagens desse recurso:

Para permitir que um modelo no Amazon Bedrock use uma ferramenta para completar uma resposta para uma mensagem, você envia a mensagem e as definições de uma ou mais ferramentas para o modelo. Com base na solicitação do seu aplicativo, se o modelo determinar que uma das ferramentas pode ajudar a gerar uma resposta, ele retornará uma solicitação para que a Bedrock use a ferramenta e envie os resultados da ferramenta de volta ao modelo. O modelo usa os resultados para gerar uma resposta para a mensagem original.

As etapas a seguir mostram como usar uma ferramenta com a API de respostas.

Como funciona

Etapa 1: Defina a função Lambda para obter a música mais popular

Crie uma função Lambda que implemente o protocolo MCP. Aqui está um exemplo simples 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"
        }
    }

Etapa 2: implantar a função Lambda

Em seguida, use sua função do IAM para implantar essa função Lambda para obter um ARN. Você pode ler mais sobre a implantação de uma função Lambda aqui.

# 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

Digamos que seu ARN seja: arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool

Etapa 3: definir a mensagem e a definição da ferramenta em sua solicitação de inferência

Para enviar a mensagem e a definição da ferramenta, você usa as operações da API de respostas. O Amazon Bedrock usa a funcionalidade de conectores e servidores MCP remotos da API de respostas para fornecer a capacidade de uso de ferramentas. A definição da ferramenta é um esquema JSON que você passa no parâmetro de solicitação mcp para a operação Create. No connector_id campo da API de conectores de respostas, você pode passar o ARN do Lambda que você criou na etapa anterior. Você não precisa fornecer credenciais de autorização, pois o Bedrock usa as mesmas funções e políticas do IAM usadas para seu aplicativo que invoca o modelo. O exemplo a seguir é de uma ferramenta que obtém as músicas mais tocadas em uma estação de rádio.

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)

Etapa 4: Bedrock chama a ferramenta e passa a resposta de volta para o modelo

A capacidade de usar a ferramenta de conexão está disponível nos modelos compatíveis com a API de respostas. Confira quais ferramentas são compatíveis com seu modelo aqui. Ao usar ferramentas usando a API de respostas, você paga apenas pelos tokens usados ao importar definições de ferramentas ou fazer chamadas de ferramentas. Não há taxas adicionais envolvidas por chamada de ferramenta.

Quando você especifica uma função Lambda no tools parâmetro, a API tenta obter uma lista de ferramentas do servidor. Se conseguir recuperar a lista de ferramentas, um novo item mcp_list_tools de saída aparecerá na saída de resposta do modelo. A tools propriedade desse objeto mostrará as ferramentas que foram importadas com sucesso. Depois que o modelo tiver acesso a essas definições de ferramentas, ele poderá optar por chamá-las, dependendo do contexto do modelo. Quando o modelo decide chamar uma ferramenta Lambda, a API faz uma solicitação à função Lambda para chamar a ferramenta e colocar sua saída no contexto do modelo. Você pode ler mais sobre as ferramentas de lista e as ferramentas de chamada na documentação do OpenAI. Observe que sua função Lambda deve ter as mesmas funções e políticas do IAM associadas ao aplicativo que está chamando o modelo no Bedrock, caso contrário, a função Lambda falhará. A seguir está a definição do erro.

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

Usando as ferramentas fornecidas pela AWS na API de respostas

Há duas ferramentas fornecidas pela AWS que estão disponíveis no Bedrock: funcionalidade de anotações (ferramenta de anotações) e gerenciamento de tarefas (ferramenta de tarefas). Vamos examinar os dois em detalhes.

Visão geral da ferramenta Notes

A notes ferramenta permite que você armazene e recupere pares de valores-chave na mesma sessão de conversação. Isso fornece um mecanismo de memória simples para manter o contexto em várias interações. As chaves diferenciam maiúsculas de minúsculas e não há limite no comprimento da chave ou nas convenções de nomenclatura. O sistema sobrescreve os valores anteriores para a mesma chave. Os valores são armazenados como cadeias de caracteres (JSON, URLs etc.) e nenhum limite de tamanho é imposto no nível da ferramenta. Os valores são mantidos durante toda a sessão de conversação. A memória tem como escopo somente a conversa atual.

Parâmetros

Operações válidas

Você pode usar qualquer linguagem natural (por exemplo, “Lembre-se de que minha cor favorita é azul”, “O que eu disse sobre minha cor favorita?” , “Guarde o fato de que eu prefiro reuniões matinais”, “Lembre-se do que eu disse sobre as preferências de reunião”) ou você pode usar ferramentas diretas de chamadas em seu prompt (“Use a ferramenta de notas para armazenar meu e-mail como john@example.com “, “Verifique as notas do meu endereço de e-mail”).

Visão geral da ferramenta de tarefas

A tasks ferramenta fornece uma pilha Last-In-First-Out (LIFO) para gerenciar tarefas em uma sessão de conversação. Isso permite que você coloque tarefas em uma pilha e as coloque na ordem inversa, tornando-a perfeita para gerenciar fluxos de trabalho aninhados, lembretes temporários ou gerenciamento hierárquico de tarefas. As tarefas persistem durante toda a sessão de conversação. O estado da pilha é mantido em várias interações. A memória tem como escopo somente a conversa atual.

Você pode chamar a ferramenta Tarefas usando linguagens naturais (por exemplo, “Adicionar uma tarefa para revisar o orçamento”, “Enviar um lembrete para ligar para o cliente”, “Qual é a próxima tarefa que preciso fazer?” , “Retirar a tarefa mais recente”, “Obter a tarefa mais recente da minha pilha”) ou você pode chamar a ferramenta diretamente em seu prompt (“Use a ferramenta de tarefas para finalizar apresentação”, “Retirar uma tarefa da pilha”, “Adicionar 'agendar reunião' à minha lista de tarefas”).

Integração do uso de ferramentas do lado do servidor com o Gateway AgentCore

O Amazon Bedrock agora oferece suporte ao AgentCore Gateway como uma ferramenta do lado do servidor que chama o tipo de integração. Esse recurso permite que você conecte seus modelos diretamente aos endpoints do AgentCore Gateway, permitindo acesso contínuo às ferramentas gerenciadas por meio da infraestrutura do gateway.

A integração do AgentCore Gateway segue o mesmo padrão da integração da função Lambda, com uma diferença fundamental.

Integração com o Lambda:

AgentCore Integração de gateway:

Configuração

Estrutura da solicitação

Ao configurar o AgentCore Gateway como fonte de ferramentas, use a estrutura a seguir em sua tools matriz na solicitação da API de respostas.

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

Exemplo completo de solicitação

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

Pré-requisitos

Antes de usar a integração com o AgentCore Gateway, verifique se você tem:

Benefícios da integração de AgentCore gateway

Permissões do IAM

Sua função de execução no Bedrock precisa de permissão para invocar o AgentCore Gateway:

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

Próximas etapas