@aws/nx-plugin-mcp 1.0.0-rc.7 → 1.0.0-rc.71

package/docs/guides/agentcore-harness.mdx

@@ -0,0 +1,275 @@
+---
+title: AgentCore Harness
+description: Create an Amazon Bedrock AgentCore Harness project
+generator: agentcore-harness
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Snippet from '@components/snippet.astro';
+
+Generate an [Amazon Bedrock AgentCore Harness](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness.html) project. A Harness is a managed agent loop powered by Strands Agents: it owns deployment defaults for the model, system prompt, tools, memory, skills, environments, truncation, authorization, and execution limits, while the service accepts per-invocation overrides for supported fields. Reusing the same Runtime Session ID continues the same Harness session.
+
+## Usage
+
+### Generate an AgentCore Harness
+
+<RunGenerator generator="agentcore-harness" />
+
+### Options
+
+<GeneratorParameters generator="agentcore-harness" />
+
+## Generator Output
+
+The generator creates a standalone project at `packages/<name>/`. Because AWS runs the agent loop for you, the project holds only the prompt that shapes it and a script for talking to it:
+
+<FileTree>
+  - packages/\<name>/
+    - src/PROMPT.md The Harness system prompt
+    - scripts/chat.ts Multi-turn chat client for the deployed Harness
+    - project.json Adds the `chat` target
+    - README.md Chat and customization instructions
+</FileTree>
+
+### Infrastructure
+
+Infrastructure is generated when `infra` is `agentcore` (the default). With `infra: none` no infrastructure is generated — set `HARNESS_ARN` to invoke a Harness managed elsewhere, and re-run the generator with `infra: agentcore` later to add infrastructure; existing project files (including your edits) are preserved.
+
+<Snippet name="shared-constructs" />
+
+<Infrastructure>
+  <Fragment slot="cdk">
+    <FileTree>
+      - packages/common/constructs/src/app/harnesses/\<name>/
+        - \<name>.ts CDK construct containing the Harness and execution role
+    </FileTree>
+  </Fragment>
+  <Fragment slot="terraform">
+    <FileTree>
+      - packages/common/terraform/src/app/harnesses/\<name>/
+        - \<name>.tf Terraform module containing the Harness and execution role
+    </FileTree>
+  </Fragment>
+</Infrastructure>
+
+The generated infrastructure manages the Harness through the native resource (CDK `aws_bedrockagentcore.CfnHarness`, Terraform `aws_bedrockagentcore_harness`) with your generated defaults, creates an IAM execution role with the baseline permissions described below, and uses IAM inbound authorization (no custom JWT authorizer is configured by default).
+
+The Harness ARN is registered at `agentcore.harnesses.<ClassName>` in <Link path="guides/runtime-config">Runtime Configuration</Link>, preserving any existing entries.
+
+## Deploying your AgentCore Harness
+
+The generator creates CDK or Terraform infrastructure as code based on your selected `iac` provider. You can use this to deploy your Harness through your usual infrastructure workflow.
+
+<Infrastructure>
+  <Fragment slot="cdk">
+The CDK construct for deploying your Harness lives in the `common/constructs` folder. Instantiate it from a CDK application:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyHarness } from '@my-scope/common-constructs';
+import { Stack, type StackProps } from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    new MyHarness(this, 'MyHarness');
+  }
+}
+```
+
+The construct's props interface (`MyHarnessProps`) extends `Partial<Omit<CfnHarnessProps, 'executionRoleArn' | 'allowedTools'>>`, so any native Harness property can be supplied and takes precedence over the generated defaults:
+
+```ts
+const harness = new MyHarness(this, 'MyHarness', {
+  maxIterations: 20,
+  timeoutSeconds: 600,
+});
+```
+
+The construct also accepts:
+
+- `allowedTools` — the tools the Harness may use. The Harness deploys with none unless you supply them, see <a href="#configuring-tools">Configuring tools</a>.
+- `executionRole` — an existing IAM role to use instead of the generated role. A supplied role is used as-is: the baseline permissions are not added to it, and its ARN always feeds the Harness (the raw `executionRoleArn` string cannot be overridden).
+- `modelResourceArns` — the Bedrock model and inference-profile ARNs the generated execution role may invoke, replacing the default list.
+- `vpc`, `vpcSubnets` and `securityGroups` — run the Harness in a VPC so it can reach private resources, see <a href="#running-in-a-vpc">Running in a VPC</a>.
+
+Its public members are `harness` (the `CfnHarness`), `executionRole`, `grantPrincipal`, the `harnessArn` getter, `connections` (in a VPC), `addToRolePolicy(statement)` for execution role extensions, and `grantInvokeAccess(grantee)` for authorizing callers.
+
+Deploy the stack with your infrastructure project as usual — see the <Link path="guides/typescript-infrastructure">CDK infrastructure guide</Link>.
+  </Fragment>
+  <Fragment slot="terraform">
+The Terraform module for deploying your Harness is in the `common/terraform` folder. Reference it from a Terraform configuration:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_harness" {
+  source = "../../common/terraform/src/app/harnesses/my-harness"
+}
+```
+
+The module exposes three variables:
+
+- `model_id` — the Bedrock model or inference profile the Harness uses by default.
+- `model_resource_arns` — the Bedrock model and inference-profile ARNs the execution role may invoke, replacing the default list.
+- `additional_execution_role_policy_statements` — a list of IAM statement objects (`Effect`, `Action`, `Resource`, optional `Sid` and `Condition`) appended to the execution role policy.
+
+Everything else is configured on the generated `aws_bedrockagentcore_harness` resource in the module itself.
+
+The module outputs `harness_id`, `harness_arn`, and `execution_role_arn`.
+
+Deploy with your Terraform project's plan/apply workflow as usual — see the <Link path="guides/terraform-project">Terraform project guide</Link>.
+  </Fragment>
+</Infrastructure>
+
+:::note[System prompt visibility]
+Your infrastructure reads `packages/<name>/src/PROMPT.md` when you synthesize (CDK) or plan (Terraform), so the prompt is deployment configuration rather than secret storage: its contents appear in the synthesized CloudFormation template or in Terraform state.
+:::
+
+## Granting access to invoke the harness
+
+You can grant a caller permissions to invoke the harness as follows:
+
+<Infrastructure>
+  <Fragment slot="cdk">
+```ts
+const harness = new MyHarness(this, 'MyHarness');
+
+harness.grantInvokeAccess(caller);
+```
+  </Fragment>
+  <Fragment slot="terraform">
+```hcl
+# Attach to the calling principal's role
+resource "aws_iam_role_policy" "invoke_my_harness" {
+  name = "InvokeMyHarness"
+  role = aws_iam_role.caller.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect = "Allow"
+      Action = [
+        "bedrock-agentcore:InvokeHarness",
+        "bedrock-agentcore:InvokeAgentRuntime",
+      ]
+      Resource = [module.my_harness.harness_arn]
+    }]
+  })
+}
+```
+  </Fragment>
+</Infrastructure>
+
+A caller needs both `bedrock-agentcore:InvokeHarness` and `bedrock-agentcore:InvokeAgentRuntime` on the Harness ARN, which is exactly what `grantInvokeAccess` grants.
+
+## Chatting with your Harness
+
+The generated `chat` target runs `scripts/chat.ts`, dropping you into an interactive terminal chat with your deployed Harness:
+
+<NxCommands commands={['run <project>:chat']} />
+
+Every turn of a run shares one session, so the Harness keeps the conversation context until you exit. Credentials come from the standard AWS SDK credential provider chain, and the AWS Region is derived from the Harness ARN.
+
+The Harness ARN is resolved in this order:
+
+1. `HARNESS_ARN` (non-empty): used directly, without reading Runtime Configuration:
+
+   <NxCommands commands={['run <project>:chat']} env={{ HARNESS_ARN: '<harness-arn>' }} />
+
+2. `RUNTIME_CONFIG_APP_ID`: resolves the ARN from the `agentcore.harnesses.<ClassName>` entry published by the deployed infrastructure:
+
+   <NxCommands commands={['run <project>:chat']} env={{ RUNTIME_CONFIG_APP_ID: '<application-id>' }} />
+
+With neither set, the script fails with an error naming both options.
+
+## Customizing your Harness
+
+`src/PROMPT.md` is the Harness system prompt: edit it and redeploy to change how the Harness behaves. Everything else is configured where you instantiate the infrastructure, or by editing the generated construct or module directly. Re-running the generator never overwrites existing files (it only adds missing files and merges project metadata), so your edits to the prompt and to the generated infrastructure are preserved.
+
+<Infrastructure>
+  <Fragment slot="cdk">
+Every native Harness property of the pinned `aws-cdk-lib/aws-bedrockagentcore` module is available through the construct's props — alternate model providers, tool definitions, memory, skills, environment configuration, truncation, custom JWT authorization, and execution limits — and explicit props take precedence over the generated defaults. Alternatively, edit the generated construct in `packages/common/constructs/src/app/harnesses/<name>/<name>.ts`.
+  </Fragment>
+  <Fragment slot="terraform">
+The generated module keeps the native `aws_bedrockagentcore_harness` resource directly editable, so provider-native fields — alternate model providers (`gemini_model_config`, `openai_model_config`), `tool` blocks, `memory`, `skill` blocks, environments (`environment`, `environment_variables`, `environment_artifact`), `truncation`, and `authorizer_configuration` with a `custom_jwt_authorizer` — are configured by editing `packages/common/terraform/src/app/harnesses/<name>/<name>.tf`.
+  </Fragment>
+</Infrastructure>
+
+Omitting authorizer configuration (the default) means IAM inbound authorization; configure a custom JWT authorizer through the native field to change that.
+
+### Configuring tools
+
+The Harness deploys with no tools, so it starts with the least capability. Opt in to the tools it may use:
+
+<Infrastructure>
+  <Fragment slot="cdk">
+```ts
+new MyHarness(this, 'Harness', { allowedTools: ['@builtin'] });
+```
+  </Fragment>
+  <Fragment slot="terraform">
+```hcl title="packages/common/terraform/src/app/harnesses/my-harness/my-harness.tf"
+resource "aws_bedrockagentcore_harness" "this" {
+  # ...
+  allowed_tools = ["@builtin"]
+}
+```
+
+Add an `allowed_tools` variable to the module if you would rather set it as a module argument where you reference the module.
+  </Fragment>
+</Infrastructure>
+
+Narrow `@builtin` to specific patterns such as `@builtin/file_operations` to restrict what the agent loop can do. See [Harness tools](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-tools.html) for the built-in tools you can add.
+
+### Running in a VPC
+
+<Infrastructure>
+  <Fragment slot="cdk">
+Supply a `vpc` to run the Harness inside it, so it can reach private resources such as a database. The construct implements `IConnectable`, so those resources grant it access the same way they would any other:
+
+```ts
+const harness = new MyHarness(this, 'MyHarness', { vpc });
+
+database.connections.allowDefaultPortFrom(harness, 'Harness to database');
+```
+
+The Harness is placed in the VPC's private subnets with egress, in a security group created for it. Override either with `vpcSubnets` and `securityGroups`. Both require `vpc`, and `connections` is only available when the Harness runs in a VPC.
+  </Fragment>
+  <Fragment slot="terraform">
+Add a `network_configuration` block to the generated `aws_bedrockagentcore_harness` resource's `environment.agent_core_runtime_environment`, then reference the security group you place it in from your other resources' rules:
+
+```hcl title="packages/common/terraform/src/app/harnesses/my-harness/my-harness.tf"
+resource "aws_security_group" "harness" {
+  vpc_id = var.vpc_id
+}
+
+resource "aws_bedrockagentcore_harness" "this" {
+  # ...
+  environment {
+    agent_core_runtime_environment {
+      network_configuration {
+        network_mode = "VPC"
+        network_mode_config {
+          security_groups = [aws_security_group.harness.id]
+          subnets         = var.subnet_ids
+        }
+      }
+    }
+  }
+}
+```
+  </Fragment>
+</Infrastructure>
+
+### Per-invocation overrides
+
+The values configured in infrastructure are deployment defaults. The service also accepts per-invocation overrides for supported Harness fields (such as models, tools, and skills) in the `InvokeHarness` request; deployment defaults apply wherever a field is not overridden.
+
+:::caution[Validate invocation overrides]
+Per-invocation overrides are trusted inputs at the service boundary: any authorized caller can override supported fields. If untrusted users can reach an application that forwards overrides to `InvokeHarness`, validate and authorize them at the application layer (for example, allowlist models and tools), keep the execution role scoped to required resources, and do not grant `bedrock-agentcore:InvokeAgentRuntimeCommand` unless you specifically need it.
+:::

package/docs/guides/astro-docs.mdx

@@ -86,6 +86,14 @@ When run without `--all`, the script only translates files that have changed
 since the last translation commit on the current branch — meaning you can
 safely re-run it on every docs PR without re-translating the whole site.
 
+Translations whose source file no longer exists are deleted, so renaming or
+removing a page does not leave stale copies behind in each locale.
+
+Each translation is written as a whole file. The agent is given the source, the
+existing translation, and a diff of what changed, and reuses the existing
+wording for sections the diff left alone — so only prose the diff touched is
+retranslated, and code blocks are copied from the source as-is.
+
 ### Configuring translation
 
 Edit `scripts/translate.config.json` to change:

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.
+:::