@aws/nx-plugin-mcp 1.0.0-rc.4 → 1.0.0-rc.41

package/docs/guides/connection/py-agent-a2a.mdx

@@ -7,7 +7,7 @@ when:
     - ts#agent
     - py#agent
 ---
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
 import Link from '@components/link.astro';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
@@ -22,7 +22,7 @@ The generator sets up all the necessary wiring so your agent can discover and in
 
 Before using this generator, ensure you have:
 
-1. A Python project with a <Link path="guides/py-agent">Strands Agent</Link> component (any protocol)
+1. A Python project with a <Link path="guides/py-agent">Python Agent</Link> component (Strands or LangChain)
 2. A project with an Agent component generated with `--protocol=A2A` and `--auth=IAM` (either <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link>)
 3. Both components created with `infra: agentcore`
 
@@ -48,30 +48,37 @@ The generator creates a shared `agent_connection` Python project at `packages/co
   - \<scope>\_agent\_connection
     - \_\_init\_\_.py Re-exports per-connection clients
     - core
-      - agentcore\_a2a\_client.py Core AgentCore A2A client with SigV4 authentication
+      - agentcore\_endpoints.py Framework-agnostic ARN/URL resolution
+      - agentcore\_a2a\_client\_config.py Framework-agnostic A2A client config (signed `ClientConfig`)
+      - agentcore\_a2a\_client\_\<framework>.py A2A client wrapping the config for your agent's framework
+      - auth/ Framework-agnostic SigV4 / session-forwarding `httpx.Auth`
     - app
-      - \<target\_agent\_name>\_client.py Per-connection client for each A2A agent
+      - \<target\_agent\_name>\_client\_\<framework>.py Per-connection A2A client for each A2A agent
 
 </FileTree>
 
+The client suffix matches your agent's framework (`_strands` or `_langchain`). Both wrap the same framework-agnostic signed `ClientConfig`: the Strands client wraps a Strands `A2AAgent`, while the LangChain client drives the [a2a SDK](https://pypi.org/project/a2a-sdk/) directly.
+
 Additionally, the generator:
 - Transforms your agent's `agent.py` to register the remote A2A agent as a tool using `@tool`
 - Adds the `agent_connection` project as a workspace dependency of your agent project
-- Updates the agent's `serve-local` target to depend on the target agent's `serve-local` target
+- Updates the agent's `dev` target to depend on the target agent's `dev` target
 
 ## Using the Connected A2A Agent
 
-The generator transforms your agent's `agent.py` to wrap the remote A2A agent as a tool:
+The generator transforms your agent's `agent.py` to wrap the remote A2A agent as a tool. The remote agent is registered with a `@tool`-decorated delegate — the decorator's import and the agent constructor differ by framework:
 
-```python title="packages/my-project/my_module/agent/agent.py" {4,9-15,21}
+<Tabs syncKey="agent-framework">
+<TabItem label="Strands" _filter={{ framework: 'strands' }}>
+```python title="packages/my-project/my_module/agent/agent.py" {4,8-13,15}
 from contextlib import contextmanager
 from strands import Agent, tool
 
-from my_scope_agent_connection import RemoteAgentClient
+from my_scope_agent_connection import RemoteAgentClientStrands
 
 @contextmanager
-def get_agent(session_id: str):
-    remote_agent = RemoteAgentClient.create(session_id=session_id)
+def get_agent():
+    remote_agent = RemoteAgentClientStrands.create()
 
     @tool
     def ask_remote_agent(prompt: str) -> str:
@@ -83,10 +90,35 @@ def get_agent(session_id: str):
         tools=[ask_remote_agent],
     )
 ```
+</TabItem>
+<TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
+```python title="packages/my-project/my_module/agent/agent.py" {4,7-12,14}
+from langchain.agents import create_agent
+from langchain_aws import ChatBedrockConverse
+from langchain_core.tools import tool
+
+from my_scope_agent_connection import RemoteAgentClientLangChain
+
+def get_agent():
+    remote_agent = RemoteAgentClientLangChain.create()
+
+    @tool
+    def ask_remote_agent(prompt: str) -> str:
+        """Delegate a question to the remote RemoteAgent A2A agent and return its reply."""
+        return str(remote_agent(prompt))
+
+    return create_agent(
+        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
+        system_prompt="...",
+        tools=[ask_remote_agent],
+    )
+```
+</TabItem>
+</Tabs>
 
-The `session_id` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
+Both clients are directly callable, returning the remote agent's reply, and wrap an `httpx.AsyncClient` that signs requests with SigV4 when deployed to AWS and uses a plain `http://localhost:<port>/` endpoint when `LOCAL_DEV=true`. The Strands client wraps a Strands `A2AAgent`; the LangChain client drives the a2a SDK directly.
 
