AWS::Bedrock::Agent
Specifies an agent as a resource in a top-level template. Minimally, you must specify the following properties:
-
AgentName – Specify a name for the agent.
-
AgentResourceRoleArn – Specify the Amazon Resource Name (ARN) of the service role with permissions to invoke API operations on the agent. For more information, see Create a service role for Agents for Amazon Bedrock.
-
FoundationModel – Specify the model ID of a foundation model to use when invoking the agent. For more information, see Supported regions and models for Agents for Amazon Bedrock.
For more information about using agents in Amazon Bedrock, see Agents for Amazon Bedrock.
See the Properties section below for descriptions of both the required and optional properties.
Syntax
To declare this entity in your AWS CloudFormation template, use the following syntax:
JSON
{ "Type" : "AWS::Bedrock::Agent", "Properties" : { "ActionGroups" :
[ AgentActionGroup, ... ]
, "AgentName" :String
, "AgentResourceRoleArn" :String
, "AutoPrepare" :Boolean
, "CustomerEncryptionKeyArn" :String
, "Description" :String
, "FoundationModel" :String
, "GuardrailConfiguration" :GuardrailConfiguration
, "IdleSessionTTLInSeconds" :Number
, "Instruction" :String
, "KnowledgeBases" :[ AgentKnowledgeBase, ... ]
, "PromptOverrideConfiguration" :PromptOverrideConfiguration
, "SkipResourceInUseCheckOnDelete" :Boolean
, "Tags" :{
, "TestAliasTags" :Key
:Value
, ...}{
} }Key
:Value
, ...}
YAML
Type: AWS::Bedrock::Agent Properties: ActionGroups:
- AgentActionGroup
AgentName:String
AgentResourceRoleArn:String
AutoPrepare:Boolean
CustomerEncryptionKeyArn:String
Description:String
FoundationModel:String
GuardrailConfiguration:GuardrailConfiguration
IdleSessionTTLInSeconds:Number
Instruction:String
KnowledgeBases:- AgentKnowledgeBase
PromptOverrideConfiguration:PromptOverrideConfiguration
SkipResourceInUseCheckOnDelete:Boolean
Tags:TestAliasTags:
Key
:Value
Key
:Value
Properties
ActionGroups
-
The action groups that belong to an agent.
Required: No
Type: Array of AgentActionGroup
Update requires: No interruption
AgentName
-
The name of the agent.
Required: Yes
Type: String
Pattern:
^([0-9a-zA-Z][_-]?){1,100}$
Update requires: No interruption
AgentResourceRoleArn
-
The Amazon Resource Name (ARN) of the IAM role with permissions to invoke API operations on the agent.
Required: No
Type: String
Maximum:
2048
Update requires: No interruption
AutoPrepare
-
Specifies whether to automatically update the
DRAFT
version of the agent after making changes to the agent. TheDRAFT
version can be continually iterated upon during internal development. By default, this value isfalse
.Required: No
Type: Boolean
Update requires: No interruption
CustomerEncryptionKeyArn
-
The Amazon Resource Name (ARN) of the AWS KMS key that encrypts the agent.
Required: No
Type: String
Pattern:
^arn:aws(|-cn|-us-gov):kms:[a-zA-Z0-9-]*:[0-9]{12}:key/[a-zA-Z0-9-]{36}$
Minimum:
1
Maximum:
2048
Update requires: No interruption
Description
-
The description of the agent.
Required: No
Type: String
Minimum:
1
Maximum:
200
Update requires: No interruption
FoundationModel
-
The foundation model used for orchestration by the agent.
Required: No
Type: String
Pattern:
^arn:aws(-[^:]+)?:bedrock:[a-z0-9-]{1,20}:(([0-9]{12}:custom-model/[a-z0-9-]{1,63}[.]{1}[a-z0-9-]{1,63}(([:][a-z0-9-]{1,63}){0,2})?/[a-z0-9]{12})|(:foundation-model/([a-z0-9-]{1,63}[.]{1}[a-z0-9-]{1,63}([.]?[a-z0-9-]{1,63})([:][a-z0-9-]{1,63}){0,2}))|([0-9]{12}:(inference-profile|application-inference-profile)/[a-zA-Z0-9-:.]+))|(([a-z0-9-]{1,63}[.]{1}[a-z0-9-]{1,63}([.]?[a-z0-9-]{1,63})([:][a-z0-9-]{1,63}){0,2}))|(([0-9a-zA-Z][_-]?)+)$
Minimum:
1
Maximum:
2048
Update requires: No interruption
GuardrailConfiguration
-
Details about the guardrail associated with the agent.
Required: No
Type: GuardrailConfiguration
Update requires: No interruption
IdleSessionTTLInSeconds
-
The number of seconds for which Amazon Bedrock keeps information about a user's conversation with the agent.
A user interaction remains active for the amount of time specified. If no conversation occurs during this time, the session expires and Amazon Bedrock deletes any data provided before the timeout.
Required: No
Type: Number
Minimum:
60
Maximum:
3600
Update requires: No interruption
Instruction
-
Instructions that tell the agent what it should do and how it should interact with users.
Required: No
Type: String
Minimum:
40
Update requires: No interruption
KnowledgeBases
-
The knowledge bases associated with the agent.
Required: No
Type: Array of AgentKnowledgeBase
Update requires: No interruption
PromptOverrideConfiguration
-
Contains configurations to override prompt templates in different parts of an agent sequence. For more information, see Advanced prompts.
Required: No
Type: PromptOverrideConfiguration
Update requires: No interruption
SkipResourceInUseCheckOnDelete
-
Specifies whether to delete the resource even if it's in use. By default, this value is
false
.Required: No
Type: Boolean
Update requires: No interruption
-
Metadata that you can assign to a resource as key-value pairs. For more information, see the following resources:
Required: No
Type: Object of String
Pattern:
^[a-zA-Z0-9\s._:/=+@-]*$
Minimum:
0
Maximum:
256
Update requires: No interruption
-
Metadata that you can assign to a resource as key-value pairs. For more information, see the following resources:
Required: No
Type: Object of String
Pattern:
^[a-zA-Z0-9\s._:/=+@-]*$
Minimum:
0
Maximum:
256
Update requires: No interruption
Return values
Ref
When you pass the logical ID of this resource to the intrinsic Ref
function, Ref
returns the agent base ID.
For example, { "Ref": "myAgent" }
could return the value "AGENT12345"
.
For more information about using the Ref
function, see Ref
.
Fn::GetAtt
The Fn::GetAtt
intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.
For more information about using the Fn::GetAtt
intrinsic function, see Fn::GetAtt
.
AgentArn
-
The Amazon Resource Name (ARN) of the agent.
AgentId
-
The unique identifier of the agent.
AgentStatus
-
The status of the agent and whether it is ready for use. The following statuses are possible:
-
CREATING – The agent is being created.
-
PREPARING – The agent is being prepared.
-
PREPARED – The agent is prepared and ready to be invoked.
-
NOT_PREPARED – The agent has been created but not yet prepared.
-
FAILED – The agent API operation failed.
-
UPDATING – The agent is being updated.
-
DELETING – The agent is being deleted.
-
AgentVersion
-
The version of the agent.
CreatedAt
-
The time at which the agent was created.
FailureReasons
-
Contains reasons that the agent-related API that you invoked failed.
PreparedAt
-
The time at which the agent was last prepared.
RecommendedActions
-
Contains recommended actions to take for the agent-related API that you invoked to succeed.
UpdatedAt
-
The time at which the agent was last updated.
Examples
Create an agent
The following example creates an agent that orchestrates on the Anthropic Claude v2 foundation model to help customers with IT problems. It contains one action group and one knowledge base.
YAML
AWSTemplateFormatVersion: 2010-09-09 Description: "CFN stack for creating an agent" Resources: ExampleAgentResource: Type: AWS::Bedrock::Agent Properties: AgentName: "Example Agent" AgentResourceRoleArn: "arn:aws:iam::123456789012:role/AmazonBedrockExecutionRoleForAgents_user" FoundationModel: "anthropic.claude-v2" Instruction: "You are an IT agent who solves customer's problems" Description: "Description is here" IdleSessionTTLInSeconds: 900 CustomerEncryptionKeyArn: "arn:aws:kms:us-west-2:123456789012:key/1234abcd-ab12-34cd-56ef-abcdefg123456" ActionGroups: - ActionGroupName: "IT Action" Description: "Testing latest IT Management action" ActionGroupExecutor: Lambda: "arn:aws:lambda:us-west-2:123456789012:function:ItAgentLambda" ApiSchema: S3: S3BucketName: "apischema-s3" S3ObjectKey: "ApiSchema.json" KnowledgeBases: - KnowledgeBaseId: "1234567890" Description: "IT Knowledge Base" KnowledgeBaseState: ENABLED
JSON
{ "AWSTemplateFormatVersion": "2010-09-09", "Description": "CFN stack for creating an agent", "Resources": { "ExampleAgentResource": { "Type": "AWS::Bedrock::Agent", "Properties": { "AgentName": "Example Agent", "AgentResourceRoleArn": "arn:aws:iam::123456789012:role/AmazonBedrockExecutionRoleForAgents_user", "FoundationModel": "anthropic.claude-v2", "Instruction": "You are an IT agent who solves customer's problems", "Description": "Description is here", "IdleSessionTTLInSeconds": 900, "CustomerEncryptionKeyArn": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-ab12-34cd-56ef-abcdefg123456", "ActionGroups": [ { "ActionGroupName": "IT Action", "Description": "Testing latest IT Management action", "ActionGroupExecutor": { "Lambda": "arn:aws:lambda:us-west-2:123456789012:function:ItAgentLambda" }, "ApiSchema": { "S3": { "S3BucketName": "apischema-s3", "S3ObjectKey": "ApiSchema.json" } } } ], "KnowledgeBases": [ { "KnowledgeBaseId": "1234567890", "Description": "IT Knowledge Base", "KnowledgeBaseState": "ENABLED" } ] } } } }