# Build and modify agents in Amazon Bedrock for your application
Build and modify agents for your application

Amazon Bedrock agents automate tasks for your application users by orchestrating interactions between the foundation model, data sources, software applications and user conversations. Agents also automatically call APIs to take actions and invoke knowledge bases to supplement information for these actions. Before you can start using agents for your application, you must first build your agent by creating and then configuring your agent to perform the tasks.

Amazon Bedrock provides you with the following options for building an agent for your use case.

**Create and configure your agent manually**

After you've created your agent, configure the agent by setting up an action group that defines actions that the agent can help end users perform. Action group includes the parameters that the agent must elicit from your application user, APIs that can be called, how to handle the action, and how to return a response. 

You can skip defining an action group for your agent and instead choose to set up knowledge bases that provides a repository of information that agent can query to answer queries from your application users. 

You can manually create, configure, modify, and delete your agent in the console, using the CLI, or using the SDKs. For more information, see [Create and configure agent manually](agents-create.md).

**Configure your agent using conversational builder**

After you’ve created your agent, you can optionally use *Conversational Builder* to configure your agent. Conversational builder is an interactive assistant that is available in the Amazon Bedrock console. Conversational builder helps in configuring an agent for you. With conversational builder, you interact with the assistant using natural language to describe the purpose of your agent and information your agent might require to fulfill the purpose. The agent is built for you using the information you provide. Use conversational builder if you want to quickly configure or modify an agent. You can modify and delete your agent at any time in the console, using the conversational builder. For more information, see [Configure your agent using conversational builder](agents-create-cb.md).

**Configure and invoke an agent dynamically at runtime**

You can configure and invoke an inline Amazon Bedrock agent dynamically at runtime using [InvokeInlineAgent](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_InvokeInlineAgent.html) API. Using an inline agent provides you with flexibility to specify your agent capabilities like foundation models, instructions, action groups, guardrails, and knowledge bases at the same time you invoke your agent. You do not need to pre-define agent capabilities before you can use it. For more information, see [Configure an inline agent at runtime](agents-create-inline.md).

**Use pre-built templates to jumpstart the use of agents for your use case**

Amazon Bedrock provides you with *Agent Blueprints* to jumpstart your use of Amazon Bedrock Agents. Blueprints are a collection of pre-built templates optimized for popular use cases. These templates allows you to quickly experiment with agent-based applications without the need for configurations and lengthy development cycles. Agent Blueprints are open-source templates hosted on [amazon-bedrock-samples](https://github.com/aws-samples/amazon-bedrock-samples/tree/main/agents-and-function-calling/bedrock-agents/agent-blueprint-templates) GitHib repository. The templates come with sample actions, Guardrails, and Knowledge Bases. For more information, see [Introducing Blueprints to simplify agent-based automation on Amazon Bedrock](https://aws.amazon.com/about-aws/whats-new/2024/08/blueprints-agent-based-automation-amazon-bedrock/).

**Topics**
+ [

# Configure your agent using conversational builder
](agents-create-cb.md)
+ [

# Configure an inline agent at runtime
](agents-create-inline.md)
+ [

# Create and configure agent manually
](agents-create.md)
+ [

# View information about an agent
](agents-view.md)
+ [

# Modify an agent
](agents-edit.md)
+ [

# Delete an agent
](agents-delete.md)

# Configure your agent using conversational builder


Conversational builder is an interactive assistant that helps in configuring an agent for you. With conversational builder, you use natural language to describe the purpose of your agent which results in a fully testable agent being built that fulfills the purpose. The conversational builder interacts with you to get all the necessary information to build or update your agent.

**Important**  
The conversational builder is available in the Amazon Bedrock console in US East (N. Virginia), US West (Oregon), Europe (Frankfurt), Asia Pacific (Sydney), and Europe (Paris) regions.

Conversational builder performs *only* the following actions based on the interactions:
+ Update your agent’s name and description
+ Generate a summary of the agent instruction based on the instruction you provided in natural language
+ Create an action group 
+ Update an action group’s name and description
+ Define an action group function based off of a summary of the action group
+ Associate, list, and disassociate knowledge base
+ List or delete action groups

The following is an example of an interaction with the conversational builder:

```
Conversational builder: Hello, I can help you update your Agent's configurations.

What configurations would you like to update?
You can say something like "Associate a knowledge base"

User: Create a travel agent
Conversational builder:  What is the purpose of this travel agent? What kind of tasks or capabilities should it have?
User: Travel agent books flights and hotels for vacation
Conversational builder: The travel agent with the purpose of booking flights and hotels for vacations has been successfully created.
```

## Create and configure an agent using conversational builder in the Amazon Bedrock console


**To create an agent**

1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

1. Select **Agents** from the left navigation pane.

1. In the **Agents** section, choose **Create Agent**.

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

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

1. 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 with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

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

1. Choose **Edit in Agent builder**.

1. In the Agent builder, choose **Assistant**

1. In the Agent builder pane, enter the purpose of your agent. See the example interaction to get started interacting with the conversational builder assistant.

1. When conversational builder has completed 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](agents-test.md).
   + To return to the **Agent Details** page, choose **Save and exit**.

