@aws/nx-plugin 1.0.0-rc.3 → 1.0.0-rc.31

package/src/py/agent/files/http/init.py.template

@@ -1,11 +1,10 @@
+import logging
 from collections.abc import AsyncIterator
 from typing import Any
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.openapi.utils import get_openapi
 from fastapi.responses import JSONResponse, StreamingResponse
-from fastapi.routing import APIRoute
 from pydantic import BaseModel
 from starlette.middleware.exceptions import ExceptionMiddleware
 
@@ -61,7 +60,11 @@ class JsonStreamingResponse(StreamingResponse):
         }
 
 
-app = FastAPI(title="<%= agentNameClassName %>", responses={500: {"model": InternalServerErrorDetails}})
+app = FastAPI(
+    title="<%= agentNameClassName %>",
+    responses={500: {"model": InternalServerErrorDetails}},
+    generate_unique_id_function=lambda route: route.name,
+)
 
 # Add cors middleware
 app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
@@ -72,28 +75,7 @@ app.add_middleware(ExceptionMiddleware, handlers=app.exception_handlers)
 
 @app.exception_handler(Exception)
 async def unhandled_exception_handler(request, err):
-    print(request)
-    print(err)
+    logging.exception("Unhandled exception while handling request")
     return JSONResponse(
         status_code=500, content=InternalServerErrorDetails(detail="Internal Server Error").model_dump()
     )
-
-
-def custom_openapi() -> dict[str, Any]:
-    if app.openapi_schema:
-        return app.openapi_schema
-    for route in app.routes:
-        if isinstance(route, APIRoute):
-            route.operation_id = route.name
-    openapi_schema = get_openapi(
-        title=app.title,
-        version=app.version,
-        openapi_version=app.openapi_version,
-        description=app.description,
-        routes=app.routes,
-    )
-    app.openapi_schema = openapi_schema
-    return app.openapi_schema
-
-
-app.openapi = custom_openapi  # ty: ignore[invalid-assignment]

package/src/py/agent/files/http/main.py.template

@@ -3,7 +3,7 @@ import uuid
 import uvicorn
 from bedrock_agentcore.runtime.models import PingStatus
 from fastapi import Request
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from starlette.middleware.base import BaseHTTPMiddleware
 from <%- agentConnectionModuleName %> import session_id_context, with_session_id
 
@@ -21,7 +21,7 @@ _agent = _agent_ctx.__enter__()
 
 
 class InvokeInput(BaseModel):
-    message: str
+    message: str = Field(max_length=100000)
 
 
 class StreamChunk(BaseModel):
@@ -32,7 +32,6 @@ 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)

package/src/py/agent/files/http-langchain/main.py.template

