@aws/nx-plugin-mcp 1.0.0-rc.6 → 1.0.0-rc.62

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

@@ -0,0 +1,222 @@
+---
+title: AgentCore Gateway to Agent
+description: Front an agent with an AgentCore Gateway as a runtime target
+when:
+  sourceType: agentcore-gateway
+  targetType:
+    - ts#agent
+    - py#agent
+---
+import { 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 Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator can register an agent (either <Link path="guides/ts-agent">TypeScript</Link> or <Link path="guides/py-agent">Python</Link>) as an [AgentCore Runtime target](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-http-runtime.html) of an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link> generated with `protocol: http`.
+
+Once connected, the Gateway proxies requests for the agent under `<gatewayUrl>/<targetName>/invocations`, signing outbound traffic to the runtime with IAM SigV4. This gives your agents a single governed entry point — and since callers only need to reach the Gateway, the agent runtimes themselves can be deployed inside a VPC behind it.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. An <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project generated with `protocol: http`
+2. An agent component (<Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link>) created with `infra: agentcore`. Either `auth: iam` (the Gateway invokes it with its own role) or `auth: cognito` (the Gateway forwards the caller's JWT — see [Forwarding caller identity](#forwarding-caller-identity-to-the-runtime)) works.
+
+:::caution[TypeScript HTTP agents]
+A TypeScript `http` agent serves tRPC over WebSocket, and AgentCore Gateway does not support WebSocket or bidirectional streaming — the generator rejects this combination. Generate the agent with the `ag-ui` protocol instead.
+:::
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the Gateway project as the source and the agent project as the target. If the agent project contains multiple components, specify `targetComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator wires existing projects together rather than emitting new source files. The following files are modified:
+
+<FileTree>
+
+- packages/\<gateway>
+  - project.json the Gateway's `dev` target gains a dependency on the agent's `<agent>-dev`
+  - local-dev.ts `ATTACHED_AGENTS` updated so the local gateway proxies to the agent
+
+</FileTree>
+
+## Adding the agent target to your stack
+
+The generator **cannot** automatically wire the agent target into your infrastructure because it doesn't know which stack or module instantiates the Gateway. Add a single call to `gateway.addAgent(agent)` yourself.
+
+<Infrastructure>
+<Fragment slot="cdk">
+In the stack where you instantiate the Gateway, register the agent as a target:
+
+```ts title="packages/infra/src/stacks/application-stack.ts" {5-8}
+const myAgent = new MyAgent(this, 'MyAgent');
+const myGateway = new MyGateway(this, 'MyGateway');
+
+// Register the agent as a runtime target of the Gateway. The target name
+// defaults to the agent's `agentName` (its class name in kebab-case,
+// e.g. `MyAgent` -> `my-agent`), and forms the target's invocation path:
+// <gatewayUrl>/my-agent/invocations
+myGateway.addAgent(myAgent);
+```
+
+To override the default target name, pass `gatewayTargetName`:
+
+```ts
+myGateway.addAgent(myAgent, { gatewayTargetName: 'my-target' });
+```
+
+The construct grants the Gateway's execution role invoke access to the agent runtime and configures the target with the `GATEWAY_IAM_ROLE` credential provider, so the Gateway signs outbound calls with its own role.
+
+:::tip[Deploying agents into a VPC]
+Fronting an agent with a Gateway is what makes a VPC-deployed agent reachable: callers talk to the Gateway's public endpoint, and the Gateway reaches the runtime internally. Pass a VPC network configuration to the agent construct:
+
+```ts
+import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
+
+const myAgent = new MyAgent(this, 'MyAgent', {
+  // Give each agent its own scope for the network configuration — usingVpc
+  // creates a security group named `SecurityGroup` under the scope you pass,
+  // so passing `this` for more than one agent collides on the construct id.
+  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(
+    new Construct(this, 'MyAgentNetwork'),
+    {
+      vpc,
+      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
+    },
+  ),
+});
+```
+
+Use a **private subnet with egress**, not a private isolated subnet: the runtime needs outbound internet access to reach Bedrock and read its configuration from AWS AppConfig.
+
+AgentCore Runtime VPC deployments are only supported in certain availability zones. If a deploy fails with `subnets are in unsupported availability zones`, restrict the VPC (or the subnet selection) to the supported zones for your region.
+:::
+</Fragment>
+<Fragment slot="terraform">
+In the Terraform file where you instantiate the Gateway, wire the agent target in:
+
+```hcl title="packages/infra/src/main.tf" {9-20,24-40}
+module "my_agent" {
+  source = "../../common/terraform/src/app/agents/my-agent"
+  # ...
+}
+
+module "my_gateway" {
+  source = "../../common/terraform/src/app/gateways/my-gateway"
+
+  # The Gateway signs outbound calls to the runtime with its own role and
+  # validates access at target creation, so it needs invoke access first.
+  additional_iam_policy_statements = [
+    {
+      Effect = "Allow"
+      Action = [
+        "bedrock-agentcore:InvokeAgentRuntime",
+        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
+        # A2A targets additionally serve their agent card via the gateway
+        "bedrock-agentcore:GetAgentCard",
+      ]
+      Resource = [
+        module.my_agent.agent_core_runtime_arn,
+        "${module.my_agent.agent_core_runtime_arn}/*",
+      ]
+    }
+  ]
+}
+
+# Register the agent as a runtime target of the Gateway. The target name
+# forms the invocation path: <gatewayUrl>/my-agent/invocations
+resource "aws_bedrockagentcore_gateway_target" "my_agent" {
+  gateway_identifier = module.my_gateway.gateway_id
+  name               = "my-agent"
+  # AgentCore fills in a description when none is set, which the provider
+  # reports as an inconsistent result after apply — so always set one.
+  description = "Agent runtime target my-agent"
+
+  target_configuration {
+    http {
+      agentcore_runtime {
+        arn = module.my_agent.agent_core_runtime_arn
+      }
+    }
+  }
+
+  credential_provider_configuration {
+    gateway_iam_role {}
+  }
+}
+```
+
+:::tip[Deploying agents into a VPC]
+Fronting an agent with a Gateway is what makes a VPC-deployed agent reachable: callers talk to the Gateway's public endpoint, and the Gateway reaches the runtime internally. Set the agent module's VPC variables:
+
+```hcl
+module "my_agent" {
+  source = "../../common/terraform/src/app/agents/my-agent"
+
+  enable_vpc = true
+  vpc_id     = aws_vpc.my_vpc.id
+  subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]
+}
+```
+
+Use private subnets with egress (a route to a NAT gateway), not private isolated subnets: the runtime needs outbound internet access to reach Bedrock and read its configuration from AWS AppConfig.
+:::
+</Fragment>
+</Infrastructure>
+
+## Invoking the agent through the Gateway
+
+Requests to `<gatewayUrl origin>/<targetName>/invocations` are forwarded to the agent runtime without protocol translation, so callers use the same request shape they'd use against the runtime directly — SSE streams (AG-UI), JSON streaming (Python HTTP) and A2A JSON-RPC all proxy through. Callers authenticate with the Gateway (IAM SigV4 or Cognito JWT depending on the Gateway's `auth`) rather than with the agent.
+
+To connect a website to the Gateway's agents, use the <Link path="guides/connection/react-agentcore-gateway">`connection` generator</Link>.
+
+## Forwarding caller identity to the runtime
+
+By default the Gateway signs outbound calls with its own IAM role (the `GATEWAY_IAM_ROLE` credential provider), so the runtime sees the _Gateway's_ identity, not the caller's. If instead you want the agent to authorize on the caller — for example to read the user's `sub` or `scope` claims — front a **Cognito** agent with a **Cognito** Gateway. The Gateway then forwards the caller's JWT to the runtime unchanged (the `JWT_PASSTHROUGH` credential provider), and the runtime revalidates it.
+
+Generate both ends with `auth: cognito` and connect them as above:
+
+- an agent (<Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link>) created with `auth: cognito`, and
+- a Gateway created with `auth: cognito` fronting the **same** Cognito user pool.
+
+Everything else is automatic — `gateway.addAgent(agent)` (CDK) and the generated Terraform runtime module handle the wiring for you based on the agent's `auth`:
+
+- the target is created with the `JWT_PASSTHROUGH` credential provider (rather than `GATEWAY_IAM_ROLE`), and
+- the runtime allowlists the `Authorization` header so the forwarded token reaches your agent code. Without this allowlist AgentCore validates the token but strips the header before your container.
+
+Callers invoke the Gateway with `Authorization: Bearer <jwt>` (no SigV4), and the agent reads the claims from the `Authorization` header — skipping signature validation, since the runtime's inbound authorizer has already verified the token:
+
+```python title="packages/py_project/.../my_agent/main.py"
+import jwt  # PyJWT
+
+@app.post('/invocations')
+async def invoke(input: InvokeInput, request: Request):
+    token = request.headers['authorization'].removeprefix('Bearer ')
+    claims = jwt.decode(token, options={'verify_signature': False})
+    # authorize on claims['sub'], claims['scope'], ...
+```
+
+:::note
+JWT passthrough suits a single identity provider whose token audience already covers the runtime. If one Gateway fronts agents across multiple tenants or audiences, use OAuth [on-behalf-of token exchange](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets-authorization.html) instead.
+:::
+
+## Local Development
+
+Running the Gateway locally with:
+
+<NxCommands commands={["dev <gateway-name>"]} />
+
+starts a local gateway plus every attached agent on its assigned local port. The local gateway proxies `/<targetName>/...` paths to each agent's local server, matching the deployed Gateway's path-based routing.

package/docs/guides/connection/agentcore-gateway-gateway.mdx

@@ -0,0 +1,154 @@
+---
+title: AgentCore Gateway to AgentCore Gateway
+description: Connect an AgentCore Gateway to another AgentCore Gateway
+when:
+  sourceType: agentcore-gateway
+  targetType: agentcore-gateway
+---
+import { 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 Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator can register an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link> as a target of another AgentCore Gateway. This lets you compose gateways hierarchically — for example a team-level gateway aggregating several domain gateways, each of which fronts its own MCP servers.
+
+Once connected, the source Gateway aggregates the target Gateway's tools into its single MCP endpoint. Since the target Gateway already prefixes its tools with its own target names, tools surface through the source Gateway as `<gateway-target-name>___<target-name>___<tool-name>` — each gateway in the chain adds one prefix. Both gateways evaluate their own Cedar policies: the source Gateway authorizes the caller for the prefixed action, then the target Gateway authorizes the source Gateway's execution role for the inner action.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. Two <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> projects
+
+Both gateways must have `protocol: mcp`, and the target gateway must have `auth: iam` — the source gateway invokes the target signing with its own execution role, so only the target's inbound auth needs to be IAM. The generator validates this, and also rejects connections that would create a cycle between gateways, which would otherwise recurse infinitely on `tools/list`.
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the aggregating Gateway project as the source and the Gateway to be aggregated as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator wires existing projects together rather than emitting new source files. The following files are modified:
+
+<FileTree>
+
+- packages/\<source-gateway>
+  - project.json the source Gateway's `dev` target gains a dependency on the target gateway's `dev` target
+  - local-dev.ts `ATTACHED_MCP_SERVERS` updated so the local gateway aggregates the target gateway
+
+</FileTree>
+
+The source Gateway project's `dev` target gains a dependency on the target Gateway's `dev` target, so running the source Gateway locally also starts the target gateway (and, transitively, every MCP server attached to it). The target gateway is also registered in the source Gateway project's `local-dev.ts` so the local gateway aggregates its tools.
+
+## Adding the gateway target to your stack
+
+The generator **cannot** automatically wire the gateway target into your infrastructure because it doesn't know which stack or module instantiates the Gateways. Add a single call to `gateway.addGateway(targetGateway)` yourself.
+
+<Infrastructure>
+<Fragment slot="cdk">
+In the stack where you instantiate the Gateways, register the target gateway as a target of the source gateway:
+
+```ts title="packages/infra/src/stacks/application-stack.ts" {4-7}
+const innerGateway = new InnerGateway(this, 'InnerGateway');
+const outerGateway = new OuterGateway(this, 'OuterGateway');
+
+// Register the inner gateway as a target of the outer gateway. The target
+// name defaults to the inner gateway's `gatewayName` (its class name in
+// kebab-case, e.g. `InnerGateway` -> `inner-gateway`).
+outerGateway.addGateway(innerGateway);
+```
+
+The Gateway target name (the target gateway's `gatewayName` by default) prefixes Cedar action names on the source gateway — the action format is ``AgentCore::Action::"<gatewayTargetName>___<targetName>___<toolName>"``. See the <Link path="guides/agentcore-gateway">Writing Policies section</Link>. Keep the target name short and stable; changing it later invalidates any Cedar policies that reference the old name.
+
+To override the default target name, pass `gatewayTargetName`:
+
+```ts
+outerGateway.addGateway(innerGateway, { gatewayTargetName: 'inner' });
+```
+
+The construct grants the source gateway's execution role `bedrock-agentcore:InvokeGateway` access to the target gateway, and configures the target with `iamCredentialProvider.service = 'bedrock-agentcore'` so the source gateway signs outbound calls using its own execution role. The target is created after the target gateway and all of its own targets, since AgentCore fetches the target's tools during creation.
+</Fragment>
+<Fragment slot="terraform">
+In the Terraform file where you instantiate the Gateways, wire the gateway target in:
+
+```hcl title="packages/infra/src/main.tf" {4-6,11,13-19,22-40}
+module "inner_gateway" {
+  source = "../../common/terraform/src/app/gateways/inner-gateway"
+
+  # Target ids of the inner gateway's own targets (e.g. its MCP servers), so
+  # its gateway_url is not consumed until it serves their tools.
+  tool_dependencies = [aws_bedrockagentcore_gateway_target.my_mcp_server.target_id]
+}
+
+module "outer_gateway" {
+  source              = "../../common/terraform/src/app/gateways/outer-gateway"
+  policy_dependencies = [aws_bedrockagentcore_gateway_target.inner_gateway.target_id]
+
+  additional_iam_policy_statements = [
+    {
+      Effect   = "Allow"
+      Action   = ["bedrock-agentcore:InvokeGateway"]
+      Resource = [module.inner_gateway.gateway_arn]
+    }
+  ]
+}
+
+# Register the inner gateway as a target of the outer gateway
+resource "aws_bedrockagentcore_gateway_target" "inner_gateway" {
+  gateway_identifier = module.outer_gateway.gateway_id
+  name               = "inner-gateway"
+
+  target_configuration {
+    mcp {
+      mcp_server {
+        endpoint = module.inner_gateway.gateway_url
+      }
+    }
+  }
+
+  credential_provider_configuration {
+    gateway_iam_role {
+      service = "bedrock-agentcore"
+    }
+  }
+}
+```
+
+The target `name` (`inner-gateway` above) prefixes Cedar action names on the outer gateway — see the <Link path="guides/agentcore-gateway">Writing Policies section</Link>. The `additional_iam_policy_statements` entry grants the outer gateway's execution role invoke access to the inner gateway, which is required both to fetch the inner gateway's tools at target creation time and to route calls at runtime. `policy_dependencies` ensures Cedar policies referencing this target's actions are created after the target has registered them.
+
+:::note[Target ordering]
+AgentCore fetches the inner gateway's tools when the `aws_bedrockagentcore_gateway_target` is created, so the inner gateway must already be serving them. Set the inner gateway's `tool_dependencies` to its own targets' ids: its `gateway_url` then flows through a readiness probe that polls `tools/list` until those tools are served, so the outer gateway's target waits for the inner gateway to be ready.
+:::
+</Fragment>
+</Infrastructure>
+
+## Cedar policies across chained gateways
+
+Each gateway in the chain evaluates its own policy set:
+
+1. The **source gateway** evaluates the original caller (e.g. an agent's execution role) against the prefixed action, e.g. `AgentCore::Action::"inner-gateway___my-mcp___add"`.
+2. The **target gateway** evaluates the source gateway's execution role against the inner action, e.g. `AgentCore::Action::"my-mcp___add"`.
+
+This means a tool call through a gateway chain must be permitted at every hop. The default `permit-all.cedar` permits any caller in the same AWS account, which includes the source gateway's role; if you write narrower policies on the target gateway, remember that the principal it sees is the *source gateway's* role, not the original caller.
+
+## Local Development
+
+Running the source Gateway locally with:
+
+<NxCommands commands={["dev <source-gateway-name>"]} />
+
+starts the local source gateway, the local target gateway, and every MCP server attached to either, each on its assigned local port. Tool names are prefixed at each hop exactly as deployed (`<gateway-target-name>___<target-name>___<tool-name>`), so agent prompts and Cedar action names remain consistent across local and deployed runs.
+
+:::caution[Local fidelity]
+Local development uses **local stand-in gateways** — lightweight MCP aggregators started by each Gateway project, not the AgentCore Gateway service. As a consequence, **Cedar policies are not evaluated locally** at either hop. To exercise Cedar policies, run the agent's `serve` target instead (see the <Link path="guides/connection/ts-agent-gateway">TypeScript</Link> / <Link path="guides/connection/py-agent-gateway">Python</Link> agent-connection guides) so the locally-running agent calls the deployed Gateway.
+:::

package/docs/guides/connection/agentcore-gateway-mcp.mdx

@@ -0,0 +1,134 @@
+---
+title: AgentCore Gateway to MCP Server
+description: Connect an AgentCore Gateway to an MCP server
+when:
+  sourceType: agentcore-gateway
+  targetType:
+    - ts#mcp-server
+    - py#mcp-server
+---
+import { 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 Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator can register an MCP server (either <Link path="guides/ts-mcp-server">TypeScript</Link> or <Link path="guides/py-mcp-server">Python</Link>) as a target of an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link>.
+
+Once connected, the Gateway aggregates the MCP server's tools into its single MCP endpoint, evaluates calls against its Cedar policy engine, and signs outbound traffic to the MCP server with IAM SigV4.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project
+2. An MCP server component (<Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> or <Link path="guides/py-mcp-server">`py#mcp-server`</Link>) created with `infra: agentcore` and `auth: iam`
+
+The Gateway must have `protocol: mcp` and the MCP server must have `auth: iam` — the generator validates both. Non-IAM MCP servers cannot be attached because the Gateway signs outbound traffic with SigV4.
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the Gateway project as the source and the MCP server project as the target. If the MCP server project contains multiple components, specify `targetComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator wires existing projects together rather than emitting new source files. The following files are modified:
+
+<FileTree>
+
+- packages/\<gateway>
+  - project.json the Gateway's `dev` target gains a dependency on the MCP server's `<mcp>-dev`
+  - local-dev.ts `ATTACHED_MCP_SERVERS` updated so the local gateway aggregates the MCP server
+
+</FileTree>
+
+The Gateway project's `dev` target gains a dependency on the MCP server's `<mcp>-dev` target, so running the Gateway locally also starts the MCP server. The MCP server is also registered in the Gateway project's `local-dev.ts` so the local gateway aggregates its tools.
+
+## Adding the MCP server target to your stack
+
+The generator **cannot** automatically wire the MCP server target into your infrastructure because it doesn't know which stack or module instantiates the Gateway. Add a single call to `gateway.addMcpServer(server)` yourself.
+
+<Infrastructure>
+<Fragment slot="cdk">
+In the stack where you instantiate the Gateway, register the MCP server as a target:
+
+```ts title="packages/infra/src/stacks/application-stack.ts" {4-7}
+const myMcpServer = new MyMcpServer(this, 'MyMcpServer');
+const myGateway = new MyGateway(this, 'MyGateway');
+
+// Register the MCP server as a target of the Gateway. The target name
+// defaults to the MCP server's `mcpServerName` (its class name in
+// kebab-case, e.g. `MyMcpServer` -> `my-mcp-server`).
+myGateway.addMcpServer(myMcpServer);
+```
+
+The Gateway target name (the MCP server's `mcpServerName` by default) is used as the prefix for Cedar action names — the action format is ``AgentCore::Action::"<targetName>___<toolName>"``. See the <Link path="guides/agentcore-gateway">Writing Policies section</Link>. Keep the target name short and stable; changing it later invalidates any Cedar policies that reference the old name.
+
+To override the default target name, pass `gatewayTargetName`:
+
+```ts
+myGateway.addMcpServer(myMcpServer, { gatewayTargetName: 'my-mcp' });
+```
+
+The construct configures the target with `iamCredentialProvider.service = 'bedrock-agentcore'` so the Gateway signs outbound calls using its own execution role.
+</Fragment>
+<Fragment slot="terraform">
+In the Terraform file where you instantiate the Gateway, wire the MCP server target in:
+
+```hcl title="packages/infra/src/main.tf" {7,10-28}
+module "my_mcp_server" {
+  source = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
+}
+
+module "my_gateway" {
+  source              = "../../common/terraform/src/app/gateways/my-gateway"
+  policy_dependencies = [aws_bedrockagentcore_gateway_target.my_mcp_server.target_id]
+}
+
+# Register the MCP server as a target of the Gateway
+resource "aws_bedrockagentcore_gateway_target" "my_mcp_server" {
+  gateway_identifier = module.my_gateway.gateway_id
+  name               = "my-mcp-server"
+
+  target_configuration {
+    mcp {
+      mcp_server {
+        endpoint = module.my_mcp_server.invocation_url
+      }
+    }
+  }
+
+  credential_provider_configuration {
+    gateway_iam_role {
+      service = "bedrock-agentcore"
+    }
+  }
+}
+```
+
+The target `name` (`my-mcp-server` above) is used as the prefix for Cedar action names — see the <Link path="guides/agentcore-gateway">Writing Policies section</Link>. `policy_dependencies` ensures Cedar policies referencing this target's actions are created after the target has registered them.
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+Running the Gateway locally with:
+
+<NxCommands commands={["dev <gateway-name>"]} />
+
+starts a local gateway plus every attached MCP server on its assigned local port. The local gateway exposes a single MCP endpoint that aggregates the attached servers' tools. Agents connected to the Gateway via the <Link path="guides/connection/ts-agent-gateway">TypeScript</Link> or <Link path="guides/connection/py-agent-gateway">Python</Link> gateway-connection generators point at it when running with `LOCAL_DEV=true`.
+
+:::caution[Local fidelity]
+Local development uses a **local stand-in gateway** — a lightweight MCP aggregator started by the Gateway project, not the AgentCore Gateway service. As a consequence, **Cedar policies are not evaluated locally**. Every agent sees every tool on every attached MCP server. To exercise Cedar policies, run the agent's `serve` target instead (see the <Link path="guides/connection/ts-agent-gateway">TypeScript</Link> / <Link path="guides/connection/py-agent-gateway">Python</Link> agent-connection guides) so the locally-running agent calls the deployed Gateway.
+
+Tool names are still prefixed locally as `<target-name>___<tool-name>` to match the deployed Gateway's namespacing, so an agent's system prompt and the Cedar action names you reference remain consistent across local and deployed runs.
+:::

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,8 +22,8 @@ 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)
-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>)
+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`
 
 ## Usage
@@ -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" {5,8-13,15}
+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.