# Deploy and use an Amazon Bedrock agent in your application Before you can use an agent, you must deploy the agent by creating an alias. You can then use the agent in your application by calling the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) operation. In this section, you learn how to create and manage an alias and how to call your agent from an application. **Topics** + [Deploy an agent](deploy-agent.md) + [Invoke an agent from your application](agents-invoke-agent.md) # Deploy an agent When you first create an Amazon Bedrock agent, you have a working draft version (`DRAFT`) and a test alias (`TSTALIASID`) that points to the working draft version. When you make changes to your agent, the changes apply to the working draft. You iterate on your working draft until you're satisfied with the behavior of your agent. Then, you can set up your agent for deployment and integration into your application by creating *aliases* of your agent. **Aliases and Versions** To deploy your agent, you must create an *alias*. During alias creation, Amazon Bedrock creates a version of your agent automatically. The alias points to this newly created version. Alternatively, you can point the alias to a previously created version of your agent. Then, you configure your application to make API calls to that alias. A *version* is a snapshot that preserves the resource as it exists at the time it was created. You can continue to modify the working draft and create new aliases (and consequently, versions) of your agent as necessary. In Amazon Bedrock, you create a new version of your agent by creating an alias that points to the new version by default. Amazon Bedrock creates versions in numerical order, starting from 1. Versions are immutable because they act as a snapshot of your agent at the time you created it. To make updates to an agent in production, you must create a new version and set up your application to make calls to the alias that points to that version. With aliases, you can switch efficiently between different versions of your agent without requiring the application to keep track of the version. For example, you can change an alias to point to a previous version of your agent if there are changes that you need to revert quickly. ## Pausing a deployed agent You might need to temporarily pause the running of an agent. For example, during maintenance, updates, or when addressing performance issues. To pause an agent, you use the alias for the agent with the [UpdateAgentAlias](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgentAlias.html) operation. To pause an agent, set the `aliasInvocationState` field to `REJECT_INVOCATIONS`. To start the agent running again, set `aliasInvocationState` to `ACCEPT_INVOCATIONS`. You don't need to make any IAM policy modifications to pause the agent. To check if an agent is currently paused, call [GetAgentAlias](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgentAlias.html) and check the `aliasInvocationState` field. You can also check the `aliasInvocationState` field for an alias in the response from [ListAgentAliases](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_ListAgentAliases.html). **Topics** + [Pausing a deployed agent](#agent-pause) + [Create an alias for your agent](deploy-agent-proc.md) + [View information about versions of agents in Amazon Bedrock](agents-version-view.md) + [Delete a version of an agent in Amazon Bedrock](agents-version-delete.md) + [View information about aliases of agents in Amazon Bedrock](agents-alias-view.md) + [Edit an alias of an agent in Amazon Bedrock](agents-alias-edit.md) + [Delete an alias of an agent in Amazon Bedrock](agents-alias-delete.md) # Create an alias for your agent The following procedure shows you how to create an alias and a version for your agent. After you create an alias, you can use the agent in your application by making an [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) request with an [Agents for Amazon Bedrock runtime endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt). **To create an alias** + Create an alias and version of your agent. Choose the tab for your preferred method, and then follow the steps: ------ #### [ Console ] **To create an alias (and optionally a new version)** 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. In the **Aliases** section, choose **Create**. 1. Enter a unique **Alias name** and provide an optional **Description**. 1. Under **Associate a version**, choose one of the following options: + To create a new version, choose **Create a new version and to associate it to this alias**. + To use an existing version, choose **Use an existing version to associate this alias**. From the dropdown menu, choose the version that you want to associate the alias to. 1. Under **Select throughput**, select one of the following options: + To let your agent run model inference at the rates set for your account, select **On-demand (ODT)**. For more information, see [Quotas for Amazon Bedrock](quotas.md). + To let your agent run model inference at an increased rate using a Provisioned Throughput that you previously purchased for the model, select **Provisioned Throughput (PT)** and then select a provisioned model. For more information, see [Increase model invocation capacity with Provisioned Throughput in Amazon Bedrock](prov-throughput.md). 1. Select **Create alias**. ------ #### [ API ] To create an alias for an agent, send a [CreateAgentAlias](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgentAlias.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). The following fields are required: **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/deploy-agent-proc.html) The following fields are optional: **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/deploy-agent-proc.html) ``` def create_agent_alias(self, name, agent_id): """ Creates an alias of an agent that can be used to deploy the agent. :param name: The name of the alias. :param agent_id: The unique identifier of the agent. :return: Details about the alias that was created. """ try: response = self.client.create_agent_alias( agentAliasName=name, agentId=agent_id ) agent_alias = response["agentAlias"] except ClientError as e: logger.error(f"Couldn't create agent alias. {e}") raise else: return agent_alias ``` For more information, see [Hello Amazon Bedrock Agents](bedrock-agent_example_bedrock-agent_Hello_section.md). ------ # View information about versions of agents in Amazon Bedrock After you create a version of your agent, you can view information about it or delete it. You can only create a new version of an agent by creating a new alias. To learn how to view information about the versions of an agent, choose the tab for your preferred method, and then follow the steps: ------ #### [ Console ] **To view information about a version of 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 the version to view from the **Versions** section. 1. To view details about the model, action groups, or knowledge bases attached to version of the agent, choose the name of the information that you want to view. You can't modify any part of a version. To make modifications to the agent, use the working draft and create a new version. ------ #### [ API ] To get information about an agent version, send a [GetAgentVersion](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgentVersion.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Specify the `agentId` and `agentVersion`. To list information about an agent's versions, send a [ListAgentVersions](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_ListAgentVersions.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`. 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. | ------ # Delete a version of an agent in Amazon Bedrock To learn how to delete a version of an agent, choose the tab for your preferred method, and then follow the steps: ------ #### [ Console ] **To delete a version of 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. To choose the version for deletion, in the **Versions** section, choose the option button next to the version that you want to delete. 1. Choose **Delete**. 1. A dialog box appears warning you about the consequences of deletion. To confirm that you want to delete the version, enter **delete** in the input field and choose **Delete**. 1. A banner appears to inform you that the version is being deleted. When deletion is complete, a success banner appears. ------ #### [ API ] To delete a version of an agent, send a [DeleteAgentVersion](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_DeleteAgentVersion.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). 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. ------ # View information about aliases of agents in Amazon Bedrock To learn how to view information about the aliases of an agent, choose the tab for your preferred method, and then follow the steps: ------ #### [ Console ] **To view the details of an alias** 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 the alias to view from the **Aliases** section. 1. You can view the name and description of the alias and tags that are associated with the alias. ------ #### [ API ] To get information about an agent alias, send a [GetAgentAlias](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgentAlias.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). Specify the `agentId` and `agentAliasId`. To list information about an agent's aliases, send a [ListAgentVersions](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_ListAgentVersions.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`. 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 view all the tags for an alias, 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 alias. ------ # Edit an alias of an agent in Amazon Bedrock To learn how to edit an alias of an agent, choose the tab for your preferred method, and then follow the steps: ------ #### [ Console ] **To edit an alias** 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. In the **Aliases** section, choose the option button next to the alias that you want to edit. Then choose **Edit** 1. Edit any of the existing fields as necessary. For more information about these fields, see [Deploy and use an Amazon Bedrock agent in your application](agents-deploy.md). 1. Select **Save**. **To add or remove tags associated with an alias** 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 the alias for which you want to manage tags from the **Aliases** 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 edit an agent alias, send an [UpdateAgentAlias](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgentAlias.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. To add tags to an alias, 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 alias. 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 alias, 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 alias. The `tagKeys` request parameter is a list containing the keys for the tags that you want to remove. ------ # Delete an alias of an agent in Amazon Bedrock To learn how to delete an alias of an agent, choose the tab for your preferred method, and then follow the steps: ------ #### [ Console ] **To delete an alias** 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. To choose the alias for deletion, in the **Aliases** section, choose the option button next to the alias that you want to delete. 1. Choose **Delete**. 1. A dialog box appears warning you about the consequences of deletion. To confirm that you want to delete the alias, enter **delete** in the input field and choose **Delete**. 1. A banner appears to inform you that the alias is being deleted. When deletion is complete, a success banner appears. ------ #### [ API ] To delete an alias of an agent, send a [DeleteAgentAlias](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_DeleteAgentAlias.html) request with an [Agents for Amazon Bedrock build-time endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt). 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_alias(self, agent_id, agent_alias_id): """ Deletes an alias of an Amazon Bedrock agent. :param agent_id: The unique identifier of the agent that the alias belongs to. :param agent_alias_id: The unique identifier of the alias to delete. :return: The response from Amazon Bedrock Agents if successful, otherwise raises an exception. """ try: response = self.client.delete_agent_alias( agentId=agent_id, agentAliasId=agent_alias_id ) except ClientError as e: logger.error(f"Couldn't delete agent alias. {e}") raise else: return response ``` For more information, see [Hello Amazon Bedrock Agents](bedrock-agent_example_bedrock-agent_Hello_section.md). ------ # Invoke an agent from your application Use your agent in an application by making an [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) request with an [Agents for Amazon Bedrock runtime endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt). By default, the response from `InvokeAgent` includes a chunk that contains the complete response from the agent, which can take a while to complete. Alternatively, you can configure `InvokeAgent` to stream the response in multiple smaller chunks. This decreases the latency of the initial response from the agent. **Streaming responses** You can optionally enable streaming of the response by setting the `streamFinalResponse` to `true` in streaming configurations ( [StreamingConfigurations](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_StreamingConfigurations.html)). The response stream contains multiple events with chunks for each part of the response in order. To stream responses, make sure the agent execution role includes the `bedrock:InvokeModelWithResponseStream` permission for the configured Agent model. For more information, see [Identity-based permissions for the Agents service role](agents-permissions.md#agents-permissions-identity). If your agent is configured with a Guardrail, you can also specify the `applyGuardrailInterval` in the `StreamingConfigurations`, to control how often an `ApplyGuardrail` call is made on outgoing response characters (for example, every 50 characters). By default, the guardrail interval is set to 50 characters. If a larger interval is specified, the response will be generated in larger chunks with fewer `ApplyGuardrail` calls. The following examples show the response generated for *Hello, I am an agent* input string. **Example response in chunks: Interval set to 3 characters** ``` 'Hel', 'lo, ', 'I am', ' an', ' Age', 'nt' ``` Each chunk has at least 3 characters except for the last chunk. **Example response in chunks: Interval set to 20 or more characters** ``` 'Hello, I am an Agent' ``` ## Invoke an agent The following Python example shows how to call the [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) operation and display the output from the agent, as well as any [trace](trace-events.md) information that the call generates. **To invoke an agent** 1. Create an agent by following the instructions at [Create and configure agent manually](agents-create.md). Note the ID for the agent. If necessary, you can get the ID later. For more information, see [View information about an agent](agents-view.md). 1. Create an alias for the agent, by following the instructions at [Create an alias for your agent](deploy-agent-proc.md). Note the ID of the alias. If necessary, you can get the ID later. For more information, see [View information about aliases of agents in Amazon Bedrock](agents-alias-view.md). 1. Run the following code. Update the value of `agent_id` to your agent's ID and the value of `alias_id` to the alias ID of the agent. To stream the response from the agent, change the value of `streamFinalResponse` to `True`. You can also change the guardrail interval by changing the value of `applyGuardrailInterval`. ``` 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" ) agent_id = "AGENT_ID" alias_id = "ALIAS_ID" session_id = "MY_SESSION_ID" prompt = "Prompt to send to agent" 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)}) ```