@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.71

package/src/py/agent/__snapshots__/{generator.spec.ts.snap → generator.protocols.spec.ts.snap}

@@ -1,165 +1,5 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`py#agent generator > should match snapshot for BedrockAgentCoreRuntime generated constructs files > agent-Dockerfile 1`] = `
-"FROM public.ecr.aws/docker/library/python:3.14-slim
-
-WORKDIR /app
-
-# Copy bundled package
-COPY . /app
-
-EXPOSE 8080
-
-ENV PYTHONPATH=/app
-ENV PATH="/app/bin:\${PATH}"
-
-# Auto-instrument with AWS Distro for OpenTelemetry
-# https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr
-CMD ["python", "bin/opentelemetry-instrument", "python", "-m", "proj_test_project.snapshot_bedrock_agent.main"]
-"
-`;
-
-exports[`py#agent generator > should match snapshot for BedrockAgentCoreRuntime generated constructs files > agent-construct.ts 1`] = `
-"import { Lazy, Names } from 'aws-cdk-lib';
-import { Platform } from 'aws-cdk-lib/aws-ecr-assets';
-import { Connections, IConnectable } from 'aws-cdk-lib/aws-ec2';
-import { Construct } from 'constructs';
-import * as path from 'path';
-import * as url from 'url';
-import {
-  AgentRuntimeArtifact,
-  ProtocolType,
-  Runtime,
-  RuntimeProps,
-} from 'aws-cdk-lib/aws-bedrockagentcore';
-import {
-  PolicyStatement,
-  IGrantable,
-  IPrincipal,
-  Grant,
-} from 'aws-cdk-lib/aws-iam';
-import { RuntimeConfig } from '../../../core/runtime-config.js';
-import { findWorkspaceRoot } from '../../../core/workspace.js';
-
-export type SnapshotBedrockAgentProps = Omit<
-  RuntimeProps,
-  | 'runtimeName'
-  | 'protocolConfiguration'
-  | 'agentRuntimeArtifact'
-  | 'authorizerConfiguration'
->;
-
-export class SnapshotBedrockAgent
-  extends Construct
-  implements IGrantable, IConnectable
-{
-  public readonly dockerImage: AgentRuntimeArtifact;
-  public readonly agentCoreRuntime: Runtime;
-
-  constructor(scope: Construct, id: string, props?: SnapshotBedrockAgentProps) {
-    super(scope, id);
-
-    const rc = RuntimeConfig.ensure(this);
-
-    // Resolve the bundle output directory containing the Dockerfile and built artifacts
-    const bundleDir = path.join(
-      findWorkspaceRoot(url.fileURLToPath(new URL(import.meta.url))),
-      'dist/apps/test-project/docker/snapshot-bedrock-agent',
-    );
-
-    this.dockerImage = AgentRuntimeArtifact.fromAsset(bundleDir, {
-      platform: Platform.LINUX_ARM64,
-    });
-
-    this.agentCoreRuntime = new Runtime(this, 'SnapshotBedrockAgent', {
-      runtimeName: Lazy.string({
-        produce: () =>
-          Names.uniqueResourceName(this.agentCoreRuntime, { maxLength: 40 }),
-      }),
-      protocolConfiguration: ProtocolType.HTTP,
-      agentRuntimeArtifact: this.dockerImage,
-      ...props,
-      environmentVariables: {
-        RUNTIME_CONFIG_APP_ID: rc.appConfigApplicationId,
-        ...props?.environmentVariables,
-      },
-    });
-
-    // Grant access for the agent to invoke bedrock models
-    this.agentCoreRuntime.addToRolePolicy(
-      new PolicyStatement({
-        actions: [
-          'bedrock:InvokeModel',
-          'bedrock:InvokeModelWithResponseStream',
-        ],
-        resources: [
-          'arn:aws:bedrock:*:*:foundation-model/*',
-          'arn:aws:bedrock:*:*:inference-profile/*',
-        ],
-      }),
-    );
-
-    rc.grantReadAppConfig(this.agentCoreRuntime);
-
-    rc.set('agentcore', 'agentRuntimes', {
-      ...rc.get('agentcore').agentRuntimes,
-      SnapshotBedrockAgent: this.agentCoreRuntime.agentRuntimeArn,
-    });
-  }
-
-  /**
-   * The principal to grant permissions to.
-   */
-  public get grantPrincipal(): IPrincipal {
-    return this.agentCoreRuntime.grantPrincipal;
-  }
-
-  /**
-   * Network connections for this agent runtime.
-   */
-  public get connections(): Connections {
-    return this.agentCoreRuntime.connections;
-  }
-
-  /**
-   * Grants IAM permissions to invoke this agent runtime.
-   *
-   * @param grantee - The IAM principal to grant permissions to
-   */
-  public grantInvokeAccess(grantee: IGrantable) {
-    this.agentCoreRuntime.grantInvoke(grantee);
-
-    Grant.addToPrincipal({
-      grantee,
-      actions: ['bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream'],
-      resourceArns: [
-        this.agentCoreRuntime.agentRuntimeArn,
-        \`\${this.agentCoreRuntime.agentRuntimeArn}/*\`,
-      ],
-    });
-  }
-}
-"
-`;
-
-exports[`py#agent generator > should match snapshot for BedrockAgentCoreRuntime generated constructs files > agents-index.ts 1`] = `
-"export * from './snapshot-bedrock-agent/snapshot-bedrock-agent.js';
-"
-`;
-
-exports[`py#agent generator > should match snapshot for BedrockAgentCoreRuntime generated constructs files > app-index.ts 1`] = `
-"export * from './agents/index.js';
-"
-`;
-
-exports[`py#agent generator > should match snapshot for BedrockAgentCoreRuntime generated constructs files > core-index.ts 1`] = `
-"export * from './app.js';
-export * from './checkov.js';
-export * from './runtime-config.js';
-export * from './workspace.js';
-"
-`;
-
 exports[`py#agent generator > should match snapshot for Terraform generated files > terraform-agent.tf 1`] = `
 "variable "env" {
   description = "Environment variables to pass to the agent core runtime"
@@ -183,6 +23,25 @@ variable "tags" {
   default     = {}
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Run the agent core runtime inside a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to run the agent core runtime in. Required when enable_vpc is true."
+  type        = string
+  default     = null
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to run the agent core runtime in. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 variable "appconfig_application_id" {
   description = "ID of the shared runtime-config AppConfig application (from \`core/runtime-config/appconfig.application_id\`). The agent reads its runtime configuration from this application."
   type        = string
@@ -198,6 +57,9 @@ module "agent_core_runtime" {
   agent_runtime_name = "TerraformSnapshotAgent"
   docker_image_tag = "proj-terraform-snapshot-agent:latest"
   server_protocol = "HTTP"
+  enable_vpc = var.enable_vpc
+  vpc_id = var.vpc_id
+  subnet_ids = var.subnet_ids
 
   env = merge({
     RUNTIME_CONFIG_APP_ID = var.appconfig_application_id
@@ -233,7 +95,7 @@ module "add_agent_runtime_to_runtime_config" {
 
   namespace = "agentcore"
   key       = "agentRuntimes"
-  value     = { "TerraformSnapshotAgent" = module.agent_core_runtime.agent_core_runtime_arn }
+  value     = { "TerraformSnapshotAgent" = { arn = module.agent_core_runtime.agent_core_runtime_arn } }
 
   depends_on = [module.agent_core_runtime]
 }
@@ -248,10 +110,20 @@ output "agent_core_runtime_arn" {
   value       = module.agent_core_runtime.agent_core_runtime_arn
 }
 
+output "invocation_url" {
+  description = "HTTPS invocation URL of the runtime"
+  value       = module.agent_core_runtime.invocation_url
+}
+
 output "appconfig_application_id" {
   description = "AppConfig Application ID for runtime config (passthrough of the shared \`appconfig_application_id\` input)."
   value       = var.appconfig_application_id
 }
+
+output "security_group_id" {
+  description = "Security group ID of the agent core runtime, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = module.agent_core_runtime.security_group_id
+}
 "
 `;
 
