Create an agent in Amazon Bedrock - Amazon Bedrock

Create an agent in Amazon Bedrock

To create an agent with Amazon Bedrock, you set up the following components:

  • The configuration of the agent, which defines the purpose of the agent and indicates the foundation model (FM) that it uses to generate prompts and responses.

  • At least one of the following:

    • Action groups that define what actions the agent is designed to perform.

    • A knowledge base of data sources to augment the generative capabilities of the agent by allowing search and query.

You can minimally create an agent that only has a name. To Prepare an agent so that you can test or deploy it, you must minimally configure the following components:

Configuration Description
Agent resource role The ARN of the service role with permissions to call API operations on the agent
Foundation model (FM) An FM for the agent to invoke to perform orchestration
Instructions Natural language describing what the agent should do and how it should interact with users

You should also configure at least one action group or knowledge base for the agent. If you prepare an agent with no action groups or knowledge bases, it will return responses based only on the FM and instructions and base prompt templates.

To learn how to create an agent, select the tab corresponding to your method of choice and follow the steps.

Console
To create an agent

  1. Sign in to the AWS Management Console, and open the Amazon Bedrock console at https://console.aws.amazon.com/bedrock/.

  2. Select Agents from the left navigation pane.

  3. In the Agents section, choose Create Agent.

  4. (Optional) Change the automatically generated Name for the agent and provide an optional Description for it.

  5. Choose Create. Your agent is created and you will be taken to the Agent builder for your newly created agent, where you can configure your agent.

  6. You can continue to the following procedure to configure your agent or return to the Agent builder later.

To configure your agent

  1. If you're not already in the agent builder, do the following:

    1. Sign in to the AWS Management Console, and open the Amazon Bedrock console at https://console.aws.amazon.com/bedrock/.

    2. Select Agents from the left navigation pane. Then, choose an agent in the Agents section.

    3. Choose Edit in Agent builder.

  2. In the Agent details section, you can set up the following configurations:

    1. (Optional) Edit the Agent name or Agent description.

    2. For the Agent resource role, select one of the following options:

      • Create and use a new service role – Let Amazon Bedrock create the service role and set up the required permissions on your behalf.

      • Use an existing service role – Use a custom role that you set up previously. The role must begin with the prefix AmazonBedrockExecutionRoleForAgents_.

    3. For Select model, select an FM for your agent to invoke during orchestration.

    4. In Instructions for the Agent, enter details to tell the agent what it should do and how it should interact with users. The instructions replace the $instructions$ placeholder in the orchestration prompt template. Following is an example of instructions:

      You are an office assistant in an insurance agency. You are friendly and polite. You help with managing insurance claims and coordinating pending paperwork.

    5. (Optional) If you want to use a Guardrail to block and filter out harmful content, select the Guardrail name from the drop down menu. Choose the Version of the guardrail you want to use. Select View to see your guardrail settings. For more information, see Guardrails for Amazon Bedrock

    6. If you expand Additional settings, you can modify the following configurations:

      User input – Choose whether to allow the agent to request more information from the user if it doesn't have enough information.

      • If you choose Enabled, the agent returns an Observation reprompting the user for more information if it needs to invoke an API in an action group, but doesn't have enough information to complete the API request.

      • If you choose Disabled, the agent doesn't request the user for additional details and instead informs the user that it doesn't have enough information to complete the task.

      • KMS key selection – (Optional) By default, AWS encrypts agent resources with an AWS managed key. To encrypt your agent with your own customer managed key, for the KMS key selection section, select Customize encryption settings (advanced). To create a new key, select Create an AWS KMS key and then refresh this window. To use an existing key, select a key for Choose an AWS KMS key.

      • Idle session timeout – By default, if a user hasn't responded for 30 minutes in a session with a Amazon Bedrock agent, the agent no longer maintains the conversation history. Conversation history is used to both resume an interaction and to augment responses with context from the conversation. To change this default length of time, enter a number in the Session timeout field and choose a unit of time.

    7. For the IAM permissions section, for Agent resource role, choose a service role. To let Amazon Bedrock create the service role on your behalf, choose Create and use a new service role. To use a custom role that you created previously, choose Use an existing service role. The role must begin with the prefix AmazonBedrockExecutionRoleForAgents_.

      Note

      The service role that Amazon Bedrock creates for you doesn't include permissions for features that are in preview. To use these features, attach the correct permissions to the service role.

    8. (Optional) By default, AWS encrypts agent resources with an AWS managed key. To encrypt your agent with your own customer managed key, for the KMS key selection section, select Customize encryption settings (advanced). To create a new key, select Create an AWS KMS key and then refresh this window. To use an existing key, select a key for Choose an AWS KMS key.

    10. (Optional) To associate tags with this agent, for the Tags – optional section, choose Add new tag and provide a key-value pair.

    11. When you are done setting up the agent configuration, select Next.

  3. In the Action groups section, you can choose Add to add action groups to your agent. For more information on setting up action groups, see Create an action group for an Amazon Bedrock agent. To learn how to add action groups to your agent, see Add an action group to your agent in Amazon Bedrock.

  4. In the Knowledge bases section, you can choose Add to associate knowledge groups with your agent. For more information on setting up knowledge bases, see Knowledge bases for Amazon Bedrock. To learn how to associate knowledge bases with your agent, see Associate a knowledge base with an Amazon Bedrock agent.

  5. In the Advanced prompts section, you can choose Edit to customize the prompts that are sent to the FM by your agent in each step of orchestration. For more information about the prompt templates that you can use for customization, see Advanced prompts in Amazon Bedrock. To learn how to configure advanced prompts, see Configure the prompt templates.

  6. When you finish configuring your agent, select one of the following options:

    • To stay in the Agent builder, choose Save. You can then Prepare the agent in order to test it with your updated configurations in the test window. To learn how to test your agent, see Test an Amazon Bedrock agent.

    • To return to the Agent Details page, choose Save and exit.

API

To create an agent, send a CreateAgent request (see link for request and response formats and field details) with an Agents for Amazon Bedrock build-time endpoint.

See code examples

To prepare your agent and test or deploy it, so that you can test or deploy it, you must minimally include the following fields (if you prefer, you can skip these configurations and configure them later by sending an UpdateAgent request):

Field Use case
agentResourceRoleArn To specify an ARN of the service role with permissions to call API operations on the agent
foundationModel To specify a foundation model (FM) for the agent to orchestrate with
instruction To provide instructions to tell the agent what to do. Used in the $instructions$ placeholder of the orchestration prompt template.

The following fields are optional:

Field Use case
description Describes what the agent does
idleSessionTTLInSeconds Duration after which the agent ends the session and deletes any stored information.
customerEncryptionKeyArn ARN of a KMS key to encrypt agent resources
tags To attach tags to your agent.
promptOverrideConfiguration To customize the prompts sent to the FM at each step of orchestration.
clientToken Identifier to ensure the API request completes only once.

The response returns an CreateAgent object that contains details about your newly created agent. If your agent fails to be created, the CreateAgent object in the response returns a list of failureReasons and a list of recommendedActions for you to troubleshoot.