@aws/nx-plugin-mcp 1.0.0-rc.73 → 1.0.0-rc.75

package/docs/get_started/concepts.mdx

@@ -5,7 +5,7 @@ description: Key concepts.
 import Link from '@components/link.astro';
 import FrameworkLogos from '@components/framework-logos.astro';
 
-The `@aws/nx-plugin` is an [Nx](https://nx.dev/) plugin that provides a toolkit for building and deploying full-stack applications on AWS. It gives you a collection of [Generators](#generators) which scaffold production-ready application code _and_ the infrastructure to deploy it — type-safe, locally runnable, and ready to ship.
+The `@aws/nx-plugin` is an [Nx](https://nx.dev/) plugin that provides a toolkit for building and deploying full-stack applications on AWS. It gives you a collection of [Generators](#generators) which scaffold best-practice application code _and_ the infrastructure to deploy it — type-safe, locally runnable, and deployable from the start, getting you closer to production.
 
 Rather than starting from a blank page, you (or your AI agent) pick the components you need — APIs, websites, authentication, AI agents, infrastructure — provide a few configuration options, and the plugin generates best-practice starter code. It even wires projects together for you (including updating existing files via AST transforms) to produce type-safe clients between your frontend and backend.
 

package/docs/get_started/tutorials/dungeon-game/1.mdx

@@ -452,6 +452,8 @@ The `py#agent` generates these files:
         - main.py entrypoint for your agent in Bedrock AgentCore Runtime
         - agent.py defines an example agent and tools
         - session.py resolves a SessionManager for persisting conversation state
+        - middleware/
+          - session_id_middleware.py binds the inbound AgentCore session ID for the request
         - Dockerfile defines the docker image for deployment to AgentCore Runtime
   - common/constructs/
     - src
@@ -492,6 +494,29 @@ Refer to tools as your 'spellbook'.
 
 This creates an example Strands agent and defines a subtraction tool. `log_model_errors` and `log_tool_errors` are hooks from the shared `dungeon_adventure_agent_connection` project that log model/tool failures instead of letting them fail silently.
 
+```python
+# agent/middleware/session_id_middleware.py
+import uuid
+
+from fastapi import Request
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from dungeon_adventure_agent_connection import session_id_context
+
+SESSION_ID_HEADER = "x-amzn-bedrock-agentcore-runtime-session-id"
+
+
+class SessionIdMiddleware(BaseHTTPMiddleware):
+    """Bind the session ID for this request so downstream MCP / A2A clients forward it on outbound calls."""
+
+    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)
+```
+
+The `SessionIdMiddleware` binds the inbound AgentCore runtime session ID onto a `ContextVar` for the duration of the request.
+
 ```python
 # agent/main.py
 import logging
@@ -505,15 +530,13 @@ from dungeon_adventure_agent_connection import get_current_session_id, session_i
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import StreamingResponse
-from starlette.middleware.base import BaseHTTPMiddleware
 
 from .agent import get_agent
+from .middleware.session_id_middleware import SESSION_ID_HEADER, SessionIdMiddleware
 from .session import get_session_manager
 
 logging.basicConfig(level=logging.INFO)
 
-SESSION_ID_HEADER = "x-amzn-bedrock-agentcore-runtime-session-id"
-
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
@@ -529,15 +552,6 @@ async def lifespan(app: FastAPI):
         yield
 
 
-class _SessionIdMiddleware(BaseHTTPMiddleware):
-    """Bind the session ID for this request so downstream MCP / A2A clients forward it on outbound calls."""
-
-    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 = FastAPI(title="AWS Strands - StoryAgent", lifespan=lifespan)
 app.add_middleware(
     CORSMiddleware,
@@ -546,7 +560,7 @@ app.add_middleware(
     allow_methods=["*"],
     allow_headers=["*"],
 )
-app.add_middleware(_SessionIdMiddleware)
+app.add_middleware(SessionIdMiddleware)
 
 
 @app.post("/invocations")
@@ -589,7 +603,7 @@ async def ping():
     return {"status": "healthy"}
 ```
 
-This is the entrypoint for the agent. Because we selected `--protocol=ag-ui`, the generator wraps our Strands `Agent` with `StrandsAgent` from [`ag_ui_strands`](https://docs.copilotkit.ai/aws-strands/integration) and mounts it on a FastAPI app that speaks the [AG-UI protocol](https://docs.copilotkit.ai/aws-strands/protocol) — this is what CopilotKit will talk to from the React website. The agent is built inside a `lifespan` handler — not at import time — so container startup, not module import, owns construction, and each AgentCore session gets its own container. The `_SessionIdMiddleware` binds the inbound AgentCore runtime session ID onto a `ContextVar` so any downstream MCP/A2A client we wire up later (e.g. the Inventory MCP server in <Link path="get_started/tutorials/dungeon-game/2">Module 2</Link>) automatically forwards it on its outbound calls. Since AG-UI caches one Strands agent per `thread_id`, we plug in a `session_manager_provider` rather than the template agent's own session manager — this gives each thread its own `SessionManager` so conversation history persists across turns. That `get_session_manager()` function comes from a generated `session.py` sibling: deployed, it returns a `strands.session.S3SessionManager` backed by an S3 bucket the generator provisions automatically; under `agent-dev` (`LOCAL_DEV=true`) it always returns a `FileSessionManager` writing to a local temp directory instead, regardless of deployed configuration.
+This is the entrypoint for the agent. Because we selected `--protocol=ag-ui`, the generator wraps our Strands `Agent` with `StrandsAgent` from [`ag_ui_strands`](https://docs.copilotkit.ai/aws-strands/integration) and mounts it on a FastAPI app that speaks the [AG-UI protocol](https://docs.copilotkit.ai/aws-strands/protocol) — this is what CopilotKit will talk to from the React website. The agent is built inside a `lifespan` handler — not at import time — so container startup, not module import, owns construction, and each AgentCore session gets its own container. The `SessionIdMiddleware` we saw above forwards the inbound AgentCore runtime session ID so any downstream MCP/A2A client we wire up later (e.g. the Inventory MCP server in <Link path="get_started/tutorials/dungeon-game/2">Module 2</Link>) automatically forwards it on its outbound calls. Since AG-UI caches one Strands agent per `thread_id`, we plug in a `session_manager_provider` rather than the template agent's own session manager — this gives each thread its own `SessionManager` so conversation history persists across turns. That `get_session_manager()` function comes from a generated `session.py` sibling: deployed, it returns a `strands.session.S3SessionManager` backed by an S3 bucket the generator provisions automatically; under `agent-dev` (`LOCAL_DEV=true`) it always returns a `FileSessionManager` writing to a local temp directory instead, regardless of deployed configuration.
 
 ```ts
 // common/constructs/src/app/agents/story-agent/story-agent.ts

package/docs/guides/py-agent.mdx

@@ -51,6 +51,9 @@ The generator will add the following files to your existing Python project. The
         - init.py FastAPI application setup with CORS and error handling middleware
         - agent.py Main agent definition with sample tools
         - session.py Resolves the framework-specific session persistence implementation
+        - middleware/
+          - \_\_init\_\_.py Python package initialization
+          - session_id_middleware.py Binds the inbound AgentCore session ID for the request
         - main.py FastAPI entry point for Bedrock AgentCore Runtime
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
     - pyproject.toml Updated with Strands dependencies
@@ -70,6 +73,9 @@ The entry point exposes your agent over the A2A protocol (Strands uses the [Stra
         - \_\_init\_\_.py Python package initialization
         - agent.py Main agent definition with sample tools
         - session.py Resolves the framework-specific session persistence implementation
+        - middleware/
+          - \_\_init\_\_.py Python package initialization
+          - session_id_middleware.py Binds the inbound AgentCore session ID for the request
         - main.py A2A server entry point
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
     - pyproject.toml Updated with framework and A2A dependencies
@@ -89,6 +95,9 @@ The entry point exposes your agent via the [AG-UI](https://docs.ag-ui.com/) prot
         - \_\_init\_\_.py Python package initialization
         - agent.py Main agent definition with sample tools
         - session.py Resolves the framework-specific session persistence implementation
+        - middleware/
+          - \_\_init\_\_.py Python package initialization
+          - session_id_middleware.py Binds the inbound AgentCore session ID for the request
         - main.py AG-UI server entry point
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
     - pyproject.toml Updated with framework and AG-UI dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.73",
+  "version": "1.0.0-rc.75",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",