@@ -262,15 +134,15 @@ exports[`py#agent generator > should match snapshot for Terraform generated file
   required_providers {
     aws = {
       source  = "hashicorp/aws"
-      version = ">= 6.23"
+      version = "6.60.0"
     }
     null = {
       source  = "hashicorp/null"
-      version = ">= 3.0"
+      version = "3.3.0"
     }
     random = {
       source  = "hashicorp/random"
-      version = ">= 3.0"
+      version = "3.9.0"
     }
   }
 }
@@ -328,6 +200,30 @@ variable "additional_iam_policy_statements" {
   default = []
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Run the agent core runtime inside a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to run the agent core runtime in. Required when enable_vpc is true."
+  type        = string
+  default     = null
+
+  validation {
+    condition     = !var.enable_vpc || (var.vpc_id != null && var.subnet_ids != null)
+    error_message = "vpc_id and subnet_ids must be set when enable_vpc is true."
+  }
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to run the agent core runtime in. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 variable "tags" {
   description = "Tags to apply to resources"
   type        = map(string)
@@ -353,8 +249,7 @@ resource "aws_ecr_repository" "agent_core_repository" {
   #checkov:skip=CKV_AWS_136:AES256 encryption is sufficient for ECR repositories
   name = "\${lower(var.agent_runtime_name)}_repository_\${random_id.unique_suffix.hex}"
 
-  #checkov:skip=CKV_AWS_51:Image tag is reused for latest deployments
-  image_tag_mutability = "MUTABLE"
+  image_tag_mutability = "IMMUTABLE"
   force_delete         = true
 
   image_scanning_configuration {
@@ -528,30 +423,64 @@ data "external" "docker_digest" {
   program = ["sh", "-c", "echo '{\\"digest\\":\\"'$(docker inspect \${var.docker_image_tag} --format '{{.Id}}')'\\"}' "]
 }
 
+locals {
+  # Content-based, immutable image tag derived from the local image digest
+  image_tag = replace(data.external.docker_digest.result.digest, "sha256:", "")
+}
+
 # Null resource for container image publish
 resource "null_resource" "docker_publish" {
   triggers = {
     docker_digest    = data.external.docker_digest.result.digest
     repository_url   = aws_ecr_repository.agent_core_repository.repository_url
     docker_image_tag = var.docker_image_tag
+    image_tag        = local.image_tag
   }
 
   provisioner "local-exec" {
     command = <<-EOT
       # Get ECR login token
-      aws ecr get-login-password --region \${local.aws_region} | docker login --username AWS --password-stdin \${self.triggers.repository_url}
+      aws ecr get-login-password --region "$AWS_REGION" | docker login --username AWS --password-stdin "$REPOSITORY_URL"
 
-      # Tag the image
-      docker tag \${self.triggers.docker_image_tag} \${self.triggers.repository_url}:latest
+      # Tag the image with the immutable content-based tag
+      docker tag "$DOCKER_IMAGE_TAG" "$REPOSITORY_URL:$IMAGE_TAG"
 
       # Push the image
-      docker push \${self.triggers.repository_url}:latest
+      docker push "$REPOSITORY_URL:$IMAGE_TAG"
     EOT
+    environment = {
+      AWS_REGION       = local.aws_region
+      REPOSITORY_URL   = self.triggers.repository_url
+      DOCKER_IMAGE_TAG = self.triggers.docker_image_tag
+      IMAGE_TAG        = self.triggers.image_tag
+    }
   }
 
   depends_on = [aws_ecr_repository_policy.agent_core_ecr_policy]
 }
 
+# Security group for the agent core runtime, used when running inside a VPC
+resource "aws_security_group" "agent_core_runtime" {
+  count = var.enable_vpc ? 1 : 0
+
+  #checkov:skip=CKV2_AWS_5:Attached to the runtime via network_configuration; Checkov cannot resolve this reference
+  name_prefix = "\${var.agent_runtime_name}-runtime-"
+  description = "Security group for the \${var.agent_runtime_name} agent core runtime"
+  vpc_id      = var.vpc_id
+  tags        = var.tags
+}
+
+resource "aws_vpc_security_group_egress_rule" "agent_core_runtime_https" {
+  count = var.enable_vpc ? 1 : 0
+
+  security_group_id = aws_security_group.agent_core_runtime[0].id
+  cidr_ipv4         = "0.0.0.0/0"
+  from_port         = 443
+  to_port           = 443
+  ip_protocol       = "tcp"
+  description       = "Allow outbound HTTPS to AWS service endpoints"
+}
+
 # Bedrock AgentCore Agent Runtime
 resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
   agent_runtime_name = "\${var.agent_runtime_name}_\${random_id.unique_suffix.hex}"
@@ -560,7 +489,7 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
 
   agent_runtime_artifact {
     container_configuration {
-      container_uri = "\${aws_ecr_repository.agent_core_repository.repository_url}:latest"
+      container_uri = "\${aws_ecr_repository.agent_core_repository.repository_url}:\${local.image_tag}"
     }
   }
 
@@ -577,8 +506,24 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
     }
   }
 
+  # Receive the caller's Authorization header (validated by the JWT authorizer).
+  dynamic "request_header_configuration" {
+    for_each = var.authorizer_configuration != null && try(var.authorizer_configuration.custom_jwt_authorizer, null) != null ? [1] : []
+    content {
+      request_header_allowlist = ["Authorization"]
+    }
+  }
+
   network_configuration {
-    network_mode = "PUBLIC"
+    network_mode = var.enable_vpc ? "VPC" : "PUBLIC"
+
+    dynamic "network_mode_config" {
+      for_each = var.enable_vpc ? [1] : []
+      content {
+        security_groups = [aws_security_group.agent_core_runtime[0].id]
+        subnets         = var.subnet_ids
+      }
+    }
   }
 
   protocol_configuration {
@@ -593,7 +538,70 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
   ]
 }
 
+# MCP consumers (e.g. gateway targets, which fetch tools at creation) can race
+# the runtime's first cold start, so probe it until it serves MCP. The ARN
+# output is routed through this resource so consumers wait for readiness.
+resource "null_resource" "runtime_ready" {
+  count = var.server_protocol == "MCP" ? 1 : 0
+
+  triggers = {
+    runtime_arn = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+  }
+
+  provisioner "local-exec" {
+    command = <<-EOT
+      uv run --with boto3==1.43.67 python -c "
+import boto3
+import json
+import os
+import time
+import uuid
+
+runtime_arn = os.environ['RUNTIME_ARN']
+client = boto3.client('bedrock-agentcore')
+initialize_request = json.dumps({
+    'jsonrpc': '2.0',
+    'id': 1,
+    'method': 'initialize',
+    'params': {
+        'protocolVersion': '2025-03-26',
+        'capabilities': {},
+        'clientInfo': {'name': 'readiness-probe', 'version': '1.0'},
+    },
+})
+
+deadline = time.time() + 5 * 60
+while True:
+    try:
+        client.invoke_agent_runtime(
+            agentRuntimeArn=runtime_arn,
+            runtimeSessionId=f'readiness-probe-{uuid.uuid4()}',
+            contentType='application/json',
+            accept='application/json, text/event-stream',
+            payload=initialize_request,
+        )
+        break
+    except Exception:
+        if time.time() >= deadline:
+            raise
+        time.sleep(5)
+
+print(f'Runtime {runtime_arn} is serving MCP')
+"
+    EOT
+    environment = {
+      RUNTIME_ARN = self.triggers.runtime_arn
+    }
+  }
+}
+
 # Outputs
+locals {
+  # For MCP runtimes the ARN flows through the readiness probe, so consumers
+  # wait until the runtime serves MCP.
+  ready_runtime_arn = var.server_protocol == "MCP" ? null_resource.runtime_ready[0].triggers.runtime_arn : aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+}
+
 output "agent_core_runtime_role_arn" {
   description = "ARN of the Agent Core Runtime IAM role"
   value       = aws_iam_role.agent_core_runtime_role.arn
@@ -610,8 +618,13 @@ output "agent_runtime_name" {
 }
 
 output "agent_core_runtime_arn" {
-  description = "ARN of the Bedrock Agent Core runtime"
-  value       = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+  description = "ARN of the Bedrock Agent Core runtime. For MCP runtimes the value flows through the readiness probe, so consumers wait until the runtime serves MCP."
+  value       = local.ready_runtime_arn
+}
+
+output "invocation_url" {
+  description = "HTTPS invocation URL of the runtime. MCP runtimes get the MCP endpoint (e.g. for use as a Gateway target endpoint), A2A runtimes the A2A endpoint (trailing slash required). For MCP runtimes the value flows through the readiness probe, so consumers wait until the runtime serves MCP."
+  value       = "https://bedrock-agentcore.\${local.aws_region}.amazonaws.com/runtimes/\${urlencode(local.ready_runtime_arn)}/invocations\${var.server_protocol == "A2A" ? "/" : "?qualifier=DEFAULT"}"
 }
 
 output "agent_runtime_id" {
@@ -623,147 +636,10 @@ output "agent_runtime_version" {
   description = "Version of the Bedrock Agent Core runtime"
   value       = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_version
 }
-"
-`;
-
-exports[`py#agent generator > should match snapshot for generated files > agent-__init__.py 1`] = `""`;
-
-exports[`py#agent generator > should match snapshot for generated files > agent-agent.py 1`] = `
-"from contextlib import contextmanager
-
-from strands import Agent, tool
-from strands_tools import current_time
 
-
-@tool
-def subtract(a: int, b: int) -> int:
-    return a - b
-
-
-@contextmanager
-def get_agent():
-    yield Agent(
-        name="SnapshotAgent",
-        description="SnapshotAgent Strands Agent",
-        system_prompt="""
-You are a mathematical wizard.
-Use your tools for mathematical tasks.
-Refer to tools as your 'spellbook'.
-""",
-        tools=[subtract, current_time],
-    )
-"
-`;
-
-exports[`py#agent generator > should match snapshot for generated files > agent-main.py 1`] = `
-"import uuid
-
-import uvicorn
-from bedrock_agentcore.runtime.models import PingStatus
-from fastapi import Request
-from pydantic import BaseModel
-from starlette.middleware.base import BaseHTTPMiddleware
-from proj_agent_connection import session_id_context, with_session_id
-
-from .agent import get_agent
-from .init import JsonStreamingResponse, app
-
-SESSION_ID_HEADER = "x-amzn-bedrock-agentcore-runtime-session-id"
-
-_agent_ctx = with_session_id(
-    get_agent,
-    name="SnapshotAgent",
-    description="A Strands Agent exposed via HTTP streaming.",
-)
-_agent = _agent_ctx.__enter__()
-
-
-class InvokeInput(BaseModel):
-    message: str
-
-
-class StreamChunk(BaseModel):
-    content: str
-
-
-async def handle_invoke(input: InvokeInput):
-    """Streaming handler for agent invocation"""
-    stream = _agent.stream_async(input.message)
-    async for event in stream:
-        print(event)
-        text = (
-            event.get("event", {})
-            .get("contentBlockDelta", {})
-            .get("delta", {})
-            .get("text")
-        )
-        if text is not None:
-            yield StreamChunk(content=text)
-        elif event.get("event", {}).get("messageStop") is not None:
-            yield StreamChunk(content="\\n")
-
-
-@app.post(
-    "/invocations",
-    response_class=JsonStreamingResponse,
-    responses={
-        200: JsonStreamingResponse.openapi_response(
-            StreamChunk, "Stream of agent response chunks"
-        )
-    },
-)
-async def invoke(input: InvokeInput) -> JsonStreamingResponse:
-    """Entry point for agent invocation"""
-    return JsonStreamingResponse(handle_invoke(input))
-
-
-class _SessionIdMiddleware(BaseHTTPMiddleware):
-    """Bind the inbound session (or a fresh UUID) to async context."""
-
-    async def dispatch(self, request: Request, call_next):
-        session_id = request.headers.get(SESSION_ID_HEADER) or str(uuid.uuid4())
-        with session_id_context(session_id):
-            return await call_next(request)
-
-
-app.add_middleware(_SessionIdMiddleware)
-
-
-@app.get("/ping")
-def ping() -> str:
-    # TODO: if running an async task, return PingStatus.HEALTHY_BUSY
-    return PingStatus.HEALTHY
-
-
-if __name__ == "__main__":
-    uvicorn.run("proj_test_project.snapshot_agent.main:app", port=8080)
-"
-`;
-
-exports[`py#agent generator > should match snapshot for generated files > updated-pyproject.toml 1`] = `
-"[project]
-name = "proj.test_project"
-version = "0.1.0"
-dependencies = [
-  "proj.agent_connection",
-  "aws-lambda-powertools==3.29.0",
-  "aws-opentelemetry-distro==0.17.1",
-  "bedrock-agentcore==1.13.0",
-  "boto3==1.43.20",
-  "fastapi==0.136.3",
-  "mcp==1.27.2",
-  "strands-agents==1.42.0",
-  "strands-agents-tools==0.7.0",
-  "uvicorn==0.48.0"
-]
-
-[dependency-groups]
-dev = [ "fastapi[standard]==0.136.3" ]
-
-[tool.uv]
-dev-dependencies = [ ]
-
-[tool.uv.sources."proj.agent_connection"]
-workspace = true
+output "security_group_id" {
+  description = "Security group ID of the agent core runtime, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = var.enable_vpc ? aws_security_group.agent_core_runtime[0].id : null
+}
 "
 `;