AgentCore CLI does not support specifying a custom IAM execution role for runtime deployment

[syedwasimwb]

Description

The AgentCore CLI (@aws/agentcore) does not provide any mechanism to specify a custom IAM execution role when deploying an agent runtime. The underlying bedrock-agentcore-control API supports --role-arn as a required parameter on create-agent-runtime, but the CLI abstracts this away and auto-creates a CDK-managed role during agentcore deploy. There is no CLI flag or agentcore.json configuration field to override this behavior.

Additionally, manually adding a roleArn field to the runtime spec in agentcore.json passes agentcore validate without error but is silently ignored during deploy — the CLI still creates and assigns its own role.

This is a gap for users who need to follow least-privilege IAM practices or use pre-existing roles that comply with their organization's security policies.

Steps to Reproduce

Steps to Reproduce:

Install the AgentCore CLI:
npm install -g @aws/agentcore
Create a custom IAM role with the AgentCore trust policy:
aws iam create-role
--role-name MyCustomAgentCoreRole
--assume-role-policy-document '{
"Version":"2012-10-17",
"Statement":[{
"Effect":"Allow",
"Principal":{"Service":"bedrock-agentcore.amazonaws.com"},
"Action":"sts:AssumeRole",
"Condition":{
"StringEquals":{"aws:SourceAccount":"ACCOUNT_ID"},
"ArnLike":{"aws:SourceArn":"arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:*"}
}
}]
}'
Attach the standard AgentCore execution permissions (CloudWatch Logs, X-Ray, Bedrock, ECR, CloudWatch Metrics) to the role.

Create a new AgentCore project:

agentcore create --name RoleTest --defaults
Add "roleArn": "arn:aws:iam::ACCOUNT_ID:role/MyCustomAgentCoreRole" to the runtime spec in
agentcore.json
.

Configure
aws-targets.json
with your account and region.

Validate:

agentcore validate
Output: Valid — no error or warning about the unknown field.

Deploy:
agentcore deploy -y --json
Output shows the CLI created its own role (e.g. AgentCore-RoleTest-defau-ApplicationAgentRoleTestR-xxxxx).

Verify:
aws bedrock-agentcore-control get-agent-runtime
--agent-runtime-id <RUNTIME_ID>
--query "roleArn" --output text
Output: arn:aws:iam::ACCOUNT_ID:role/AgentCore-RoleTest-defau-ApplicationAgentRoleTestR-xxxxx

Expected Behavior

Expected: The runtime should use arn:aws:iam::ACCOUNT_ID:role/MyCustomAgentCoreRole.

Actual Behavior

Actual: The CLI ignores the roleArn field and creates its own CDK-managed role.

CLI Version

No response

Operating System

Windows

Additional Context

No response

[jesseturner21]

please try this input in the agentcore.json under the runtime - "executionRoleArn": "arn:aws:iam::<AccountID>:role/CustomExecutionRole"

For example

...
 "runtimes": [
    {
      "name": "MyAgent",
      "build": "CodeZip",
      "entrypoint": "main.py",
      "codeLocation": "app/MyAgent/",
      "runtimeVersion": "PYTHON_3_13",
      "networkMode": "PUBLIC",
      "protocol": "HTTP",
      "executionRoleArn": "arn:aws:iam::<AccountID>:role/CustomExecutionRole"
    }
  ],
...

[syedwasimwb]

Thanks for the pointer! I tested executionRoleArn in agentcore.json and can confirm it works — both for initial deployment and for updating to a different role on subsequent deploys.

This field is not documented in the configuration.md (https://github.com/aws/agentcore-cli/blob/main/docs/configuration.md) runtime spec table. Could this be added to the docs so users can discover it? That's the root cause of the confusion here.