## Add the following permissions to use conversational builder in the Amazon Bedrock console


If you plan to [Configure your agent using conversational builder](#agents-create-cb), make sure to attach the following permissions:

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "InvokeInlineAgent",
      "Effect": "Allow",
      "Action": "bedrock:InvokeInlineAgent",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "bedrock:InlineAgentName": "AgentName-123"
        }
      }
    },
    {
      "Sid": "InvokeFoundationModel",
      "Effect": "Allow",
      "Action": "bedrock:InvokeModel",
      "Resource": "arn:aws:bedrock:us-east-1::foundation-model/{modelId}"
    },
    {
      "Sid": "S3AccessForKBAndActions",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws:s3:::bucket-name/*"
    },
    {
      "Sid": "S3AccessForCodeInterpreter",
      "Effect": "Allow",
      "Action": [
        "s3:GetObjectVersion",
        "s3:GetObjectVersionAttributes",
        "s3:GetObjectAttributes"
      ],
      "Resource": "arn:aws:s3:::bucket/path/to/file"
    },
    {
      "Sid": "KnowledgeBaseAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:Retrieve",
        "bedrock:RetrieveAndGenerate"
      ],
      "Resource": "arn:aws:bedrock:us-east-1:123456789012:knowledge-base/knowledge-base-id"
    },
    {
      "Sid": "GuardrailAccess",
      "Effect": "Allow",
      "Action": "bedrock:ApplyGuardrail",
      "Resource": "arn:aws:bedrock:us-east-1:123456789012:guardrail/guardrail-id"
    },
    {
      "Sid": "LambdaInvoke",
      "Effect": "Allow",
      "Action": "lambda:InvokeFunction",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:function-name"
    },
    {
      "Sid": "KMSAccess",
      "Effect": "Allow",
      "Action": [
        "kms:GenerateDataKey*",
        "kms:Decrypt"
      ],
      "Resource": "arn:aws:kms:us-east-1:123456789012:key/key-id"
    }
  ]
}
```

------

# Configure an inline agent at runtime


You can configure and invoke an inline Amazon Bedrock agent dynamically at runtime using [InvokeInlineAgent](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_InvokeInlineAgent.html) API. Using an inline agent provides you with flexibility to specify your agent capabilities like foundation models, instructions, action groups, guardrails, and knowledge bases at the same time you invoke your agent. You do not need to pre-define agent capabilities before you can use it. 

The following are some of the use cases where using inline agents can help by providing you the flexibility to configure your agent at invocation time.
+ Conduct rapid experimentation by trying out various agent features with different configurations and dynamically updating tools available to your agent without creating separate agents.
+ Dynamically invoke an agent to perform specific tasks without creating new agent versions or preparing the agent. 
+ Run simple queries or use code interpreter for simple tasks by creating and invoking the agent at runtime.
+ Create multiple agents in a [ multi-agent collaboration](agents-multi-agent-collaboration.md) setup to work together on a task or a conversation.

  To use multi-agent collaboration, you can create your agents in the following combinations using inline agents APIs.  
**Agent types**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/agents-create-inline.html)

**Supported models and Regions**

You can use any foundation model supported by Amazon Bedrock Agents to configure your inline agent and can invoke your inline agent in any of the Regions where Amazon Bedrock Agents are supported. For more information about the models and Regions supported by Amazon Bedrock Agents, see the following:
+ [Supported Regions for Amazon Bedrock Agents](https://docs.aws.amazon.com//bedrock/latest/userguide/agents-supported.html)
+ [Model support by feature](https://docs.aws.amazon.com//bedrock/latest/userguide/models-features.html)

With inline agents you can switch between models. We recommend that you switch between the models that belong to the same family. Switching between models that belong to different families might result in inconsistent behaviors and might cause failures. 

Configuring and invoking an inline agent is currently not supported in the Amazon Bedrock console.

## Guidelines for using advanced prompt templates for inline agents

+ **Base prompt templates** — By default, Amazon Bedrock will use the default base prompt template for your inline agent and the prompts can be changed in the background at any time. This might make the responses inconsistent. If you want consistent responses to your queries, customize your inline agent's behavior by overriding the logic in the default base prompt template with your own configurations. For more information, see [Advanced prompt templates](https://docs.aws.amazon.com//bedrock/latest/userguide/advanced-prompts-templates.html).
+ **Encryption** — Use `customer managed key ` to encrypt the session details at rest/storage. If a session is started with a customer managed key, it will be required for all future requests made for the same session. using a different customer managed key for the same sessions will result in an exception. 
+ **Session sharing** — Going forward all sessions are account level instead of role level. You can isolate sessions at the agent level by specifying a unique value for `agentName`.
+ **Inline sessions state** — The attributes inside of `InlineSessionState` persists through the session. Use the attributes to provide additional context for your model and for [few-shot prompting](https://docs.aws.amazon.com//bedrock/latest/userguide/what-is-a-prompt.html#few-shot-prompting-vs-zero-shot-prompting).

# Prerequisites


**Note**  
Configuring and invoking an inline agent feature is in preview release for Amazon Bedrock and is subject to change.

Complete the following prerequisites before you invoke your inline agent:

1. Decide on the foundation model you want to use for configuring your inline agent, Region where you want to invoke the agent, and an instruction that tells the inline agent what it should do. 

1. Create or prepare one or more of the following Amazon Bedrock agent properties you want to use for your inline agent.   
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/inline-agent-prereq.html)

1. Create a AWS Identity and Access Management (IAM) role and attach the policy mentioned in this step to the role. 

   Before you can invoke an inline agent, you must create an IAM role that provides the necessary permissions for using the `InvokeInlineAgent` API and to access resources like Lambda functions, knowledge bases, and foundation models. 

   Create a custom service role for your inline agent by following steps at [Creating a role to delegate permissions to an IAM user](https://docs.aws.amazon.com//bedrock/latest/userguide/getting-started.html). After you create the IAM role, attach the following policy to the role.
**Note**  
As a best practice for security purposes, replace the *\$1\$1region\$1*, *\$1\$1account-id\$1*, and *\$1.ids* with Region, your account id, and specific resource ids. after you have created them.

# Invoke an inline agent


**Note**  
Configuring and invoking an inline agent feature is in preview release for Amazon Bedrock and is subject to change.

Before you invoke your inline agent, make sure you've completed the [Prerequisites](https://docs.aws.amazon.com//bedrock/latest/userguide/inline-agent-prereq.html).

To invoke an inline agent, send a [InvokeInlineAgent](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_InvokeInlineAgent.html) API request with an [Agents for Amazon Bedrock runtime endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt) and minimally include the following fields.


****  

| Field | Use case | 
| --- | --- | 
| instruction | Provide instructions that tell the inline agent what it should do and how it should interact with users. | 
| foundationModel | Specify a [foundation model](https://docs.aws.amazon.com//bedrock/latest/userguide/foundation-models-reference.html) to use for orchestration by the inline agent you create. For example, anthropic claude, meta Llama3.1, etc. | 
| sessionId | An unique identifier of the session. Use the same value across requests to continue same conversation. | 

The following fields are optional:


****  

| Field | Use case | 
| --- | --- | 
| actionGroups | List of action groups with each action group defining the actions that the inline agent can carry out.  | 
| knowledgeBases | Knowledge base associations with inline agent to augment response generated by the model.  | 
| guardrailConfiguration | Guardrail configurations to block topics, to prevent hallucinations, and to implement safeguards for your application.  | 
| agentCollaboration | Defines how the collaborator agent handles information across multiple collaborator agents to coordinate a final response. The collaborator agent can also be the supervisor. | 
| collaboratorConfigurations | Configurations for collaborator agent.  | 
| collaborators | List of collaborator agents. | 
| promptOverrideConfiguration | Configurations for advanced prompts used to override the default prompts. | 
| enableTrace | Specify whether to turn on the trace or not to track the inline agent's reasoning process. | 
| idleSessionTTLInSeconds | Specify the duration after which the inline agent should end the session and delete any stored information. | 
| customerEncryptionKeyArn | Specify the ARN of a KMS key to encrypt agent resources, | 
| endSession | Specify whether to end the session with the inline agent or not. | 
| inlineSessionState | Parameters that specify the various attributes of a sessions. | 
| inputText | Specify the prompt text to send to the agent. | 
| reasoning\$1config | To enable model reasoning so that the model explains how it reached its conclusions. Use inside of a additionalModelRequestFields field. You must specify the number of budget\$1tokens that are used for model reasoning, which are a subset of the output tokens. For more information, see [Enhance model responses with model reasoning](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-reasoning.html). | 

The following `InvokeInlineAgent` API example provides complete inline agent configurations including the foundation model, instructions, action groups with code interpreter, guardrails, and knowledge bases. 

```
response = bedrock_agent_runtime.invoke_inline_agent(
    // Initialization parameters: cannot be changed for a conversation
    sessionId='uniqueSessionId',
    customerEncryptionKeyArn: String,
    
    // Input
    inputText="Hello, can you help me with a task?",
    endSession=False,
    enableTrace=True,
    
    // Agent configurations
    foundationModel='anthropic.claude-3-7-sonnet-20250219-v1:0',
    instruction="You are a helpful assistant...",
    actionGroups=[
        {
            'name': 'CodeInterpreterAction',
            'parentActionGroupSignature': 'AMAZON.CodeInterpreter'
        },
        {
            'actionGroupName': 'FetchDetails',
            'parentActionGroupSignature': '',
            "actionGroupExecutor": { ... },
            "apiSchema": { ... },
            "description": "string",
            "functionSchema": { ... }
        }
    ],
    knowledgeBases=[
        {
            knowledgeBaseId: "string",
            description: 'Use this KB to get all the info',
            retrievalConfiguration: { 
                vectorSearchConfiguration: { 
                    filter: { ... },
                    numberOfResults: number,
                    overrideSearchType: "string"
               }
            }
        }
    ],
    guardrailConfiguration={
        guardrailIdentifier: 'BlockEverything',
        gurardrailVersion: '1.0'
    },
    promptOverrideConfiguration: {...}
    
    // session properties: persisted throughout conversation
    inlineSessionState = {
        sessionAttributes = { 'key': 'value' },
        promptSessionAttributes = {k:v},
        returnControlInvocationResults = {...},
        invocationId = 'abc',
        files = {...},
    }
  }
```

You can include model reasoning parameters in the request. The following is an example of a single prompt that turns on model reasoning in the `additionalModelRequestFields`.

```
{
    "basePromptTemplate": " ... ",
    "inferenceConfiguration": {
        "stopSequences": [
            "</answer>"
        ]
    },
    "parserMode": "DEFAULT",
    "promptCreationMode": "DEFAULT",
    "promptState": "DISABLED",
    "promptType": "ORCHESTRATION",
    "additionalModelRequestFields":
    "reasoning_config": {
        "type": "enabled",
        "budget_tokens": 1024
    }
}
```

# Create and configure agent manually


# Prerequisites for creating Amazon Bedrock Agents
Prerequisites for creating an agent

Ensure that your IAM role has the [necessary permissions](security_iam_id-based-policy-examples-agent.md#iam-agents-ex-all) to perform actions related to Amazon Bedrock Agents.

Before creating an agent, review the following prerequisites and determine which ones you need to fulfill:

1. You must set up at least one of the following for your agent:
   + [Action group](agents-action-create.md) – Defines actions that the agent can help end users perform. Each action group includes the parameters that the agent must elicit from the end-user. You can also define the APIs that can be called, how to handle the action, and how to return the response. To see the quota for action groups in an agent, refer to the **Action groups per Agent** quota in [Amazon Bedrock endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/bedrock.html) in the AWS General Reference. You can skip this prerequisite if you plan to have no action groups for your agent.
   + [Knowledge base](knowledge-base.md) – Provides a repository of information that the agent can query to answer customer queries and improve its generated responses. Associating at least one knowledge base can help improve responses to customer queries by using private data sources. To see the quota for knowledge bases attached to an agent, refer to the **Associated knowledge bases per Agent** quota in [Amazon Bedrock endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/bedrock.html) in the AWS General Reference. You can skip this prerequisite if you plan to have no knowledge bases associated with your agent.

1. (Optional) [Create a custom AWS Identity and Access Management (IAM) [service role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-role) for your agent with the proper permissions](agents-permissions.md). You can skip this prerequisite if you plan to use the AWS Management Console to automatically create a service role for you.

1. (Optional) Create a [guardrail](guardrails.md) to implement safeguards for your agent and to prevent unwanted behavior from model responses and user messages. You can then associate it with your agent.

1. (Optional) Purchase [Provisioned Throughput](prov-throughput.md) to increase the number and rate of tokens that your agent can process in a given time frame. You can then associate it with an alias of your agent when you [create a version of your agent and associate an alias with it](agents-deploy.md).

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](agents-test.md) or [deploy](agents-deploy.md) 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](agents-permissions.md) | 
| 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](advanced-prompts.md).

To learn how to create an agent, choose the tab for your preferred method, and then follow the steps:

------
#### [ Console ]

**To create an agent**

1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

1. Select **Agents** from the left navigation pane.

1. In the **Agents** section, choose **Create Agent**.

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

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

1. 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 with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

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

   1. Choose **Edit in Agent builder**.

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

   1. Edit the **Agent name** or **Agent description**.

   1. 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](agents-permissions.md) that you set up previously.

   1. 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.\]](http://docs.aws.amazon.com/bedrock/latest/userguide/images/agents/agents-optimized-model-selection.png)

   1. 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 \$1instructions\$1 placeholder in the [orchestration prompt template](prompt-placeholders.md#placeholders-orchestration). 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.
      ```

   1. 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](agents-code-interpretation.md).
      + **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](agents-user-input.md).
      + **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 an 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.

   1. For the **IAM permissions** section, for **Agent resource role**, choose a [service role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-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](agents-permissions.md) 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](agents-permissions.md).

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

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

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

1. 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](agents-action-create.md). To learn how to add action groups to your agent, see [Add an action group to your agent in Amazon Bedrock](agents-action-add.md).

1. 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 Amazon Bedrock Knowledge Bases](knowledge-base.md). To learn how to associate knowledge bases with your agent, see [Augment response generation for your agent with knowledge base](agents-kb-add.md).

1. 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 [Detect and filter harmful content by using Amazon Bedrock Guardrails](guardrails.md).

1. In the **Orchestration strategy** section, you can choose **Edit** to customize your agent's orchestration. For more information about the orchestration strategy you can use for your agent, see [Customize agent orchestration strategy](orch-strategy.md).

1. In the **Multi-agent collaboration** section, you can choose **Edit** to create a multi-agent collaboration team. For more information about multi-agent collaboration, see [Use multi-agent collaboration with Amazon Bedrock Agents](agents-multi-agent-collaboration.md).

1. 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](agents-test.md).
   + To return to the **Agent Details** page, choose **Save and exit**.

------
#### [ API ]

To create an agent, send a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html) request (see link for request and response formats and field details) with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt).

[See code examples](bedrock-agent_example_bedrock-agent_CreateAgent_section.md)

To prepare your agent and test or deploy it, so that you can [test](agents-test.md) or [deploy](agents-deploy.md) it, you must minimally include the following fields (if you prefer, you can skip these configurations and configure them later by sending an [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html) 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 \$1instructions\$1 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](tagging.md) with your agent. | 
| promptOverrideConfiguration | To [customize the prompts](advanced-prompts.md) sent to the FM at each step of orchestration. | 
| guardrailConfiguration | To add a [guardrail](guardrails.md) 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](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html). | 
| cachingState | To enable prompt caching of input to the agent. For more information, see [Prompt caching for faster model inference](prompt-caching.md). | 
| reasoning\$1config | To enable model reasoning so that the model explains how it reached its conclusions. Use inside of a additionalModelRequestFields field. You must specify the number of budget\$1tokens that are used for model reasoning, which are a subset of the output tokens. For more information, see [Enhance model responses with model reasoning](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-reasoning.html). | 

The response returns an [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) object that contains details about your newly created agent. If your agent fails to be created, the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) object in the response returns a list of `failureReasons` and a list of `recommendedActions` for you to troubleshoot.

```
    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"]
```

For more information, see [Hello Amazon Bedrock Agents](bedrock-agent_example_bedrock-agent_Hello_section.md).

------

# View information about an agent


After you create an agent, you can view or update its configuration as required. The configuration applies to the working draft. If you no longer need an agent, you can delete it.

To learn how to view information about an agent, choose the tab for your preferred method, and then follow the steps:

------
#### [ Console ]

**To view information about an agent**

1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

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

1. On the agent details page, you can see configurations that apply to all versions of the agent, associated tags, and its versions and aliases.

1. To see details about the working draft of the agent, choose **Edit in Agent builder**.

------
#### [ API ]

To get information about an agent, send a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgent.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt) and specify the `agentId`. 

```
    def get_agent(self, agent_id, log_error=True):
        """
        Gets information about an agent.

        :param agent_id: The unique identifier of the agent.
        :param log_error: Whether to log any errors that occur when getting the agent.
                          If True, errors will be logged to the logger. If False, errors
                          will still be raised, but not logged.
        :return: The information about the requested agent.
        """

        try:
            response = self.client.get_agent(agentId=agent_id)
            agent = response["agent"]
        except ClientError as e:
            if log_error:
                logger.error(f"Couldn't get agent {agent_id}. {e}")
            raise
        else:
            return agent
```

For more information, see [Hello Amazon Bedrock Agents](bedrock-agent_example_bedrock-agent_Hello_section.md).

To list information about your agents, send a [ListAgents](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_ListAgents.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). [See code examples](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-agent_example_bedrock-agent_ListAgents_section.html). You can specify the following optional parameters:


****  

| Field | Short description | 
| --- | --- | 
| maxResults | The maximum number of results to return in a response. | 
| nextToken | If there are more results than the number you specified in the maxResults field, the response returns a nextToken value. To see the next batch of results, send the nextToken value in another request. | 

To list all the tags for an agent, send a [ListTagsForResource](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_ListTagsForResource.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt) and include the Amazon Resource Name (ARN) of the agent.

```
    def list_agents(self):
        """
        List the available Amazon Bedrock Agents.

        :return: The list of available bedrock agents.
        """

        try:
            all_agents = []

            paginator = self.client.get_paginator("list_agents")
            for page in paginator.paginate(PaginationConfig={"PageSize": 10}):
                all_agents.extend(page["agentSummaries"])

        except ClientError as e:
            logger.error(f"Couldn't list agents. {e}")
            raise
        else:
            return all_agents
```

For more information, see [Hello Amazon Bedrock Agents](bedrock-agent_example_bedrock-agent_Hello_section.md).

------

# Modify an agent


After you create an agent, you can update its configuration as required. The configuration applies to the working draft.

To learn how to modify an agent, choose the tab for your preferred method, and then follow the steps:

------
#### [ Console ]

**To edit an agent's configuration or its components**

1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

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

1. Choose **Edit in Agent Builder**

1. Edit the existing information in the **Agent details** section, or choose **Add**, **Edit**, or **Delete** in any of the other subsections and modify as necessary. To edit an action group or knowledge base, select it in the respective section. For more information about the components of the agent that you can edit, see [Create and configure agent manually](agents-create.md).
**Note**  
If you change the foundation model, any [prompt templates](advanced-prompts.md) that you modified will be set to default for that model.

1. When you're done editing the information, choose **Save** to remain in the same window or **Save and exit** to return to the agent details page. A success banner appears at the top. To apply the new configurations to your agent, select **Prepare** in the test window.

**To edit the tags associated with an agent**

1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

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

1. Choose an agent in the **Agents** section.

1. In the **Tags** section, choose **Manage tags**.

1. To add a tag, choose **Add new tag**. Then enter a **Key** and optionally enter a **Value**. To remove a tag, choose **Remove**. For more information, see [Tagging Amazon Bedrock resources](tagging.md).

1. When you're done editing tags, choose **Submit**.

------
#### [ API ]

To modify an agent, send an [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Because all fields will be overwritten, include both fields that you want to update as well as fields that you want to keep the same. For more information about required and optional fields, see [Create and configure agent manually](agents-create.md).

To apply the changes to the working draft, send a [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Include the `agentId` in the request. The changes apply to the `DRAFT` version, which the `TSTALIASID` alias points to.

To add tags to an agent, send a [TagResource](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_TagResource.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt) and include the Amazon Resource Name (ARN) of the agent. The request body contains a `tags` field, which is an object containing a key-value pair that you specify for each tag.

To remove tags from an agent, send an [UntagResource](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UntagResource.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt) and include the Amazon Resource Name (ARN) of the agent. The `tagKeys` request parameter is a list containing the keys for the tags that you want to remove.

------

# Delete an agent


If you no longer need an agent, you can delete it at any time.

To learn how to delete an agent, choose the tab for your preferred method, and then follow the steps:

------
#### [ Console ]

**To delete an agent**

1. Sign in to the AWS Management Console with an IAM identity that has permissions to use the Amazon Bedrock console. Then, open the Amazon Bedrock console at [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock).

1. Select **Agents** from the left navigation pane.

1. To delete an agent, choose the option button that's next to the agent you want to delete.

1. A dialog box appears warning you about the consequences of deletion. To confirm that you want to delete the agent, enter **delete** in the input field and then select **Delete**.

1. When deletion is complete, a success banner appears.

------
#### [ API ]

To delete an agent, send a [DeleteAgent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_DeleteAgent.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt) and specify the `agentId`.

By default, the `skipResourceInUseCheck` parameter is `false` and deletion is stopped if the resource is in use. If you set `skipResourceInUseCheck` to `true`, the resource will be deleted even if the resource is in use.

```
    def delete_agent(self, agent_id):
        """
        Deletes an Amazon Bedrock agent.

        :param agent_id: The unique identifier of the agent to delete.
        :return: The response from Amazon Bedrock Agents if successful, otherwise raises an exception.
        """

        try:
            response = self.client.delete_agent(
                agentId=agent_id, skipResourceInUseCheck=False
            )
        except ClientError as e:
            logger.error(f"Couldn't delete agent. {e}")
            raise
        else:
            return response
```

For more information, see [Hello Amazon Bedrock Agents](bedrock-agent_example_bedrock-agent_Hello_section.md).

------