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á.
# Criar e configurar o agente manualmente
# Pré-requisitos para criar agentes do Amazon Bedrock
Verifique se o perfil do IAM tem as [permissões necessárias](security_iam_id-based-policy-examples-agent.md#iam-agents-ex-all) para executar ações relacionadas a agentes do Amazon Bedrock.
Antes de criar um agente, analise os seguintes pré-requisitos e determine quais deles precisam ser atendidos:
1. Configure pelo menos um dos seguintes itens para o agente:
+ [Grupo de ação](agents-action-create.md): define ações que o agente pode ajudar os usuários finais a executar. Cada grupo de ação inclui os parâmetros que o agente deve obter do usuário final. Você também pode definir as APIs que podem ser chamadas, como lidar com a ação e como apresentar a resposta. Para obter a cota de grupos de ação em um agente, consulte a cota em **Action groups per Agent** em [Amazon Bedrock endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/bedrock.html) no Referência geral da AWS. É possível ignorar esse pré-requisito se você planeja não ter grupos de ação para o agente.
+ [Base de conhecimento](knowledge-base.md): fornece um repositório de informações que o agente pode consultar para responder às dúvidas dos clientes e melhorar as respostas geradas. Associar pelo menos uma base de conhecimento pode ajudar a melhorar as respostas às consultas dos clientes usando fontes de dados privadas. Para obter a cota de bases de conhecimento anexadas a um agente, consulte a cota em **Associated knowledge bases per Agent** em [Amazon Bedrock endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/bedrock.html) no Referência geral da AWS. É possível ignorar esse pré-requisito caso não pretenda ter nenhuma base de conhecimento associada ao agente.
1. (Opcional) [Criar um [perfil de serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-role) personalizado do AWS Identity and Access Management (IAM) para o agente com as permissões adequadas](agents-permissions.md). É possível ignorar esse pré-requisito caso pretenda usar o Console de gerenciamento da AWS para criar um perfil de serviço automaticamente para você.
1. (Opcional) Criar uma [barreira de proteção](guardrails.md) para implementar proteções para o agente e evitar comportamentos indesejados nas respostas do modelo e nas mensagens do usuário. Depois é possível associá-la ao agente.
1. (Opcional) Comprar [throughput provisionado](prov-throughput.md) para aumentar o número e a taxa de tokens que o agente pode processar em determinado período. É possível associá-lo a um alias do agente ao [criar uma versão do agente e associar um alias a ele](agents-deploy.md).
Para criar um agente com o Amazon Bedrock, configure os seguintes componentes:
+ A configuração do agente, que define a finalidade do agente e indica o modelo de base (FM) que ele deve usar para interpretar e gerar prompts e respostas.
+ Pelo menos um dos seguintes:
+ Grupos de ação que definem a ações que o agente foi criado para executar.
+ Uma base de conhecimento de fontes de dados para aumentar as capacidades generativas do agente por meio da permissão de pesquisa e consulta.
É possível criar no mínimo um agente que tenha apenas um nome. Para **Preparar** um agente para que possa [testá-lo](agents-test.md) ou [implantá-lo](agents-deploy.md), você deve configurar no mínimo os seguintes componentes:
****
| Configuração | Descrição |
| --- | --- |
| Função de recurso do agente | O ARN do [perfil de serviço com permissões para chamar operações de API no agente](agents-permissions.md) |
| Modelo de base (FM) | Um FM para o agente invocar e executar a orquestração |
| Instruções | Linguagem natural que descreve o que o agente deve fazer e como ele deve interagir com os usuários |
Configure também pelo menos um grupo de ação ou base de conhecimento para o agente. Se você preparar um agente sem grupos de ação ou bases de conhecimento, ele apresentará respostas com base somente no FM, nas instruções e nos [modelos de base de prompts](advanced-prompts.md).
Para saber como criar um agente, escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ Console ]
**Para criar um agente**
1. Faça login no Console de gerenciamento da AWS com uma identidade do IAM que tenha permissões para usar o console do Amazon Bedrock. Em seguida, abra o console do Amazon Bedrock em [https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock).
1. No painel de navegação à esquerda, selecione **Agentes**.
1. Na sessão **Agentes**, escolha **Criar agente**.
1. (Opcional) Altere o **Nome** gerado automaticamente para o agente e forneça uma **Descrição** opcional para ele.
1. Escolha **Criar**. O agente é criado e o **Construtor de agentes** do agente recém-criado será aberto, onde você poderá configurá-lo.
1. É possível continuar com o procedimento a seguir para configurar o agente ou retornar ao Construtor de agentes posteriormente.
**Como configurar o agente**
1. Se você ainda não estiver no Construtor de agentes, faça o seguinte:
1. Faça login no Console de gerenciamento da AWS com uma identidade do IAM que tenha permissões para usar o console do Amazon Bedrock. Em seguida, abra o console do Amazon Bedrock em [https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock).
1. No painel de navegação à esquerda, selecione **Agentes**. Escolha um agente na seção **Agentes**.
1. Escolha **Editar no Construtor de agentes**.
1. Na seção **Detalhes do agente**, é possível definir as seguintes configurações:
1. Edite o **Nome do agente** ou a **Descrição do agente**.
1. Para a **Função de recurso do agente**, selecione uma das seguintes opções:
+ **Criar e usar um novo perfil de serviço**: permita que o Amazon Bedrock crie o perfil de serviço e configure as permissões necessárias em seu nome.
+ **Usar um perfil de serviço existente**: use um [perfil personalizado](agents-permissions.md) que tenha configurado anteriormente.
1. Em **Selecionar modelo**, escolha um FM para o agente invocar durante a orquestração.
Por padrão, os modelos otimizados para agentes são exibidos. Para ver todos os modelos compatíveis com o Amazon Bedrock Agents, desmarque **Agentes otimizados do Bedrock**.
![\[É possível criar agentes com qualquer modelo de base. Atualmente, alguns dos modelos oferecidos são otimizados com prompts/analisadores ajustados para integração com a arquitetura dos agentes. Com o tempo, planejamos oferecer otimização para todos os modelos oferecidos.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/agents/agents-optimized-model-selection.png)
1. Em **Instruções para o agente**, forneça detalhes para informar ao agente o que deve fazer e como deve interagir com os usuários. As instruções substituem o espaço reservado \$1instructions\$1 no [modelo de prompt de orquestração](prompt-placeholders.md#placeholders-orchestration). Veja abaixo um exemplo de instruções:
```
You are an office assistant in an insurance agency. You are friendly and polite. You help with managing insurance claims and coordinating pending paperwork.
```
1. Se você expandir **Configurações adicionais**, poderá modificar as seguintes configurações:
+ **Interpretador de código**: (opcional) escolha se deseja permitir que o agente execute tarefas que envolvam escrever, executar, testar e solucionar problemas de código. Para obter detalhes, consulte [Gerar, executar e testar código com a interpretação de código](agents-code-interpretation.md).
+ **Entrada do usuário**: (opcional) escolha se deseja permitir que o agente solicite mais informações do usuário quando não tiver informações suficientes. Para obter detalhes, consulte [Configurar o agente para solicitar informações do usuário](agents-user-input.md).
+ **Seleção de chaves do KMS**: (opcional) por padrão, a AWScriptografa os recursos do agente com uma chave gerenciada pela Chave gerenciada pela AWS. Para criptografar o agente com sua chave gerenciada pelo cliente, na seção Seleção de chaves do KMS, escolha **Personalizar configurações de criptografia (avançado)**. Para criar uma chave, selecione **Criar uma chave do AWS KMS** e atualize essa janela. Para usar uma chave existente, selecione uma chave em **Escolher uma chave do AWS KMS**.
+ **Tempo limite da sessão ociosa**: por padrão, se um usuário não responder depois de 30 minutos em uma sessão com um agente do Amazon Bedrock, o agente não manterá mais o histórico da conversa. O histórico de conversa é usado tanto para retomar uma interação quanto para aumentar as respostas com o contexto da conversa. Para alterar esse período padrão, insira um número no campo **Tempo limite da sessão** e escolha uma unidade de tempo.
1. Na seção de **Permissões do IAM**, em **Função de recurso do agente**, escolha um [perfil de serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-role). Para permitir que o Amazon Bedrock crie o perfil de serviço em seu nome, escolha **Criar e usar um novo perfil de serviço**. Para usar um [perfil personalizado](agents-permissions.md) criado anteriormente, escolha **Usar perfil de serviço existente**.
**nota**
O perfil de serviço que o Amazon Bedrock cria para você não inclui permissões para recursos que estão em versão prévia. Para usar esses recursos, [anexe as permissões corretas ao perfil de serviço](agents-permissions.md).
1. (Opcional) Por padrão, a AWS criptografa os recursos de agente com uma Chave gerenciada pela AWS. Para criptografar o agente com sua chave gerenciada pelo cliente, na seção **Seleção de chaves do KMS**, escolha **Personalizar configurações de criptografia (avançado)**. Para criar uma chave, selecione **Criar uma chave do AWS KMS** e atualize essa janela. Para usar uma chave existente, selecione uma chave em **Escolher uma chave do AWS KMS**.
1. (Opcional) Para associar tags a esse agente, na seção **Tags: opcional**, escolha **Adicionar nova tag** e forneça um par de chave-valor.
1. Ao concluir a configuração do agente, selecione **Próximo**.
1. Na seção **Grupos de ação**, é possível escolher **Adicionar** para adicionar grupos de ação ao agente. Para obter mais informações sobre como configurar grupos de ação, consulte [Como usar grupos de ação para definir as ações para que o agente execute](agents-action-create.md). Para saber como adicionar grupos de ação ao agente, consulte [Adicionar um grupo de ação ao agente no Amazon Bedrock](agents-action-add.md).
1. Na seção **Bases de conhecimento**, é possível escolher **Adicionar** para associar grupos de conhecimento ao agente. Para obter mais informações sobre como configurar bases de conhecimento, consulte [Recuperar dados e gerar respostas de IA com as Bases de Conhecimento do Amazon Bedrock](knowledge-base.md). Para saber como associar bases de conhecimento ao agente, consulte[Aumentar a geração de respostas do agente com a base de conhecimento](agents-kb-add.md).
1. Na seção **Detalhes da barreira de proteção**, é possível escolher **Editar** para associar uma barreira de proteção ao agente e bloquear e filtrar conteúdo nocivo. Escolha uma barreira de proteção que deseja usar no menu suspenso em **Selecionar a barreira de proteção** e escolha a versão a ser usada em **Versão da barreira de proteção**. É possível selecionar **Visualizar** para ver as configurações da barreira de proteção. Para obter mais informações, consulte [Detectar e filtrar conteúdo nocivo usando as Barreiras de Proteção do Amazon Bedrock](guardrails.md).
1. Na seção **Estratégia de orquestração**, você pode escolher **Editar** para personalizar a orquestração do agente. Para ter mais informações sobre a estratégia de orquestração que você pode usar para o agente, consulte [Personalizar a estratégia de orquestração de agentes](orch-strategy.md).
1. Na seção **Colaboração multiagente**, você pode escolher **Editar** para criar uma equipe de colaboração multiagente. Para ter mais informações sobre colaboração multiagente, consulte [Usar a colaboração multiagente com Agentes do Amazon Bedrock](agents-multi-agent-collaboration.md).
1. Ao concluir a configuração do agente, selecione uma das seguintes opções:
+ Para permanecer no **Construtor de agentes**, escolha **Salvar**. Será possível **Preparar** o agente para testá-lo com as configurações atualizadas na janela de teste. Para saber como testar o agente, consulte [Testar e solucionar problemas de comportamento do agente](agents-test.md).
+ Para retornar à página **Detalhes do agente**, escolha **Salvar e sair**.
------
#### [ API ]
Para criar um agente, envie uma solicitação [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html) (consulte o link para obter os formatos de solicitação e de resposta e os detalhes do campo) com um [endpoint de tempo de compilação do Agentes para Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt).
[Consulte exemplos de código](bedrock-agent_example_bedrock-agent_CreateAgent_section.md)
Para preparar o agente para que possa [testá-lo](agents-test.md) ou [implantá-lo](agents-deploy.md), você deve incluir no mínimo os seguintes campos (se preferir, é possível ignorar essas configurações e configurá-las posteriormente enviando uma solicitação [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html)):
****
| Campo | Caso de uso |
| --- | --- |
| agentResourceRoleArn | Especificar um ARN do perfil de serviço com permissões para chamar operações de API no agente. |
| foundationModel | Especificar um modelo de base (FM) com o qual o agente orquestrar. |
| instruction | Fornecer instruções para informar ao agente o que fazer. Usada no espaço reservado \$1instructions\$1 no modelo de prompt de orquestração. |
Os seguintes campos são opcionais:
****
| Campo | Caso de uso |
| --- | --- |
| description | Descreve o que o agente faz. |
| idleSessionTTLInSeconds | Tempo após o qual o agente encerra a sessão e exclui todas as informações armazenadas. |
| customerEncryptionKeyArn | ARN de uma chave do KMS para criptografar recursos do agente. |
| tags | Para associar [tags](tagging.md) ao agente. |
| promptOverrideConfiguration | Para [personalizar os prompts](advanced-prompts.md) enviados ao FM em cada etapa da orquestração. |
| guardrailConfiguration | Para adicionar uma [barreira de proteção](guardrails.md) ao agente. Especifique o ID ou o ARN da barreira de proteção e a versão a ser usada. |
| clientToken | Para garantir que a solicitação de API seja concluída apenas uma vez. Para obter mais informações, consulte [Ensuring idempotency](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html). |
| cachingState | Para habilitar o armazenamento em cache de prompts da entrada para o agente. Para obter mais informações, consulte [Armazenamento em cache de prompts para agilizar a inferência do modelo](prompt-caching.md). |
| reasoning\$1config | Para habilitar o raciocínio de modelo para que o modelo explique como chegou às respectivas conclusões. Use dentro de um campo additionalModelRequestFields. Você deve especificar o número de budget\$1tokens que é usado para o raciocínio de modelo, que são um subconjunto dos tokens de saída. Para ter mais informações, consulte [Aprimorar as respostas do modelo com o raciocínio de modelo](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-reasoning.html). |
A resposta retorna um objeto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) que contém detalhes sobre o agente recém-criado. Se o agente não for criado, o objeto [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) apresentará uma lista de `failureReasons` na resposta e uma lista de `recommendedActions` para você solucionar o problema.
```
def create_agent(self, agent_name, foundation_model, role_arn, instruction):
"""
Creates an agent that orchestrates interactions between foundation models,
data sources, software applications, user conversations, and APIs to carry
out tasks to help customers.
:param agent_name: A name for the agent.
:param foundation_model: The foundation model to be used for orchestration by the agent.
:param role_arn: The ARN of the IAM role with permissions needed by the agent.
:param instruction: Instructions that tell the agent what it should do and how it should
interact with users.
:return: The response from Amazon Bedrock Agents if successful, otherwise raises an exception.
"""
try:
response = self.client.create_agent(
agentName=agent_name,
foundationModel=foundation_model,
agentResourceRoleArn=role_arn,
instruction=instruction,
)
except ClientError as e:
logger.error(f"Error: Couldn't create agent. Here's why: {e}")
raise
else:
return response["agent"]
```
Para obter mais informações, consulte [Olá, agentes do Amazon Bedrock](bedrock-agent_example_bedrock-agent_Hello_section.md).
------