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á.

Server-side uso de ferramentas

Se você usar a API de respostas para invocar o modelo, ele poderá usar a chamada de ferramenta do lado do servidor, além da chamada de ferramenta do lado do cliente que discutimos anteriormente. Server-side a chamada de ferramentas é 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 lida com a execução de 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 oferece suporte aos mais altos padrões de governança, como os elegíveis para ISO, SOC e HIPAA. Você pode enviar sua própria função personalizada do Lambda para executar a ferramenta ou usar ferramentas predefinidas existentes, como notas e tarefas. Server-side as ferramentas que usam a API de respostas estão disponíveis a partir dos 20B/120B modelos GPT OSS, com suporte para outros modelos em breve. Você pode usar a API de modelos para descobrir os modelos disponíveis que você pode usar com a API de respostas. Para obter mais detalhes sobre a API de respostas, consulte Gerar respostas usando APIs OpenAI.

Há dois tipos de ferramentas que você pode usar com o Amazon Bedrock: ferramentas personalizadas usando o Lambda ou ferramentas predefinidas suportadas pelo Amazon Bedrock. Esta seção aborda como criar uma ferramenta Lambda personalizada com a API Responses. As seções a seguir descrevem cada tipo em detalhes.

Ferramentas personalizadas usando o Lambda na API de respostas

Ao usar uma função do Lambda como uma ferramenta personalizada no Amazon Bedrock, você pode ampliar os recursos do agente integrando funções personalizadas do Lambda como ferramentas. Com isso, você pode 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 responder a 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 Amazon 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 do 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 do Lambda e obter um ARN. Você pode ler mais em Introdução ao Lambda no Guia do desenvolvedor do Lambda.

# 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: Defina 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 Responses para fornecer recursos 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 porque o Amazon 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 conectores está disponível nos modelos que suportam a API Responses. Verifique quais ferramentas suportam seu modelo em Gerar respostas usando APIs OpenAI. 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 do Lambda no tools parâmetro, a API tentará obter uma lista de ferramentas do servidor. Se for bem-sucedido na recuperação da 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á escolher 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 do Lambda deve ter as mesmas funções e políticas do IAM anexadas à do aplicativo que chama o modelo no Amazon 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 AWS fornecidas na API de respostas

Há duas ferramentas AWS fornecidas incorporadas aos openai.gpt-oss-120b modelos: Note-taking funcionalidade (ferramenta de notas) e gerenciamento de tarefas (ferramenta de tarefas). openai.gpt-oss-20b Essas ferramentas estão disponíveis automaticamente — você não precisa defini-las no tools parâmetro.

Visão geral da ferramenta Notes

A notes ferramenta permite que o modelo armazene notas na mesma sessão de conversa. Isso fornece um mecanismo de memória simples para manter o contexto em várias interações. A memória tem como escopo somente a conversa atual.

Quando o modelo usa a ferramenta de notas, ele emite uma mcp_call saída com name set to"notes". O modelo determina os argumentos apropriados com base em sua solicitação.

Você pode usar qualquer linguagem natural (por exemplo, “Lembra que minha cor favorita é azul”, “O que eu te 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 chamadas diretas de ferramentas quando solicitado (“Use a ferramenta de notas para armazenar meu e-mail como john@example.com “, “Verifique as anotações do meu endereço de e-mail”).

Visão geral da ferramenta de tarefas

A tasks ferramenta fornece uma pilha para gerenciar tarefas em uma sessão de conversação. Você pode colocar as tarefas na pilha e retirá-las, o que as torna úteis para gerenciar fluxos de trabalho, lembretes ou gerenciamento hierárquico de tarefas. As tarefas persistem durante toda a sessão de conversação. A memória tem como escopo somente a conversa atual.

Quando o modelo usa a ferramenta de tarefas, ele emite uma mcp_call saída com name set to"tasks". O modelo determina os argumentos apropriados (como methodtask.title, etask.description) com base em sua solicitação.

Você pode chamar a ferramenta Tarefas usando linguagem natural (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?” , “Retire 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 pressionar 'concluir apresentação'”, “Retirar uma tarefa da pilha”, “Adicionar 'agendar reunião' à minha lista de tarefas”).

Exemplo de código: usando as ferramentas de notas e tarefas

As ferramentas de notas e tarefas são incorporadas openai.gpt-oss-120b aos modelos openai.gpt-oss-20b e. Você não precisa defini-los explicitamente no tools parâmetro — basta referenciá-los em seu prompt:

from openai import OpenAI

client = OpenAI(
    base_url="https://bedrock-mantle.us-east-1.api.aws/v1"
)

# The notes tool is built-in — just ask the model to use it
resp = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Use the notes tool to store that my preferred language is Python.",
)

print(resp.output)
# The model automatically calls the notes tool via mcp_call

# Use the tasks tool to push a task
resp = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Use the tasks tool to push a task: review the API documentation",
)

print(resp.output)

Server-side integração de uso de ferramentas 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. Com esse recurso, você pode conectar seus modelos diretamente aos endpoints do AgentCore Gateway para 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 uma fonte de ferramentas, use a estrutura a seguir em sua tools matriz em sua 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 de solicitação completa

{
  "model":"openai.gpt-oss-120b",
  "stream":true,
  "background":false,
  "store":false,
  "tools": [
    {
      "type":"mcp",
      "server_label":"agentcore_tools",
      "connector_id":"arn:aws:bedrock-agentcore:us-west-2:342789630635:gateway/agentcore-intro-gateway-v2-swvq44sovp",
      "server_description":"AgentCore Gateway providing custom tools",
      "require_approval":"never"
    }
  ],
  "input": [
    {
      "type":"message",
      "role":"user",
      "content": [
        {
          "type":"input_text",
          "text":"What is the weather in Seattle?"
        }
      ]
    }
  ]
}

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 do 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