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, ela 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 ferramenta é 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. Server-side as ferramentas que usam a API de respostas estão disponíveis a partir dos 20B/120B modelos GPT OSS 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 as APIs OpenAI](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html). 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: + Estenda a funcionalidade: adicione lógica de negócios personalizada, integrações de API ou recursos de processamento de dados. + Execute ferramentas com segurança: o Lambda permite que as ferramentas acessem recursos dentro de uma VPC sem precisar conceder acesso total à VPC. + Arquitetura sem servidor: sem gerenciamento de infraestrutura, o Lambda gerencia a escalabilidade automaticamente. + Econômico: pague somente pelo tempo de execução, não pelos recursos ociosos. + Fácil integração: as funções Lambda aparecem perfeitamente ao lado das ferramentas integradas. 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](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html). **Como funciona** 1. Função **Lambda: crie sua função** Lambda que implemente o protocolo MCP 1. **Descoberta de ferramentas**: o Bedrock chama sua função Lambda para descobrir as ferramentas disponíveis 1. **Registro de ferramentas**: Suas ferramentas estão registradas no Bedrock 1. **Execução da ferramenta**: Quando o agente solicita sua ferramenta, o Bedrock invoca sua função Lambda 1. **Tratamento da resposta**: os resultados são retornados ao agente por meio da interface padrão **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.](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) ``` # 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](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html). O Amazon Bedrock usa a [funcionalidade de conectores e servidores MCP remotos](https://platform.openai.com/docs/guides/tools-connectors-mcp) 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](https://platform.openai.com/docs/api-reference/responses/create). Confira quais ferramentas são compatíveis com seu modelo [aqui](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html). Ao usar ferramentas usando a API de respostas, você paga apenas pelos [tokens](https://platform.openai.com/docs/pricing) 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](https://platform.openai.com/docs/guides/tools-connectors-mcp?quickstart-panels=connector). 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 incorporadas aos `openai.gpt-oss-120b` modelos `openai.gpt-oss-20b` e: Note-taking funcionalidade (ferramenta de notas) e gerenciamento de tarefas (ferramenta de tarefas). 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 dentro da 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` definido como. `"notes"` O modelo determina os argumentos apropriados com base na sua solicitação. 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 chamadas diretas de ferramentas 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 para gerenciar tarefas em uma sessão de conversação. Você pode colocar tarefas na pilha e retirá-las, tornando-as ú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` definido como. `"tasks"` O modelo determina os argumentos apropriados (como `method``task.title`, e`task.description`) com base na sua solicitação. Você pode ligar para 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?” , “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”). **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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html) 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:** + Usa ARNs da função Lambda + Invoca diretamente as funções do AWS Lambda **AgentCore Integração de gateway:** + Usa ARNs de AgentCore gateway + Encaminha chamadas de ferramentas por meio da infraestrutura do AgentCore Gateway + Oferece gerenciamento e descoberta centralizados de ferramentas ### 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** | Parâmetro | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | type | string | Sim | Deve ser definida como mcp. | | server\_label | string | Sim | Um identificador exclusivo para esse conector de ferramenta em sua solicitação | | connector\_id | string | Sim | O ARN do seu Gateway AgentCore | | server\_description | string | Não | Human-readable descrição das ferramentas fornecidas por este gateway | | require\_approval | string | Sim | O campo tem que ser "never" | **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: 1. **Criou um AgentCore gateway** com destinos configurados (funções Lambda, estágios do API Gateway, esquemas OpenAPI ou servidores MCP) 1. **Permissões IAM configuradas**, permitindo que sua função de serviço Bedrock invoque o gateway. Observe que o Bedrock só oferece suporte a gateways com autenticação IAM. 1. **ARN do gateway** no formato correto ### Benefícios da integração de AgentCore gateway + **Gerenciamento centralizado de ferramentas**: gerencie todas as suas ferramentas por meio de um único terminal de gateway + **Descoberta de ferramentas**: os agentes podem descobrir dinamicamente as ferramentas disponíveis por meio do gateway + **Segurança**: Built-in autenticação e autorização por meio de políticas de IAM e gateway + **Observabilidade**: monitoramento e registro abrangentes de invocações de ferramentas + **Flexibilidade**: Support para vários tipos de alvo (servidores Lambda, API Gateway, OpenAPI, MCP) ### 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 + Saiba mais sobre a [criação de AgentCore gateways](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-create.html) + Explore os [tipos de destino do gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-targets.html) + Analise as [melhores práticas de segurança do gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-security.html)