@@ -0,0 +1,84 @@
+import uuid
+
+import uvicorn
+from bedrock_agentcore.runtime.models import PingStatus
+from fastapi import Request
+from pydantic import BaseModel, Field
+from starlette.middleware.base import BaseHTTPMiddleware
+from <%- agentConnectionModuleName %> import get_current_session_id, session_id_context
+
+from .agent import get_agent
+from .init import JsonStreamingResponse, app
+
+SESSION_ID_HEADER = "x-amzn-bedrock-agentcore-runtime-session-id"
+
+_graph = get_agent()
+
+
+class InvokeInput(BaseModel):
+    message: str = Field(max_length=100000)
+
+
+class StreamChunk(BaseModel):
+    content: str
+
+
+def _text(content) -> str:
+    # ChatBedrockConverse streams content as a list of blocks, not a plain string.
+    if isinstance(content, str):
+        return content
+    return "".join(
+        block.get("text", "")
+        for block in content
+        if isinstance(block, dict) and block.get("type") == "text"
+    )
+
+
+async def handle_invoke(input: InvokeInput, session_id: str):
+    """Streaming handler for agent invocation"""
+    # The session id is the LangGraph thread id, so the checkpointer keeps memory per session.
+    config = {"configurable": {"thread_id": session_id}}
+    # Re-bind the session: the streaming body runs outside the middleware scope.
+    with session_id_context(session_id):
+        stream = _graph.astream(
+            {"messages": [{"role": "user", "content": input.message}]},
+            config,
+            stream_mode="messages",
+        )
+        async for message_chunk, _metadata in stream:
+            text = _text(message_chunk.content)
+            if text:
+                yield StreamChunk(content=text)
+
+
+@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"""
+    session_id = get_current_session_id() or str(uuid.uuid4())
+    return JsonStreamingResponse(handle_invoke(input, session_id))
+
+
+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("<%- moduleName %>.<%- agentNameSnakeCase %>.main:app", port=8080)

package/src/py/agent/gateway-connection/__snapshots__/generator.spec.ts.snap

@@ -0,0 +1,184 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`py#agent#gateway-connection generator > should match snapshot for agent-connection core files > agentcore_gateway_mcp_client_strands.py 1`] = `
+"from strands.tools.mcp.mcp_client import MCPClient
+
+from .agentcore_gateway_mcp_transport import AgentCoreGatewayMCPTransport
+
+
+class AgentCoreGatewayMCPClientStrands:
+    """Factory for Strands MCP clients that connect to an AgentCore Gateway."""
+
+    @staticmethod
+    def with_iam_auth(
+        gateway_url: str,
+        region: str | None = None,
+    ) -> MCPClient:
+        """Create a gateway MCP client authenticated with IAM SigV4."""
+        return MCPClient(AgentCoreGatewayMCPTransport.with_iam_auth(gateway_url, region))
+
+    @staticmethod
+    def without_auth(gateway_url: str) -> MCPClient:
+        """Plain-HTTP gateway client, for the local gateway started by the dev target."""
+        return MCPClient(AgentCoreGatewayMCPTransport.without_auth(gateway_url))
+"
+`;
+
+exports[`py#agent#gateway-connection generator > should match snapshot for agent-connection core files > agentcore_gateway_mcp_transport.py 1`] = `
+"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 the dev target."""
+        return no_auth_transport(gateway_url)
+"
+`;
+
+exports[`py#agent#gateway-connection generator > should match snapshot for agent-connection core files > agentcore_transport.py 1`] = `
+"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())
+"
+`;
+
+exports[`py#agent#gateway-connection generator > should match snapshot for agent-connection core files > my_gateway_client_strands.py 1`] = `
+"import os
+
+from strands.tools.mcp.mcp_client import MCPClient
+
+from proj_agent_connection.core.agentcore_gateway_mcp_client_strands import (
+    AgentCoreGatewayMCPClientStrands,
+)
+from proj_agent_connection.core.runtime_config import (
+    get_agentcore_runtime_config,
+)
+
+
+class MyGatewayClientStrands:
+    """Strands client for the MyGateway AgentCore Gateway.
+
+    Deployed: a SigV4-signed MCP client pointing at the gateway URL.
+    Local (\`\`LOCAL_DEV=true\`\`): a plain-HTTP client pointing at the local
+    gateway started by the gateway project's dev target. The local
+    gateway aggregates every attached MCP server but does not evaluate
+    Cedar policies.
+    """
+
+    @staticmethod
+    def create() -> MCPClient:
+        if os.environ.get("LOCAL_DEV") == "true":
+            return AgentCoreGatewayMCPClientStrands.without_auth(gateway_url="http://localhost:8100/mcp")
+        config = get_agentcore_runtime_config()
+        gateway_url = config.get("gateways", {}).get("MyGateway")
+        if not gateway_url:
+            raise RuntimeError("No connected gateway named 'MyGateway' found in runtime configuration.")
+        return AgentCoreGatewayMCPClientStrands.with_iam_auth(gateway_url=gateway_url)
+"
+`;
+
+exports[`py#agent#gateway-connection generator > should match snapshot for agent-connection core files > session.py 1`] = `
+"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/py/agent/gateway-connection/files/agent-connection/app/__gatewaySnakeCase___client_strands.py.template

@@ -0,0 +1,35 @@
+import os
+
+from strands.tools.mcp.mcp_client import MCPClient
+
+from <%- agentConnectionModuleName %>.core.agentcore_gateway_mcp_client_strands import (
+    AgentCoreGatewayMCPClientStrands,
+)
+from <%- agentConnectionModuleName %>.core.runtime_config import (
+    get_agentcore_runtime_config,
+)
+
+
+class <%- gatewayClassName %>ClientStrands:
+    """Strands client for the <%- gatewayClassName %> AgentCore Gateway.
+
+    Deployed: a SigV4-signed MCP client pointing at the gateway URL.
+    Local (``LOCAL_DEV=true``): a plain-HTTP client pointing at the local
+    gateway started by the gateway project's dev target. The local
+    gateway aggregates every attached MCP server but does not evaluate
+    Cedar policies.
+    """
+
+    @staticmethod
+    def create() -> MCPClient:
+        if os.environ.get("LOCAL_DEV") == "true":
+            return AgentCoreGatewayMCPClientStrands.without_auth(
+                gateway_url="http://localhost:<%- gatewayPort %>/mcp"
+            )
+        config = get_agentcore_runtime_config()
+        gateway_url = config.get("gateways", {}).get("<%- gatewayClassName %>")
+        if not gateway_url:
+            raise RuntimeError(
+                "No connected gateway named '<%- gatewayClassName %>' found in runtime configuration."
+            )
+        return AgentCoreGatewayMCPClientStrands.with_iam_auth(gateway_url=gateway_url)

