Create a service role for Agents for Amazon Bedrock

To use a custom service role for agents instead of the one Amazon Bedrock automatically creates, create an IAM role and attach the following permissions by following the steps at Creating a role to delegate permissions to an AWS service.

• Trust policy

• A policy containing the following identity-based permissions:

  • Access to the Amazon Bedrock base models.

  • Access to the Amazon S3 objects containing the OpenAPI schemas for the action groups in your agents.

  • Permissions for Amazon Bedrock to query knowledge bases that you want to attach to your agents.

  • If any of the following situations pertain to your use case, add the statement to the policy or add a policy with the statement to the service role:

    • (Optional) If you associate a Provisioned Throughput with your agent alias, permissions to perform model invocation using that Provisioned Throughput.

    • (Optional) If you associate a guardrail with your agent, permissions to apply that guardrail. If the guardrail is encrypted with a KMS key, the service role will also need permissions to decrypt the key

    • (Optional) If you encrypt your agent with a KMS key, permissions to decrypt the key.

Whether you use a custom role or not, you also need to attach a resource-based policy to the Lambda functions for the action groups in your agents to provide permissions for the service role to access the functions. For more information, see Resource-based policy to allow Amazon Bedrock to invoke an action group Lambda function.

Trust relationship

The following trust policy allows Amazon Bedrock to assume this role and create and manage agents. Replace the ${values} as necessary. The policy contains optional condition keys (see Condition keys for Amazon Bedrock and AWS global condition context keys) in the Condition field that we recommend you use as a security best practice.

Note

As a best practice for security purposes, replace the * with specific agent IDs after you have created them.

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {
            "Service": "bedrock.amazonaws.com"
        },
        "Action": "sts:AssumeRole",
        "Condition": {
            "StringEquals": {
                "aws:SourceAccount": "${account-id}"
            },
            "ArnLike": {
                "AWS:SourceArn": "arn:aws:bedrock:${region}:${account-id}:agent/*"
            }
        }
    }]
}

Identity-based permissions for the Agents service role

Attach the following policy to provide permissions for the service role, replacing ${values} as necessary. The policy contains the following statements. Omit a statement if it isn't applicable to your use-case. The policy contains optional condition keys (see Condition keys for Amazon Bedrock and AWS global condition context keys) in the Condition field that we recommend you use as a security best practice.

Note

If you encrypt your agent with a customer-managed KMS key, refer to Encryption of agent resources for further permissions you need to add.

• Permissions to use Amazon Bedrock foundation models to run model inference on prompts used in your agent's orchestration.

• Permissions to access your agent's action group API schemas in Amazon S3. Omit this statement if your agent has no action groups.

• Permissions to access knowledge bases associated with your agent. Omit this statement if your agent has no associated knowledge bases.

• Permissions to access a third-party (Pinecone or Redis Enterprise Cloud) knowledge base associated with your agent. Omit this statement if your knowledge base is first-party (Amazon OpenSearch Serverless or Amazon Aurora) or if your agent has no associated knowledge bases.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Allow model invocation for orchestration",
            "Effect": "Allow",
            "Action": [
                "bedrock:InvokeModel"
            ],
            "Resource": [
                "arn:aws:bedrock:${region}::foundation-model/anthropic.claude-v2",
                "arn:aws:bedrock:${region}::foundation-model/anthropic.claude-v2:1",
                "arn:aws:bedrock:${region}::foundation-model/anthropic.claude-instant-v1"
            ]
        },
        {
            "Sid": "Allow access to action group API schemas in S3",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::bucket/path/to/schema"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "${account-id}"
                }
            }
        },
        {
            "Sid": "Query associated knowledge bases",
            "Effect": "Allow",
            "Action": [
                "bedrock:Retrieve",
                "bedrock:RetrieveAndGenerate"
            ],
            "Resource": [
                "arn:aws:bedrock:${region}:${account-id}:knowledge-base/knowledge-base-id"
            ]
        },
        {
            "Sid": "Associate a third-party knowledge base with your agent",
            "Effect": "Allow",
            "Action": [
                "bedrock:AssociateThirdPartyKnowledgeBase",
            ],
            "Resource": "arn:aws:bedrock:${region}:${account-id}:knowledge-base/knowledge-base-id",
            "Condition": { 
                "StringEquals" : { 
                    "bedrock:ThirdPartyKnowledgeBaseCredentialsSecretArn": "arn:aws:kms:${region}:${account-id}:key/${key-id}"
                }
            }
        }
    ]
}

(Optional) Identity-based policy to allow Amazon Bedrock to use Provisioned Throughput with your agent alias

If you associate a Provisioned Throughput with an alias of your agent, attach the following identity-based policy to the service role or add the statement to the policy in Identity-based permissions for the Agents service role.

{
    "Version": "2012-10-17",
    "Statement": [
      {        
        "Sid": "Use a Provisioned Throughput in model invocation",
        "Effect": "Allow",
        "Action": [
            "bedrock:InvokeModel", 
            "bedrock:GetProvisionedModelThroughput"
        ],
        "Resource": [
            "arn:aws:bedrock:{${region}}:{${account-id}}:${provisioned-model-id}"
        ]
      }
    ]
}

(Optional) Identity-based policy to allow Amazon Bedrock to use guardrails with your Agent

If you associate a guardrail with your agent, attach the following identity-based policy to the service role or add the statement to the policy in Identity-based permissions for the Agents service role.

{
    "Version": "2012-10-17",
    "Statement": [
        {  
            "Sid": "Apply a guardrail to your agent",
            "Effect": "Allow",
            "Action": "bedrock:ApplyGuardrail",
            "Resource": [
                "arn:aws:bedrock:{${region}}:{${account-id}}:guardrail/${guardrail-id}"
            ]
        }
    ]
}

(Optional) Identity-based policy to allow Amazon Bedrock to access files from S3 to use with code interpretation

If you enable Enable code interpretation in Amazon Bedrock, attach the following identity-based policy to the service role or add the statement to the policy in Identity-based permissions for the Agents service role.

{
  "Version": "2012-10-17",
  "Statement": [
      {       
        "Sid": "AmazonBedrockAgentFileAccess", 
        "Effect": "Allow",
        "Action": [
            "s3:GetObject",
            "s3:GetObjectVersion",
            "s3:GetObjectVersionAttributes",
            "s3:GetObjectAttributes"
        ],
        "Resource": [
            "arn:aws:s3:::[[customerProvidedS3BucketWithKey]]"
        ]
      }
    ]
}
       

Resource-based policy to allow Amazon Bedrock to invoke an action group Lambda function

Follow the steps at Using resource-based policies for Lambda and attach the following resource-based policy to a Lambda function to allow Amazon Bedrock to access the Lambda function for your agent's action groups, replacing the ${values} as necessary. The policy contains optional condition keys (see Condition keys for Amazon Bedrock and AWS global condition context keys) in the Condition field that we recommend you use as a security best practice.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Allow Amazon Bedrock to access action group Lambda function",
            "Effect": "Allow",
            "Principal": {
                "Service": "bedrock.amazonaws.com"
            },
            "Action": "lambda:InvokeFunction",
            "Resource":  "arn:aws:lambda:${region}:${account-id}:function:function-name",
            "Condition": {
                "StringEquals": {
                    "AWS:SourceAccount": "${account-id}"
                },
                "ArnLike": {
                    "AWS:SourceArn": "arn:aws:bedrock:${region}:${account-id}:agent/${agent-id}"
                }
            }
        }
    ]
}