@aws/nx-plugin-mcp 1.0.0-rc.95 → 1.0.0-rc.97

package/docs/guides/py-agent.mdx

@@ -163,15 +163,25 @@ You can edit `agent.py` to add tools, configure the model and customize the syst
 
 Tools are functions that the AI agent can call to perform actions. Both frameworks use a decorator-based approach for defining tools, derive the tool name and description from the function name and docstring, and generate the input schema from your type hints.
 
+Define the tool, then add it to the `tools` list inside `get_agent()`:
+
 <Tabs syncKey="agent-framework">
 <TabItem label="Strands" _filter={{ framework: 'strands' }}>
-```python
+```python title="packages/my-project/my_module/agent/agent.py" {16-20,32}
+from contextlib import contextmanager
+
 from strands import Agent, tool
+from strands.hooks import HookCallback, HookProvider
+from strands_tools import current_time
+from my_scope_agent_connection import log_model_errors, log_tool_errors
+
+from .session import get_session_manager
+
 
 @tool
-def calculate_sum(numbers: list[int]) -> int:
-    """Calculate the sum of a list of numbers"""
-    return sum(numbers)
+def subtract(a: int, b: int) -> int:
+    return a - b
+
 
 @tool
 def get_weather(city: str) -> str:
@@ -179,23 +189,41 @@ def get_weather(city: str) -> str:
     # Your weather API integration here
     return f"Weather in {city}: Sunny, 25°C"
 
-# Add tools to your agent
-agent = Agent(
-    system_prompt="You are a helpful assistant with access to various tools.",
-    tools=[calculate_sum, get_weather],
-)
+
+AGENT_HOOKS: list[HookProvider | HookCallback] = [log_model_errors, log_tool_errors]
+
+
+@contextmanager
+def get_agent():
+    yield Agent(
+        name="MyAgent",
+        description="MyAgent Strands Agent",
+        system_prompt="You are a helpful assistant with access to various tools.",
+        tools=[subtract, current_time, get_weather],
+        hooks=AGENT_HOOKS,
+        session_manager=get_session_manager(),
+    )
 ```
 </TabItem>
 <TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
-```python
+```python title="packages/my-project/my_module/agent/agent.py" {19-23,30}
+import os
+
 from langchain.agents import create_agent
 from langchain_aws import ChatBedrockConverse
 from langchain_core.tools import tool
 
+from .session import get_checkpointer
+
+REGION = os.environ.get("AWS_REGION", "us-east-1")
+MODEL_ID = os.environ.get("MODEL_ID", "global.anthropic.claude-haiku-4-5-20251001-v1:0")
+
+
 @tool
-def calculate_sum(numbers: list[int]) -> int:
-    """Calculate the sum of a list of numbers"""
-    return sum(numbers)
+def subtract(a: int, b: int) -> int:
+    """Subtract b from a."""
+    return a - b
+
 
 @tool
 def get_weather(city: str) -> str:
@@ -203,12 +231,15 @@ def get_weather(city: str) -> str:
     # Your weather API integration here
     return f"Weather in {city}: Sunny, 25°C"
 
-# Add tools to your agent
-agent = create_agent(
-    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
-    tools=[calculate_sum, get_weather],
-    system_prompt="You are a helpful assistant with access to various tools.",
-)
+
+def get_agent():
+    model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
+    return create_agent(
+        model=model,
+        tools=[subtract, get_weather],
+        system_prompt="You are a helpful assistant with access to various tools.",
+        checkpointer=get_checkpointer(),
+    )
 ```
 </TabItem>
 </Tabs>