package/src/py/agent/gateway-connection/files/langchain/agent-connection/app/__gatewaySnakeCase___client_langchain.py.template

@@ -0,0 +1,34 @@
+import os
+
+from langchain_core.tools import BaseTool
+
+from <%- agentConnectionModuleName %>.core.agentcore_gateway_mcp_client_langchain import (
+    AgentCoreGatewayMCPClientLangChain,
+)
+from <%- agentConnectionModuleName %>.core.runtime_config import (
+    get_agentcore_runtime_config,
+)
+
+
+class <%- gatewayClassName %>ClientLangChain:
+    """Loads LangChain tools from the <%- gatewayClassName %> AgentCore Gateway.
+
+    Deployed: SigV4-signed tools pointing at the gateway URL. Local
+    (``LOCAL_DEV=true``): plain-HTTP tools pointing at the local gateway
+    started by the gateway project's dev target. The local gateway
+    aggregates every attached MCP server but does not evaluate Cedar policies.
+    """
+
+    @staticmethod
+    def create() -> list[BaseTool]:
+        if os.environ.get("LOCAL_DEV") == "true":
+            return AgentCoreGatewayMCPClientLangChain.without_auth(
+                gateway_url="http://localhost:<%- gatewayPort %>/mcp"
+            )
+        config = get_agentcore_runtime_config()
+        gateway_url = config.get("gateways", {}).get("<%- gatewayClassName %>")
+        if not gateway_url:
+            raise RuntimeError(
+                "No connected gateway named '<%- gatewayClassName %>' found in runtime configuration."
+            )
+        return AgentCoreGatewayMCPClientLangChain.with_iam_auth(gateway_url=gateway_url)

package/src/py/agent/gateway-connection/generator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type GeneratorCallback, type Tree } from '@nx/devkit';
+import { type NxGeneratorInfo } from '../../../utils/nx';
+import type { PyAgentGatewayConnectionGeneratorSchema } from './schema';
+export declare const PY_AGENT_GATEWAY_CONNECTION_GENERATOR_INFO: NxGeneratorInfo;
+export declare const pyAgentGatewayConnectionGenerator: (tree: Tree, options: PyAgentGatewayConnectionGeneratorSchema) => Promise<GeneratorCallback>;
+export default pyAgentGatewayConnectionGenerator;

package/src/py/agent/gateway-connection/generator.js