-Under the hood, `RemoteAgentClient.create(session_id=...)` returns a Strands `A2AAgent` configured with an `httpx.AsyncClient` that signs requests with SigV4 when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `SERVE_LOCAL=true`.
+The AgentCore session ID is propagated to the remote agent automatically via the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header, regardless of framework: the agent server binds the inbound request's session into an async context, and the connection client's signed `httpx.Auth` stamps it on every outbound call — ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
 
 ## Infrastructure
 
@@ -94,12 +126,12 @@ Under the hood, `RemoteAgentClient.create(session_id=...)` returns a Strands `A2
 
 ## Local Development
 
-The generator configures the host agent's `serve-local` target to:
+The generator configures the host agent's `dev` target to:
 1. Start the connected A2A agent(s) automatically
-2. Set `SERVE_LOCAL=true` so the generated client connects directly to `http://localhost:<port>/` instead of AgentCore
+2. Set `LOCAL_DEV=true` so the generated client connects directly to `http://localhost:<port>/` instead of AgentCore
 
 Run the agent locally with:
 
-<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
 
 This will start both the host agent and all connected A2A agents, with the host agent calling the remote agents over plain HTTP on their assigned local ports.

package/docs/guides/connection/py-agent-dynamodb.mdx

@@ -0,0 +1,116 @@
+---
+title: Python Agent to DynamoDB
+description: Connect a Python Agent to a Python DynamoDB project
+when:
+  sourceType: py#agent
+  targetType: py#dynamodb
+---
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/py-agent">Python Agent</Link> to a <Link path="guides/py-dynamodb">Python DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/py-agent">`py#agent`</Link> project
+2. A <Link path="guides/py-dynamodb">`py#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your Agent project as the source and your DynamoDB project as the target. If the project contains multiple agent components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates the agent's `<agent-name>-dev` target in `project.json` to depend on the DynamoDB project's `dev` target, and adds the DynamoDB package as a workspace dependency. No source files are modified.
+
+## Using DynamoDB in Agents
+
+Import entity classes from the DynamoDB package and use them inside your agent tools:
+
+```python title="packages/my_project/my_project/my_agent/agent.py"
+from my_scope.my_table.entities.example import ExampleModel
+from strands import tool
+
+@tool
+def list_examples() -> list:
+    """List all example items."""
+    return [item.attribute_values for item in ExampleModel.scan()]
+```
+
+## Infrastructure
+
+To allow the agent's Lambda function to access the DynamoDB table, grant the necessary permissions in your infrastructure.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from ':my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+table.grantReadWriteData(myAgent);
+```
+
+`grantReadWriteData` grants both the DynamoDB and KMS permissions to the agent's execution role.
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source = "../../common/terraform/src/app/dynamodb/my-table"
+}
+
+resource "aws_iam_role_policy" "dynamodb_access" {
+  role = module.my_agent.lambda_role_name
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = [
+          "dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem",
+          "dynamodb:DeleteItem", "dynamodb:Query", "dynamodb:Scan",
+          "dynamodb:BatchGetItem", "dynamodb:BatchWriteItem",
+        ]
+        Resource = [
+          module.my_table.table_arn,
+          "${module.my_table.table_arn}/index/*",
+        ]
+      },
+      {
+        Effect = "Allow"
+        Action = [
+          "kms:Encrypt",
+          "kms:Decrypt",
+          "kms:ReEncrypt*",
+          "kms:GenerateDataKey*",
+          "kms:DescribeKey"
+        ]
+        Resource = [module.my_table.kms_key_arn]
+      },
+    ]
+  })
+}
+```
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+<Snippet name="connection/py-dynamodb-local-development" />

package/docs/guides/connection/py-agent-gateway.mdx

@@ -0,0 +1,176 @@
+---
+title: Python Agent to Gateway
+description: Connect a Python Agent to an AgentCore Gateway
+when:
+  sourceType: py#agent
+  targetType: agentcore-gateway
+---
+import { FileTree, Tabs, TabItem } 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 Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator can connect your <Link path="guides/py-agent">Python Agent</Link> to an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link>.
+
+The generator wires the agent so it authenticates to the Gateway with IAM SigV4 (via `httpx` request signing) when deployed, and connects to the local gateway started by the Gateway project when running locally.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A Python project with a <Link path="guides/py-agent">Agent</Link> component (`infra: agentcore`)
+2. A <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the agent project as the source and the Gateway project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator emits shared core-gateway modules into your `agent_connection` Python project, plus a per-Gateway wrapper, and modifies your agent:
+
+<FileTree>
+
+- packages/common/agent\_connection
+  - \<scope>\_agent\_connection
+    - core/
+      - agentcore\_endpoints.py Framework-agnostic ARN/URL resolution
+      - agentcore\_gateway\_mcp\_transport.py Framework-agnostic Gateway MCP transport
+      - agentcore\_gateway\_mcp\_client\_\<framework>.py Gateway MCP client for your agent's framework
+      - auth/ Framework-agnostic SigV4 / session-forwarding `httpx.Auth`
+    - app/
+      - \<gateway\_snake>\_client\_\<framework>.py Per-Gateway client wrapper
+    - \_\_init\_\_.py Re-exports the Gateway client
+
+</FileTree>
+
+The client suffix matches your agent's framework (`_strands` or `_langchain`).
+
+Additionally, the generator:
+
+- Modifies your agent's `agent.py` to import the Gateway client and register its tools in `tools`
+- Adds `agent_connection` as a workspace dependency of the agent
+- Wires the agent's `<agent>-dev` target to depend on the Gateway's `dev` target
+
+## Using the connected Gateway
+
+The generator transforms your agent's `agent.py` to use the Gateway client:
+
+<Tabs syncKey="agent-framework">
+<TabItem label="Strands" _filter={{ framework: 'strands' }}>
+```python title="packages/example/example/my_agent/agent.py" {4,8,9-13}
+from contextlib import contextmanager
+from strands import Agent
+
+from my_scope_agent_connection import MyGatewayClientStrands
+
+@contextmanager
+def get_agent():
+    my_gateway = MyGatewayClientStrands.create()
+    with (
+        my_gateway,
+    ):
+        yield Agent(
+            system_prompt="...",
+            tools=[*my_gateway.list_tools_sync()],
+        )
+```
+
+`MyGatewayClientStrands.create()` returns a single context-manageable `MCPClient` whose `list_tools_sync()` yields every tool available through the Gateway.
+</TabItem>
+<TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
+```python title="packages/example/example/my_agent/agent.py" {4,8,12}
+from langchain.agents import create_agent
+from langchain_aws import ChatBedrockConverse
+
+from my_scope_agent_connection import MyGatewayClientLangChain
+
+def get_agent():
+    my_gateway = MyGatewayClientLangChain.create()
+    return create_agent(
+        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
+        system_prompt="...",
+        tools=[*my_gateway],
+    )
+```
+
+`MyGatewayClientLangChain.create()` returns a list of tools loaded via [`langchain-mcp-adapters`](https://docs.langchain.com/oss/python/langchain/mcp). Each tool opens a fresh session per call, so no `with` block is needed.
+</TabItem>
+</Tabs>
+
+In both cases the client behaves the same way per mode:
+
+- **Deployed mode** (`LOCAL_DEV` unset): tools pointed at the Gateway's MCP endpoint, SigV4-signed.
+- **Local mode** (`LOCAL_DEV=true`): plain-HTTP tools pointed at the local gateway started by the Gateway project's `dev` target.
+
+The session ID is propagated to downstream MCP servers automatically via the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header.
+
+## Infrastructure
+
+After running the generator you must grant the agent permission to invoke the Gateway.
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {5}
+const gateway = new MyGateway(this, 'MyGateway');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+// Grant the agent permissions to invoke the Gateway
+gateway.grantInvokeAccess(myAgent);
+```
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated CDK construct, so the agent can discover it at runtime.
+</Fragment>
+<Fragment slot="terraform">
+```hcl title="packages/infra/src/main.tf" {6-13}
+module "my_gateway" {
+  source = "../../common/terraform/src/app/gateways/my-gateway"
+}
+
+module "my_agent" {
+  source = "../../common/terraform/src/app/agents/my-agent"
+
+  # Grant the agent permission to invoke the Gateway
+  additional_iam_policy_statements = [{
+    Effect   = "Allow"
+    Action   = ["bedrock-agentcore:InvokeGateway"]
+    Resource = [module.my_gateway.gateway_arn]
+  }]
+}
+```
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated Terraform module, so the agent can discover it at runtime.
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+The generator configures the agent's `dev` target to:
+
+1. Start the connected Gateway's local gateway and every attached MCP server
+2. Set `LOCAL_DEV=true` so the generated client points at the local gateway instead of the deployed Gateway
+
+Run the agent locally with:
+
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
+
+To run the agent locally **against the deployed Gateway** instead (for example, to exercise Cedar policies), use the agent's `serve` target. Without `LOCAL_DEV` set, the client resolves the deployed Gateway URL from runtime configuration and SigV4-signs requests with your local AWS credentials:
+
+<NxCommands commands={["<agent-name>-serve <project-name>"]} />
+
+### Local fidelity
+
+The local gateway stands in for the deployed Gateway, so:
+
+- **No Cedar policy evaluation.** Every tool is visible to the agent regardless of policies. Use the `serve` target to exercise policies against the deployed Gateway.
+- **Tool-name prefixing is preserved.** Each local MCP server's tools are exposed as `<target-name>___<tool-name>`, matching what the deployed Gateway emits. This keeps the agent's system prompt and the Cedar action names you reference consistent across local and deployed runs.

