Create and configure agent manually - Amazon Bedrock

Create and configure agent manually

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 using an IAM role with Amazon Bedrock permissions, 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 using an IAM role with Amazon Bedrock permissions, 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. 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.

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

      By default, models optimized for agents are shown. To see all models supported by Amazon Bedrock Agents, clear Bedrock Agents optimized.

      You can create agents with any foundation model. Currently, some of the offered models are optimized with prompts/parsers fine-tuned for integrating with the agents architecture. Over time, we plan to offer optimization for all of the offered models.

    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. If you expand Additional settings, you can modify the following configurations:

      • Code Interpreter – (Optional) Choose whether to enable agent to handle tasks that involve writing, running, testing, and troubleshooting code. For details, see Generate, run, and test code with code interpretation.

      • User input – (Optional) Choose whether to allow the agent to request more information from the user if it doesn't have enough information. For details, see Configure agent to request information from user.

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

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

      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.

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

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

    9. 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 Use action groups to define actions for your agent to perform. 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 Retrieve data and generate AI responses with knowledge bases. To learn how to associate knowledge bases with your agent, see Augment response generation for your agent with knowledge base.

  5. In the Guardrails details section, you can choose Edit to associate a guardrail with your agent to block and filter out harmful content. Select a guardrail you want to use from the drop down menu under Select guardrail and then choose the version to use under Guardrail version. You can select View to see your Guardrail settings. For more information, see Stop harmful content in models using Amazon Bedrock Guardrails.

  6. 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 Enhance agent's accuracy using advanced prompt templates in Amazon Bedrock. To learn how to configure advanced prompts, see Advanced prompt templates.

  7. 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 and troubleshoot agent behavior.

    • 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 associate tags with your agent.
promptOverrideConfiguration To customize the prompts sent to the FM at each step of orchestration.
guardrailConfiguration To add a guardrail to the agent. Specify the ID or ARN of the guardrail and the version to use.
clientToken To ensure the API request completes only once. For more information, see Ensuring idempotency.

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.