@@ -0,0 +1,119 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { generateFiles, joinPathFragments, OverwriteStrategy, updateProjectConfiguration } from "@nx/devkit";
+import { readAgentCoreGatewayMetadata } from "../../../agentcore-gateway/generator.js";
+import { addPythonCoreClient, addPythonReExport, ensurePythonAgentConnectionProject, getPythonAgentConnectionModuleName, getPythonAgentConnectionProject, getPythonAgentConnectionProjectDir, PY_MCP_FAMILY_CONNECTIONS, resolveAgentFramework } from "../../../utils/agent-connection/agent-connection.js";
+import { addPythonDestructuredImport } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+import { installDependencies } from "../../../utils/install.js";
+import { addGeneratorMetricsIfApplicable } from "../../../utils/metrics.js";
+import { snakeCase } from "../../../utils/names.js";
+import { addDependencyToTargetIfNotPresent, getGeneratorInfo, readProjectConfigurationUnqualified } from "../../../utils/nx.js";
+import { addDependenciesToPyProjectToml, addWorkspaceDependencyToPyProject } from "../../../utils/py.js";
+export const PY_AGENT_GATEWAY_CONNECTION_GENERATOR_INFO = getGeneratorInfo(import.meta.filename);
+export const pyAgentGatewayConnectionGenerator = async (tree, options)=>{
+    const sourceProject = readProjectConfigurationUnqualified(tree, options.sourceProject);
+    const targetProject = readProjectConfigurationUnqualified(tree, options.targetProject);
+    const agentComponent = options.sourceComponent;
+    if (!agentComponent) {
+        throw new Error('sourceComponent must be provided for py#agent -> agentcore-gateway connections');
+    }
+    const gateway = readAgentCoreGatewayMetadata(targetProject);
+    if (gateway.protocol !== 'mcp') {
+        throw new Error(`Gateway '${gateway.name}' has protocol='${gateway.protocol}'. Only MCP-protocol gateways are supported.`);
+    }
+    if (gateway.auth !== 'iam') {
+        throw new Error(`Gateway '${gateway.name}' uses auth='${gateway.auth}'. Only IAM-authenticated gateways are supported in v1.`);
+    }
+    if (agentComponent.auth && agentComponent.auth !== 'iam') {
+        throw new Error(`Agent '${agentComponent.name}' uses auth='${agentComponent.auth}'. Only IAM-authenticated agents can connect to IAM gateways.`);
+    }
+    const gatewayClassName = gateway.rc;
+    const gatewaySnakeCase = snakeCase(gatewayClassName);
+    // A gateway is its own standalone project, so it exposes plain serve / dev.
+    const gatewayServeTargetName = 'serve';
+    const gatewayDevTargetName = 'dev';
+    // The source agent's framework selects the client shape, dependencies and the
+    // agent.py transform — see PY_MCP_FAMILY_CONNECTIONS (keyed by framework, not a
+    // boolean, so a third framework is an additive entry there). A Gateway exposes
+    // its tools over MCP, so it reuses the same wiring as an MCP server connection.
+    const framework = resolveAgentFramework(agentComponent.framework);
+    const connection = PY_MCP_FAMILY_CONNECTIONS[framework];
+    await ensurePythonAgentConnectionProject(tree);
+    await addPythonCoreClient(tree, 'gateway', framework);
+    const agentConnectionProjectDir = getPythonAgentConnectionProjectDir(tree);
+    const agentConnectionModuleName = getPythonAgentConnectionModuleName(tree);
+    // Shared MCP transport + signed httpx auth deps, plus whatever extra deps the
+    // framework's MCP client needs (e.g. langchain-mcp-adapters for LangChain).
+    addDependenciesToPyProjectToml(tree, agentConnectionProjectDir, [
+        'boto3',
+        'httpx',
+        'mcp',
+        ...connection.deps
+    ]);
+    const appDir = joinPathFragments(agentConnectionProjectDir, agentConnectionModuleName, 'app');
+    // Local mode points at the gateway project's local gateway port.
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', connection.appTemplateSubdir), appDir, {
+        gatewaySnakeCase,
+        gatewayClassName,
+        agentConnectionModuleName,
+        gatewayPort: gateway.port
+    }, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
+    const appInitPath = joinPathFragments(appDir, '__init__.py');
+    if (!tree.exists(appInitPath)) {
+        tree.write(appInitPath, '');
+    }
+    const moduleInitPath = joinPathFragments(agentConnectionProjectDir, agentConnectionModuleName, '__init__.py');
+    await addPythonReExport(tree, moduleInitPath, `.app.${gatewaySnakeCase}_client_${connection.clientModuleSuffix}`, `${gatewayClassName}Client${connection.clientClassSuffix}`);
+    const agentSourceDir = joinPathFragments(sourceProject.root, agentComponent.path ?? 'src');
+    const agentFilePath = joinPathFragments(agentSourceDir, 'agent.py');
+    if (tree.exists(agentFilePath)) {
+        const clientClassName = `${gatewayClassName}Client${connection.clientClassSuffix}`;
+        const clientVarName = gatewaySnakeCase;
+        await addPythonDestructuredImport(tree, agentFilePath, [
+            clientClassName
+        ], agentConnectionModuleName);
+        await connection.wireClientIntoAgent(tree, agentFilePath, clientClassName, clientVarName);
+    }
+    addWorkspaceDependencyToPyProject(tree, sourceProject, getPythonAgentConnectionProject(tree));
+    const agentName = agentComponent.name ?? 'agent';
+    const serveTargetName = `${agentName}-serve`;
+    const devTargetName = `${agentName}-dev`;
+    let projectConfigChanged = false;
+    if (sourceProject.targets?.[serveTargetName]) {
+        addDependencyToTargetIfNotPresent(sourceProject, serveTargetName, {
+            projects: [
+                targetProject.name
+            ],
+            target: gatewayServeTargetName
+        });
+        projectConfigChanged = true;
+    }
+    if (sourceProject.targets?.[devTargetName]) {
+        addDependencyToTargetIfNotPresent(sourceProject, devTargetName, {
+            projects: [
+                targetProject.name
+            ],
+            target: gatewayDevTargetName
+        });
+        projectConfigChanged = true;
+    }
+    if (projectConfigChanged) {
+        updateProjectConfiguration(tree, sourceProject.name, sourceProject);
+    }
+    await addGeneratorMetricsIfApplicable(tree, [
+        PY_AGENT_GATEWAY_CONNECTION_GENERATOR_INFO
+    ]);
+    await formatFilesInSubtree(tree);
+    return ()=>installDependencies(tree, options.preferInstallDependencies, {
+            languages: [
+                'typescript'
+            ]
+        });
+};
+export default pyAgentGatewayConnectionGenerator;
+
+//# sourceMappingURL=generator.js.map

