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á. # Tutorial: criar um agente simples do Amazon Bedrock Este tutorial mostra como criar e configurar um agente simples do Amazon Bedrock usando o Console de Gerenciamento da AWS. Você aprenderá a criar um agente que possa responder às consultas dos usuários sobre a data e a hora atuais invocando uma função do Lambda. Neste tutorial, você vai: 1. Criar uma função do Lambda: crie uma função em Python que exiba a data e a hora atuais quando invocada pelo agente. 1. Criar um agente do Amazon Bedrock: defina um agente no console do Amazon Bedrock e configure-o com instruções para lidar com consultas de data e hora. 1. Testar o agente: use a interface de teste integrada para verificar se o agente consegue responder corretamente às solicitações de data e hora. 1. Implantar o agente com um alias: crie uma versão do agente e implante-a com um alias para disponibilizá-la para uso. 1. Chamar o agente usando o código Python: aprenda a interagir programaticamente com o agente usando o AWS SDK para Python (Boto). 1. Limpar os recursos: remova os recursos da AWS criados durante este tutorial para evitar cobranças desnecessárias. Ao final deste tutorial, você terá um agente do Amazon Bedrock ativo que consegue entender solicitações em linguagem natural de informações de data e hora e responder com dados precisos da função do Lambda. Este tutorial é baseado no exemplo de código de agente no [repositório do GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/python/example_code/bedrock-agent/scenario_get_started_with_agents.py) da documentação da AWS. **Topics** + [Pré-requisitos](agent-tutorial-prereq.md) + [Etapa 1: criar uma função do Lambda](agent-tutorial-step1.md) + [Etapa 2: criar um agente do Amazon Bedrock](agent-tutorial-step2.md) + [Etapa 3: testar o agente](agent-tutorial-step3.md) + [Etapa 4: implantar o agente com um alias](agent-tutorial-step4.md) + [Etapa 5: chamar o agente usando código Python](agent-tutorial-step5.md) + [Etapa 6: limpar os recursos](agent-tutorial-step6.md) + [Recursos adicionais](agent-tutorial-resources.md) # Pré-requisitos Certifique-se de atender aos seguintes pré-requisitos antes de iniciar este tutorial: + Conta da AWS com as seguintes políticas gerenciadas: + [AmazonBedrockFullAccess](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonBedrockFullAccess) + [AWSLambda\$1FullAccess](https://docs.aws.amazon.com/lambda/latest/dg/security-iam-awsmanpol.html#lambda-security-iam-awsmanpol-AWSLambda_FullAccess) + [IAMFullAccess](aws-managed-policy/latest/reference/IAMFullAccess.html) **Importante** Essas permissões possibilitam que você execute este tutorial e outras tarefas não relacionadas. Em ambientes de produção, você deve atribuir somente as permissões das quais os usuários precisam para executar sua aplicação. + Conhecimento básico das permissões e dos perfis do IAM ([Guia do usuário do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)) + Familiaridade com as funções do AWS Lambda ([Guia do desenvolvedor do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)) # Etapa 1: criar uma função do Lambda Primeiro, crie uma função do Lambda que o agente invocará para realizar ações. Neste procedimento, você criará uma função do Lambda em Python que exibe a data e a hora atuais quando invocada. Você configurará a função com permissões básicas, adicionará o código necessário para lidar com as solicitações do agente do Amazon Bedrock e implantará a função para que esteja pronta para ser conectada ao agente. Para ter mais informações, consulte [Criar sua primeira função do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) no *Guia do desenvolvedor do AWS Lambda*. **Criar uma função do Lambda** 1. Faça login no Console de Gerenciamento da AWS e abra o console do AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/). 1. Escolha a opção **Criar função**. 1. Selecione **Criar do zero**. 1. Na seção **Basic information (Informações básicas)**: + Em **Nome do perfil**, insira um nome para o perfil (por exemplo, `DateTimeFunction`). Anote o nome da função, pois será necessário na Etapa 15 de [Etapa 2: criar um agente do Amazon Bedrock](agent-tutorial-step2.md). + Em **Runtime**, selecione **Python 3.9** (ou a versão de sua preferência). + Em **Arquitetura**, deixe inalterado. + Em **Permissões**, selecione **Alterar a função de execução padrão** e escolha **Criar um perfil com permissões básicas do Lambda**. 1. Escolha a opção **Criar função**. 1. Em **Visão geral da função**, em **ARN da função**, anote o nome do recurso da Amazon (ARN) da função. Você precisará dele para a etapa 24 de [Etapa 2: criar um agente do Amazon Bedrock](agent-tutorial-step2.md). 1. Na guia **Código**, substitua o código existente pelo seguinte: ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 import datetime import json def lambda_handler(event, context): now = datetime.datetime.now() response = {"date": now.strftime("%Y-%m-%d"), "time": now.strftime("%H:%M:%S")} response_body = {"application/json": {"body": json.dumps(response)}} action_response = { "actionGroup": event["actionGroup"], "apiPath": event["apiPath"], "httpMethod": event["httpMethod"], "httpStatusCode": 200, "responseBody": response_body, } session_attributes = event["sessionAttributes"] prompt_session_attributes = event["promptSessionAttributes"] return { "messageVersion": "1.0", "response": action_response, "sessionAttributes": session_attributes, "promptSessionAttributes": prompt_session_attributes, } ``` 1. Escolha **Implantar** para implantar sua função. 1. Escolha a guia **Configuração**. 1. Escolha **Permissões**. 1. Em **Declarações de política baseadas em recursos**, escolha **Adicionar permissões**. 1. Em **Editar declaração de política**, faça o seguinte: 1. Selecione **Serviço da AWS**. 1. Em **Serviço**, selecione **Outro**. 1. Em **ID da declaração**, insira um identificador exclusivo (por exemplo, `AllowBedrockInvocation`). 1. Em **Entidade principal**, insira `bedrock.amazonaws.com`. 1. Em **ARN do recurso**, insira `arn:aws:bedrock:region:AWS account ID:agent/*`. Substitua `region` pela região da AWS que você está usando, como `us-east-1`. Substitua `AWS account ID` pelo ID da conta da AWS. 1. Em **Ação**, selecione `lambda:InvokeFunction`. 1. Escolha **Salvar**. # Etapa 2: criar um agente do Amazon Bedrock A seguir, você criará um agente do Amazon Bedrock. Neste procedimento, você configurará um agente no console do Amazon Bedrock, o configurará com um modelo de base e fornecerá instruções que definem seu comportamento como um chatbot amigável que exibe informações de data e hora. Você também criará um grupo de ação com um esquema da OpenAPI que define os endpoints da API que o agente pode chamar, especificamente o endpoint para obter a data e a hora atuais. Além disso, você adicionará uma política em linha ao perfil do IAM do agente para permitir que ele invoque a função do Lambda. O agente servirá como interface entre os usuários e a função do Lambda, interpretando solicitações em linguagem natural e convertendo-as em chamadas de função estruturadas para recuperar informações de data e hora. Para obter mais informações, consulte [Criar e configurar o agente manualmente](agents-create.md). **Criar um agente do Amazon Bedrock** 1. Faça login no Console de gerenciamento da AWS com uma identidade do IAM que tenha permissões para usar o console Amazon Bedrock. Em seguida, abra o console Amazon Bedrock em [https://console.aws.amazon.com/bedrock.](https://console.aws.amazon.com/bedrock) 1. Certifique-se de que você esteja em uma AWS [região](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/select-region.html) que ofereça suporte aos [agentes](agents-supported.md) do Amazon Bedrock. 1. No painel de navegação, em **Ferramentas para construtores**, selecione **Agentes**. 1. Escolha **Criar agente**. 1. Em **Nome**, insira um nome para o agente (por exemplo, `MyBedrockAgent`). 1. (Opcional) Em **Description (Descrição)**, insira uma descrição. 1. Escolha **Criar**. O painel **Construtor de agentes** é aberto. 1. Na seção **Detalhes do agente**: + Em **Função de recurso do agente**, selecione **Criar e usar um novo perfil de serviço**. + Em **Selecionar modelo**, selecione um modelo, como Claude 3 Haiku. + Na seção **Instruções para agentes**, insira as instruções a seguir. ``` You are a friendly chat bot. You have access to a function called that returns information about the current date and time. When responding with date or time, please make sure to add the timezone UTC. ``` 1. Escolha **Salvar**. 1. Escolha a guia **Grupos de ação**. 1. Em **Grupos de ação**, escolha **Adicionar**. 1. Em **Inserir o nome do grupo de ação**, insira um nome para o grupo de ação (por exemplo, `TimeActions`). 1. (Opcional) Em **Descrição**, insira uma descrição para o grupo de ação. 1. Em **Tipo do grupo de ação**, selecione **Definir com esquemas de API**. 1. Em **Invocação do grupo de ação**, escolha **Selecionar uma função do Lambda existente**. 1. Em **Selecionar função do Lambda**, escolha o nome da função do Lambda que você criou em [Etapa 1: criar uma função do Lambda](agent-tutorial-step1.md). 1. Em **Esquema do grupo de ação**, selecione **Definir por meio do editor de esquema em linha**. 1. Na caixa de texto **Esquema OpenAPI em linha**, substitua o esquema existente pelo seguinte esquema OpenAPI em YAML: ``` openapi: 3.0.0 info: title: Time API version: 1.0.0 description: API to get the current date and time. paths: /get-current-date-and-time: get: summary: Gets the current date and time. description: Gets the current date and time. operationId: getDateAndTime responses: '200': description: Gets the current date and time. content: 'application/json': schema: type: object properties: date: type: string description: The current date time: type: string description: The current time ``` 1. Analise a configuração do grupo de ação e escolha **Criar**. 1. Escolha **Salvar** para salvar as alterações. 1. Escolha **Preparar** para preparar o agente. 1. Escolha **Salvar e sair** para salvar suas alterações e sair do criador de agentes. 1. Na seção **Visão geral do agente**, em **Permissões**, escolha a perfil de serviço do IAM. Isso abre o perfil no console do IAM. 1. No console do IAM, escolha a guia **Permissões**. 1. Escolha **Adicionar permissões** e, em seguida, selecione **Criar política em linha**. 1. Escolha **JSON** e cole a política a seguir. Observe que `Resource` é o nome do recurso da Amazon (ARN) da função do Lambda. Você anotou o ARN na Etapa 6 de [Etapa 1: criar uma função do Lambda](agent-tutorial-step1.md). 1. Escolha **Próximo**. 1. Insira um nome para a política (por exemplo, `BedrockAgentLambdaInvoke`). 1. Selecione **Criar política**. # Etapa 3: testar o agente Neste procedimento, você testará o rascunho de trabalho do agente usando a interface de teste integrada no console do Amazon Bedrock. Você enviará consultas em linguagem natural solicitando a data e a hora atuais e observará como o agente processa essas solicitações, invoca a função do Lambda e exibe respostas formatadas. Essa etapa de teste permite que você verifique se o agente compreende corretamente a intenção do usuário, chama adequadamente a função do Lambda e apresenta as informações de uma forma fácil de usar. Para obter mais informações, consulte [Testar e solucionar problemas de comportamento do agente](agents-test.md). **Como testar o agente** 1. No console do Amazon Bedrock, abra o agente que você criou em [Etapa 2: criar um agente do Amazon Bedrock](agent-tutorial-step2.md) 1. Escolha **Testar** para abrir o painel **Teste**. 1. No menu suspenso **Alias**, selecione o alias **TestAlias: rascunho de trabalho**. 1. Na interface de chat, insira um prompt que acionaria uma das ações do agente, como: + **What time is it?** + **Can you tell me today's date?** 1. O agente processará o prompt, invocará a função do Lambda, se necessário, e exibirá uma resposta. 1. (Opcional) Escolha **Mostrar rastreamento** para ver as etapas de [rastreamento](trace-events.md) do prompt que você enviou ao modelo. No rastreamento, você deve ver o raciocínio que o modelo usa para determinar quando chamar a função do Lambda para obter data e hora. # Etapa 4: implantar o agente com um alias Depois de configurar o agente, você precisa implantá-lo com um alias para disponibilizá-lo para uso. Neste procedimento, você preparará o agente para implantação criando um alias e uma versão dele. O alias aponta para a versão, permitindo que você invoque o agente por meio de um endpoint estável, mantendo a capacidade de atualizar a implementação subjacente. Para obter mais informações, consulte [Implantar e usar um agente do Amazon Bedrock na aplicação](agents-deploy.md). **Implantar o agente com um alias** 1. No console do Amazon Bedrock, abra o agente que você criou em [Etapa 2: criar um agente do Amazon Bedrock](agent-tutorial-step2.md) 1. Escolha **Criar alias**. 1. Em **Nome do alias**, digite um nome para o alias. Por exemplo, . **DateTimeAliasAgentAlias**. 1. (Opcional) Em **Description (Descrição)**, insira uma descrição. 1. Em **Associar uma versão**, selecione **Criar uma versão e a associe a esse alias**. 1. Escolha **Criar alias**. 1. Teste o alias seguindo as instruções em [Etapa 3: testar o agente](agent-tutorial-step3.md). Para a Etapa 6, escolha o alias que você acabou de criar. # Etapa 5: chamar o agente usando código Python Nesta etapa, você aprenderá a interagir programaticamente com o agente usando o AWS SDK para Python (Boto). O código de exemplo demonstra como usar a [InvokeAgent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html)operação, que exige o ID do AGENTE e o ID do ALIAS como parâmetros para chamar seu agente. O código mostra como enviar um prompt ao agente, processar a resposta e lidar com os modos de resposta de streaming e sem streaming. Isso permite que você integre o agente do Bedrock em seus próprias aplicações Python. Para obter mais informações, consulte [Invocar um agente por meio de sua aplicação](agents-invoke-agent.md). **Chamar o agente usando Python** 1. Obtenha o ID do agente. Para obter mais informações, consulte [Obter informações sobre um agente](agents-view.md). 1. Obtenha o ID do alias do agente. Para obter mais informações, consulte [Visualizar as informações sobre os aliases de agentes no Amazon Bedrock.](agents-alias-view.md). 1. Execute o código a seguir. Atualize o seguinte: + **AGENT\$1ID**: para o ID do agente. + **ALIAS\$1ID**: para o ID do alias do agente. + **REGIÃO** — para a AWS região na qual você criou seu agente, como`us-east-1`. Para transmitir a resposta do agente, altere o valor de `streamFinalResponse` para `True`. ``` import boto3 import logging from botocore.exceptions import ClientError logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) def invoke_agent(client, agent_id, alias_id, prompt, session_id): response = client.invoke_agent( agentId=agent_id, agentAliasId=alias_id, enableTrace=True, sessionId = session_id, inputText=prompt, streamingConfigurations = { "applyGuardrailInterval" : 20, "streamFinalResponse" : False } ) completion = "" for event in response.get("completion"): #Collect agent output. if 'chunk' in event: chunk = event["chunk"] completion += chunk["bytes"].decode() # Log trace output. if 'trace' in event: trace_event = event.get("trace") trace = trace_event['trace'] for key, value in trace.items(): logging.info("%s: %s",key,value) print(f"Agent response: {completion}") if __name__ == "__main__": client=boto3.client( service_name="bedrock-agent-runtime", region_name="REGION") agent_id = "AGENT_ID" alias_id = "ALIAS_ID" session_id = "123456" prompt = "What's the current time?" try: invoke_agent(client, agent_id, alias_id, prompt, session_id) except ClientError as e: print(f"Client error: {str(e)}") logger.error("Client error: %s", {str(e)}) ``` # Etapa 6: limpar os recursos Quando não precisar mais usar o agente do Amazon Bedrock, você deverá limpar os recursos para evitar cobranças desnecessárias. Neste procedimento final, você excluirá sistematicamente todos os AWS recursos criados durante este tutorial, incluindo o agente Bedrock, a função Lambda e as funções\$1IAM associadas. Esse processo de limpeza é importante para o gerenciamento de custos, pois evita cobranças contínuas por recursos que você não está mais utilizando. O procedimento é organizado em três partes: excluir o agente, remover a função do Lambda e limpar os perfis do IAM que foram criados para atender a esses serviços. **Topics** + [Excluir o agente](#agent-tutorial-step6-console-agent) + [Excluir a função Lambda](#agent-tutorial-step6-console-lambda) + [Excluas os perfis do IAM](#agent-tutorial-step6-console-iam) ## Excluir o agente **Excluir o agente** 1. No console do Amazon Bedrock, abra o agente que você criou em [Etapa 2: criar um agente do Amazon Bedrock](agent-tutorial-step2.md) 1. Selecione o agente que você criou. 1. Escolha **Excluir**. 1. Confirme a exclusão. ## Excluir a função Lambda **Excluir a função Lambda** 1. Abra o AWS Lambda console em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/). 1. Selecione a função do Lambda que você criou. 1. Escolha **Ações** e **Excluir**. 1. Confirme a exclusão. ## Excluas os perfis do IAM **Excluas os perfis do IAM** 1. Abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. No painel de navegação, escolha **Perfis**. 1. Selecione o perfil de serviço do agente que você criou. 1. Escolha **Excluir**. 1. Confirme a exclusão. 1. Repita para o perfil de execução do Lambda. # Recursos adicionais + [Guia do Usuário do Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) + [Referência de API do Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/APIReference/welcome.html) + [Guia do desenvolvedor do AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) + [Manual do usuário do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) + [Documentação de Agentes do Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html) + [Especificação OpenAPI](https://swagger.io/specification/)