@@ -217,28 +248,45 @@ agent = create_agent(
 
 <Tabs syncKey="agent-framework">
 <TabItem label="Strands" _filter={{ framework: 'strands' }}>
-Strands provides a collection of pre-built tools through the `strands-tools` package:
-
-```python
-from strands_tools import current_time, http_request, file_read
-
-agent = Agent(
-    system_prompt="You are a helpful assistant.",
-    tools=[current_time, http_request, file_read],
-)
+Strands provides a collection of pre-built tools through the `strands-agents-tools` package, which the generator already adds to your project's `pyproject.toml`. Import the tools you want and add them to `get_agent()`:
+
+```python title="packages/my-project/my_module/agent/agent.py" {1,11}
+from strands_tools import current_time, file_read, http_request
+
+# ...
+
+@contextmanager
+def get_agent():
+    yield Agent(
+        name="MyAgent",
+        description="MyAgent Strands Agent",
+        system_prompt="You are a helpful assistant.",
+        tools=[current_time, file_read, http_request],
+        hooks=AGENT_HOOKS,
+        session_manager=get_session_manager(),
+    )
 ```
 </TabItem>
 <TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
-LangChain provides a large ecosystem of [tools and integrations](https://docs.langchain.com/oss/python/integrations/tools). Install the relevant integration package, then pass the tools to `create_agent`:
+LangChain provides a large ecosystem of [tools and integrations](https://docs.langchain.com/oss/python/integrations/tools), each distributed in its own package. The generator does not add these, so install the one you need first — for example `langchain-community`, which the search tool below comes from:
 
-```python
+<NxCommands commands={['run <project-name>:add langchain-community']} />
+
+Then import the tools and add them to `get_agent()`:
+
+```python title="packages/my-project/my_module/agent/agent.py" {1,9}
 from langchain_community.tools import DuckDuckGoSearchRun
 
-agent = create_agent(
-    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
-    tools=[DuckDuckGoSearchRun()],
-    system_prompt="You are a helpful assistant.",
-)
+# ...
+
+def get_agent():
+    model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
+    return create_agent(
+        model=model,
+        tools=[DuckDuckGoSearchRun()],
+        system_prompt="You are a helpful assistant.",
+        checkpointer=get_checkpointer(),
+    )
 ```
 </TabItem>
 </Tabs>
@@ -247,33 +295,50 @@ agent = create_agent(
 
 <Tabs syncKey="agent-framework">
 <TabItem label="Strands" _filter={{ framework: 'strands' }}>
-By default, Strands agents use Claude Sonnet 4.6 on Amazon Bedrock, but you can customize the model provider. See the [Strands documentation on model providers](https://strandsagents.com/docs/user-guide/concepts/model-providers/) for configuration options:
+The generated agent uses the default Strands model on Amazon Bedrock. To configure it, pass a `model` to the `Agent`. See the [Strands documentation on model providers](https://strandsagents.com/docs/user-guide/concepts/model-providers/) for the available providers and their options:
 
-```python
-from strands import Agent
+```python title="packages/my-project/my_module/agent/agent.py" {1,5-9,14}
 from strands.models import BedrockModel
 
-# Create a BedrockModel
-bedrock_model = BedrockModel(
+# ...
+
+MODEL = BedrockModel(
     model_id="anthropic.claude-sonnet-4-20250514-v1:0",
     region_name="us-west-2",
     temperature=0.3,
 )
 
-agent = Agent(model=bedrock_model)
+@contextmanager
+def get_agent():
+    yield Agent(
+        model=MODEL,
+        name="MyAgent",
+        description="MyAgent Strands Agent",
+        system_prompt="You are a helpful assistant.",
+        tools=[subtract, current_time],
+        hooks=AGENT_HOOKS,
+        session_manager=get_session_manager(),
+    )
 ```
 </TabItem>
 <TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
-LangChain agents use a [`ChatBedrockConverse`](https://docs.langchain.com/oss/python/integrations/chat/bedrock_converse) model. The generated agent reads the model id and region from the `MODEL_ID` and `AWS_REGION` environment variables, but you can configure the model directly in `agent.py`:
-
-```python
-from langchain_aws import ChatBedrockConverse
-
-model = ChatBedrockConverse(
-    model="anthropic.claude-sonnet-4-20250514-v1:0",
-    region_name="us-west-2",
-    temperature=0.3,
-)
+LangChain agents use a [`ChatBedrockConverse`](https://docs.langchain.com/oss/python/integrations/chat/bedrock_converse) model. The generated agent reads the model id and region from the `MODEL_ID` and `AWS_REGION` environment variables, which the infrastructure sets for the deployed agent. To configure the model further, add arguments where it is constructed in `get_agent()`:
+
+```python title="packages/my-project/my_module/agent/agent.py" {4-8}
+# ...
+
+def get_agent():
+    model = ChatBedrockConverse(
+        model=MODEL_ID,
+        region_name=REGION,
+        temperature=0.3,
+    )
+    return create_agent(
+        model=model,
+        tools=[subtract],
+        system_prompt="You are a helpful assistant.",
+        checkpointer=get_checkpointer(),
+    )
 ```
 </TabItem>
 </Tabs>
@@ -425,6 +490,10 @@ If you have added multiple components to your project (agents, MCP servers, etc.
 
 This uses `uv run` to execute your Agent using the [Bedrock AgentCore Python SDK](https://github.com/aws/bedrock-agentcore-sdk-python).
 
+The agent listens on a port assigned from the workspace pool when it was generated. Read it from `metadata.ports` in the project's `project.json`, or from the `--port` flag in the `<your-agent-name>-dev` target's command. The examples below use `8081`, the port a first HTTP agent is assigned in a fresh workspace.
+
+A `<your-agent-name>-serve` target is also generated, which runs the agent against your deployed infrastructure and therefore requires `RUNTIME_CONFIG_APP_ID` to be set. See the <Link path="guides/local-development">Local Development</Link> guide for the difference between `dev` and `serve`.
+
 ### Chat with Your Agent
 
 The generator configures a `<your-agent-name>-chat` Nx target that drops you into an interactive terminal chat with your agent.
@@ -439,11 +508,13 @@ Then, in another terminal, start the chat:
 
 The generator emits a `scripts/<your-agent-name>/chat.ts` for every protocol. It connects to the local agent by default, or to your deployed agent when `RUNTIME_CONFIG_APP_ID` is set (see [Chat with your deployed agent](#chat-with-your-deployed-agent) below).
 
-For **HTTP** agents, the chat script uses a type-safe TypeScript client generated from the agent's OpenAPI spec. The generator also emits:
+<OptionFilter when={{ protocol: 'http' }} description="OpenAPI client generation for the chat script">
+For HTTP agents, the chat script uses a type-safe TypeScript client generated from the agent's OpenAPI spec. The generator also emits:
 
-- `scripts/<your-agent-name>_openapi.py` — a small script that exports the agent's OpenAPI spec
+- `scripts/<your_agent_name>_openapi.py` — a small script that exports the agent's OpenAPI spec (named with your agent's name in `snake_case`)
 - An `<your-agent-name>-openapi` Nx target that runs it
 - An `<your-agent-name>-generate-client` Nx target that produces a type-safe TypeScript client under `scripts/<your-agent-name>/generated/`
+</OptionFilter>
 
 When you customize the agent's input shape (e.g. add new fields to `InvokeInput`), update `chat.ts` to pass the new fields when invoking the agent and the rest works automatically.
 
@@ -567,7 +638,11 @@ When running locally (`LOCAL_DEV=true`, set automatically by the `-dev` target),
 <OptionFilter when={{ protocol: 'http' }} description="FastAPI HTTP invocation details">
 ### Invoke the Local Server
 
-To invoke an Agent running locally via the `<your-agent-name>-serve` target, you can send a simple POST request to `/invocations` on the port your local agent is running on. For example, with `curl`:
+Start your agent with the `<your-agent-name>-dev` target:
+
+<NxCommands commands={['agent-dev your-project']} />
+
+Then send a POST request to `/invocations` on the port your local agent is running on. Substitute the port assigned to your agent — read it from `metadata.ports` in the project's `project.json`, or from the `--port` flag in the `<your-agent-name>-dev` target's command. A first HTTP agent in a fresh workspace is assigned `8081`:
 
 ```bash
 curl -N -X POST http://localhost:8081/invocations \

package/docs/guides/py-mcp-server.mdx

@@ -157,7 +157,9 @@ If you would like to run your MCP server locally using [Streamable HTTP transpor
 
 <NxCommands commands={['your-server-name-serve your-project']} />
 
-This command uses `uv run uvicorn --reload` to run your MCP server with HTTP transport (typically on port `8000`), and automatically restarts when files change.
+This command uses `uv run uvicorn --reload` to run your MCP server with HTTP transport, and automatically restarts when files change.
+
+Each MCP server is assigned its own port, starting at `8000`, so several servers can run side by side in the same workspace. Read the port your server listens on from its `<your-server-name>-serve` target in `project.json`.
 
 <OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} description="Bedrock AgentCore Runtime deployment details">
 ## Deploying Your MCP Server to Bedrock AgentCore Runtime

package/docs/guides/py-rdb.mdx

@@ -33,22 +33,31 @@ The generator creates the following project structure in the `<directory>/<name>
 
 <FileTree>
   - \<name>
-    - \_\_init\_\_.py Package exports (`get_engine`, `session_context`)
+    - \_\_init\_\_.py Package exports
     - connection.py Database engine and session factory with IAM authentication
     - utils.py Runtime config and local development helpers
     - migration_handler.py Lambda handler that runs Alembic migrations during deployment
     - create_db_user_handler.py Lambda handler that creates the application database user during deployment
     - models
+      - \_\_init\_\_.py Model exports, imported by Alembic to discover your tables
       - example.py Example SQLModel table definition
   - migrations
     - versions Alembic-generated migration scripts
     - env.py Alembic environment (connects to the database)
     - script.py.mako Alembic migration script template
+  - tests
+    - \_\_init\_\_.py Module initialisation
+    - conftest.py Test configuration
+    - test_noop.py Placeholder test
   - alembic.ini Alembic configuration
   - config.json Local development connection details and runtime config key
   - Dockerfile.migration Container image for the migration handler
   - Dockerfile.create-db-user Container image for the create-db-user handler
   - project.json Project configuration and build targets
+  - pyproject.toml Packaging configuration file used by UV
+  - README.md Project README
+  - .python-version Contains the project's Python version
+  - .gitignore Files excluded from version control
 </FileTree>
 
 Local development scripts are shared across all database projects and generated into `packages/common/scripts/`:
@@ -137,12 +146,12 @@ Import `session_context` from your database package and use it as an async conte
 ```python
 from sqlmodel import select
 
-from my_scope.my_db import session_context
-from my_scope.my_db.models.example import ExampleModel
+from my_scope_my_db import session_context
+from my_scope_my_db.models.example import ExampleModel
 
 async def example():
     async with session_context() as session:
-        results = (await session.execute(select(ExampleModel))).all()
+        results = (await session.execute(select(ExampleModel))).scalars().all()
 ```
 
 The database client automatically:

package/docs/guides/python-lambda-function.mdx

@@ -90,7 +90,8 @@ metrics: Metrics = Metrics()
 tracer: Tracer = Tracer()
 
 @tracer.capture_lambda_handler
-@metrics.log_metrics
+@logger.inject_lambda_context
+@metrics.log_metrics(capture_cold_start_metric=True)
 @event_parser(model=EventBridgeModel)
 def lambda_handler(event: EventBridgeModel, context: LambdaContext):
     logger.info("Received event", extra={"event": event.model_dump() })
@@ -127,11 +128,10 @@ def lambda_handler(event: EventBridgeModel, context: LambdaContext):
 It is recommended to set the correlation id for all unique requests for easier debugging and monitoring. Please refer to the [aws powertools logger](https://docs.powertools.aws.dev/lambda/python/2.22.0/core/logger/#setting-a-correlation-id) documentation for correlation id best practices.
 :::
 
-The logger automatically includes:
+The handler is decorated with [`@logger.inject_lambda_context`](https://docs.powertools.aws.dev/lambda/python/latest/core/logger/#inject-lambda-context), so every log record it emits also carries:
 
-- Event requests
-- Lambda context information
-- Cold start indicators
+- `function_name`, `function_memory_size`, `function_arn` and `function_request_id` from the Lambda context
+- `cold_start`, indicating whether the invocation initialised a new execution environment
 
 #### Tracing
 
@@ -157,9 +157,9 @@ def lambda_handler(event: EventBridgeModel, context: LambdaContext):
 
 Default metrics include:
 
-- Invocation counts
-- Success/failure counts
-- Cold start metrics
+- `InvocationCount`, added on every invocation
+- `SuccessCount` and `ErrorCount`, added by the handler's `try`/`except`
+- `ColdStart`, emitted by [`@metrics.log_metrics(capture_cold_start_metric=True)`](https://docs.powertools.aws.dev/lambda/python/latest/core/metrics/#capturing-cold-start-metric) when the invocation initialises a new execution environment
 
 ### Type Safety
 

package/docs/guides/python-project.mdx

@@ -3,11 +3,35 @@ title: Python Projects
 description: Reference documentation for Python Projects
 generator: py#project
 ---
-import { FileTree } from '@astrojs/starlight/components';
+import { Code, FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
 import NxCommands from '@components/nx-commands.astro';
 import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import { LAMBDA_RUNTIME_VERSIONS } from '../../../../../../packages/nx-plugin/src/utils/versions';
+
+export const bundleTarget = `{
+  "targets": {
+    "bundle": {
+      "dependsOn": ["bundle-x86"]
+    },
+    "bundle-x86": {
+      "cache": true,
+      "inputs": ["production", "^production"],
+      "executor": "nx:run-commands",
+      "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle-x86"],
+      "options": {
+        "commands": [
+          "uv export --frozen --no-dev --no-editable --project {projectRoot} --package my_scope.my_library -o dist/{projectRoot}/bundle-x86/requirements.txt",
+          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux_2_28 --python-version ${LAMBDA_RUNTIME_VERSIONS.python} --target dist/{projectRoot}/bundle-x86 -r dist/{projectRoot}/bundle-x86/requirements.txt"
+        ],
+        "parallel": false
+      },
+      "dependsOn": ["compile"]
+    }
+  }
+}`;
 
 The Python project generator can be used to create a modern [Python](https://www.python.org/) library or application configured with best practices, managed with [UV](https://docs.astral.sh/uv/), a single lockfile and virtual environment in an [UV workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/), [pytest](https://docs.pytest.org/en/stable/) for running tests, [Ruff](https://docs.astral.sh/ruff/) for static analysis, and [ty](https://docs.astral.sh/ty/) for type checking.
 
@@ -87,30 +111,9 @@ This will add the dependency to your project's `pyproject.toml` file, and update
 
 #### Runtime Code
 
-When you use your Python project as runtime code (for example as the handler for an AWS lambda function), you will need to create a bundle of the source code and all its dependencies. You can achieve this by adding a target such as the following to your `project.json` file:
+When you use your Python project as runtime code (for example as the handler for an AWS lambda function), you will need to create a bundle of the source code and all its dependencies. The <Link path="guides/python-lambda-function">`py#lambda-function`</Link>, <Link path="guides/fastapi">`py#api`</Link> and <Link path="guides/py-mcp-server">`py#mcp-server`</Link> generators add this for you. To add one by hand, add targets such as the following to your `project.json` file, matching the shape those generators vend:
 
-```json title="project.json"
-{
-  ...
-  "targets": {
-    ...
-    "bundle": {
-      "cache": true,
-      "inputs": ["production", "^production"],
-      "executor": "nx:run-commands",
-      "outputs": ["{workspaceRoot}/dist/packages/my_library/bundle"],
-      "options": {
-        "commands": [
-          "uv export --frozen --no-dev --no-editable --project packages/my_library --package my_scope.my_library -o dist/packages/my_library/bundle/requirements.txt",
-          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux_2_28 --python `uv python pin` --target dist/packages/my_library/bundle -r dist/packages/my_library/bundle/requirements.txt"
-        ],
-        "parallel": false
-      },
-      "dependsOn": ["compile"]
-    },
-  },
-}
-```
+<Code lang="json" title="project.json" code={bundleTarget} />
 
 ### Installing
 
@@ -158,7 +161,7 @@ The deploy targets depend on `assemble`, so deploying builds only what it is abo
 
 ### Writing Tests
 
-Tests should be written in the `test` directory within your project, in python files prefixed with `test_`, for example:
+Tests should be written in the `tests` directory within your project, in python files prefixed with `test_`, for example:
 
 <FileTree>
   - my_library

package/docs/guides/react-website-auth.mdx

@@ -106,9 +106,9 @@ browser -> backend: IAM/Cognito
 
 #### Threat protection
 
-The User Pool is created on the Cognito [Plus feature plan](https://docs.aws.amazon.com/cognito/latest/developerguide/feature-plans-features-plus.html) with [threat protection](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-settings-threat-protection.html) set to `AUDIT` mode for standard authentication. In audit mode, Cognito assigns a risk level to each sign-in and logs the assessment to CloudWatch without blocking users.
+The User Pool is created on the Cognito [Plus feature plan](https://docs.aws.amazon.com/cognito/latest/developerguide/feature-plans-features-plus.html) with [threat protection](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-settings-threat-protection.html) in **audit-only** enforcement for standard authentication. In audit-only, Cognito assigns a risk level to each sign-in and records the assessment without blocking users.
 
-Once you have observed the risk assessments for your users, you can switch to full-function enforcement to automatically respond to risky activity (for example requiring MFA or blocking sign-in):
+Once you have observed the risk assessments for your users, you can switch to full-function enforcement to automatically respond to risky activity (for example requiring MFA or blocking sign-in), then configure the response per risk level via [adaptive authentication](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-settings-adaptive-authentication.html):
 
 <Infrastructure>
 <Fragment slot="cdk">
@@ -187,13 +187,13 @@ This rule flags loopback addresses in query arguments as [SSRF](https://docs.aws
 You will need to add the user identity infrastructure to your stack, declaring it _before_ the website:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts" {3,9}
-import { Stack } from 'aws-cdk-lib';
+import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { MyWebsite, UserIdentity } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
-  constructor(scope: Construct, id: string) {
-    super(scope, id);
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
 
     new UserIdentity(this, 'Identity');
 
@@ -256,13 +256,13 @@ In order to grant authenticated users access to perform certain actions, such as
 <Infrastructure>
 <Fragment slot="cdk">
 ```ts title="packages/infra/src/stacks/application-stack.ts" {12}
-import { Stack } from 'aws-cdk-lib';
+import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { MyWebsite, UserIdentity, MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
-  constructor(scope: Construct, id: string) {
-    super(scope, id);
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
 
     const identity = new UserIdentity(this, 'Identity');
     const api = new MyApi(this, 'MyApi', {