package/src/py/agent/gateway-connection/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/py/agent/gateway-connection/generator.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  type GeneratorCallback,\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  type Tree,\n  updateProjectConfiguration,\n} from '@nx/devkit';\nimport { readAgentCoreGatewayMetadata } from '../../../agentcore-gateway/generator';\nimport {\n  addPythonCoreClient,\n  addPythonReExport,\n  ensurePythonAgentConnectionProject,\n  getPythonAgentConnectionModuleName,\n  getPythonAgentConnectionProject,\n  getPythonAgentConnectionProjectDir,\n  PY_MCP_FAMILY_CONNECTIONS,\n  resolveAgentFramework,\n} from '../../../utils/agent-connection/agent-connection';\nimport { addPythonDestructuredImport } from '../../../utils/ast';\nimport { formatFilesInSubtree } from '../../../utils/format';\nimport { installDependencies } from '../../../utils/install';\nimport { addGeneratorMetricsIfApplicable } from '../../../utils/metrics';\nimport { snakeCase } from '../../../utils/names';\nimport {\n  addDependencyToTargetIfNotPresent,\n  getGeneratorInfo,\n  type NxGeneratorInfo,\n  readProjectConfigurationUnqualified,\n} from '../../../utils/nx';\nimport {\n  addDependenciesToPyProjectToml,\n  addWorkspaceDependencyToPyProject,\n} from '../../../utils/py';\nimport type { PyAgentGatewayConnectionGeneratorSchema } from './schema';\n\nexport const PY_AGENT_GATEWAY_CONNECTION_GENERATOR_INFO: NxGeneratorInfo =\n  getGeneratorInfo(import.meta.filename);\n\nexport const pyAgentGatewayConnectionGenerator = async (\n  tree: Tree,\n  options: PyAgentGatewayConnectionGeneratorSchema,\n): Promise<GeneratorCallback> => {\n  const sourceProject = readProjectConfigurationUnqualified(\n    tree,\n    options.sourceProject,\n  );\n  const targetProject = readProjectConfigurationUnqualified(\n    tree,\n    options.targetProject,\n  );\n\n  const agentComponent = options.sourceComponent;\n  if (!agentComponent) {\n    throw new Error(\n      'sourceComponent must be provided for py#agent -> agentcore-gateway connections',\n    );\n  }\n  const gateway = readAgentCoreGatewayMetadata(targetProject);\n\n  if (gateway.protocol !== 'mcp') {\n    throw new Error(\n      `Gateway '${gateway.name}' has protocol='${gateway.protocol}'. Only MCP-protocol gateways are supported.`,\n    );\n  }\n  if (gateway.auth !== 'iam') {\n    throw new Error(\n      `Gateway '${gateway.name}' uses auth='${gateway.auth}'. Only IAM-authenticated gateways are supported in v1.`,\n    );\n  }\n  if (agentComponent.auth && agentComponent.auth !== 'iam') {\n    throw new Error(\n      `Agent '${agentComponent.name}' uses auth='${agentComponent.auth}'. Only IAM-authenticated agents can connect to IAM gateways.`,\n    );\n  }\n\n  const gatewayClassName = gateway.rc;\n  const gatewaySnakeCase = snakeCase(gatewayClassName);\n  // A gateway is its own standalone project, so it exposes plain serve / dev.\n  const gatewayServeTargetName = 'serve';\n  const gatewayDevTargetName = 'dev';\n\n  // The source agent's framework selects the client shape, dependencies and the\n  // agent.py transform — see PY_MCP_FAMILY_CONNECTIONS (keyed by framework, not a\n  // boolean, so a third framework is an additive entry there). A Gateway exposes\n  // its tools over MCP, so it reuses the same wiring as an MCP server connection.\n  const framework = resolveAgentFramework(agentComponent.framework);\n  const connection = PY_MCP_FAMILY_CONNECTIONS[framework];\n\n  await ensurePythonAgentConnectionProject(tree);\n  await addPythonCoreClient(tree, 'gateway', framework);\n\n  const agentConnectionProjectDir = getPythonAgentConnectionProjectDir(tree);\n  const agentConnectionModuleName = getPythonAgentConnectionModuleName(tree);\n\n  // Shared MCP transport + signed httpx auth deps, plus whatever extra deps the\n  // framework's MCP client needs (e.g. langchain-mcp-adapters for LangChain).\n  addDependenciesToPyProjectToml(tree, agentConnectionProjectDir, [\n    'boto3',\n    'httpx',\n    'mcp',\n    ...connection.deps,\n  ]);\n\n  const appDir = joinPathFragments(\n    agentConnectionProjectDir,\n    agentConnectionModuleName,\n    'app',\n  );\n  // Local mode points at the gateway project's local gateway port.\n  generateFiles(\n    tree,\n    joinPathFragments(\n      import.meta.dirname,\n      'files',\n      connection.appTemplateSubdir,\n    ),\n    appDir,\n    {\n      gatewaySnakeCase,\n      gatewayClassName,\n      agentConnectionModuleName,\n      gatewayPort: gateway.port,\n    },\n    { overwriteStrategy: OverwriteStrategy.KeepExisting },\n  );\n\n  const appInitPath = joinPathFragments(appDir, '__init__.py');\n  if (!tree.exists(appInitPath)) {\n    tree.write(appInitPath, '');\n  }\n\n  const moduleInitPath = joinPathFragments(\n    agentConnectionProjectDir,\n    agentConnectionModuleName,\n    '__init__.py',\n  );\n  await addPythonReExport(\n    tree,\n    moduleInitPath,\n    `.app.${gatewaySnakeCase}_client_${connection.clientModuleSuffix}`,\n    `${gatewayClassName}Client${connection.clientClassSuffix}`,\n  );\n\n  const agentSourceDir = joinPathFragments(\n    sourceProject.root,\n    agentComponent.path ?? 'src',\n  );\n  const agentFilePath = joinPathFragments(agentSourceDir, 'agent.py');\n\n  if (tree.exists(agentFilePath)) {\n    const clientClassName = `${gatewayClassName}Client${connection.clientClassSuffix}`;\n    const clientVarName = gatewaySnakeCase;\n\n    await addPythonDestructuredImport(\n      tree,\n      agentFilePath,\n      [clientClassName],\n      agentConnectionModuleName,\n    );\n    await connection.wireClientIntoAgent(\n      tree,\n      agentFilePath,\n      clientClassName,\n      clientVarName,\n    );\n  }\n\n  addWorkspaceDependencyToPyProject(\n    tree,\n    sourceProject,\n    getPythonAgentConnectionProject(tree),\n  );\n\n  const agentName = agentComponent.name ?? 'agent';\n  const serveTargetName = `${agentName}-serve`;\n  const devTargetName = `${agentName}-dev`;\n  let projectConfigChanged = false;\n  if (sourceProject.targets?.[serveTargetName]) {\n    addDependencyToTargetIfNotPresent(sourceProject, serveTargetName, {\n      projects: [targetProject.name],\n      target: gatewayServeTargetName,\n    });\n    projectConfigChanged = true;\n  }\n  if (sourceProject.targets?.[devTargetName]) {\n    addDependencyToTargetIfNotPresent(sourceProject, devTargetName, {\n      projects: [targetProject.name],\n      target: gatewayDevTargetName,\n    });\n    projectConfigChanged = true;\n  }\n  if (projectConfigChanged) {\n    updateProjectConfiguration(tree, sourceProject.name, sourceProject);\n  }\n\n  await addGeneratorMetricsIfApplicable(tree, [\n    PY_AGENT_GATEWAY_CONNECTION_GENERATOR_INFO,\n  ]);\n\n  await formatFilesInSubtree(tree);\n  return () =>\n    installDependencies(tree, options.preferInstallDependencies, {\n      languages: ['typescript'],\n    });\n};\n\nexport default pyAgentGatewayConnectionGenerator;\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","updateProjectConfiguration","readAgentCoreGatewayMetadata","addPythonCoreClient","addPythonReExport","ensurePythonAgentConnectionProject","getPythonAgentConnectionModuleName","getPythonAgentConnectionProject","getPythonAgentConnectionProjectDir","PY_MCP_FAMILY_CONNECTIONS","resolveAgentFramework","addPythonDestructuredImport","formatFilesInSubtree","installDependencies","addGeneratorMetricsIfApplicable","snakeCase","addDependencyToTargetIfNotPresent","getGeneratorInfo","readProjectConfigurationUnqualified","addDependenciesToPyProjectToml","addWorkspaceDependencyToPyProject","PY_AGENT_GATEWAY_CONNECTION_GENERATOR_INFO","filename","pyAgentGatewayConnectionGenerator","tree","options","sourceProject","targetProject","agentComponent","sourceComponent","Error","gateway","protocol","name","auth","gatewayClassName","rc","gatewaySnakeCase","gatewayServeTargetName","gatewayDevTargetName","framework","connection","agentConnectionProjectDir","agentConnectionModuleName","deps","appDir","dirname","appTemplateSubdir","gatewayPort","port","overwriteStrategy","KeepExisting","appInitPath","exists","write","moduleInitPath","clientModuleSuffix","clientClassSuffix","agentSourceDir","root","path","agentFilePath","clientClassName","clientVarName","wireClientIntoAgent","agentName","serveTargetName","devTargetName","projectConfigChanged","targets","projects","target","preferInstallDependencies","languages"],"mappings":"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"}

package/src/py/agent/gateway-connection/schema.d.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ export { };
+
+//# sourceMappingURL=schema.d.js.map

package/src/py/agent/gateway-connection/schema.d.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/py/agent/gateway-connection/schema.d.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { ComponentMetadata } from '../../../utils/nx';\n\nexport interface PyAgentGatewayConnectionGeneratorSchema {\n  sourceProject: string;\n  targetProject: string;\n  sourceComponent?: ComponentMetadata;\n  targetComponent?: ComponentMetadata;\n  preferInstallDependencies?: boolean;\n}\n"],"names":[],"mappings":"AAAA;;;CAGC,GAGD,WAMC"}

package/src/py/agent/gateway-connection/schema.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ComponentMetadata } from '../../../utils/nx';
+
+export interface PyAgentGatewayConnectionGeneratorSchema {
+  sourceProject: string;
+  targetProject: string;
+  sourceComponent?: ComponentMetadata;
+  targetComponent?: ComponentMetadata;
+  preferInstallDependencies?: boolean;
+}

