feat(bedrock-agentcore): add fromImageUri method to AgentRuntimeArtifact (#36263)

### Issue # (if applicable)

N/A

### Reason for this change

Users currently need ECR repository constructs (`fromEcrRepository`) or local Docker assets (`fromAsset`) to reference container images in AgentCore runtimes. This creates friction when:
- Container URIs come from CloudFormation parameters or stack outputs
- Referencing images in external registries (Docker Hub, private registries)
- Working with cross-stack or cross-account image references

### Description of changes

Added `fromImageUri()` static method to `AgentRuntimeArtifact` class:
- Created `ImageUriArtifact` class extending `AgentRuntimeArtifact`
- Accepts container URI as a string (supports CloudFormation tokens/expressions)
- No automatic IAM permissions granted (user manages permissions separately)
- Follows existing patterns from `EcrImage` and `AssetImage` classes

This provides a fourth deployment option alongside `fromEcrRepository()`, `fromAsset()`, and `fromS3()`.

### Description of how you validated changes

**Unit tests added:**
- Basic URI reference test
- CloudFormation token support test
- Verification that no permissions are required

**Manual testing:**
bash
cd packages/@aws-cdk/aws-bedrock-agentcore-alpha
yarn build
yarn test

All tests pass.

**Production usage:**
This change has been built locally and used successfully in my application to reference container images via CloudFormation parameters.

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

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

Author: kimsbrian

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

@@ -249,6 +249,41 @@ const runtimeInstance = new agentcore.Runtime(this, "MyAgentRuntime", {
 });
 ```
 
+#### Option 4: Use an ECR container image URI
+
+Reference an ECR container image directly by its URI. This is useful when you have a pre-existing ECR image URI from CloudFormation parameters or cross-stack references. No IAM permissions are automatically granted - you must ensure the runtime has ECR pull permissions.
+
+```typescript fixture=default
+// Direct URI reference
+const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromImageUri(
+  "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-agent:v1.0.0"
+);
+
+const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
+  runtimeName: "myAgent",
+  agentRuntimeArtifact: agentRuntimeArtifact,
+});
+```
+
+You can also use CloudFormation parameters or references:
+
+```typescript fixture=default
+// Using a CloudFormation parameter
+const imageUriParam = new cdk.CfnParameter(this, "ImageUri", {
+  type: "String",
+  description: "Container image URI for the agent runtime",
+});
+
+const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromImageUri(
+  imageUriParam.valueAsString
+);
+
+const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
+  runtimeName: "myAgent",
+  agentRuntimeArtifact: agentRuntimeArtifact,
+});
+```
+
 ### Granting Permissions to Invoke Bedrock Models or Inference Profiles
 
 To grant the runtime permissions to invoke Bedrock models or inference profiles:

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

@@ -74,6 +74,20 @@ export abstract class AgentRuntimeArtifact {
     return new S3Image(s3Location, runtime, entrypoint);
   }
 
+  /**
+   * Reference an image using an ECR container URI
+   *
+   * Use this when referencing ECR images from CloudFormation parameters or cross-stack references.
+   *
+   * **Note:** No IAM permissions are automatically granted. You must ensure the runtime has
+   * ECR pull permissions for the repository.
+   *
+   * @param containerUri The ECR container image URI (format: {account}.dkr.ecr.{region}.amazonaws.com/{repository}:{tag})
+   */
+  public static fromImageUri(containerUri: string): AgentRuntimeArtifact {
+    return new ImageUriArtifact(containerUri);
+  }
+
   /**
    * Called when the image is used by a Runtime to handle side effects like permissions
    */
@@ -188,3 +202,28 @@ class S3Image extends AgentRuntimeArtifact {
     } as any;
   }
 }
+
+class ImageUriArtifact extends AgentRuntimeArtifact {
+  constructor(private readonly containerUri: string) {
+    super();
+
+    // Validate ECR container URI format per CloudFormation requirements
+    const ecrPattern = /^\d{12}\.dkr\.ecr\.([a-z0-9-]+)\.amazonaws\.com\/((?:[a-z0-9]+(?:[._-][a-z0-9]+)*\/)*[a-z0-9]+(?:[._-][a-z0-9]+)*)([:@]\S+)$/;
+    if (!Token.isUnresolved(containerUri) && !ecrPattern.test(containerUri)) {
+      throw new ValidationError(
+        `Invalid ECR container URI format: ${containerUri}. Must be an ECR URI: {account}.dkr.ecr.{region}.amazonaws.com/{repository}:{tag}`,
+      );
+    }
+  }
+
+  public bind(_scope: Construct, _runtime: Runtime): void {
+    // No permissions are granted automatically when using a direct URI.
+    // Users must manage ECR pull permissions separately.
+  }
+
+  public _render(): CfnRuntime.AgentRuntimeArtifactProperty {
+    return {
+      containerUri: this.containerUri,
+    } as any;
+  }
+}

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

@@ -117,6 +117,61 @@ describe('AgentRuntimeArtifact tests', () => {
     expect(rendered1.containerUri).toBe(rendered2.containerUri);
   });
 
+  test('Should create artifact from image URI', () => {
+    const containerUri = '123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo:v1.0.0';
+    const artifact = AgentRuntimeArtifact.fromImageUri(containerUri);
+
+    const runtime = new Runtime(stack, 'test-runtime', {
+      runtimeName: 'test_runtime',
+      agentRuntimeArtifact: artifact,
+    });
+
+    artifact.bind(stack, runtime);
+    const rendered: any = artifact._render();
+
+    expect(rendered.containerUri).toBe(containerUri);
+  });
+
+  test('Should support CloudFormation tokens in image URI', () => {
+    const token = cdk.Fn.ref('ImageUriParameter');
+    const artifact = AgentRuntimeArtifact.fromImageUri(token);
+
+    const runtime = new Runtime(stack, 'test-runtime', {
+      runtimeName: 'test_runtime',
+      agentRuntimeArtifact: artifact,
+    });
+
+    artifact.bind(stack, runtime);
+    const rendered: any = artifact._render();
+
+    expect(rendered.containerUri).toBe(token);
+  });
+
+  test('Should not require permissions for image URI', () => {
+    const artifact = AgentRuntimeArtifact.fromImageUri('123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo:latest');
+
+    const runtime = new Runtime(stack, 'test-runtime', {
+      runtimeName: 'test_runtime',
+      agentRuntimeArtifact: artifact,
+    });
+
+    // Bind should not throw or require any permissions
+    expect(() => artifact.bind(stack, runtime)).not.toThrow();
+
+    const rendered: any = artifact._render();
+    expect(rendered.containerUri).toBe('123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo:latest');
+  });
+
+  test('Should reject non-ECR container URIs', () => {
+    expect(() => {
+      AgentRuntimeArtifact.fromImageUri('docker.io/myimage:latest');
+    }).toThrow(/Invalid ECR container URI format/);
+
+    expect(() => {
+      AgentRuntimeArtifact.fromImageUri('ghcr.io/owner/repo:tag');
+    }).toThrow(/Invalid ECR container URI format/);
+  });
+
   test('Should use static construct ID for asset image regardless of directory', () => {
     // Create two separate stacks to test that the construct ID is always 'AgentRuntimeArtifact'
     const stack1 = new cdk.Stack(app, 'test-stack-1', {