feat(agentcore): add agentcore runtime L2 construct #35623

dineshSajwan · 2025-09-29T22:32:48Z

Issue # (if applicable)

Related to aws/aws-cdk-rfcs#785

Reason for this change

Adding bedrock agent core runtime and runtime endpoint

Description of changes

Added a new L2 construct for runtime in aws -bedrock-agentcore-alpha package.
Added a new L2 construct for runtime endpoint
Added test cases
Added documentation

Describe any new or updated permissions being added

The runtime creates a role with permission to ecr repo, cloudwatch , xray .

Description of how you validated changes

Unit tests, integration tests, manual tests

Checklist

[Yes] My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

aws-cdk-automation

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/perms.ts

alvazjor · 2025-10-02T12:36:30Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-artifact.ts

+/**
+ * Agent runtime artifact configuration for Bedrock Agent Core Runtime
+ */
+export interface AgentRuntimeArtifactConfig {


Are we expecting this configuration to have more elements in the future? Do you know if there are plans for that? Seems like having this interface at the moment is not adding too much value, you could potentially return the URI directly in the bind method rather than this object (in CDK, we tend to favor flat composition over nested composition if we can)

This mirrors the cloudformation structure of agentruntimeartifact . IMHO, we should keep it as cloud formation structure because if the underlying service add any new field in this object then the flat structure of containeruri may cause breaking changes for the L2 construct.

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/types.ts

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

alvazjor · 2025-10-02T13:52:48Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

+   * @param clientId Cognito App Client ID
+   * @param region Optional AWS region (defaults to stack region)
+   */
+  public configureCognitoAuth(


This and the other methods below are exactly what I was expecting to see instead of https://github.com/aws/aws-cdk/pull/35623/files#r2398909386.
Simple and specific for each type of auth configuration. I would prefer to keep only this idea and drop the possibility for the user to set up manually the auth config with all the possible wrong combinations they could make if we let it fully configurable.

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint-base.ts

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint.ts

Pull request has been modified.

alvazjor · 2025-10-08T13:49:25Z

...s/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-authorizer-configuration.ts

+   *
+   * @returns RuntimeAuthorizerConfiguration for IAM authentication
+   */
+  public static configureIAM(): RuntimeAuthorizerConfiguration {


Rename to: usingIAM

alvazjor · 2025-10-08T13:55:02Z

...s/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-authorizer-configuration.ts

+   * @param allowedAudience Optional array of allowed audiences
+   * @returns RuntimeAuthorizerConfiguration for JWT authentication
+   */
+  public static configureJWT(


Rename to usingJWT

alvazjor · 2025-10-08T13:55:20Z

...s/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-authorizer-configuration.ts

+   * @param region Optional AWS region where the User Pool is located (defaults to stack region)
+   * @returns RuntimeAuthorizerConfiguration for Cognito authentication
+   */
+  public static configureCognito(


Rename to usingCognito

alvazjor · 2025-10-08T13:55:49Z

...s/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-authorizer-configuration.ts

+   * @param scopes Optional array of OAuth scopes
+   * @returns RuntimeAuthorizerConfiguration for OAuth authentication
+   */
+  public static configureOAuth(


Rename to usingOAuth

alvazjor · 2025-10-08T13:56:55Z

...s/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-authorizer-configuration.ts

+    provider: string,
+    discoveryUrl: string,
+    clientId: string,
+    scopes?: string[],


provider and scopes parameters are ignored in the constructor if the OAuthAuthorizerConfiguration class. Why do we need them here then?

Apparently OAuthAuthorizerConfiguration and JwtAuthorizerConfiguration are behaving same way under the hood . In my view usingOAuth provides a better user experience (having a dedicated usingOAuth method makes it clear that developers are configuring OAuth providers like GitHub or Google, even though the underlying AWS service treats it the same as JWT authentication). I kept provider and scopes for potential future enhancements where we might add OAuth-specific features or some metadata for observability.
I'm happy to remove these unused parameters to keep the code cleaner. Would you prefer I remove them, or keep them documented as reserved for future use?

Lets remove them for now, since they are not used. If we add features that need then, we can introduce them later. In the future, if more specific configuration is required for each OAuth providers, we can introduce special methods, like usingGoogleOAuth or something like that, and in there we request the additional data. From a user perspective, if the name of the method already gives you the provider, is very clear what is the intention behind it, and with the current approach we can manage to introduce this later when needed

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint.ts

alvazjor · 2025-10-08T16:12:11Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint.ts

+        value: this.description,
+        fieldName: 'Description',
+        minLength: 1,
+        maxLength: 1200,


In CFN doc, the max length is 256

Ahh they changed it. Will update thanks.

alvazjor · 2025-10-08T16:34:14Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

+    const account = Stack.of(this).account;
+
+    // ECR Image Access - scoped to account repositories
+    role.addToPolicy(new iam.PolicyStatement({


This policy is needed if the runtime artifact is fromEcrRepository right? Could we check if the agentRuntimeArtifact is of type EcrImage to add this policy? And maybe even restrict the resource to that specific one?

I was following these permission as per this . However , I realized that ECR permissions are redundant for L2 construct because these are already handled with AgentRuntimeArtifact bind function with grantPull. The ecr grantPull take care of permissions in best possible way. We need these permission during bind so that it can pull the image from ecr repository before deploying it on runtime. I have removed these permission from createExecutionRole and have tested the changes.

alvazjor · 2025-10-08T16:35:30Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

+    }));
+
+    // ECR Token Access - must be * for authorization token
+    role.addToPolicy(new iam.PolicyStatement({


Same as the previous policy, if only needed when artifact is fromEcrRepository, we should try and restrict the creation only in that case

same as above , removed the permission as they were redundant and using ecr grantPull to grant the permission.

…ws-cdk into agentcore-runtime

alvazjor · 2025-10-13T10:57:57Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint.ts

+      public readonly endpointName = attrs.endpointName;
+      public readonly agentRuntimeArn = attrs.agentRuntimeArn;
+      public readonly description = attrs.description;
+      public readonly status: string | undefined = undefined;


Lets just mark this (and the ones below) as undefined without the string | undefined. The types were already defined in the Base class, no need to add them here again

alvazjor · 2025-10-13T11:04:40Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-base.ts

+  readonly agentRuntimeName: string;
+
+  /**
+   * The IAM role ARN that provides permissions for the agent runtime


Not an ARN but an actual role here

Typo. Fixed.

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-base.ts

alvazjor · 2025-10-13T11:45:05Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-base.ts

+  /**
+   * The IAM role ARN
+   */
+  readonly role: iam.IRole;


This, as the JSDoc states, should be a ARN, not the role object itself. And with the ARN, when creating the object in the from..Attributes we construct the actual role using the Role.fromRoleArn() method

alvazjor · 2025-10-13T11:46:34Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

+
+    // Skipping  ECR Image Access (RUNTIME_ECR_IMAGE_ACTIONS)
+    // and ECR Token Access (RUNTIME_ECR_TOKEN_ACTIONS) permission
+    // because these are set by runtime-artifact (grantPull) with the bind function


Lets remove this comments

Pull request has been modified.

…ws-cdk into agentcore-runtime

aws-cdk-automation · 2025-10-19T00:13:50Z

This PR cannot be merged because it has conflicts. Please resolve them. The PR will be considered stale and closed if it remains in an unmergeable state.

aws-cdk-automation · 2025-10-20T00:13:39Z

This PR cannot be merged because it has conflicts. Please resolve them. The PR will be considered stale and closed if it remains in an unmergeable state.

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-base.ts

alvazjor · 2025-10-21T17:19:27Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/README.md

+| `runtimeName` | `string` | Yes | The name of the agent runtime. Valid characters are a-z, A-Z, 0-9, _ (underscore). Must start with a letter and can be up to 48 characters long |
+| `agentRuntimeArtifact` | `AgentRuntimeArtifact` | Yes | The artifact configuration for the agent runtime containing the container configuration with ECR URI |
+| `executionRole` | `iam.IRole` | No | The IAM role that provides permissions for the agent runtime. If not provided, a role will be created automatically |
+| `networkConfiguration` | `NetworkConfiguration` | No | Network configuration for the agent runtime. Defaults to `{ networkMode: NetworkMode.PUBLIC }` |


Lets update this to the new default value RuntimeNetworkConfiguration.usingPublicNetwork()

packages/@aws-cdk/aws-bedrock-agentcore-alpha/README.md

Pull request has been modified.

mergify · 2025-10-21T18:14:37Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

github-actions · 2025-10-21T18:15:10Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

dinsajwa added 4 commits September 29, 2025 11:57

feat(agentcore): added runtime and endpoint

9605217

feat(runtime): added integ test

356c42d

feat(runtime): added integ test

b124520

feat(runtime): updated integ test and readme

cfad025

github-actions bot added p2 repeat-contributor [Pilot] contributed between 3-5 PRs to the CDK labels Sep 29, 2025

aws-cdk-automation requested a review from a team September 29, 2025 22:32

aws-cdk-automation previously requested changes Sep 29, 2025

View reviewed changes

dineshSajwan changed the title ~~feat(agentcore): add agentcore runtime L2 constructs~~ feat(agentcore): add agentcore runtime L2 construct Sep 29, 2025

dineshSajwan and others added 2 commits September 29, 2025 18:43

Merge branch 'aws:main' into agentcore-runtime

a4cd8b7

feat(runtime): adding integ snapshot and documentation

910cf05

alvazjor self-assigned this Sep 30, 2025

dineshSajwan and others added 5 commits September 30, 2025 11:09

Merge branch 'aws:main' into agentcore-runtime

7a306af

feat(runtime): updated doc to fix rosetta build issue

778e5b0

Merge branch 'aws:main' into agentcore-runtime

bae6962

feat(runtime): updated docs for auth and fix issue in runtime

e301efd

feat(runtime): updated docs for auth and fix issue in runtime

150b222

alvazjor previously requested changes Oct 2, 2025

View reviewed changes

feat(runtime): review comments implemented

ea39263

dineshSajwan and others added 3 commits October 6, 2025 13:02

Merge branch 'aws:main' into agentcore-runtime

a4a2ccf

feat(runtime): updated docs

0062054

Merge branch 'main' into agentcore-runtime

d20e5a3

dineshSajwan marked this pull request as ready for review October 6, 2025 19:40

feat(runtime): removed unwanted method

4b87383

dineshSajwan had a problem deploying to deployment-integ-test October 7, 2025 13:54 — with GitHub Actions Error

Merge branch 'main' into agentcore-runtime

8b227b8

dineshSajwan had a problem deploying to deployment-integ-test October 7, 2025 13:55 — with GitHub Actions Error

alvazjor previously requested changes Oct 8, 2025

View reviewed changes

Merge branch 'agentcore-runtime' of https://github.com/dineshSajwan/a…

7a69a05

…ws-cdk into agentcore-runtime

alvazjor previously requested changes Oct 13, 2025

View reviewed changes

feat(agenctcore): runtime review comment and new policy

3ac39ab

dineshSajwan and others added 8 commits October 14, 2025 13:12

Merge branch 'aws:main' into agentcore-runtime

59548d1

Merge branch 'main' into agentcore-runtime

400f950

feat(agenctcore): updated docs

78e18c1

Merge branch 'agentcore-runtime' of https://github.com/dineshSajwan/a…

4ed2f90

…ws-cdk into agentcore-runtime

feat(runtime): new snapshots

aeabbb7

feat(runtime): updated runtime versioning

ee3a551

Merge branch 'aws:main' into agentcore-runtime

d0f8593

Merge branch 'agentcore-runtime' of https://github.com/dineshSajwan/a…

a1d0028

…ws-cdk into agentcore-runtime

Merge branch 'main' into agentcore-runtime

2be5f7d

krokoko mentioned this pull request Oct 20, 2025

Add AWS CDK implementation for basic-runtime sample awslabs/amazon-bedrock-agentcore-samples#507

Merged

9 tasks

dineshSajwan and others added 2 commits October 21, 2025 08:56

Merge branch 'main' into agentcore-runtime

70ef4a2

feat(agentcore): merged runtime with tools from main

0e7eb15

alvazjor previously requested changes Oct 21, 2025

View reviewed changes

dinsajwa and others added 2 commits October 21, 2025 13:43

feat(agentcore): updated runbtime docs

94d09ac

Merge branch 'main' into agentcore-runtime

520f45b

feat(agentcore): merge with main

feb1c44

alvazjor approved these changes Oct 21, 2025

View reviewed changes

mergify bot added the queued label Oct 21, 2025

mergify bot merged commit c57484a into aws:main Oct 21, 2025
22 of 23 checks passed

mergify bot removed the queued label Oct 21, 2025

github-actions bot locked as resolved and limited conversation to collaborators Oct 21, 2025

feat(agentcore): add agentcore runtime L2 construct #35623

feat(agentcore): add agentcore runtime L2 construct #35623

Uh oh!

Conversation

dineshSajwan commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue # (if applicable)

Reason for this change

Description of changes

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

aws-cdk-automation left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dineshSajwan Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dineshSajwan Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alvazjor Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

dineshSajwan commented Sep 29, 2025 •

edited

Loading

aws-cdk-automation left a comment •

edited

Loading

dineshSajwan Oct 3, 2025 •

edited

Loading

dineshSajwan Oct 8, 2025 •

edited

Loading

alvazjor Oct 9, 2025 •

edited

Loading