@aws/nx-plugin-mcp 1.0.0-rc.9 → 1.0.0-rc.91

package/docs/guides/agentcore-harness.mdx

@@ -0,0 +1,312 @@
+---
+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. Defaults to none, 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 the following variables:
+
+- `model_id` — the Bedrock model or inference profile the Harness uses by default.
+- `allowed_tools` — the tools the Harness may use. Defaults to none, see <a href="#configuring-tools">Configuring tools</a>.
+- `memory` — the Harness memory configuration, see <a href="#configuring-memory">Configuring memory</a>.
+- `environment_variables`, `max_iterations`, `timeout_seconds` — the corresponding native Harness fields.
+- `execution_role_arn` — an existing IAM role to use instead of the generated role. A supplied role is used as-is: neither the role nor its baseline policy is created, so `model_resource_arns` and `additional_execution_role_policy_statements` cannot be combined with it.
+- `model_resource_arns` — the Bedrock model and inference-profile ARNs the generated 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 generated execution role policy.
+- `enable_vpc`, `vpc_id`, `subnet_ids` — run the Harness in a VPC so it can reach private resources, see <a href="#running-in-a-vpc">Running in a VPC</a>.
+- `tags` — tags applied to the resources the module creates.
+
+Other provider-native fields are configured by editing the generated `aws_bedrockagentcore_harness` resource in the module itself, see <a href="#customizing-your-harness">Customizing your Harness</a>.
+
+The module outputs `harness_id`, `harness_arn`, `execution_role_arn` and `security_group_id`.
+
+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 module's variables cover the fields most deployments configure — `model_id`, `allowed_tools`, `memory`, `environment_variables`, `max_iterations`, `timeout_seconds` — plus the execution role and VPC placement. Terraform has no equivalent of the CDK construct's prop spread, so the remaining provider-native fields are configured by editing the `aws_bedrockagentcore_harness` resource in `packages/common/terraform/src/app/harnesses/<name>/<name>.tf`: alternate model providers (`gemini_model_config`, `openai_model_config`), `tool` blocks, `skill` blocks, `environment_artifact`, filesystem and lifecycle configuration under `environment`, `truncation`, and `authorizer_configuration` with a `custom_jwt_authorizer`.
+  </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/infra/src/main.tf"
+module "my_harness" {
+  source        = "../../common/terraform/src/app/harnesses/my-harness"
+  allowed_tools = ["@builtin"]
+}
+```
+  </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.
+
+### Configuring memory
+
+The service provisions managed memory for the Harness by default, and the generated execution role is granted access to it — scoped to the memory ARN the service assigns, and only granted while the Harness uses managed memory the infrastructure created. Configure memory explicitly to tune that managed memory, point the Harness at a memory resource you own, or turn memory off:
+
+<Infrastructure>
+  <Fragment slot="cdk">
+```ts
+new MyHarness(this, 'MyHarness', {
+  memory: { managedMemoryConfiguration: { strategies: ['SUMMARIZATION'] } },
+});
+```
+
+Supplying `memory` at all replaces the default managed memory, so the construct leaves the memory grant off the execution role: add whatever the configuration needs with `addToRolePolicy`.
+  </Fragment>
+  <Fragment slot="terraform">
+```hcl
+module "my_harness" {
+  source = "../../common/terraform/src/app/harnesses/my-harness"
+  memory = {
+    managed_memory_configuration = {
+      strategies = ["SUMMARIZATION"]
+    }
+  }
+}
+```
+
+Set exactly one of `managed_memory_configuration` (tune the service's managed memory), `agentcore_memory_configuration` (use a memory resource you own, by ARN) or `disabled` (no memory). Choosing `agentcore_memory_configuration` or `disabled` drops the managed-memory grant from the execution role; for your own memory resource, grant access through `additional_execution_role_policy_statements`.
+  </Fragment>
+</Infrastructure>
+
+### 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">
+Set `enable_vpc` alongside `vpc_id` and `subnet_ids` to run the Harness inside a VPC, so it can reach private resources such as a database:
+
+```hcl
+module "my_harness" {
+  source     = "../../common/terraform/src/app/harnesses/my-harness"
+  enable_vpc = true
+  vpc_id     = var.vpc_id
+  subnet_ids = var.private_subnet_ids
+}
+```
+
+The module creates a security group for the Harness, allowing outbound HTTPS only. Its `security_group_id` output is what resources the Harness must reach reference in their own ingress rules:
+
+```hcl
+resource "aws_vpc_security_group_ingress_rule" "harness_to_database" {
+  security_group_id            = aws_security_group.database.id
+  referenced_security_group_id = module.my_harness.security_group_id
+  from_port                    = 5432
+  to_port                      = 5432
+  ip_protocol                  = "tcp"
+  description                  = "Harness to database"
+}
+```
+
+`security_group_id` is null unless `enable_vpc` is true, and `vpc_id` and `subnet_ids` are both required when it is.
+  </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.