@aws/nx-plugin 1.0.0-rc.2 → 1.0.0-rc.21

package/src/utils/agent-connection/files/core-mcp/agentcore-mcp-transport.ts.template

@@ -0,0 +1,70 @@
+import type { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import {
+  mcpUrlFromArn,
+  regionFromArn,
+} from './agentcore-endpoints.js';
+import {
+  sigV4Transport,
+  jwtTransport,
+  noAuthTransport,
+} from './agentcore-transport.js';
+
+/**
+ * Options for an MCP transport with IAM authentication.
+ */
+export interface AgentCoreMcpTransportIamOptions {
+  /** The ARN of the Bedrock AgentCore Runtime to connect to. */
+  agentRuntimeArn: string;
+  /** AWS credential provider; defaults to the standard provider chain. */
+  credentialProvider?: ReturnType<typeof fromNodeProviderChain>;
+}
+
+/**
+ * Options for an MCP transport with JWT authentication.
+ */
+export interface AgentCoreMcpTransportJwtOptions {
+  /** The ARN of the Bedrock AgentCore Runtime to connect to. */
+  agentRuntimeArn: string;
+  /** A function which returns the JWT access token used to authenticate. */
+  accessTokenProvider: () => Promise<string>;
+}
+
+/**
+ * Options for an MCP transport with no auth (local dev).
+ */
+export interface AgentCoreMcpTransportNoAuthOptions {
+  /** Full URL of the local MCP endpoint. */
+  url: string;
+}
+
+/** Factory for MCP transports that connect to a Bedrock AgentCore runtime. */
+export class AgentCoreMcpTransport {
+  /** SigV4-authenticated transport for a Bedrock AgentCore runtime. */
+  static withIamAuth(
+    options: AgentCoreMcpTransportIamOptions,
+  ): StreamableHTTPClientTransport {
+    return sigV4Transport({
+      region: regionFromArn(options.agentRuntimeArn),
+      url: mcpUrlFromArn(options.agentRuntimeArn),
+      credentialProvider: options.credentialProvider,
+    });
+  }
+
+  /** Bearer-authenticated transport for a Bedrock AgentCore runtime. */
+  static withJwtAuth(
+    options: AgentCoreMcpTransportJwtOptions,
+  ): StreamableHTTPClientTransport {
+    return jwtTransport({
+      url: mcpUrlFromArn(options.agentRuntimeArn),
+      accessTokenProvider: options.accessTokenProvider,
+    });
+  }
+
+  /** For local dev — plain HTTP, no auth. */
+  static withoutAuth(
+    options: AgentCoreMcpTransportNoAuthOptions,
+  ): StreamableHTTPClientTransport {
+    return noAuthTransport({ url: options.url });
+  }
+}

package/src/utils/agent-connection/files/core-runtime-config/runtime-config.ts.template

@@ -1,40 +1,30 @@
 import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
 
 /**
- * Read the runtime-config `agentcore` namespace from AppConfig.
- * `RUNTIME_CONFIG_APP_ID` is set on the AgentCore runtime by the generated
- * CDK/Terraform construct for this project.
+ * Shape of this project's runtime configuration in AppConfig. Keys are the
+ * class names of connected target constructs (e.g. `MyAgent`, `MyGateway`).
  */
-const getAgentCoreRuntimeConfig = async (): Promise<{
+export interface AgentCoreRuntimeConfig {
   agentRuntimes?: Record<string, string>;
-}> => {
-  const application = process.env.RUNTIME_CONFIG_APP_ID;
-  if (!application) {
-    throw new Error(
-      'RUNTIME_CONFIG_APP_ID is not set — cannot resolve connected agent ARNs from AppConfig.',
-    );
-  }
-  return (await getAppConfig('agentcore', {
-    application,
-    environment: 'default',
-    transform: 'json',
-  })) as { agentRuntimes?: Record<string, string> };
-};
+  gateways?: Record<string, string>;
+}
 
 /**
- * Resolve the AgentCore runtime ARN for a connected agent or MCP server
- * from this project's runtime configuration. `name` must match the class
- * name of the target construct (e.g. `MyAgent`, `InventoryMcpServer`).
+ * Read the runtime-config `agentcore` namespace from AppConfig.
+ * `RUNTIME_CONFIG_APP_ID` is set on the AgentCore runtime by the generated
+ * CDK/Terraform construct for this project.
  */
-export const getConnectedAgentRuntimeArn = async (
-  name: string,
-): Promise<string> => {
-  const config = await getAgentCoreRuntimeConfig();
-  const arn = config.agentRuntimes?.[name];
-  if (!arn) {
-    throw new Error(
-      `No connected agent runtime named '${name}' found in runtime configuration.`,
-    );
-  }
-  return arn;
-};
+export const getAgentCoreRuntimeConfig =
+  async (): Promise<AgentCoreRuntimeConfig> => {
+    const application = process.env.RUNTIME_CONFIG_APP_ID;
+    if (!application) {
+      throw new Error(
+        'RUNTIME_CONFIG_APP_ID is not set — cannot resolve connected agent ARNs from AppConfig.',
+      );
+    }
+    return (await getAppConfig('agentcore', {
+      application,
+      environment: 'default',
+      transform: 'json',
+    })) as AgentCoreRuntimeConfig;
+  };

package/src/utils/agent-connection/files/core-shared/agentcore-transport.ts.template

@@ -0,0 +1,39 @@
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import {
+  createSigV4Fetch,
+  createJwtFetch,
+  createPlainFetch,
+} from './agentcore-fetch.js';
+
+const build = (
+  url: string,
+  fetchFn: typeof fetch,
+): StreamableHTTPClientTransport =>
+  new StreamableHTTPClientTransport(new URL(url), { fetch: fetchFn });
+
+/** SigV4-signed transport for a resolved AgentCore endpoint. */
+export const sigV4Transport = (options: {
+  region: string;
+  url: string;
+  credentialProvider?: ReturnType<typeof fromNodeProviderChain>;
+}): StreamableHTTPClientTransport =>
+  build(
+    options.url,
+    createSigV4Fetch({
+      region: options.region,
+      credentialProvider: options.credentialProvider,
+    }),
+  );
+
+/** Bearer-token transport for a resolved AgentCore endpoint. */
+export const jwtTransport = (options: {
+  url: string;
+  accessTokenProvider: () => Promise<string>;
+}): StreamableHTTPClientTransport =>
+  build(options.url, createJwtFetch(options.accessTokenProvider));
+
+/** Plain-HTTP transport — for local dev. */
+export const noAuthTransport = (options: {
+  url: string;
+}): StreamableHTTPClientTransport => build(options.url, createPlainFetch());

package/src/utils/agent-connection/files/core-strands/a2a/agentcore-a2a-client-strands.ts.template

@@ -0,0 +1,61 @@
+import { A2AAgent } from '@strands-agents/sdk/a2a';
+import {
+  type A2aClientConfig,
+  AgentCoreA2aClientConfig,
+  type AgentCoreA2aClientConfigIamOptions,
+  type AgentCoreA2aClientConfigJwtOptions,
+  type AgentCoreA2aClientConfigNoAuthOptions,
+} from './agentcore-a2a-client-config.js';
+
+/** Optional friendly metadata for the remote agent. */
+export interface StrandsA2aOptions {
+  /** Optional friendly name for the remote agent. */
+  name?: string;
+  /** Optional description for the remote agent. */
+  description?: string;
+}
+
+/** Strands A2A clients for a Bedrock AgentCore runtime. */
+export class AgentCoreA2aClientStrands {
+  private static build(
+    { url, clientFactory }: A2aClientConfig,
+    options: StrandsA2aOptions,
+  ): A2AAgent {
+    return new A2AAgent({
+      url,
+      clientFactory,
+      ...(options.name ? { name: options.name } : {}),
+      ...(options.description ? { description: options.description } : {}),
+    });
+  }
+
+  /** SigV4-authenticated client for a Bedrock AgentCore runtime. */
+  static withIamAuth(
+    options: AgentCoreA2aClientConfigIamOptions & StrandsA2aOptions,
+  ): A2AAgent {
+    return AgentCoreA2aClientStrands.build(
+      AgentCoreA2aClientConfig.withIamAuth(options),
+      options,
+    );
+  }
+
+  /** Bearer-authenticated client for a Bedrock AgentCore runtime. */
+  static withJwtAuth(
+    options: AgentCoreA2aClientConfigJwtOptions & StrandsA2aOptions,
+  ): A2AAgent {
+    return AgentCoreA2aClientStrands.build(
+      AgentCoreA2aClientConfig.withJwtAuth(options),
+      options,
+    );
+  }
+
+  /** For local dev — plain HTTP, no auth. */
+  static withoutAuth(
+    options: AgentCoreA2aClientConfigNoAuthOptions & StrandsA2aOptions,
+  ): A2AAgent {
+    return AgentCoreA2aClientStrands.build(
+      AgentCoreA2aClientConfig.withoutAuth(options),
+      options,
+    );
+  }
+}

package/src/utils/agent-connection/files/core-strands/base/model-errors-strands.ts.template

@@ -0,0 +1,36 @@
+import { AfterModelCallEvent, type LocalAgent } from '@strands-agents/sdk';
+
+const NO_CREDENTIALS =
+  'Unable to invoke the model: no AWS credentials found. Configure credentials ' +
+  '(e.g. run `aws configure`, set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / ' +
+  'AWS_SESSION_TOKEN, or assume a role) before running the agent.';
+const ACCESS_DENIED =
+  'Unable to invoke the model: access denied. Grant your AWS principal permission ' +
+  'to call bedrock:InvokeModelWithResponseStream for your model.';
+
+// AWS SDK v3 errors are identified by their `name` rather than `instanceof`,
+// since the SDK may be loaded from more than one place. Strands wraps them in a
+// ModelError, so we check the error and its `cause` chain.
+const hasErrorNamed = (error: unknown, name: string): boolean => {
+  let current: unknown = error;
+  while (current instanceof Error) {
+    if (current.name === name) return true;
+    current = current.cause;
+  }
+  return false;
+};
+
+/** Logs model invocation errors, calling out missing credentials or denied permissions. */
+export const logModelErrors = (agent: LocalAgent): void => {
+  agent.addHook(AfterModelCallEvent, (event) => {
+    const error = event.error;
+    if (!error) return;
+    if (hasErrorNamed(error, 'CredentialsProviderError')) {
+      console.error(NO_CREDENTIALS);
+    } else if (hasErrorNamed(error, 'AccessDeniedException')) {
+      console.error(ACCESS_DENIED);
+    } else {
+      console.error(`Model invocation failed: ${error.message}`);
+    }
+  });
+};

package/src/utils/agent-connection/files/core-strands/gateway/agentcore-gateway-mcp-client-strands.ts.template

@@ -0,0 +1,26 @@
+import { McpClient } from '@strands-agents/sdk';
+import {
+  AgentCoreGatewayMcpTransport,
+  type AgentCoreGatewayMcpTransportIamOptions,
+} from './agentcore-gateway-mcp-transport.js';
+
+/**
+ * Strands MCP clients that connect to an AgentCore Gateway.
+ */
+export class AgentCoreGatewayMcpClientStrands {
+  /** Create a gateway MCP client authenticated with IAM SigV4. */
+  static withIamAuth(
+    options: AgentCoreGatewayMcpTransportIamOptions,
+  ): McpClient {
+    return new McpClient({
+      transport: AgentCoreGatewayMcpTransport.withIamAuth(options),
+    });
+  }
+
+  /** Plain-HTTP gateway client, for the local gateway started by serve-local. */
+  static withoutAuth(options: { gatewayUrl: string }): McpClient {
+    return new McpClient({
+      transport: AgentCoreGatewayMcpTransport.withoutAuth(options),
+    });
+  }
+}

package/src/utils/agent-connection/files/core-strands/mcp/agentcore-mcp-client-strands.ts.template

@@ -0,0 +1,27 @@
+import { McpClient } from '@strands-agents/sdk';
+import {
+  AgentCoreMcpTransport,
+  type AgentCoreMcpTransportIamOptions,
+  type AgentCoreMcpTransportJwtOptions,
+  type AgentCoreMcpTransportNoAuthOptions,
+} from './agentcore-mcp-transport.js';
+
+/** Strands MCP clients for a Bedrock AgentCore runtime. */
+export class AgentCoreMcpClientStrands {
+  /** SigV4-authenticated client for a Bedrock AgentCore runtime. */
+  static withIamAuth(options: AgentCoreMcpTransportIamOptions): McpClient {
+    return new McpClient({ transport: AgentCoreMcpTransport.withIamAuth(options) });
+  }
+
+  /** Bearer-authenticated client for a Bedrock AgentCore runtime. */
+  static withJwtAuth(options: AgentCoreMcpTransportJwtOptions): McpClient {
+    return new McpClient({ transport: AgentCoreMcpTransport.withJwtAuth(options) });
+  }
+
+  /** For local dev — plain HTTP, no auth. */
+  static withoutAuth(options: AgentCoreMcpTransportNoAuthOptions): McpClient {
+    return new McpClient({
+      transport: AgentCoreMcpTransport.withoutAuth(options),
+    });
+  }
+}

package/src/utils/agent-connection/files/py-core-a2a/agentcore_a2a_client_config.py.template

@@ -0,0 +1,43 @@
+from collections.abc import Callable
+
+import boto3
+import httpx
+from a2a.client import ClientConfig
+
+from .agentcore_endpoints import a2a_url_from_arn, region_from_arn
+from .auth.session import jwt_auth, plain_auth, sigv4_auth
+
+
+def _config(url: str, auth: httpx.Auth) -> tuple[str, ClientConfig]:
+    httpx_client = httpx.AsyncClient(auth=auth, timeout=120)
+    return url, ClientConfig(httpx_client=httpx_client, streaming=False)
+
+
+class AgentCoreA2aClientConfig:
+    """Factory for A2A client configs that connect to a Bedrock AgentCore
+    runtime. Each forwards the current async-context session via the AgentCore
+    session header. Framework-agnostic — wrap the result in a framework's
+    A2A client."""
+
+    @staticmethod
+    def with_iam_auth(agent_runtime_arn: str) -> tuple[str, ClientConfig]:
+        """SigV4-authenticated A2A client config for a Bedrock AgentCore runtime."""
+        region = region_from_arn(agent_runtime_arn)
+        credentials = boto3.Session(region_name=region).get_credentials()
+        return _config(
+            a2a_url_from_arn(agent_runtime_arn), sigv4_auth(credentials, region)
+        )
+
+    @staticmethod
+    def with_jwt_auth(
+        agent_runtime_arn: str, access_token_provider: Callable[[], str]
+    ) -> tuple[str, ClientConfig]:
+        """Bearer-authenticated A2A client config for a Bedrock AgentCore runtime."""
+        return _config(
+            a2a_url_from_arn(agent_runtime_arn), jwt_auth(access_token_provider)
+        )
+
+    @staticmethod
+    def without_auth(url: str) -> tuple[str, ClientConfig]:
+        """Plain-HTTP A2A client config — for local dev."""
+        return _config(url, plain_auth())

package/src/utils/agent-connection/files/py-core-auth/agentcore_endpoints.py.template

@@ -0,0 +1,47 @@
+"""Resolve Bedrock AgentCore invocation endpoints from a runtime ARN.
+
+Framework-agnostic — reusable by any framework's connection client.
+"""
+
+import re
+from urllib.parse import quote
+
+
+def region_from_arn(agent_runtime_arn: str) -> str:
+    """Extract the AWS region from a Bedrock AgentCore runtime ARN.
+
+    ARN format: arn:partition:service:region:account-id:resource
+    """
+    return agent_runtime_arn.split(":")[3]
+
+
+def mcp_url_from_arn(agent_runtime_arn: str) -> str:
+    """The MCP invocation URL for a runtime ARN."""
+    region = region_from_arn(agent_runtime_arn)
+    encoded_arn = quote(agent_runtime_arn, safe="")
+    return (
+        f"https://bedrock-agentcore.{region}.amazonaws.com/runtimes/"
+        f"{encoded_arn}/invocations?qualifier=DEFAULT"
+    )
+
+
+def a2a_url_from_arn(agent_runtime_arn: str) -> str:
+    """The A2A invocation URL for a runtime ARN. A2A on AgentCore is mounted at
+    the `/invocations/` root (trailing slash matters)."""
+    region = region_from_arn(agent_runtime_arn)
+    encoded_arn = quote(agent_runtime_arn, safe="")
+    return (
+        f"https://bedrock-agentcore.{region}.amazonaws.com/runtimes/"
+        f"{encoded_arn}/invocations/"
+    )
+
+
+def region_from_gateway_url(gateway_url: str) -> str:
+    """Extract the AWS region from an AgentCore Gateway MCP URL."""
+    match = re.search(r"\.bedrock-agentcore\.([^.]+)\.amazonaws\.com", gateway_url)
+    if not match:
+        raise ValueError(
+            f"Cannot determine region from gateway URL '{gateway_url}'. "
+            "Pass region explicitly."
+        )
+    return match.group(1)

package/src/utils/agent-connection/files/py-core-auth/auth/session.py.template

@@ -0,0 +1,51 @@
+from collections.abc import Callable
+
+import httpx
+
+from ..session_context import get_current_session_id
+from .sigv4 import SigV4HTTPXAuth
+
+SESSION_HEADER = "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id"
+
+
+class SessionHeaderAuth(httpx.Auth):
+    """Stamps the AgentCore session header from the current async context,
+    then delegates to an optional inner auth (e.g. SigV4)."""
+
+    requires_request_body = True
+    requires_response_body = True
+
+    def __init__(self, inner: httpx.Auth | None = None):
+        self._inner = inner
+
+    def auth_flow(self, request: httpx.Request):  # type: ignore[override]
+        sid = get_current_session_id()
+        if sid:
+            request.headers[SESSION_HEADER] = sid
+        if self._inner is None:
+            yield request
+            return
+        yield from self._inner.auth_flow(request)
+
+
+def sigv4_auth(
+    credentials, region: str, service: str = "bedrock-agentcore"
+) -> httpx.Auth:
+    """Session-forwarding SigV4 auth (per-request, body-aware)."""
+    return SessionHeaderAuth(SigV4HTTPXAuth(credentials, service, region))
+
+
+def jwt_auth(access_token_provider: Callable[[], str]) -> httpx.Auth:
+    """Session-forwarding bearer-token auth."""
+
+    class _Bearer(httpx.Auth):
+        def auth_flow(self, request: httpx.Request):
+            request.headers["Authorization"] = f"Bearer {access_token_provider()}"
+            yield request
+
+    return SessionHeaderAuth(_Bearer())
+
+
+def plain_auth() -> httpx.Auth:
+    """Session-forwarding plain auth — for local dev."""
+    return SessionHeaderAuth()

package/src/utils/agent-connection/files/py-core-gateway/agentcore_gateway_mcp_transport.py.template

@@ -0,0 +1,28 @@
+from .agentcore_endpoints import region_from_gateway_url
+from .agentcore_transport import (
+    TransportFactory,
+    no_auth_transport,
+    sigv4_transport,
+)
+
+
+class AgentCoreGatewayMCPTransport:
+    """Factory for MCP transport factories that connect to an AgentCore Gateway.
+    Forwards the current async-context session via the AgentCore session header,
+    which the gateway propagates to downstream MCP server targets.
+    """
+
+    @staticmethod
+    def with_iam_auth(
+        gateway_url: str,
+        region: str | None = None,
+    ) -> TransportFactory:
+        """Create a gateway MCP transport authenticated with IAM SigV4."""
+        return sigv4_transport(
+            gateway_url, region or region_from_gateway_url(gateway_url)
+        )
+
+    @staticmethod
+    def without_auth(gateway_url: str) -> TransportFactory:
+        """Plain-HTTP gateway transport, for the local gateway started by serve-local."""
+        return no_auth_transport(gateway_url)

package/src/utils/agent-connection/files/py-core-mcp/agentcore_mcp_transport.py.template

@@ -0,0 +1,34 @@
+from collections.abc import Callable
+
+from .agentcore_endpoints import mcp_url_from_arn, region_from_arn
+from .agentcore_transport import (
+    TransportFactory,
+    jwt_transport,
+    no_auth_transport,
+    sigv4_transport,
+)
+
+
+class AgentCoreMCPTransport:
+    """Factory for MCP transport factories that connect to an AgentCore runtime."""
+
+    @staticmethod
+    def with_iam_auth(agent_runtime_arn: str) -> TransportFactory:
+        """SigV4-authenticated transport for a Bedrock AgentCore runtime."""
+        return sigv4_transport(
+            mcp_url_from_arn(agent_runtime_arn), region_from_arn(agent_runtime_arn)
+        )
+
+    @staticmethod
+    def with_jwt_auth(
+        agent_runtime_arn: str, access_token_provider: Callable[[], str]
+    ) -> TransportFactory:
+        """Bearer-authenticated transport for a Bedrock AgentCore runtime."""
+        return jwt_transport(
+            mcp_url_from_arn(agent_runtime_arn), access_token_provider
+        )
+
+    @staticmethod
+    def without_auth(url: str) -> TransportFactory:
+        """Plain-HTTP transport — for local dev."""
+        return no_auth_transport(url)

package/src/utils/agent-connection/files/py-core-runtime-config/runtime_config.py.template

@@ -5,9 +5,13 @@ from aws_lambda_powertools.utilities import parameters
 from botocore.config import Config
 
 
-def _get_agentcore_runtime_config() -> dict[str, Any]:
+def get_agentcore_runtime_config() -> dict[str, Any]:
     """Read the runtime-config ``agentcore`` namespace from AppConfig.
 
+    Returns a dict of the shape ``{"agentRuntimes": {name: arn, ...},
+    "gateways": {name: url, ...}}``, where keys are the class names of
+    connected target constructs.
+
     ``RUNTIME_CONFIG_APP_ID`` is set on the AgentCore runtime by the generated
     CDK/Terraform construct for this project.
     """
@@ -23,20 +27,3 @@ def _get_agentcore_runtime_config() -> dict[str, Any]:
         config=Config(region_name=region) if region else None,
     )
     return cast(dict[str, Any], provider.get("agentcore", transform="json"))