package/docs/guides/connection/py-agent-mcp.mdx

@@ -7,7 +7,7 @@ when:
     - ts#mcp-server
     - py#mcp-server
 ---
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
 import Link from '@components/link.astro';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
@@ -22,7 +22,7 @@ The generator sets up all the necessary wiring so your agent can discover and in
 
 Before using this generator, ensure you have:
 
-1. A Python project with a <Link path="guides/py-agent">Strands Agent</Link> component
+1. A Python project with a <Link path="guides/py-agent">Python Agent</Link> component (Strands or LangChain)
 2. A project with an MCP server component (either <Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> or <Link path="guides/py-mcp-server">`py#mcp-server`</Link>)
 3. Both components created with `infra: agentcore`
 
@@ -48,30 +48,37 @@ The generator creates a shared `agent_connection` Python project at `packages/co
   - \<scope>\_agent\_connection
     - \_\_init\_\_.py Re-exports per-connection clients
     - core
-      - agentcore\_mcp\_client.py Core AgentCore MCP client
+      - agentcore\_endpoints.py Framework-agnostic ARN/URL resolution
+      - agentcore\_mcp\_transport.py Framework-agnostic MCP transport
+      - agentcore\_mcp\_client\_\<framework>.py MCP client wrapping the transport for your agent's framework
+      - auth/ Framework-agnostic SigV4 / session-forwarding `httpx.Auth`
     - app
-      - \<mcp\_server\_name>\_client.py Per-connection client for each MCP server
+      - \<mcp\_server\_name>\_client\_\<framework>.py Per-connection client for each MCP server
 
 </FileTree>
 
+The client suffix matches your agent's framework (`_strands` or `_langchain`).
+
 Additionally, the generator:
 - Transforms your agent's `agent.py` to import and use the MCP server's tools via a class-based client
 - Adds the `agent_connection` project as a workspace dependency of your agent project
-- Updates the agent's `serve-local` target to depend on the MCP server's serve target
+- Updates the agent's `dev` target to depend on the MCP server's serve target
 
 ## Using the Connected MCP Server
 
 The generator transforms your agent's `agent.py` to use the MCP server's tools:
 
-```python title="packages/my-project/my_module/agent/agent.py" {4,10-14}
+<Tabs syncKey="agent-framework">
+<TabItem label="Strands" _filter={{ framework: 'strands' }}>
+```python title="packages/my-project/my_module/agent/agent.py" {4,9-13}
 from contextlib import contextmanager
 from strands import Agent
 
-from my_scope_agent_connection import MyMcpServerClient
+from my_scope_agent_connection import MyMcpServerClientStrands
 
 @contextmanager
-def get_agent(session_id: str):
-    my_mcp_server = MyMcpServerClient.create(session_id=session_id)
+def get_agent():
+    my_mcp_server = MyMcpServerClientStrands.create()
     with (
         my_mcp_server,
     ):
@@ -81,7 +88,29 @@ def get_agent(session_id: str):
         )
 ```
 