package/src/py/agent/gateway-connection/schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "py#agent#gateway-connection",
+  "title": "py#agent#gateway-connection",
+  "description": "Connect a Python Agent to an AgentCore Gateway",
+  "type": "object",
+  "properties": {
+    "sourceProject": {
+      "type": "string",
+      "description": "The Python Agent project"
+    },
+    "targetProject": {
+      "type": "string",
+      "description": "The AgentCore Gateway project"
+    },
+    "sourceComponent": {
+      "type": "string",
+      "description": "The agent component in the source project"
+    },
+    "targetComponent": {
+      "type": "string",
+      "description": "The gateway component in the target project"
+    },
+    "preferInstallDependencies": {
+      "type": "boolean",
+      "description": "Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.",
+      "default": true
+    }
+  },
+  "required": ["sourceProject", "targetProject"]
+}

package/src/py/agent/generator.d.ts

@@ -2,9 +2,9 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { GeneratorCallback, Tree } from '@nx/devkit';
-import { PyAgentGeneratorSchema } from './schema';
-import { NxGeneratorInfo } from '../../utils/nx';
+import { type GeneratorCallback, type Tree } from '@nx/devkit';
+import { type NxGeneratorInfo } from '../../utils/nx';
+import type { PyAgentGeneratorSchema } from './schema';
 export declare const PY_AGENT_GENERATOR_INFO: NxGeneratorInfo;
 export declare const pyAgentGenerator: (tree: Tree, options: PyAgentGeneratorSchema) => Promise<GeneratorCallback>;
 export default pyAgentGenerator;