-
-
-def get_connected_agent_runtime_arn(name: str) -> str:
-    """Resolve the AgentCore runtime ARN for a connected agent or MCP server
-    from this project's runtime configuration.
-
-    ``name`` must match the class name of the target construct
-    (e.g. ``MyAgent``, ``InventoryMcpServer``).
-    """
-    config = _get_agentcore_runtime_config()
-    agent_runtimes = config.get("agentRuntimes", {}) if config else {}
-    arn = agent_runtimes.get(name)
-    if not arn:
-        raise RuntimeError(
-            f"No connected agent runtime named '{name}' found in runtime configuration."
-        )
-    return arn

package/src/utils/agent-connection/files/py-core-shared/agentcore_transport.py.template

@@ -0,0 +1,40 @@
+from collections.abc import Callable
+from typing import Any
+
+import boto3
+
+from mcp.client.streamable_http import streamablehttp_client
+
+from .auth.session import jwt_auth, plain_auth, sigv4_auth
+
+# Agent frameworks wrap a transport *factory* — a no-arg callable returning a
+# streamable-HTTP transport context manager. Typed as ``Any`` so this layer
+# stays free of any framework-specific transport type.
+TransportFactory = Callable[[], Any]
+
+
+def _factory(url: str, auth) -> TransportFactory:
+    return lambda: streamablehttp_client(
+        url,
+        auth=auth,
+        timeout=120,
+        terminate_on_close=False,
+    )
+
+
+def sigv4_transport(url: str, region: str) -> TransportFactory:
+    """SigV4-signed transport factory for a resolved AgentCore endpoint."""
+    credentials = boto3.Session(region_name=region).get_credentials()
+    return _factory(url, sigv4_auth(credentials, region))
+
+
+def jwt_transport(
+    url: str, access_token_provider: Callable[[], str]
+) -> TransportFactory:
+    """Bearer-token transport factory for a resolved AgentCore endpoint."""
+    return _factory(url, jwt_auth(access_token_provider))
+
+
+def no_auth_transport(url: str) -> TransportFactory:
+    """Plain-HTTP transport factory — for local dev."""
+    return _factory(url, plain_auth())