-The `session_id` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
+The Strands client is a context manager, entered in a `with` block around the agent.
+</TabItem>
+<TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
+```python title="packages/my-project/my_module/agent/agent.py" {4,8,13}
+from langchain.agents import create_agent
+from langchain_aws import ChatBedrockConverse
+
+from my_scope_agent_connection import MyMcpServerClientLangChain
+
+def get_agent():
+    my_mcp_server = MyMcpServerClientLangChain.create()
+    return create_agent(
+        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
+        system_prompt="...",
+        tools=[*my_mcp_server],
+    )
+```
+
+The LangChain client returns a list of tools loaded via [`langchain-mcp-adapters`](https://docs.langchain.com/oss/python/langchain/mcp). Each tool opens a fresh MCP session per call, so the tools stay usable for the agent's lifetime — no `with` block is needed.
+</TabItem>
+</Tabs>
+
+The AgentCore session ID is propagated to the MCP server automatically via the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header for both frameworks, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
 
 ## Infrastructure
 
@@ -136,12 +165,12 @@ The MCP server's AgentCore runtime ARN is automatically registered in the `agent
 
 ## Local Development
 
-The generator configures the agent's `serve-local` target to:
+The generator configures the agent's `dev` target to:
 1. Start the connected MCP server(s) automatically
-2. Set `SERVE_LOCAL=true` so the generated client uses direct HTTP transport instead of AgentCore
+2. Set `LOCAL_DEV=true` so the generated client uses direct HTTP transport instead of AgentCore
 
 Run the agent locally with:
 
-<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
 
 This will start both the agent and all connected MCP servers, with the agent connecting to the MCP servers directly via HTTP on their assigned local ports.