Amazon Bedrock AgentCore Setup Confusion: Which IAM Role Do I Need?

If you’re trying to deploy an agent into Amazon Bedrock AgentCore Runtime and you see a CLI flag like:

agentcore configure --entrypoint my_agent.py -er <YOUR_IAM_ROLE_ARN>

…it’s easy to get stuck.

Because is not your IAM user, and it’s not your SSO role. It’s a separate Execution Role that AgentCore Runtime assumes to run your agent.

Even after publishing my earlier article on building an agent with AgentCore, I noticed there’s still a common point of confusion for many people. So I decided to write this article and explain what role you need to create!

Once you create that role correctly, deployment becomes straightforward.

This guide is based on the official AWS documentation for AgentCore Runtime permissions: IAM Permissions for AgentCore Runtime

What you actually need (2 identities)

1) Your “caller identity”
This is the identity you use to run the CLI:

• IAM User, or
• SSO Role (IAM Identity Center)

This identity needs permission to deploy/configure and often PassRole.

2) The “AgentCore Runtime execution role” (the important one)
This is the role AgentCore uses at runtime to:

• pull images from ECR (if applicable),
• write logs to CloudWatch,
• send traces to X-Ray,
• publish metrics,
• call Bedrock models,
• get workload access tokens.

This is the ARN you pass via -er.

Step-by-step: Create the AgentCore Runtime Execution Role in AWS Console

Step 1 — Create the Role

1. Go to AWS Console → IAM
2. Click Roles → Create role
3. Choose Custom trust policy
4. Paste this trust policy (replace region/account, 123456789012 and us-east-1):

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Sid": "AssumeRolePolicy",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}

1. Name the role something clear, for example:

• AgentCoreRuntimeExecutionRole- Create the role.

Step 2 — Attach the correct permissions policy

This is where most people get confused.

You want the policy titled “AgentCore Runtime execution role” (NOT the “direct deploy execution role”, and NOT the “starter toolkit” caller policy).

1. Open the role you just created
2. Go to Permissions tab
3. Click Add permissions → Create inline policy
4. Choose JSON
5. Paste the following policy JSON :

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ECRImageAccess",
            "Effect": "Allow",
            "Action": [
                "ecr:BatchGetImage",
                "ecr:GetDownloadUrlForLayer"
            ],
            "Resource": [
                "arn:aws:ecr:us-east-1:123456789012:repository/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:DescribeLogStreams",
                "logs:CreateLogGroup"
            ],
            "Resource": [
                "arn:aws:logs:us-east-1:123456789012:log-group:/aws/bedrock-agentcore/runtimes/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:DescribeLogGroups"
            ],
            "Resource": [
                "arn:aws:logs:us-east-1:123456789012:log-group:*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": [
                "arn:aws:logs:us-east-1:123456789012:log-group:/aws/bedrock-agentcore/runtimes/*:log-stream:*"
            ]
        },
        {
            "Sid": "ECRTokenAccess",
            "Effect": "Allow",
            "Action": [
                "ecr:GetAuthorizationToken"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "xray:PutTraceSegments",
                "xray:PutTelemetryRecords",
                "xray:GetSamplingRules",
                "xray:GetSamplingTargets"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Effect": "Allow",
            "Resource": "*",
            "Action": "cloudwatch:PutMetricData",
            "Condition": {
                "StringEquals": {
                    "cloudwatch:namespace": "bedrock-agentcore"
                }
            }
        },
        {
            "Sid": "GetAgentAccessToken",
            "Effect": "Allow",
            "Action": [
                "bedrock-agentcore:GetWorkloadAccessToken",
                "bedrock-agentcore:GetWorkloadAccessTokenForJWT",
                "bedrock-agentcore:GetWorkloadAccessTokenForUserId"
            ],
            "Resource": [
                "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
                "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/agentName-*"
            ]
        },
        {
            "Sid": "BedrockModelInvocation",
            "Effect": "Allow",
            "Action": [
                "bedrock:InvokeModel",
                "bedrock:InvokeModelWithResponseStream"
            ],
            "Resource": [
                "arn:aws:bedrock:*::foundation-model/*",
                "arn:aws:bedrock:us-east-1:123456789012:*"
            ]
        }
    ]
}

1. (replace region/account, 123456789012 and us-east-1).
2. Click on Next and save policy name.

Step 3 — Copy the Role ARN (this is what -er needs)
In IAM → Roles → open your role → copy ARN.

Deploy using the role ARN in your CLI

agentcore configure --entrypoint my_agent.py -er YOUR-ROLE_ARN

Please note that my_agent.py has to be replaced by your entry file where you define your agentCore setup

Summary
The key unlock is understanding:

✅ -er expects the AgentCore Runtime execution role ARN
❌ It is NOT your user/SSO identity ARN

Once that role exists (trust + runtime policy), deployment works.